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

# API Reference

> Complete reference for all SwiftPay API endpoints

# API Reference

The SwiftPay API is organized around REST. Our API has predictable resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes.

## Base URL

```
https://api.swiftpay.cx
```

All API requests must be made over HTTPS. Calls made over plain HTTP will fail.

## Authentication

The SwiftPay API uses API keys to authenticate requests. Include your API key in the `Authorization` header:

```
Authorization: Bearer mp_live_your_api_key
```

<Warning>
  Keep your API keys secure. Do not share them in publicly accessible areas
  such as GitHub, client-side code, or in your documentation.
</Warning>

## Request Format

For `POST` and `PUT` requests, include a `Content-Type: application/json` header and pass parameters as JSON in the request body.

```bash theme={null}
curl -X POST https://api.swiftpay.cx/api/checkout/sessions \
  -H "Authorization: Bearer mp_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"amountInCents": 2999, "currency": "USD"}'
```

## Response Format

All responses are returned as JSON objects with the following structure:

### Success Response

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

### List Response

```json theme={null}
{
   "success": true,
   "data": {
      "items": [
         // Array of items
      ],
      "meta": {
         "total": 150,
         "page": 1,
         "limit": 20,
         "totalPages": 8,
         "hasNextPage": true,
         "hasPreviousPage": false
      }
   }
}
```

### Error Response

```json theme={null}
{
   "success": false,
   "error": {
      "type": "validation_error",
      "message": "Human-readable error message",
      "requestId": "req_abc123"
   }
}
```

## HTTP Status Codes

| Code  | Description                             |
| ----- | --------------------------------------- |
| `200` | Success                                 |
| `201` | Created                                 |
| `400` | Bad Request - Invalid parameters        |
| `401` | Unauthorized - Invalid API key          |
| `403` | Forbidden - Insufficient permissions    |
| `404` | Not Found - Resource doesn't exist      |
| `429` | Too Many Requests - Rate limit exceeded |
| `500` | Server Error - Something went wrong     |

## Pagination

List endpoints support cursor-based pagination:

| Parameter | Type    | Description                                        |
| --------- | ------- | -------------------------------------------------- |
| `limit`   | integer | Number of results per page (default: 20, max: 100) |
| `cursor`  | string  | Cursor for the next page of results                |

```bash theme={null}
# First page
curl "https://api.swiftpay.cx/api/checkout/sessions?limit=20" \
  -H "Authorization: Bearer mp_live_your_api_key"

# Next page
curl "https://api.swiftpay.cx/api/checkout/sessions?limit=20&cursor=cursor_abc123" \
  -H "Authorization: Bearer mp_live_your_api_key"
```

## Rate Limiting

API requests are rate limited per API key:

| Tier       | Requests/Min | Burst  |
| ---------- | ------------ | ------ |
| Standard   | 60           | 120    |
| Growth     | 300          | 600    |
| Enterprise | Custom       | Custom |

Rate limit headers are included in all responses:

```
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 55
X-RateLimit-Reset: 1705315200
```

## Idempotency

For `POST` requests, you can pass an `Idempotency-Key` header to ensure exactly-once delivery:

```bash theme={null}
curl -X POST https://api.swiftpay.cx/api/checkout/sessions \
  -H "Authorization: Bearer mp_live_your_api_key" \
  -H "Idempotency-Key: unique-request-id-123" \
  -H "Content-Type: application/json" \
  -d '{"amountInCents": 2999, "currency": "USD"}'
```

Idempotency keys are cached for 24 hours.

## Versioning

The current API version is `v1`. The version is included in the URL path:

```
https://api.swiftpay.cx/api/v1/checkout/sessions
```

<Note>
  Currently, all routes are unversioned. Versioning will be introduced in
  future releases with backward compatibility.
</Note>

## Available Endpoints

### Balance

* [GET /api/balance](/api-reference/balance/get-balance) - Get your current balance

### Checkout Sessions

* [POST /api/checkout/sessions](/api-reference/checkout/create-session) - Create a checkout session
* [GET /api/checkout/sessions](/api-reference/checkout/list-sessions) - List all sessions
* [GET /api/checkout/sessions/:id](/api-reference/checkout/get-session) - Get a session

### Refunds

* [POST /api/refunds](/api-reference/refunds/create-refund) - Create a refund
* [GET /api/refunds](/api-reference/refunds/list-refunds) - List all refunds
* [GET /api/refunds/:id](/api-reference/refunds/get-refund) - Get a refund

### Reserves

* [GET /api/reserves/config](/api-reference/reserves/get-config) - Get reserve configuration
* [GET /api/reserves/summary](/api-reference/reserves/get-summary) - Get reserve summary
* [GET /api/reserves](/api-reference/reserves/list-reserves) - List all reserves
* [GET /api/reserves/:id](/api-reference/reserves/get-reserve) - Get a reserve

### Withdrawals

* [POST /api/withdrawals](/api-reference/withdrawals/create-withdrawal) - Create a withdrawal
* [GET /api/withdrawals](/api-reference/withdrawals/list-withdrawals) - List withdrawals
* [GET /api/withdrawals/:id](/api-reference/withdrawals/get-withdrawal) - Get a withdrawal
* [POST /api/withdrawals/:id/cancel](/api-reference/withdrawals/cancel-withdrawal) - Cancel a withdrawal

### Webhooks

* [POST /api/webhooks](/api-reference/webhooks/create-endpoint) - Create webhook endpoint
* [GET /api/webhooks](/api-reference/webhooks/list-endpoints) - List webhook endpoints
* [GET /api/webhooks/:id](/api-reference/webhooks/get-endpoint) - Get webhook endpoint
* [PUT /api/webhooks/:id](/api-reference/webhooks/update-endpoint) - Update webhook endpoint
* [DELETE /api/webhooks/:id](/api-reference/webhooks/delete-endpoint) - Delete webhook endpoint
* [GET /api/webhooks/events](/api-reference/webhooks/list-events) - List webhook events
* [POST /api/webhooks/retry/:id](/api-reference/webhooks/retry-delivery) - Retry event delivery

## SDKs

Official SDKs are coming soon for:

* Node.js / TypeScript
* Python
* PHP
* Go
* Ruby

In the meantime, use the REST API directly with any HTTP client.