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; for statuses and codes see Statuses and errors.

Paths follow {{base_url}}, the API address issued to you for the sandbox or production (see Environments).

Interactive reference Download openapi.yaml

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)¶

POST{{base_url}}/api/v1/payments

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.

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

{
  "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

{
  "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¶

GET{{base_url}}/api/v1/payments/{id}

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

{
  "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)¶

GET{{base_url}}/api/v1/project

Access: signature if the project policy requires it

Responses¶

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