> For the complete documentation index, see [llms.txt](https://docs.xpayconnect.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.xpayconnect.io/documentation/eng/concepts/protocol.md).

# Protocol Overview

## Base URL

All requests are sent to:

```
https://api.xpayconnect.io
```

## Request Format

API requests are made over HTTPS using GET and POST methods.

### Required Headers

| Header             | Description                                                                |
| ------------------ | -------------------------------------------------------------------------- |
| **Content-Type**   | `application/json`                                                         |
| **client-api-key** | Merchant API key (issued by administrator)                                 |
| **x-api-key**      | SHA-256 request signature ([details](/documentation/eng/concepts/auth.md)) |

### Request Body

* **POST requests** — data is sent as JSON in the request body
* **GET requests** — parameters are passed in the query string or URL path

***

## Response Format

All responses are returned in JSON format.

### Successful order creation response

The `POST /merchant/createOrder` endpoint returns `ok: true` on success:

```json
{
    "ok": true,
    "id": "lux01993328-a828-7581-b3a9-e712a6a0e88c",
    "status": "pending"
}
```

### Successful responses for other endpoints

Reference endpoints (`/merchant/orders`, `/merchant/balance/{id}`, `/merchant/banks`, `/merchant/pool/requisites`, etc.) use the `success: true` flag and place the payload in the `data` field:

```json
{
    "success": true,
    "data": [ ... ]
}
```

### Errors

All errors are returned with `success: false` and a `message` field (error code or description). The HTTP error code is delivered in the response status:

```json
{
    "success": false,
    "message": "ORDER_AMOUNT_BELOW_MIN_LIMIT"
}
```

{% hint style="info" %}
The full list of errors and their descriptions can be found in the [Errors](/documentation/eng/reference/error-codes.md) section.
{% endhint %}

***

## Rate Limits

Public endpoints have rate limits per IP + merchant to protect the system from overload. On exceedance the API returns `429 Too Many Requests` with the body:

```json
{ "ok": false, "error": "Too many requests, slow down." }
```

| Endpoint                                                  | Limit                                                  |
| --------------------------------------------------------- | ------------------------------------------------------ |
| `GET /merchant/balance/{merchant_id}`                     | 6 requests / sec                                       |
| `GET /merchant/order/{id}`                                | 6 requests / sec                                       |
| `GET /merchant/orders`                                    | 6 requests / sec                                       |
| `GET /merchant/pool/requisites`                           | 6 requests / sec                                       |
| `GET /merchant/banks`, `GET /merchant/bank-standards`     | 6 requests / sec                                       |
| `POST /merchant/receipt/upload`                           | 6 requests / sec                                       |
| `POST /merchant/createOrder` (when `direction: "PAYOUT"`) | 1 request / 5 sec — protects against duplicate payouts |

Limits are applied per (IP, endpoint, `client-api-key`), so each merchant has its own counter. To increase the limit on `POST /merchant/createOrder` in PAYIN mode, contact your account manager.

{% hint style="info" %}
If you regularly receive `429`, use **exponential backoff**: double the delay between retries (e.g. 500ms → 1s → 2s → 4s), capped at 30 seconds. Do not retry without a delay.
{% endhint %}