> ## Documentation Index
> Fetch the complete documentation index at: https://docs.quidkey.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API Reference

> Technical overview of the Quidkey API

## Base URLs

Quidkey provides separate environments for development and production:

| Environment  | Base URL                   | Purpose          |
| ------------ | -------------------------- | ---------------- |
| **Base URL** | `https://core.quidkey.com` | All API requests |

All endpoints are served under the `/api/v1` prefix (for example `https://core.quidkey.com/api/v1/oauth2/token`).

<Warning>
  Always use `test_transaction: true` in development to avoid processing real payments.
</Warning>

## Authentication

All API endpoints require authentication using **OAuth 2.0 Client Credentials** flow.

<Steps>
  <Step title="Obtain credentials">
    Sign up at [console.quidkey.com](https://console.quidkey.com) to get your `client_id` and `client_secret`
  </Step>

  <Step title="Exchange for access token">
    Call `POST /api/v1/oauth2/token` with your credentials to receive an `access_token`
  </Step>

  <Step title="Use in requests">
    Include the token in all API requests: `Authorization: Bearer <access_token>`
  </Step>
</Steps>

**Token Lifecycle:**

* **Validity:** 15 minutes (900 seconds)
* **Refresh:** Use `POST /api/v1/oauth2/refresh` with your `refresh_token`
* **Best practice:** Cache tokens and refresh before expiry

<Card title="Try Authentication" icon="key" href="/api-reference/endpoint/issue-token">
  Test the authentication flow in the interactive playground
</Card>

## API Endpoints

The Quidkey API is organized into logical groups:

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/api-reference/endpoint/issue-token">
    Obtain and refresh access tokens
  </Card>

  <Card title="Embedded Payment Flow" icon="credit-card" href="/api-reference/embedded/create-a-payment-request-and-return-a-payment_token-for-iframe-flow">
    Create, update, and initiate payments
  </Card>

  <Card title="Payment Links" icon="link" href="/api-reference/payment-links/create-a-payment-link">
    Create, list, and manage checkout links
  </Card>

  <Card title="Webhooks" icon="webhook" href="/api-reference/webhook/register-or-update-a-merchant-webhook-url">
    Configure webhook endpoints and secrets
  </Card>
</CardGroup>

## Common Response Format

All Quidkey API responses follow a consistent structure:

```json Success Response theme={null}
{
  "success": true,
  "data": {
    // Response data here
  }
}
```

```json Error Response theme={null}
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Human-readable error message",
    "metadata": {
      "errors": [
        {
          "field": "amount",
          "message": "Amount must be greater than 0"
        }
      ]
    }
  }
}
```

## HTTP Status Codes

| Status Code | Description           | Common Scenarios                        |
| ----------- | --------------------- | --------------------------------------- |
| `200`       | Success               | Request processed successfully          |
| `201`       | Created               | Resource created successfully           |
| `400`       | Bad Request           | Validation error or malformed request   |
| `401`       | Unauthorized          | Missing or invalid authentication       |
| `403`       | Forbidden             | Valid auth but insufficient permissions |
| `404`       | Not Found             | Resource doesn't exist                  |
| `500`       | Internal Server Error | Server-side issue (rare)                |

## Error Codes

Common error codes you may encounter:

| Code                         | Description                           | Resolution                                              |
| ---------------------------- | ------------------------------------- | ------------------------------------------------------- |
| `VALIDATION_ERROR`           | Request validation failed             | Check `error.metadata.errors` for field-specific issues |
| `NO_TOKEN` / `INVALID_TOKEN` | Missing or expired token (HTTP `401`) | Refresh your access token; branch on the `401` status   |
| `MERCHANT_NOT_FOUND`         | Invalid merchant ID                   | Verify your credentials                                 |
| `PAYMENT_REQUEST_NOT_FOUND`  | Invalid payment token                 | Check token hasn't expired (15 min TTL)                 |
| `PAYMENT_ALREADY_INITIATED`  | Payment already in progress           | Cannot update amount after customer selects bank        |
| `PAYMENT_LINK_NOT_FOUND`     | Invalid payment link token or ID      | Verify the token or link ID                             |
| `PAYMENT_LINK_NOT_ACTIVE`    | Link is used, expired, or cancelled   | Check link status before attempting payment             |

<Tip>
  All error responses include a human-readable `message` field. Use `code` for programmatic handling, `message` for logging/debugging.
</Tip>

## Rate Limits

<Info>
  Quidkey currently does not enforce strict rate limits. However, we recommend implementing exponential backoff for retry logic and avoiding unnecessary API calls.
</Info>

## API Versioning

The current API version is **v1**, indicated in all endpoint paths: `/api/v1/...`

* **Breaking changes:** Will be released as new versions (v2, v3, etc.)
* **Non-breaking changes:** Added to existing version without path changes
* **Deprecation:** Minimum 6 months notice before removing endpoints

## Getting Started

<CardGroup cols={2}>
  <Card title="Quickstart Guide" icon="rocket" href="/quickstart">
    Get your first payment working in 10 minutes
  </Card>

  <Card title="Embedded Flow" icon="credit-card" href="/guides/embedded-flow/overview">
    Complete embedded payment integration guide
  </Card>
</CardGroup>

## Need Help?

<Card title="Contact Support" icon="headset" href="mailto:rabea@quidkey.com">
  Email [rabea@quidkey.com](mailto:rabea@quidkey.com) - we typically respond within one business day
</Card>