# API reference

Every merchant API method: path, access, request fields, responses and examples. The page is
generated from the OpenAPI spec, so it matches what the server checks. For the end-to-end
flow see the [quickstart](quickstart.md); for statuses and codes see
[Statuses and errors](statuses.md).

Paths follow `{{base_url}}`, the API address issued to you for the sandbox or production
(see [Environments](index.md#environments)).

<a class="md-button md-button--primary" href="../../openapi/">Interactive reference</a>
<a class="md-button" href="../../openapi/openapi.yaml" download>Download openapi.yaml</a>

!!! warning "Temporary spec"
    These are the main methods from a temporary spec. The full spec will come from the backend
    repository, and this page will rebuild from it automatically.

## Create a payment (SBP or card) { #createPayment }

<div class="pp-endpoint"><span class="pp-method pp-method--post">POST</span><code><span class="pp-endpoint__base">{{base_url}}</span>/api/v1/payments</code></div>

Creates a pay-in and synchronously picks requisites. Idempotent by
`merchant_payment_id`: the same id with the same request returns `200` and the stored
payment; the same id with a different request returns `409 payment_idempotency_conflict`.
A `201` may already carry `status: error` with `error_code` when no requisites were issued; no callback follows
for it. Strict JSON: an unknown field returns `400 bad_request`. The payment lifetime is a project
setting (15 minutes by default) and is not part of the request. Signature is always
required. Recommended client timeout: at least 15 seconds.

**Access:** scope `payments:create` · signature required

Signing headers `Signature-Input`, `Signature`, `Content-Digest`, `X-Request-ID`, `X-Request-Nonce` — see [Request signing](signing.md).

### Request body

| Field | Type | Req. | Description |
| --- | --- | --- | --- |
| `merchant_payment_id` | string | yes | Your order id, unique per project; the idempotency key. 1–64 chars `A-Za-z0-9._:-`. |
| `amount` | number \| string | yes | Major currency units, > 0, up to 6 decimals: `3400` or `"3400.50"`. A string avoids rounding errors. |
| `payment_method` | string: `sbp`, `card_transfer` | yes | `sbp` — SBP transfer, `card_transfer` — transfer to a card. |
| `currency` | string | no | Currency code. Default `RUB`. |
| `geo_code` | string | no | Country, 2 letters. Default `RU`. |
| `bank_code` | string | no | The payer's bank, a code from the bank catalog (`sber`, `tinkoff`, `ozon`); not a BIC. Empty — any bank. |
| `is_intrabank` | boolean | no | Transfer within one bank only. Default `false`. |
| `callback_url` | string, uri | no | HTTPS address for this payment's callback, public host. Otherwise the project address is used. |

**Example request**

```json
{
  "merchant_payment_id": "order-42",
  "amount": 3400,
  "payment_method": "sbp",
  "bank_code": "sber",
  "callback_url": "https://merchant.example/callbacks"
}
```

### Responses

| Code | Meaning |
| --- | --- |
| `201` | Payment created |
| `200` | Idempotent repeat, the stored payment is returned |
| `400` | Invalid JSON or unknown field (`bad_request`), invalid payment fields (`invalid_payment`) |
| `401` | Error |
| `403` | Error |
| `409` | Error |
| `413` | Error |
| `422` | Payment not accepted (not covered, no rate, not routable) |
| `429` | Error |
| `500` | Error |
| `503` | Error |

**Example response**

```json
{
  "id": "3f1c2b9e-6a8d-4c4b-9a71-2c7f5d1e0a42",
  "merchant_payment_id": "order-42",
  "flow": "runtime_live",
  "status": "processing",
  "amount": 3400,
  "initial_amount": 3400,
  "currency": "RUB",
  "geo_code": "RU",
  "payment_method": "sbp",
  "bank_code": "sber",
  "is_intrabank": false,
  "callback_url": "https://merchant.example/callbacks",
  "is_test": false,
  "merchant_information": {
    "course": 100.0,
    "rate": 11.0,
    "amount_usdt": "34.0000",
    "amount_rate": "3026.0000",
    "amount_usdt_rate": "30.2600"
  },
  "requisite": "+79991234567",
  "holder_name": "Иван Петров",
  "created_at": "2026-09-29T09:30:00Z",
  "updated_at": "2026-09-29T09:30:01Z"
}
```


## Read a payment { #getPayment }

<div class="pp-endpoint"><span class="pp-method pp-method--get">GET</span><code><span class="pp-endpoint__base">{{base_url}}</span>/api/v1/payments/{id}</code></div>

Returns the payment in the same shape as the create response. Signature is required only when the project policy has `signature_required`.

**Access:** scope `payments:read` · signature if the project policy requires it

### Path parameters

| Parameter | Type | Req. | Description |
| --- | --- | --- | --- |
| `id` | string, uuid | yes | Payment `id` returned on create. |

### Responses

| Code | Meaning |
| --- | --- |
| `200` | Payment |
| `401` | Error |
| `403` | Error |
| `404` | Error |
| `429` | Error |

**Example response**

```json
{
  "id": "3f1c2b9e-6a8d-4c4b-9a71-2c7f5d1e0a42",
  "merchant_payment_id": "order-42",
  "flow": "runtime_live",
  "status": "processing",
  "amount": 3400,
  "initial_amount": 3400,
  "currency": "RUB",
  "geo_code": "RU",
  "payment_method": "sbp",
  "bank_code": "sber",
  "is_intrabank": false,
  "callback_url": "https://merchant.example/callbacks",
  "is_test": false,
  "merchant_information": {
    "course": 100.0,
    "rate": 11.0,
    "amount_usdt": "34.0000",
    "amount_rate": "3026.0000",
    "amount_usdt_rate": "30.2600"
  },
  "requisite": "+79991234567",
  "holder_name": "Иван Петров",
  "created_at": "2026-09-29T09:30:00Z",
  "updated_at": "2026-09-29T09:30:01Z"
}
```


## Who am I (token check) { #getProject }

<div class="pp-endpoint"><span class="pp-method pp-method--get">GET</span><code><span class="pp-endpoint__base">{{base_url}}</span>/api/v1/project</code></div>



**Access:** signature if the project policy requires it

### Responses

| Code | Meaning |
| --- | --- |
| `200` | Project of the token |
| `401` | Error |