API docs by Redocly

KASSA Merchant API (1.0.0)

Download OpenAPI specification:

URL: https://docs.kassa.example

Приём платежей, возвраты, платёжные ссылки, события и расчёты для мерчантов KASSA (РФ, КЗ)

Контракт Merchant API v1. Состав версии заморожен (ADR-0007): в /v1 поля и коды ответов не удаляются и не переименовываются, изменения — только совместимые и только записью в changelog. Правила:

  • Все запросы — HTTPS, JSON (UTF-8). Аутентификация — HTTP Basic: shop_id как имя пользователя, secret_key как пароль. Тестовые ключи имеют префикс test_, боевые — live_; ключ несёт регион (live_ru_…, live_kz_…).
  • Все POST-запросы, создающие или изменяющие ресурсы, требуют заголовок Idempotency-Key (принимается также Idempotence-Key). Ключ действует 24 часа. Повтор с тем же ключом и телом возвращает исходный ответ с кодом 200; с другим телом — 409 idempotency_conflict; параллельный повтор — 409 idempotency_in_progress.
  • Суммы передаются объектом amount {value, currency}, где value — строка с двумя знаками после запятой. В ответах, где отрицательное значение штатно (Balance.available, Settlement.net_amount), используется SignedAmount — та же строка со знаком минус.
  • Идентификаторы объектов — строки с префиксом типа (sh_, pay_, rf_, pl_, dsp_, evd_, evt_, whe_, po_, set_).
  • Все временные метки — ISO 8601 в UTC с суффиксом Z (например 2026-09-10T12:34:56Z).
  • Ошибки — единый формат Error с кодом из закрытого справочника ErrorCode и request_id.
  • События доставляются вебхуками с подписью X-Kassa-Signature (HMAC-SHA256 с меткой времени), см. раздел webhooks; тип вложенного объекта определяется полем data.object_type, а не префиксом id.
  • Тестовые и боевые данные не смешиваются: тестовый ключ видит только объекты с test: true (баланс тестового контура, пустые списки расчётов и споров), боевой — только боевые; чужой объект неотличим от несуществующего (404).
  • Списки — курсорная пагинация: limit (1–100, по умолчанию 20) и cursor; ответ содержит next_cursor; сортировка created_at desc.
  • Каждый ответ содержит заголовок X-Request-Id.
  • Клиенты обязаны игнорировать неизвестные поля ответов и неизвестные значения справочников: именно это позволяет расширять контракт без смены версии.
  • Операции с расширением x-stage (M2 — споры, M5 — выплаты) объявлены заранее и до наступления этапа отвечают 501 not_implemented.

payments

Платежи

Создать платёж

Коды: 400 invalid_request с parameter, 401 invalid_credentials, 403 forbidden, 409 duplicate_order_id (идентификатор существующего платежа — в description ошибки), 409 idempotency_conflict, 409 idempotency_in_progress, 422 amount_limit (пер-транзакционные min/max способа), 422 limits_exceeded (портфельные лимиты магазина и мерчанта), 422 method_unavailable, 422 payments_suspended (приём платежей магазина заморожен риском), 422 receipt_invalid, 422 shop_not_live, 429 too_many_requests с Retry-After, 503 provider_unavailable.

Authorizations:
basicAuth
header Parameters
Idempotency-Key
required
string [ 8 .. 128 ] characters

Уникальный ключ запроса (рекомендуется UUID v4). Действует 24 часа.

Request Body schema: application/json
required
required
object (Amount)
order_id
required
string [ 1 .. 128 ] characters

Идентификатор заказа у мерчанта; уникален в пределах магазина. Повтор с тем же order_id → 409 duplicate_order_id

required
object or object or object (ConfirmationRequest)
description
string <= 256 characters
capture
boolean
Default: true

true — списать сразу после авторизации; false — двухстадийная схема

object (PaymentMethodRequest)

Ограничить способ оплаты (иначе плательщик выбирает на чекауте)

object (Customer)
object (Receipt)

Чек операции. Режим фискализации задаётся магазином (Shop.receipt_mode), а не запросом: в режиме agent чек пробивает касса как агент через свой ККТ-сервис, с признаком агента и реквизитами поставщика из KYB; в режиме merchant_issues магазин фискализирует сам, объект хранится для сверки.

expires_at
string <date-time>

Срок жизни платежа (5 минут … 7 дней; по умолчанию — настройка магазина, 24 часа)

object (Metadata) <= 16 properties

Произвольные пары «ключ — строка» мерчанта: до 16 ключей, ключ ≤ 64 символов, значение ≤ 512 символов. Возвращается без изменений во всех объектах и событиях. Нарушение ограничений — 400 invalid_request с parameter: metadata. Отдельного потолка в килобайтах нет: ограничение задаётся только этой схемой.

client_ip
string <= 45 characters

IP плательщика, если платёж создаётся сервером мерчанта

Responses

Response Schema: application/json
id
required
string^pay_[0-9A-Z]{26}$
status
required
string (PaymentStatus)
Enum: "pending" "waiting_for_capture" "succeeded" "canceled"
required
object (Amount)

Сумма авторизации; при частичном списании не меняется — фактически списанное в captured_amount

order_id
required
string
created_at
required
string <date-time>
test
required
boolean
paid
required
boolean

Деньги списаны с плательщика: true только в статусе succeeded. В waiting_for_capture средства лишь заблокированы — отгружать товар по этому признаку нельзя

refundable
required
boolean

Возврат возможен прямо сейчас: статус succeeded, способ оплаты поддерживает возврат и refundable_amount > 0

required
object (Amount)

Списано с плательщика; 0.00 до списания

required
object (Amount)

Сумма подтверждённых возвратов (статус succeeded); возвраты в пути — в pending_refunds_amount

required
object (Amount)

Остаток к возврату = captured − refunded − charged_back − pending_refunds − disputed. Именно он ограничивает сумму возврата: превышение — 422 refund_exceeds_captured, в том числе когда refunded_amount = 0.00, а сумма занята чарджбэком, возвратом в пути или открытым спором

merchant_display_name
required
string <= 256 characters

Название магазина, показанное плательщику на чекауте. Формируется кассой из настроек магазина, в запросе не принимается, фиксируется при создании платежа и задним числом не меняется

object (Amount)

Списано банком по чарджбэкам

object (Amount)

Возвраты в пути: созданы, провайдером ещё не подтверждены

object (Amount)

Удержано по открытым спорам этого платежа

object (Amount)

Комиссия KASSA, зафиксированная в момент succeeded по действующему тарифу; задним числом не пересчитывается

object (Amount)

Часть комиссии, возвращённая мерчанту по возвратам; никогда не превышает fee_amount

statement_descriptor
string <= 32 characters

Строка в выписке плательщика в формате «бренд кассы + короткое имя магазина», в пределах возможностей банка. Формируется кассой, в запросе не принимается, задним числом не меняется

description
string
capture
boolean
object (Confirmation)
object (PaymentMethodData)
object (Customer)
object (ReceiptStatus)
object (CancellationDetails)
object (AuthorizationDetails)

Реквизиты авторизации для расследований и споров

object (Metadata) <= 16 properties

Произвольные пары «ключ — строка» мерчанта: до 16 ключей, ключ ≤ 64 символов, значение ≤ 512 символов. Возвращается без изменений во всех объектах и событиях. Нарушение ограничений — 400 invalid_request с parameter: metadata. Отдельного потолка в килобайтах нет: ограничение задаётся только этой схемой.

expires_at
string <date-time>
authorized_at
string <date-time>
captured_at
string <date-time>
canceled_at
string <date-time>
Response Schema: application/json
id
required
string^pay_[0-9A-Z]{26}$
status
required
string (PaymentStatus)
Enum: "pending" "waiting_for_capture" "succeeded" "canceled"
required
object (Amount)

Сумма авторизации; при частичном списании не меняется — фактически списанное в captured_amount

order_id
required
string
created_at
required
string <date-time>
test
required
boolean
paid
required
boolean

Деньги списаны с плательщика: true только в статусе succeeded. В waiting_for_capture средства лишь заблокированы — отгружать товар по этому признаку нельзя

refundable
required
boolean

Возврат возможен прямо сейчас: статус succeeded, способ оплаты поддерживает возврат и refundable_amount > 0

required
object (Amount)

Списано с плательщика; 0.00 до списания

required
object (Amount)

Сумма подтверждённых возвратов (статус succeeded); возвраты в пути — в pending_refunds_amount

required
object (Amount)

Остаток к возврату = captured − refunded − charged_back − pending_refunds − disputed. Именно он ограничивает сумму возврата: превышение — 422 refund_exceeds_captured, в том числе когда refunded_amount = 0.00, а сумма занята чарджбэком, возвратом в пути или открытым спором

merchant_display_name
required
string <= 256 characters

Название магазина, показанное плательщику на чекауте. Формируется кассой из настроек магазина, в запросе не принимается, фиксируется при создании платежа и задним числом не меняется

object (Amount)

Списано банком по чарджбэкам

object (Amount)

Возвраты в пути: созданы, провайдером ещё не подтверждены

object (Amount)

Удержано по открытым спорам этого платежа

object (Amount)

Комиссия KASSA, зафиксированная в момент succeeded по действующему тарифу; задним числом не пересчитывается

object (Amount)

Часть комиссии, возвращённая мерчанту по возвратам; никогда не превышает fee_amount

statement_descriptor
string <= 32 characters

Строка в выписке плательщика в формате «бренд кассы + короткое имя магазина», в пределах возможностей банка. Формируется кассой, в запросе не принимается, задним числом не меняется

description
string
capture
boolean
object (Confirmation)
object (PaymentMethodData)
object (Customer)
object (ReceiptStatus)
object (CancellationDetails)
object (AuthorizationDetails)

Реквизиты авторизации для расследований и споров

object (Metadata) <= 16 properties

Произвольные пары «ключ — строка» мерчанта: до 16 ключей, ключ ≤ 64 символов, значение ≤ 512 символов. Возвращается без изменений во всех объектах и событиях. Нарушение ограничений — 400 invalid_request с parameter: metadata. Отдельного потолка в килобайтах нет: ограничение задаётся только этой схемой.

expires_at
string <date-time>
authorized_at
string <date-time>
captured_at
string <date-time>
canceled_at
string <date-time>

Request samples

Content type
application/json
{
  • "amount": {
    • "value": "1500.00",
    • "currency": "RUB"
    },
  • "order_id": "ORD-10042",
  • "description": "Заказ №10042",
  • "capture": true,
  • "confirmation": {},
  • "customer": {
    • "email": "buyer@example.com"
    },
  • "receipt": {
    • "profile": "ru",
    • "customer": {
      },
    • "items": [
      ]
    },
  • "metadata": {
    • "cart_id": "c-77"
    }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "status": "pending",
  • "paid": true,
  • "refundable": true,
  • "test": true,
  • "amount": {
    • "value": "string",
    • "currency": "RUB"
    },
  • "captured_amount": {
    • "value": "string",
    • "currency": "RUB"
    },
  • "refunded_amount": {
    • "value": "string",
    • "currency": "RUB"
    },
  • "charged_back_amount": {
    • "value": "string",
    • "currency": "RUB"
    },
  • "pending_refunds_amount": {
    • "value": "string",
    • "currency": "RUB"
    },
  • "disputed_amount": {
    • "value": "string",
    • "currency": "RUB"
    },
  • "refundable_amount": {
    • "value": "string",
    • "currency": "RUB"
    },
  • "fee_amount": {
    • "value": "string",
    • "currency": "RUB"
    },
  • "fee_refunded_amount": {
    • "value": "string",
    • "currency": "RUB"
    },
  • "merchant_display_name": "string",
  • "statement_descriptor": "string",
  • "order_id": "string",
  • "description": "string",
  • "capture": true,
  • "confirmation": {},
  • "payment_method": {
    • "type": "bank_card",
    • "card": {
      },
    • "sbp": {
      },
    • "saved": true,
    • "id": "string"
    },
  • "customer": {
    • "email": "user@example.com",
    • "phone": "string",
    • "full_name": "string",
    • "tax_id": "string",
    • "ip": "string"
    },
  • "receipt_status": {
    • "status": "pending",
    • "fiscal_document_number": "string",
    • "fiscal_storage_number": "string",
    • "ofd_receipt_url": "http://example.com",
    • "error": "string"
    },
  • "cancellation_details": {
    • "party": "merchant",
    • "reason": "expired_on_confirmation",
    • "provider_code": "string"
    },
  • "authorization_details": {
    • "rrn": "string",
    • "auth_code": "string",
    • "three_d_secure": {
      }
    },
  • "metadata": {
    • "property1": "string",
    • "property2": "string"
    },
  • "created_at": "2019-08-24T14:15:22Z",
  • "expires_at": "2019-08-24T14:15:22Z",
  • "authorized_at": "2019-08-24T14:15:22Z",
  • "captured_at": "2019-08-24T14:15:22Z",
  • "canceled_at": "2019-08-24T14:15:22Z"
}

Список платежей магазина

Authorizations:
basicAuth
query Parameters
limit
integer [ 1 .. 100 ]
Default: 20
cursor
string
order_id
string <= 128 characters
status
string (PaymentStatus)
Enum: "pending" "waiting_for_capture" "succeeded" "canceled"
created_at_gte
string <date-time>
created_at_lt
string <date-time>

Responses

Response Schema: application/json
required
Array of objects (Payment)
next_cursor
required
string or null

Курсор следующей страницы; null — страниц больше нет

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ],
  • "next_cursor": "string"
}

Получить платёж

Authorizations:
basicAuth
path Parameters
payment_id
required
string (PaymentId) ^pay_[0-9A-Z]{26}$

Идентификатор платежа. Схема применяется там, где инлайновый тип породил бы безымянную модель в кодогенерации (элементы массивов, параметры пути); в скалярных полях объектов паттерн остаётся записанным на месте

Responses

Response Schema: application/json
id
required
string^pay_[0-9A-Z]{26}$
status
required
string (PaymentStatus)
Enum: "pending" "waiting_for_capture" "succeeded" "canceled"
required
object (Amount)

Сумма авторизации; при частичном списании не меняется — фактически списанное в captured_amount

order_id
required
string
created_at
required
string <date-time>
test
required
boolean
paid
required
boolean

Деньги списаны с плательщика: true только в статусе succeeded. В waiting_for_capture средства лишь заблокированы — отгружать товар по этому признаку нельзя

refundable
required
boolean

Возврат возможен прямо сейчас: статус succeeded, способ оплаты поддерживает возврат и refundable_amount > 0

required
object (Amount)

Списано с плательщика; 0.00 до списания

required
object (Amount)

Сумма подтверждённых возвратов (статус succeeded); возвраты в пути — в pending_refunds_amount

required
object (Amount)

Остаток к возврату = captured − refunded − charged_back − pending_refunds − disputed. Именно он ограничивает сумму возврата: превышение — 422 refund_exceeds_captured, в том числе когда refunded_amount = 0.00, а сумма занята чарджбэком, возвратом в пути или открытым спором

merchant_display_name
required
string <= 256 characters

Название магазина, показанное плательщику на чекауте. Формируется кассой из настроек магазина, в запросе не принимается, фиксируется при создании платежа и задним числом не меняется

object (Amount)

Списано банком по чарджбэкам

object (Amount)

Возвраты в пути: созданы, провайдером ещё не подтверждены

object (Amount)

Удержано по открытым спорам этого платежа

object (Amount)

Комиссия KASSA, зафиксированная в момент succeeded по действующему тарифу; задним числом не пересчитывается

object (Amount)

Часть комиссии, возвращённая мерчанту по возвратам; никогда не превышает fee_amount

statement_descriptor
string <= 32 characters

Строка в выписке плательщика в формате «бренд кассы + короткое имя магазина», в пределах возможностей банка. Формируется кассой, в запросе не принимается, задним числом не меняется

description
string
capture
boolean
object (Confirmation)
object (PaymentMethodData)
object (Customer)
object (ReceiptStatus)
object (CancellationDetails)
object (AuthorizationDetails)

Реквизиты авторизации для расследований и споров

object (Metadata) <= 16 properties

Произвольные пары «ключ — строка» мерчанта: до 16 ключей, ключ ≤ 64 символов, значение ≤ 512 символов. Возвращается без изменений во всех объектах и событиях. Нарушение ограничений — 400 invalid_request с parameter: metadata. Отдельного потолка в килобайтах нет: ограничение задаётся только этой схемой.

expires_at
string <date-time>
authorized_at
string <date-time>
captured_at
string <date-time>
canceled_at
string <date-time>

Response samples

Content type
application/json
{
  • "id": "string",
  • "status": "pending",
  • "paid": true,
  • "refundable": true,
  • "test": true,
  • "amount": {
    • "value": "string",
    • "currency": "RUB"
    },
  • "captured_amount": {
    • "value": "string",
    • "currency": "RUB"
    },
  • "refunded_amount": {
    • "value": "string",
    • "currency": "RUB"
    },
  • "charged_back_amount": {
    • "value": "string",
    • "currency": "RUB"
    },
  • "pending_refunds_amount": {
    • "value": "string",
    • "currency": "RUB"
    },
  • "disputed_amount": {
    • "value": "string",
    • "currency": "RUB"
    },
  • "refundable_amount": {
    • "value": "string",
    • "currency": "RUB"
    },
  • "fee_amount": {
    • "value": "string",
    • "currency": "RUB"
    },
  • "fee_refunded_amount": {
    • "value": "string",
    • "currency": "RUB"
    },
  • "merchant_display_name": "string",
  • "statement_descriptor": "string",
  • "order_id": "string",
  • "description": "string",
  • "capture": true,
  • "confirmation": {},
  • "payment_method": {
    • "type": "bank_card",
    • "card": {
      },
    • "sbp": {
      },
    • "saved": true,
    • "id": "string"
    },
  • "customer": {
    • "email": "user@example.com",
    • "phone": "string",
    • "full_name": "string",
    • "tax_id": "string",
    • "ip": "string"
    },
  • "receipt_status": {
    • "status": "pending",
    • "fiscal_document_number": "string",
    • "fiscal_storage_number": "string",
    • "ofd_receipt_url": "http://example.com",
    • "error": "string"
    },
  • "cancellation_details": {
    • "party": "merchant",
    • "reason": "expired_on_confirmation",
    • "provider_code": "string"
    },
  • "authorization_details": {
    • "rrn": "string",
    • "auth_code": "string",
    • "three_d_secure": {
      }
    },
  • "metadata": {
    • "property1": "string",
    • "property2": "string"
    },
  • "created_at": "2019-08-24T14:15:22Z",
  • "expires_at": "2019-08-24T14:15:22Z",
  • "authorized_at": "2019-08-24T14:15:22Z",
  • "captured_at": "2019-08-24T14:15:22Z",
  • "canceled_at": "2019-08-24T14:15:22Z"
}

Списать авторизованный платёж (полностью или частично)

Доступно только в статусе waiting_for_capture. Пустое тело — полное списание. При частичном списании остаток авторизации отменяется. Повтор с тем же Idempotency-Key и телом возвращает исходный ответ (200); с другим телом — 409 idempotency_conflict.

Authorizations:
basicAuth
path Parameters
payment_id
required
string (PaymentId) ^pay_[0-9A-Z]{26}$

Идентификатор платежа. Схема применяется там, где инлайновый тип породил бы безымянную модель в кодогенерации (элементы массивов, параметры пути); в скалярных полях объектов паттерн остаётся записанным на месте

header Parameters
Idempotency-Key
required
string [ 8 .. 128 ] characters

Уникальный ключ запроса (рекомендуется UUID v4). Действует 24 часа.

Request Body schema: application/json
optional
object (Amount)
object (Receipt)

Чек операции. Режим фискализации задаётся магазином (Shop.receipt_mode), а не запросом: в режиме agent чек пробивает касса как агент через свой ККТ-сервис, с признаком агента и реквизитами поставщика из KYB; в режиме merchant_issues магазин фискализирует сам, объект хранится для сверки.

Responses

Response Schema: application/json
id
required
string^pay_[0-9A-Z]{26}$
status
required
string (PaymentStatus)
Enum: "pending" "waiting_for_capture" "succeeded" "canceled"
required
object (Amount)

Сумма авторизации; при частичном списании не меняется — фактически списанное в captured_amount

order_id
required
string
created_at
required
string <date-time>
test
required
boolean
paid
required
boolean

Деньги списаны с плательщика: true только в статусе succeeded. В waiting_for_capture средства лишь заблокированы — отгружать товар по этому признаку нельзя

refundable
required
boolean

Возврат возможен прямо сейчас: статус succeeded, способ оплаты поддерживает возврат и refundable_amount > 0

required
object (Amount)

Списано с плательщика; 0.00 до списания

required
object (Amount)

Сумма подтверждённых возвратов (статус succeeded); возвраты в пути — в pending_refunds_amount

required
object (Amount)

Остаток к возврату = captured − refunded − charged_back − pending_refunds − disputed. Именно он ограничивает сумму возврата: превышение — 422 refund_exceeds_captured, в том числе когда refunded_amount = 0.00, а сумма занята чарджбэком, возвратом в пути или открытым спором

merchant_display_name
required
string <= 256 characters

Название магазина, показанное плательщику на чекауте. Формируется кассой из настроек магазина, в запросе не принимается, фиксируется при создании платежа и задним числом не меняется

object (Amount)

Списано банком по чарджбэкам

object (Amount)

Возвраты в пути: созданы, провайдером ещё не подтверждены

object (Amount)

Удержано по открытым спорам этого платежа

object (Amount)

Комиссия KASSA, зафиксированная в момент succeeded по действующему тарифу; задним числом не пересчитывается

object (Amount)

Часть комиссии, возвращённая мерчанту по возвратам; никогда не превышает fee_amount

statement_descriptor
string <= 32 characters

Строка в выписке плательщика в формате «бренд кассы + короткое имя магазина», в пределах возможностей банка. Формируется кассой, в запросе не принимается, задним числом не меняется

description
string
capture
boolean
object (Confirmation)
object (PaymentMethodData)
object (Customer)
object (ReceiptStatus)
object (CancellationDetails)
object (AuthorizationDetails)

Реквизиты авторизации для расследований и споров

object (Metadata) <= 16 properties

Произвольные пары «ключ — строка» мерчанта: до 16 ключей, ключ ≤ 64 символов, значение ≤ 512 символов. Возвращается без изменений во всех объектах и событиях. Нарушение ограничений — 400 invalid_request с parameter: metadata. Отдельного потолка в килобайтах нет: ограничение задаётся только этой схемой.

expires_at
string <date-time>
authorized_at
string <date-time>
captured_at
string <date-time>
canceled_at
string <date-time>

Request samples

Content type
application/json
{
  • "amount": {
    • "value": "string",
    • "currency": "RUB"
    },
  • "receipt": {
    • "profile": "ru",
    • "customer": {
      },
    • "tax_system_code": 0,
    • "items": [
      ]
    }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "status": "pending",
  • "paid": true,
  • "refundable": true,
  • "test": true,
  • "amount": {
    • "value": "string",
    • "currency": "RUB"
    },
  • "captured_amount": {
    • "value": "string",
    • "currency": "RUB"
    },
  • "refunded_amount": {
    • "value": "string",
    • "currency": "RUB"
    },
  • "charged_back_amount": {
    • "value": "string",
    • "currency": "RUB"
    },
  • "pending_refunds_amount": {
    • "value": "string",
    • "currency": "RUB"
    },
  • "disputed_amount": {
    • "value": "string",
    • "currency": "RUB"
    },
  • "refundable_amount": {
    • "value": "string",
    • "currency": "RUB"
    },
  • "fee_amount": {
    • "value": "string",
    • "currency": "RUB"
    },
  • "fee_refunded_amount": {
    • "value": "string",
    • "currency": "RUB"
    },
  • "merchant_display_name": "string",
  • "statement_descriptor": "string",
  • "order_id": "string",
  • "description": "string",
  • "capture": true,
  • "confirmation": {},
  • "payment_method": {
    • "type": "bank_card",
    • "card": {
      },
    • "sbp": {
      },
    • "saved": true,
    • "id": "string"
    },
  • "customer": {
    • "email": "user@example.com",
    • "phone": "string",
    • "full_name": "string",
    • "tax_id": "string",
    • "ip": "string"
    },
  • "receipt_status": {
    • "status": "pending",
    • "fiscal_document_number": "string",
    • "fiscal_storage_number": "string",
    • "ofd_receipt_url": "http://example.com",
    • "error": "string"
    },
  • "cancellation_details": {
    • "party": "merchant",
    • "reason": "expired_on_confirmation",
    • "provider_code": "string"
    },
  • "authorization_details": {
    • "rrn": "string",
    • "auth_code": "string",
    • "three_d_secure": {
      }
    },
  • "metadata": {
    • "property1": "string",
    • "property2": "string"
    },
  • "created_at": "2019-08-24T14:15:22Z",
  • "expires_at": "2019-08-24T14:15:22Z",
  • "authorized_at": "2019-08-24T14:15:22Z",
  • "captured_at": "2019-08-24T14:15:22Z",
  • "canceled_at": "2019-08-24T14:15:22Z"
}

Отменить платёж

В статусе pending — закрывает чекаут; в статусе waiting_for_capture — снимает авторизацию (void). Для succeeded используйте возвраты. Повтор с тем же Idempotency-Key и телом возвращает исходный ответ (200); с другим телом — 409 idempotency_conflict.

Authorizations:
basicAuth
path Parameters
payment_id
required
string (PaymentId) ^pay_[0-9A-Z]{26}$

Идентификатор платежа. Схема применяется там, где инлайновый тип породил бы безымянную модель в кодогенерации (элементы массивов, параметры пути); в скалярных полях объектов паттерн остаётся записанным на месте

header Parameters
Idempotency-Key
required
string [ 8 .. 128 ] characters

Уникальный ключ запроса (рекомендуется UUID v4). Действует 24 часа.

Responses

Response Schema: application/json
id
required
string^pay_[0-9A-Z]{26}$
status
required
string (PaymentStatus)
Enum: "pending" "waiting_for_capture" "succeeded" "canceled"
required
object (Amount)

Сумма авторизации; при частичном списании не меняется — фактически списанное в captured_amount

order_id
required
string
created_at
required
string <date-time>
test
required
boolean
paid
required
boolean

Деньги списаны с плательщика: true только в статусе succeeded. В waiting_for_capture средства лишь заблокированы — отгружать товар по этому признаку нельзя

refundable
required
boolean

Возврат возможен прямо сейчас: статус succeeded, способ оплаты поддерживает возврат и refundable_amount > 0

required
object (Amount)

Списано с плательщика; 0.00 до списания

required
object (Amount)

Сумма подтверждённых возвратов (статус succeeded); возвраты в пути — в pending_refunds_amount

required
object (Amount)

Остаток к возврату = captured − refunded − charged_back − pending_refunds − disputed. Именно он ограничивает сумму возврата: превышение — 422 refund_exceeds_captured, в том числе когда refunded_amount = 0.00, а сумма занята чарджбэком, возвратом в пути или открытым спором

merchant_display_name
required
string <= 256 characters

Название магазина, показанное плательщику на чекауте. Формируется кассой из настроек магазина, в запросе не принимается, фиксируется при создании платежа и задним числом не меняется

object (Amount)

Списано банком по чарджбэкам

object (Amount)

Возвраты в пути: созданы, провайдером ещё не подтверждены

object (Amount)

Удержано по открытым спорам этого платежа

object (Amount)

Комиссия KASSA, зафиксированная в момент succeeded по действующему тарифу; задним числом не пересчитывается

object (Amount)

Часть комиссии, возвращённая мерчанту по возвратам; никогда не превышает fee_amount

statement_descriptor
string <= 32 characters

Строка в выписке плательщика в формате «бренд кассы + короткое имя магазина», в пределах возможностей банка. Формируется кассой, в запросе не принимается, задним числом не меняется

description
string
capture
boolean
object (Confirmation)
object (PaymentMethodData)
object (Customer)
object (ReceiptStatus)
object (CancellationDetails)
object (AuthorizationDetails)

Реквизиты авторизации для расследований и споров

object (Metadata) <= 16 properties

Произвольные пары «ключ — строка» мерчанта: до 16 ключей, ключ ≤ 64 символов, значение ≤ 512 символов. Возвращается без изменений во всех объектах и событиях. Нарушение ограничений — 400 invalid_request с parameter: metadata. Отдельного потолка в килобайтах нет: ограничение задаётся только этой схемой.

expires_at
string <date-time>
authorized_at
string <date-time>
captured_at
string <date-time>
canceled_at
string <date-time>

Response samples

Content type
application/json
{
  • "id": "string",
  • "status": "pending",
  • "paid": true,
  • "refundable": true,
  • "test": true,
  • "amount": {
    • "value": "string",
    • "currency": "RUB"
    },
  • "captured_amount": {
    • "value": "string",
    • "currency": "RUB"
    },
  • "refunded_amount": {
    • "value": "string",
    • "currency": "RUB"
    },
  • "charged_back_amount": {
    • "value": "string",
    • "currency": "RUB"
    },
  • "pending_refunds_amount": {
    • "value": "string",
    • "currency": "RUB"
    },
  • "disputed_amount": {
    • "value": "string",
    • "currency": "RUB"
    },
  • "refundable_amount": {
    • "value": "string",
    • "currency": "RUB"
    },
  • "fee_amount": {
    • "value": "string",
    • "currency": "RUB"
    },
  • "fee_refunded_amount": {
    • "value": "string",
    • "currency": "RUB"
    },
  • "merchant_display_name": "string",
  • "statement_descriptor": "string",
  • "order_id": "string",
  • "description": "string",
  • "capture": true,
  • "confirmation": {},
  • "payment_method": {
    • "type": "bank_card",
    • "card": {
      },
    • "sbp": {
      },
    • "saved": true,
    • "id": "string"
    },
  • "customer": {
    • "email": "user@example.com",
    • "phone": "string",
    • "full_name": "string",
    • "tax_id": "string",
    • "ip": "string"
    },
  • "receipt_status": {
    • "status": "pending",
    • "fiscal_document_number": "string",
    • "fiscal_storage_number": "string",
    • "ofd_receipt_url": "http://example.com",
    • "error": "string"
    },
  • "cancellation_details": {
    • "party": "merchant",
    • "reason": "expired_on_confirmation",
    • "provider_code": "string"
    },
  • "authorization_details": {
    • "rrn": "string",
    • "auth_code": "string",
    • "three_d_secure": {
      }
    },
  • "metadata": {
    • "property1": "string",
    • "property2": "string"
    },
  • "created_at": "2019-08-24T14:15:22Z",
  • "expires_at": "2019-08-24T14:15:22Z",
  • "authorized_at": "2019-08-24T14:15:22Z",
  • "captured_at": "2019-08-24T14:15:22Z",
  • "canceled_at": "2019-08-24T14:15:22Z"
}

refunds

Возвраты

Создать возврат

Возврат по успешному платежу. Сумму ограничивает Payment.refundable_amount (= captured − refunded − charged_back − pending_refunds − disputed): при открытом споре удержанная сумма недоступна к возврату, даже если refunded_amount равен 0.00. В модели A возврат оплачивается из денег мерчанта: если его не покрывают вместе реверс ещё не выпущенной части этого платежа и положительный остаток Balance.available — 422 insufficient_merchant_balance (резерв и депозит на возврат по инициативе мерчанта не расходуются). Коды: 400 invalid_request с parameter, 401 invalid_credentials, 404 not_found (платёж другого магазина), 409 idempotency_conflict, 409 idempotency_in_progress, 422 invalid_state (платёж не в succeeded), 422 refund_exceeds_captured, 422 insufficient_merchant_balance, 422 receipt_invalid, 429 too_many_requests, 503 provider_unavailable.

Authorizations:
basicAuth
header Parameters
Idempotency-Key
required
string [ 8 .. 128 ] characters

Уникальный ключ запроса (рекомендуется UUID v4). Действует 24 часа.

Request Body schema: application/json
required
payment_id
required
string^pay_[0-9A-Z]{26}$
required
object (Amount)
reason
string <= 256 characters
object (Receipt)

Обязателен при частичном возврате, если чек формирует KASSA

object (Metadata) <= 16 properties

Произвольные пары «ключ — строка» мерчанта: до 16 ключей, ключ ≤ 64 символов, значение ≤ 512 символов. Возвращается без изменений во всех объектах и событиях. Нарушение ограничений — 400 invalid_request с parameter: metadata. Отдельного потолка в килобайтах нет: ограничение задаётся только этой схемой.

Responses

Response Schema: application/json
id
required
string^rf_[0-9A-Z]{26}$
payment_id
required
string^pay_[0-9A-Z]{26}$
status
required
string (RefundStatus)
Enum: "pending" "succeeded" "canceled"
required
object (Amount)
created_at
required
string <date-time>
test
required
boolean

Возврат тестового контура

order_id
string <= 128 characters

Идентификатор заказа возвращаемого платежа у мерчанта. Копируется из Payment.order_id при создании возврата и задним числом не меняется; в запросе не принимается. Позволяет сопоставить события refund.succeeded и refund.canceled с заказом тем же полем, что и события платежа

reason
string
object (ReceiptStatus)
object (CancellationDetails)
object (Metadata) <= 16 properties

Произвольные пары «ключ — строка» мерчанта: до 16 ключей, ключ ≤ 64 символов, значение ≤ 512 символов. Возвращается без изменений во всех объектах и событиях. Нарушение ограничений — 400 invalid_request с parameter: metadata. Отдельного потолка в килобайтах нет: ограничение задаётся только этой схемой.

succeeded_at
string <date-time>
Response Schema: application/json
id
required
string^rf_[0-9A-Z]{26}$
payment_id
required
string^pay_[0-9A-Z]{26}$
status
required
string (RefundStatus)
Enum: "pending" "succeeded" "canceled"
required
object (Amount)
created_at
required
string <date-time>
test
required
boolean

Возврат тестового контура

order_id
string <= 128 characters

Идентификатор заказа возвращаемого платежа у мерчанта. Копируется из Payment.order_id при создании возврата и задним числом не меняется; в запросе не принимается. Позволяет сопоставить события refund.succeeded и refund.canceled с заказом тем же полем, что и события платежа

reason
string
object (ReceiptStatus)
object (CancellationDetails)
object (Metadata) <= 16 properties

Произвольные пары «ключ — строка» мерчанта: до 16 ключей, ключ ≤ 64 символов, значение ≤ 512 символов. Возвращается без изменений во всех объектах и событиях. Нарушение ограничений — 400 invalid_request с parameter: metadata. Отдельного потолка в килобайтах нет: ограничение задаётся только этой схемой.

succeeded_at
string <date-time>

Request samples

Content type
application/json
{
  • "payment_id": "string",
  • "amount": {
    • "value": "string",
    • "currency": "RUB"
    },
  • "reason": "string",
  • "receipt": {
    • "profile": "ru",
    • "customer": {
      },
    • "tax_system_code": 0,
    • "items": [
      ]
    },
  • "metadata": {
    • "property1": "string",
    • "property2": "string"
    }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "payment_id": "string",
  • "order_id": "string",
  • "status": "pending",
  • "amount": {
    • "value": "string",
    • "currency": "RUB"
    },
  • "reason": "string",
  • "receipt_status": {
    • "status": "pending",
    • "fiscal_document_number": "string",
    • "fiscal_storage_number": "string",
    • "ofd_receipt_url": "http://example.com",
    • "error": "string"
    },
  • "cancellation_details": {
    • "party": "merchant",
    • "reason": "expired_on_confirmation",
    • "provider_code": "string"
    },
  • "metadata": {
    • "property1": "string",
    • "property2": "string"
    },
  • "test": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "succeeded_at": "2019-08-24T14:15:22Z"
}

Список возвратов

Authorizations:
basicAuth
query Parameters
limit
integer [ 1 .. 100 ]
Default: 20
cursor
string
payment_id
string
status
string (RefundStatus)
Enum: "pending" "succeeded" "canceled"

Responses

Response Schema: application/json
required
Array of objects (Refund)
next_cursor
required
string or null

Курсор следующей страницы; null — страниц больше нет

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ],
  • "next_cursor": "string"
}

Получить возврат

Authorizations:
basicAuth
path Parameters
refund_id
required
string^rf_[0-9A-Z]{26}$

Responses

Response Schema: application/json
id
required
string^rf_[0-9A-Z]{26}$
payment_id
required
string^pay_[0-9A-Z]{26}$
status
required
string (RefundStatus)
Enum: "pending" "succeeded" "canceled"
required
object (Amount)
created_at
required
string <date-time>
test
required
boolean

Возврат тестового контура

order_id
string <= 128 characters

Идентификатор заказа возвращаемого платежа у мерчанта. Копируется из Payment.order_id при создании возврата и задним числом не меняется; в запросе не принимается. Позволяет сопоставить события refund.succeeded и refund.canceled с заказом тем же полем, что и события платежа

reason
string
object (ReceiptStatus)
object (CancellationDetails)
object (Metadata) <= 16 properties

Произвольные пары «ключ — строка» мерчанта: до 16 ключей, ключ ≤ 64 символов, значение ≤ 512 символов. Возвращается без изменений во всех объектах и событиях. Нарушение ограничений — 400 invalid_request с parameter: metadata. Отдельного потолка в килобайтах нет: ограничение задаётся только этой схемой.

succeeded_at
string <date-time>

Response samples

Content type
application/json
{
  • "id": "string",
  • "payment_id": "string",
  • "order_id": "string",
  • "status": "pending",
  • "amount": {
    • "value": "string",
    • "currency": "RUB"
    },
  • "reason": "string",
  • "receipt_status": {
    • "status": "pending",
    • "fiscal_document_number": "string",
    • "fiscal_storage_number": "string",
    • "ofd_receipt_url": "http://example.com",
    • "error": "string"
    },
  • "cancellation_details": {
    • "party": "merchant",
    • "reason": "expired_on_confirmation",
    • "provider_code": "string"
    },
  • "metadata": {
    • "property1": "string",
    • "property2": "string"
    },
  • "test": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "succeeded_at": "2019-08-24T14:15:22Z"
}

disputes

Споры и чарджбэки (этап M2)

Список споров по платежам магазина

Споры — в скоупе магазина: возвращаются споры по платежам того магазина, чьим ключом сделан запрос; чужой спор неотличим от несуществующего (404). Сортировка — created_at desc. По тестовому ключу возвращаются данные тестового контура: список по умолчанию пуст, боевые споры недоступны. Коды: 401 invalid_credentials, 403 forbidden, 429 too_many_requests, 501 not_implemented (до этапа M2).

stage: M2
Authorizations:
basicAuth
query Parameters
limit
integer [ 1 .. 100 ]
Default: 20
cursor
string
payment_id
string^pay_[0-9A-Z]{26}$
status
string (DisputeStatus)
Enum: "opened" "evidence_required" "submitted" "won" "lost" "expired"

Автомат спора: opened → evidence_required (запрошены доказательства) → submitted (оператор отправил в банк) → won | lost; evidence_required → expired при наступлении evidence_deadline_at. Загрузка доказательств разрешена в opened и evidence_required и статус спора не меняет.

kind
string (DisputeKind)
Enum: "chargeback" "retrieval" "complaint"

chargeback — чарджбэк (списание банком); retrieval — запрос документов без списания; complaint — жалоба плательщика через банк

created_at_gte
string <date-time>
created_at_lt
string <date-time>

Responses

Response Schema: application/json
required
Array of objects (Dispute)
next_cursor
required
string or null

Курсор следующей страницы; null — страниц больше нет

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ],
  • "next_cursor": "string"
}

Получить спор

Коды: 401 invalid_credentials, 404 not_found (чужой или несуществующий спор), 429 too_many_requests, 501 not_implemented (до этапа M2).

stage: M2
Authorizations:
basicAuth
path Parameters
dispute_id
required
string^dsp_[0-9A-Z]{26}$

Responses

Response Schema: application/json
id
required
string^dsp_[0-9A-Z]{26}$
payment_id
required
string^pay_[0-9A-Z]{26}$
kind
required
string (DisputeKind)
Enum: "chargeback" "retrieval" "complaint"

chargeback — чарджбэк (списание банком); retrieval — запрос документов без списания; complaint — жалоба плательщика через банк

status
required
string (DisputeStatus)
Enum: "opened" "evidence_required" "submitted" "won" "lost" "expired"

Автомат спора: opened → evidence_required (запрошены доказательства) → submitted (оператор отправил в банк) → won | lost; evidence_required → expired при наступлении evidence_deadline_at. Загрузка доказательств разрешена в opened и evidence_required и статус спора не меняет.

required
object (Amount)

Оспариваемая сумма в валюте платежа

created_at
required
string <date-time>
test
required
boolean

Спор тестового контура; по тестовому ключу боевые споры недоступны

order_id
string

Идентификатор заказа оспариваемого платежа у мерчанта

object (Amount)

Штраф банка по чарджбэку, перевыставляемый мерчанту

object (Amount)

Комиссия кассы за обработку чарджбэка сверх штрафа банка

reason_code
string <= 32 characters

Код причины платёжной системы или банка

evidence_deadline_at
string <date-time>

Крайний срок загрузки доказательств; после него загрузка → 409 evidence_deadline_passed

Array of objects (DisputeEvidence) <= 10 items
resolution
string <= 512 characters

Решение банка или платёжной системы в терминах мерчанта

closed_at
string <date-time>

Момент перехода в won, lost или expired

Response samples

Content type
application/json
{
  • "id": "string",
  • "payment_id": "string",
  • "order_id": "string",
  • "kind": "chargeback",
  • "status": "opened",
  • "amount": {
    • "value": "string",
    • "currency": "RUB"
    },
  • "bank_fine_amount": {
    • "value": "string",
    • "currency": "RUB"
    },
  • "kassa_fee_amount": {
    • "value": "string",
    • "currency": "RUB"
    },
  • "reason_code": "string",
  • "evidence_deadline_at": "2019-08-24T14:15:22Z",
  • "evidence": [
    • {
      }
    ],
  • "resolution": "string",
  • "closed_at": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z",
  • "test": true
}

Получить ссылку для загрузки файла доказательства

Шаг 1 передачи файлов (API остаётся JSON-only): в ответе upload_url, по которому файл загружается методом PUT напрямую в хранилище до upload_expires_at; затем file_id передаётся в POST /v1/disputes/{dispute_id}/evidence. Лимиты: типы application/pdf, image/jpeg, image/png, не более 10 МБ на файл, не более 10 файлов на спор. Загрузка доказательств не меняет статус спора: в банк доказательства отправляет оператор. Коды: 400 invalid_request с parameter (тип, размер, имя файла), 401 invalid_credentials, 404 not_found (чужой или несуществующий спор), 409 evidence_deadline_passed (после evidence_deadline_at, в том числе когда спор уже в статусе expired — приоритет у этого кода), 409 idempotency_conflict, 409 idempotency_in_progress, 422 invalid_state (только статусы submitted, won, lost), 429 too_many_requests, 501 not_implemented (до этапа M2).

stage: M2
Authorizations:
basicAuth
path Parameters
dispute_id
required
string^dsp_[0-9A-Z]{26}$
header Parameters
Idempotency-Key
required
string [ 8 .. 128 ] characters

Уникальный ключ запроса (рекомендуется UUID v4). Действует 24 часа.

Request Body schema: application/json
required
file_name
required
string [ 1 .. 255 ] characters
content_type
required
string (EvidenceContentType)
Enum: "application/pdf" "image/jpeg" "image/png"

Допустимые типы файлов доказательств (TZ §12.3)

size_bytes
required
integer [ 1 .. 10485760 ]

Размер файла в байтах, не более 10 МБ

Responses

Response Schema: application/json
file_id
required
string^evd_[0-9A-Z]{26}$
upload_url
required
string <uri> <= 2048 characters
upload_expires_at
required
string <date-time>
Response Schema: application/json
file_id
required
string^evd_[0-9A-Z]{26}$
upload_url
required
string <uri> <= 2048 characters
upload_expires_at
required
string <date-time>

Request samples

Content type
application/json
{
  • "file_name": "string",
  • "content_type": "application/pdf",
  • "size_bytes": 1
}

Response samples

Content type
application/json
{
  • "file_id": "string",
  • "upload_url": "http://example.com",
  • "upload_expires_at": "2019-08-24T14:15:22Z"
}

Приложить доказательства к спору

Шаг 2 передачи файлов: список ранее полученных file_id и комментарий (≤ 4096 символов). Загрузка не меняет статус спора — отправку в банк выполняет оператор кассы. Коды: 400 invalid_request с parameter (неизвестный file_id, более 10 файлов, длина комментария), 401 invalid_credentials, 404 not_found, 409 evidence_deadline_passed (приоритетный код после дедлайна), 409 idempotency_conflict, 409 idempotency_in_progress, 422 invalid_state (submitted, won, lost), 429 too_many_requests, 501 not_implemented (до этапа M2).

stage: M2
Authorizations:
basicAuth
path Parameters
dispute_id
required
string^dsp_[0-9A-Z]{26}$
header Parameters
Idempotency-Key
required
string [ 8 .. 128 ] characters

Уникальный ключ запроса (рекомендуется UUID v4). Действует 24 часа.

Request Body schema: application/json
required
file_ids
required
Array of strings (EvidenceFileId) [ 1 .. 10 ] items [ items^evd_[0-9A-Z]{26}$ ]

Идентификаторы ранее загруженных файлов; всего на спор не более 10 файлов

comment
string <= 4096 characters

Пояснение мерчанта для оператора и банка

Responses

Response Schema: application/json
id
required
string^dsp_[0-9A-Z]{26}$
payment_id
required
string^pay_[0-9A-Z]{26}$
kind
required
string (DisputeKind)
Enum: "chargeback" "retrieval" "complaint"

chargeback — чарджбэк (списание банком); retrieval — запрос документов без списания; complaint — жалоба плательщика через банк

status
required
string (DisputeStatus)
Enum: "opened" "evidence_required" "submitted" "won" "lost" "expired"

Автомат спора: opened → evidence_required (запрошены доказательства) → submitted (оператор отправил в банк) → won | lost; evidence_required → expired при наступлении evidence_deadline_at. Загрузка доказательств разрешена в opened и evidence_required и статус спора не меняет.

required
object (Amount)

Оспариваемая сумма в валюте платежа

created_at
required
string <date-time>
test
required
boolean

Спор тестового контура; по тестовому ключу боевые споры недоступны

order_id
string

Идентификатор заказа оспариваемого платежа у мерчанта

object (Amount)

Штраф банка по чарджбэку, перевыставляемый мерчанту

object (Amount)

Комиссия кассы за обработку чарджбэка сверх штрафа банка

reason_code
string <= 32 characters

Код причины платёжной системы или банка

evidence_deadline_at
string <date-time>

Крайний срок загрузки доказательств; после него загрузка → 409 evidence_deadline_passed

Array of objects (DisputeEvidence) <= 10 items
resolution
string <= 512 characters

Решение банка или платёжной системы в терминах мерчанта

closed_at
string <date-time>

Момент перехода в won, lost или expired

Response Schema: application/json
id
required
string^dsp_[0-9A-Z]{26}$
payment_id
required
string^pay_[0-9A-Z]{26}$
kind
required
string (DisputeKind)
Enum: "chargeback" "retrieval" "complaint"

chargeback — чарджбэк (списание банком); retrieval — запрос документов без списания; complaint — жалоба плательщика через банк

status
required
string (DisputeStatus)
Enum: "opened" "evidence_required" "submitted" "won" "lost" "expired"

Автомат спора: opened → evidence_required (запрошены доказательства) → submitted (оператор отправил в банк) → won | lost; evidence_required → expired при наступлении evidence_deadline_at. Загрузка доказательств разрешена в opened и evidence_required и статус спора не меняет.

required
object (Amount)

Оспариваемая сумма в валюте платежа

created_at
required
string <date-time>
test
required
boolean

Спор тестового контура; по тестовому ключу боевые споры недоступны

order_id
string

Идентификатор заказа оспариваемого платежа у мерчанта

object (Amount)

Штраф банка по чарджбэку, перевыставляемый мерчанту

object (Amount)

Комиссия кассы за обработку чарджбэка сверх штрафа банка

reason_code
string <= 32 characters

Код причины платёжной системы или банка

evidence_deadline_at
string <date-time>

Крайний срок загрузки доказательств; после него загрузка → 409 evidence_deadline_passed

Array of objects (DisputeEvidence) <= 10 items
resolution
string <= 512 characters

Решение банка или платёжной системы в терминах мерчанта

closed_at
string <date-time>

Момент перехода в won, lost или expired

Request samples

Content type
application/json
{
  • "file_ids": [
    • "string"
    ],
  • "comment": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "payment_id": "string",
  • "order_id": "string",
  • "kind": "chargeback",
  • "status": "opened",
  • "amount": {
    • "value": "string",
    • "currency": "RUB"
    },
  • "bank_fine_amount": {
    • "value": "string",
    • "currency": "RUB"
    },
  • "kassa_fee_amount": {
    • "value": "string",
    • "currency": "RUB"
    },
  • "reason_code": "string",
  • "evidence_deadline_at": "2019-08-24T14:15:22Z",
  • "evidence": [
    • {
      }
    ],
  • "resolution": "string",
  • "closed_at": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z",
  • "test": true
}

methods

Способы оплаты

Доступные магазину способы оплаты с ограничениями

Authorizations:
basicAuth
query Parameters
currency
string (Currency)
Enum: "RUB" "KZT" "USD" "EUR"

Responses

Response Schema: application/json
required
Array of objects (PaymentMethodInfo)

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

events

События и их доставка

Доставка события на адрес мерчанта Webhook

POST JSON на каждый активный адрес магазина, подписанный на тип события. Заголовки: X-Kassa-Event-Id, X-Kassa-Signature: t=<unix>,v1=<hex(hmac_sha256(secret, "<t>.<body>"))>, Content-Type: application/json, User-Agent: Kassa-Webhooks/1.0. body — сырые байты тела запроса, пересериализация JSON перед проверкой подписи ломает сравнение; t — секунды Unix. В период ротации секрета (24 часа) заголовок несёт две подписи (t=<unix>,v1=<hex>,v1=<hex>): доставка считается подлинной при совпадении любой из них. Мерчант отвечает любым 2xx в течение 10 секунд; иначе повторы: 1 м, 5 м, 15 м, 1 ч, 4 ч, 12 ч, 24 ч, 48 ч, 72 ч. Проверка подписи: отклонять, если |now − t| > 300 с или ни одна подпись не совпала. Обработка должна быть идемпотентной по id события, а тип объекта — разбираться по data.object_type. Порядок событий не гарантируется — сверяйте created_at и перезапрашивайте объект по API.

Request Body schema: application/json
required
id
required
string^evt_[0-9A-Z]{26}$
type
required
string (EventType)
Enum: "payment.waiting_for_capture" "payment.succeeded" "payment.canceled" "payment.authorize_request" "refund.succeeded" "refund.canceled" "payment_link.paid" "payout.succeeded" "payout.canceled" "settlement.paid" "settlement.frozen" "settlement.unfrozen" "dispute.opened" "dispute.evidence_required" "dispute.closed"

Типы событий. Перечень расширяется только записью в changelog с датой; существующие значения не переименовываются и не удаляются. payment.authorize_request — синхронная предпроверка (см. webhooks), а не асинхронное событие с повторами.

created_at
required
string <date-time>
test
required
boolean

Событие тестового контура; тестовые и боевые события не смешиваются

required
object or object or object or object or object or object or object (EventData)
object (EventDelivery)

Сводка доставок (только в GET /events)

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "type": "payment.waiting_for_capture",
  • "created_at": "2019-08-24T14:15:22Z",
  • "test": true,
  • "data": {
    • "object_type": "payment",
    • "object": {
      }
    },
  • "delivery": {
    • "status": "pending",
    • "attempts": 0,
    • "last_response_code": 0,
    • "last_attempt_at": "2019-08-24T14:15:22Z"
    }
}

Синхронная предпроверка (опция магазина) Webhook

Вызывается до создания попытки у провайдера, если для магазина включена предпроверка (Shop.capabilities.authorize_request_webhook). Таймаут 5 с, повторов нет. Запрос подписывается тем же заголовком X-Kassa-Signature, что и обычные события, — проверяйте подпись перед принятием решения. Ответ {"decision": "allow"} или {"decision": "deny", "reason": "..."}; отсутствие ответа трактуется по настройке магазина (по умолчанию — deny), платёж отменяется с cancellation_details.reason = authorize_request_denied. Ключ этого раздела (authorize-request) — имя вебхука в документации; тип события остаётся payment.authorize_request.

Request Body schema: application/json
required
id
required
string^evt_[0-9A-Z]{26}$
type
required
string (EventType)
Enum: "payment.waiting_for_capture" "payment.succeeded" "payment.canceled" "payment.authorize_request" "refund.succeeded" "refund.canceled" "payment_link.paid" "payout.succeeded" "payout.canceled" "settlement.paid" "settlement.frozen" "settlement.unfrozen" "dispute.opened" "dispute.evidence_required" "dispute.closed"

Типы событий. Перечень расширяется только записью в changelog с датой; существующие значения не переименовываются и не удаляются. payment.authorize_request — синхронная предпроверка (см. webhooks), а не асинхронное событие с повторами.

created_at
required
string <date-time>
test
required
boolean

Событие тестового контура; тестовые и боевые события не смешиваются

required
object or object or object or object or object or object or object (EventData)
object (EventDelivery)

Сводка доставок (только в GET /events)

Responses

Response Schema: application/json
decision
required
string
Enum: "allow" "deny"
reason
string <= 256 characters

Request samples

Content type
application/json
{
  • "id": "string",
  • "type": "payment.waiting_for_capture",
  • "created_at": "2019-08-24T14:15:22Z",
  • "test": true,
  • "data": {
    • "object_type": "payment",
    • "object": {
      }
    },
  • "delivery": {
    • "status": "pending",
    • "attempts": 0,
    • "last_response_code": 0,
    • "last_attempt_at": "2019-08-24T14:15:22Z"
    }
}

Response samples

Content type
application/json
{
  • "decision": "allow",
  • "reason": "string"
}

События магазина (для сверки и повторной обработки)

Тип объекта в data определяется полем data.object_type, а не префиксом id. События уровня мерчанта (settlement.frozen, settlement.unfrozen) создаются по одной записи на каждый магазин мерчанта: у каждой свой id, объект внутри одинаковый — дедупликация по id остаётся детерминированной. Сортировка — created_at desc. Ретеншен событий — 1 год.

Authorizations:
basicAuth
query Parameters
limit
integer [ 1 .. 100 ]
Default: 20
cursor
string
type
string (EventType)
Enum: "payment.waiting_for_capture" "payment.succeeded" "payment.canceled" "payment.authorize_request" "refund.succeeded" "refund.canceled" "payment_link.paid" "payout.succeeded" "payout.canceled" "settlement.paid" "settlement.frozen" "settlement.unfrozen" "dispute.opened" "dispute.evidence_required" "dispute.closed"

Типы событий. Перечень расширяется только записью в changelog с датой; существующие значения не переименовываются и не удаляются. payment.authorize_request — синхронная предпроверка (см. webhooks), а не асинхронное событие с повторами.

object_id
string <= 40 characters
created_at_gte
string <date-time>
created_at_lt
string <date-time>

Responses

Response Schema: application/json
required
Array of objects (Event)
next_cursor
required
string or null

Курсор следующей страницы; null — страниц больше нет

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ],
  • "next_cursor": "string"
}

Получить событие

Authorizations:
basicAuth
path Parameters
event_id
required
string^evt_[0-9A-Z]{26}$

Responses

Response Schema: application/json
id
required
string^evt_[0-9A-Z]{26}$
type
required
string (EventType)
Enum: "payment.waiting_for_capture" "payment.succeeded" "payment.canceled" "payment.authorize_request" "refund.succeeded" "refund.canceled" "payment_link.paid" "payout.succeeded" "payout.canceled" "settlement.paid" "settlement.frozen" "settlement.unfrozen" "dispute.opened" "dispute.evidence_required" "dispute.closed"

Типы событий. Перечень расширяется только записью в changelog с датой; существующие значения не переименовываются и не удаляются. payment.authorize_request — синхронная предпроверка (см. webhooks), а не асинхронное событие с повторами.

created_at
required
string <date-time>
test
required
boolean

Событие тестового контура; тестовые и боевые события не смешиваются

required
object or object or object or object or object or object or object (EventData)
object (EventDelivery)

Сводка доставок (только в GET /events)

Response samples

Content type
application/json
{
  • "id": "string",
  • "type": "payment.waiting_for_capture",
  • "created_at": "2019-08-24T14:15:22Z",
  • "test": true,
  • "data": {
    • "object_type": "payment",
    • "object": {
      }
    },
  • "delivery": {
    • "status": "pending",
    • "attempts": 0,
    • "last_response_code": 0,
    • "last_attempt_at": "2019-08-24T14:15:22Z"
    }
}

Повторно доставить событие на все активные адреса

Authorizations:
basicAuth
path Parameters
event_id
required
string^evt_[0-9A-Z]{26}$
header Parameters
Idempotency-Key
required
string [ 8 .. 128 ] characters

Уникальный ключ запроса (рекомендуется UUID v4). Действует 24 часа.

Responses

Response samples

Content type
application/json
{
  • "type": "error",
  • "code": "invalid_request",
  • "description": "string",
  • "parameter": "string",
  • "request_id": "string"
}

webhook-endpoints

Адреса для вебхуков

Создать адрес для вебхуков

Authorizations:
basicAuth
header Parameters
Idempotency-Key
required
string [ 8 .. 128 ] characters

Уникальный ключ запроса (рекомендуется UUID v4). Действует 24 часа.

Request Body schema: application/json
required
url
required
string <uri> <= 2048 characters ^https://

Только https, публичный адрес; приватные диапазоны и редиректы не поддерживаются — KASSA не следует 3xx при доставке

events
required
Array of strings (EventType) non-empty
Items Enum: "payment.waiting_for_capture" "payment.succeeded" "payment.canceled" "payment.authorize_request" "refund.succeeded" "refund.canceled" "payment_link.paid" "payout.succeeded" "payout.canceled" "settlement.paid" "settlement.frozen" "settlement.unfrozen" "dispute.opened" "dispute.evidence_required" "dispute.closed"
description
string <= 128 characters

Responses

Response Schema: application/json
id
required
string^whe_[0-9A-Z]{26}$
url
required
string <uri>
events
required
Array of strings (EventType)
Items Enum: "payment.waiting_for_capture" "payment.succeeded" "payment.canceled" "payment.authorize_request" "refund.succeeded" "refund.canceled" "payment_link.paid" "payout.succeeded" "payout.canceled" "settlement.paid" "settlement.frozen" "settlement.unfrozen" "dispute.opened" "dispute.evidence_required" "dispute.closed"
status
required
string (WebhookEndpointStatus)
Enum: "active" "disabled" "failing"

Состояние адреса: failing — доставки подряд неуспешны, адрес близок к отключению

created_at
required
string <date-time>
secret
required
string

Секрет подписи; показывается один раз

description
string
Response Schema: application/json
id
required
string^whe_[0-9A-Z]{26}$
url
required
string <uri>
events
required
Array of strings (EventType)
Items Enum: "payment.waiting_for_capture" "payment.succeeded" "payment.canceled" "payment.authorize_request" "refund.succeeded" "refund.canceled" "payment_link.paid" "payout.succeeded" "payout.canceled" "settlement.paid" "settlement.frozen" "settlement.unfrozen" "dispute.opened" "dispute.evidence_required" "dispute.closed"
status
required
string (WebhookEndpointStatus)
Enum: "active" "disabled" "failing"

Состояние адреса: failing — доставки подряд неуспешны, адрес близок к отключению

created_at
required
string <date-time>
secret
required
string

Секрет подписи; показывается один раз

description
string

Request samples

Content type
application/json
{
  • "url": "http://example.com",
  • "events": [
    • "payment.waiting_for_capture"
    ],
  • "description": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "url": "http://example.com",
  • "events": [
    • "payment.waiting_for_capture"
    ],
  • "status": "active",
  • "description": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "secret": "string"
}

Список адресов для вебхуков

Authorizations:
basicAuth

Responses

Response Schema: application/json
required
Array of objects (WebhookEndpoint)

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Получить адрес для вебхуков

Authorizations:
basicAuth
path Parameters
endpoint_id
required
string^whe_[0-9A-Z]{26}$

Responses

Response Schema: application/json
id
required
string^whe_[0-9A-Z]{26}$
url
required
string <uri>
events
required
Array of strings (EventType)
Items Enum: "payment.waiting_for_capture" "payment.succeeded" "payment.canceled" "payment.authorize_request" "refund.succeeded" "refund.canceled" "payment_link.paid" "payout.succeeded" "payout.canceled" "settlement.paid" "settlement.frozen" "settlement.unfrozen" "dispute.opened" "dispute.evidence_required" "dispute.closed"
status
required
string (WebhookEndpointStatus)
Enum: "active" "disabled" "failing"

Состояние адреса: failing — доставки подряд неуспешны, адрес близок к отключению

created_at
required
string <date-time>
description
string

Response samples

Content type
application/json
{
  • "id": "string",
  • "url": "http://example.com",
  • "events": [
    • "payment.waiting_for_capture"
    ],
  • "status": "active",
  • "description": "string",
  • "created_at": "2019-08-24T14:15:22Z"
}

Изменить адрес для вебхуков или ротировать секрет

При rotate_secret: true в ответе присутствует поле secret — новый секрет подписи, показываемый один раз; прежний секрет действует ещё 24 часа. Повтор с тем же Idempotency-Key и телом возвращает исходный ответ (200); с другим телом — 409 idempotency_conflict.

Authorizations:
basicAuth
path Parameters
endpoint_id
required
string^whe_[0-9A-Z]{26}$
header Parameters
Idempotency-Key
required
string [ 8 .. 128 ] characters

Уникальный ключ запроса (рекомендуется UUID v4). Действует 24 часа.

Request Body schema: application/json
required
url
string <uri> <= 2048 characters ^https://

Только https, публичный адрес; приватные диапазоны и редиректы не поддерживаются — KASSA не следует 3xx при доставке

events
Array of strings (EventType)
Items Enum: "payment.waiting_for_capture" "payment.succeeded" "payment.canceled" "payment.authorize_request" "refund.succeeded" "refund.canceled" "payment_link.paid" "payout.succeeded" "payout.canceled" "settlement.paid" "settlement.frozen" "settlement.unfrozen" "dispute.opened" "dispute.evidence_required" "dispute.closed"
status
string (WebhookEndpointDesiredStatus)
Enum: "active" "disabled"

Состояние адреса, которое мерчант выставляет сам; failing выставляет только KASSA

rotate_secret
boolean

Сгенерировать новый секрет; старый действует 24 часа

Responses

Response Schema: application/json
id
required
string^whe_[0-9A-Z]{26}$
url
required
string <uri>
events
required
Array of strings (EventType)
Items Enum: "payment.waiting_for_capture" "payment.succeeded" "payment.canceled" "payment.authorize_request" "refund.succeeded" "refund.canceled" "payment_link.paid" "payout.succeeded" "payout.canceled" "settlement.paid" "settlement.frozen" "settlement.unfrozen" "dispute.opened" "dispute.evidence_required" "dispute.closed"
status
required
string (WebhookEndpointStatus)
Enum: "active" "disabled" "failing"

Состояние адреса: failing — доставки подряд неуспешны, адрес близок к отключению

created_at
required
string <date-time>
description
string
secret
string

Новый секрет подписи. Присутствует только в ответе на rotate_secret: true и показывается один раз; прежний секрет действует ещё 24 часа, в течение которых заголовок X-Kassa-Signature несёт две подписи v1

Request samples

Content type
application/json
{
  • "url": "http://example.com",
  • "events": [
    • "payment.waiting_for_capture"
    ],
  • "status": "active",
  • "rotate_secret": true
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "url": "http://example.com",
  • "events": [
    • "payment.waiting_for_capture"
    ],
  • "status": "active",
  • "description": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "secret": "string"
}

Удалить адрес для вебхуков

Authorizations:
basicAuth
path Parameters
endpoint_id
required
string^whe_[0-9A-Z]{26}$

Responses

Response samples

Content type
application/json
{
  • "type": "error",
  • "code": "invalid_request",
  • "description": "string",
  • "parameter": "string",
  • "request_id": "string"
}

settlements

Расчёты и выписки

Расчёты (выписки) мерчанта по периодам

Значения уровня мерчанта: по ключу любого его магазина возвращаются одинаковые строки. Расчёт ведётся в разрезе валюты — у мультивалютного мерчанта период даёт по строке на валюту. Сортировка — created_at desc. По тестовому ключу список расчётов тестового контура (по умолчанию пуст).

Authorizations:
basicAuth
query Parameters
limit
integer [ 1 .. 100 ]
Default: 20
cursor
string
period_from
string <date>

Расчёты, период которых начинается не раньше этой даты (включительно)

period_to
string <date>

Расчёты, период которых заканчивается не позже этой даты (включительно)

currency
string (Currency)
Enum: "RUB" "KZT" "USD" "EUR"
status
string (SettlementState)
Enum: "draft" "approved" "sent" "paid" "failed"

Автомат реестра выплат: draft → approved → sent → paid | failed

Responses

Response Schema: application/json
required
Array of objects (Settlement)
next_cursor
required
string or null

Курсор следующей страницы; null — страниц больше нет

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ],
  • "next_cursor": "string"
}

Получить расчёт

Значения уровня мерчанта: по ключу любого его магазина возвращается одинаковый расчёт. По тестовому ключу боевые расчёты недоступны (404 not_found).

Authorizations:
basicAuth
path Parameters
settlement_id
required
string^set_[0-9A-Z]{26}$

Responses

Response Schema: application/json
id
required
string^set_[0-9A-Z]{26}$
status
required
string (SettlementState)
Enum: "draft" "approved" "sent" "paid" "failed"

Автомат реестра выплат: draft → approved → sent → paid | failed

period_from
required
string <date>

Первый день периода включительно, календарь региона

period_to
required
string <date>

Последний день периода включительно, календарь региона

currency
required
string (Currency)
Enum: "RUB" "KZT" "USD" "EUR"
required
object (Amount)

Оборот успешных платежей периода

required
object (Amount)

Комиссия KASSA, зафиксированная в момент события и не пересчитываемая задним числом

required
object (Amount)
required
object (SignedAmount)

К выплате. Может быть отрицательным, если возвраты, чарджбэки и удержания превысили оборот периода

test
required
boolean

Расчёт тестового контура; по тестовому ключу боевые расчёты недоступны

object (Amount)
object (Amount)

Удержано в rolling reserve за период

object (Amount)

Возвращено из rolling reserve по истечении срока партий

object (Amount)

Удержано в депозит из выплаты

object (Amount)

Штрафы банка по чарджбэкам, перевыставленные мерчанту

object (Amount)

Комиссии кассы за обработку чарджбэков

object (Amount)

Удержания по спорам, затронувшие период

settlement_delay_days
integer >= 0

Задержка отбора сумм в реестр, действовавшая при формировании

paid_at
string <date-time>
report_url
string <uri>

Ссылка на реестр (CSV/XLSX), действует 24 часа

Response samples

Content type
application/json
{
  • "id": "string",
  • "status": "draft",
  • "period_from": "2019-08-24",
  • "period_to": "2019-08-24",
  • "currency": "RUB",
  • "gross_amount": {
    • "value": "string",
    • "currency": "RUB"
    },
  • "fee_amount": {
    • "value": "string",
    • "currency": "RUB"
    },
  • "refunds_amount": {
    • "value": "string",
    • "currency": "RUB"
    },
  • "chargebacks_amount": {
    • "value": "string",
    • "currency": "RUB"
    },
  • "reserve_held_amount": {
    • "value": "string",
    • "currency": "RUB"
    },
  • "reserve_released_amount": {
    • "value": "string",
    • "currency": "RUB"
    },
  • "deposit_withheld_amount": {
    • "value": "string",
    • "currency": "RUB"
    },
  • "bank_fines_amount": {
    • "value": "string",
    • "currency": "RUB"
    },
  • "chargeback_fees_amount": {
    • "value": "string",
    • "currency": "RUB"
    },
  • "disputes_amount": {
    • "value": "string",
    • "currency": "RUB"
    },
  • "settlement_delay_days": 0,
  • "net_amount": {
    • "value": "string",
    • "currency": "RUB"
    },
  • "paid_at": "2019-08-24T14:15:22Z",
  • "test": true,
  • "report_url": "http://example.com"
}

balance

Балансы (агентская модель)

Балансы мерчанта по валютам

Значения уровня мерчанта: по ключу любого его магазина возвращаются одинаковые. Одна запись на валюту. available уже уменьшен на резерв, возвраты в пути и удержания по спорам — повторно вычитать их при оценке ближайшей выплаты нельзя, для этого есть payable. По тестовому ключу возвращается баланс тестового контура (по умолчанию нулевой); боевые суммы по тестовому ключу недоступны. Коды: 401 invalid_credentials, 403 forbidden, 429 too_many_requests, 503 provider_unavailable.

Authorizations:
basicAuth

Responses

Response Schema: application/json
required
Array of objects (Balance)

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

payouts

Выплаты (этап M5)

Создать выплату (этап M5)

stage: M5
Authorizations:
basicAuth
header Parameters
Idempotency-Key
required
string [ 8 .. 128 ] characters

Уникальный ключ запроса (рекомендуется UUID v4). Действует 24 часа.

Request Body schema: application/json
required
required
object (Amount)
required
object or object or object (PayoutDestination)
description
string <= 256 characters
order_id
string <= 128 characters
object (Metadata) <= 16 properties

Произвольные пары «ключ — строка» мерчанта: до 16 ключей, ключ ≤ 64 символов, значение ≤ 512 символов. Возвращается без изменений во всех объектах и событиях. Нарушение ограничений — 400 invalid_request с parameter: metadata. Отдельного потолка в килобайтах нет: ограничение задаётся только этой схемой.

Responses

Response Schema: application/json
id
required
string^po_[0-9A-Z]{26}$
status
required
string (PayoutStatus)
Enum: "pending" "processing" "succeeded" "canceled"

Автомат выплаты: pending → processing → succeeded | canceled

required
object (Amount)
created_at
required
string <date-time>
test
required
boolean
object (Amount)
destination_masked
string
order_id
string
object (CancellationDetails)
object (Metadata) <= 16 properties

Произвольные пары «ключ — строка» мерчанта: до 16 ключей, ключ ≤ 64 символов, значение ≤ 512 символов. Возвращается без изменений во всех объектах и событиях. Нарушение ограничений — 400 invalid_request с parameter: metadata. Отдельного потолка в килобайтах нет: ограничение задаётся только этой схемой.

succeeded_at
string <date-time>
Response Schema: application/json
id
required
string^po_[0-9A-Z]{26}$
status
required
string (PayoutStatus)
Enum: "pending" "processing" "succeeded" "canceled"

Автомат выплаты: pending → processing → succeeded | canceled

required
object (Amount)
created_at
required
string <date-time>
test
required
boolean
object (Amount)
destination_masked
string
order_id
string
object (CancellationDetails)
object (Metadata) <= 16 properties

Произвольные пары «ключ — строка» мерчанта: до 16 ключей, ключ ≤ 64 символов, значение ≤ 512 символов. Возвращается без изменений во всех объектах и событиях. Нарушение ограничений — 400 invalid_request с parameter: metadata. Отдельного потолка в килобайтах нет: ограничение задаётся только этой схемой.

succeeded_at
string <date-time>

Request samples

Content type
application/json
{
  • "amount": {
    • "value": "string",
    • "currency": "RUB"
    },
  • "destination": {
    • "type": "card_token",
    • "card_token": "string"
    },
  • "description": "string",
  • "order_id": "string",
  • "metadata": {
    • "property1": "string",
    • "property2": "string"
    }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "status": "pending",
  • "amount": {
    • "value": "string",
    • "currency": "RUB"
    },
  • "fee_amount": {
    • "value": "string",
    • "currency": "RUB"
    },
  • "destination_masked": "string",
  • "order_id": "string",
  • "cancellation_details": {
    • "party": "merchant",
    • "reason": "expired_on_confirmation",
    • "provider_code": "string"
    },
  • "metadata": {
    • "property1": "string",
    • "property2": "string"
    },
  • "test": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "succeeded_at": "2019-08-24T14:15:22Z"
}

Список выплат

stage: M5
Authorizations:
basicAuth
query Parameters
limit
integer [ 1 .. 100 ]
Default: 20
cursor
string

Responses

Response Schema: application/json
required
Array of objects (Payout)
next_cursor
required
string or null

Курсор следующей страницы; null — страниц больше нет

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ],
  • "next_cursor": "string"
}

Получить выплату

stage: M5
Authorizations:
basicAuth
path Parameters
payout_id
required
string^po_[0-9A-Z]{26}$

Responses

Response Schema: application/json
id
required
string^po_[0-9A-Z]{26}$
status
required
string (PayoutStatus)
Enum: "pending" "processing" "succeeded" "canceled"

Автомат выплаты: pending → processing → succeeded | canceled

required
object (Amount)
created_at
required
string <date-time>
test
required
boolean
object (Amount)
destination_masked
string
order_id
string
object (CancellationDetails)
object (Metadata) <= 16 properties

Произвольные пары «ключ — строка» мерчанта: до 16 ключей, ключ ≤ 64 символов, значение ≤ 512 символов. Возвращается без изменений во всех объектах и событиях. Нарушение ограничений — 400 invalid_request с parameter: metadata. Отдельного потолка в килобайтах нет: ограничение задаётся только этой схемой.

succeeded_at
string <date-time>

Response samples

Content type
application/json
{
  • "id": "string",
  • "status": "pending",
  • "amount": {
    • "value": "string",
    • "currency": "RUB"
    },
  • "fee_amount": {
    • "value": "string",
    • "currency": "RUB"
    },
  • "destination_masked": "string",
  • "order_id": "string",
  • "cancellation_details": {
    • "party": "merchant",
    • "reason": "expired_on_confirmation",
    • "provider_code": "string"
    },
  • "metadata": {
    • "property1": "string",
    • "property2": "string"
    },
  • "test": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "succeeded_at": "2019-08-24T14:15:22Z"
}

shop

Информация о магазине

Текущий магазин, режим, регион, доступные возможности

Authorizations:
basicAuth

Responses

Response Schema: application/json
id
required
string^sh_[0-9A-Z]{26}$
name
required
string

Название магазина; оно же показывается плательщику и возвращается в Payment.merchant_display_name

region
required
string (Region)
Enum: "ru" "kz"
test
required
boolean
default_currency
required
string (Currency)
Enum: "RUB" "KZT" "USD" "EUR"
settlement_model
required
string (SettlementModel)
Enum: "agent" "technology"

Модель расчётов; производная от настройки юрлица-эквайера региона, мерчантом не меняется. По умолчанию agent: получатель платежа — касса, мерчант — субмерчант

receipt_mode
required
string (ReceiptMode)
Enum: "agent" "merchant_issues" "none"

Режим чеков: agent — чек пробивает касса как агент через свой ККТ-сервис с реквизитами поставщика из KYB; merchant_issues — магазин фискализирует сам своей ККТ; none — чек не требуется по закону региона. Меняется только оператором с указанием основания и записью в аудит

required
object (ShopCapabilities)

Возможности, доступные магазину; выключенная возможность — отказ 422 при попытке ею воспользоваться

required
object (ShopSettlement)

Расчёты мерчанта: политика резерва по валютам и состояние выплат. Значения уровня мерчанта — одинаковы по ключу любого его магазина. Удержанные суммы отдаются в Balance.reserve и Balance.deposit по валютам

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "region": "ru",
  • "test": true,
  • "default_currency": "RUB",
  • "settlement_model": "agent",
  • "receipt_mode": "agent",
  • "settlement": {
    • "reserve": [
      ],
    • "status": {
      }
    },
  • "capabilities": {
    • "two_stage": true,
    • "partial_capture": true,
    • "partial_refund": true,
    • "receipts": true,
    • "payouts": true,
    • "authorize_request_webhook": true
    }
}

test

Только для тестовых ключей

Сымитировать исход платежа (только тестовые ключи)

Authorizations:
basicAuth
path Parameters
payment_id
required
string (PaymentId) ^pay_[0-9A-Z]{26}$

Идентификатор платежа. Схема применяется там, где инлайновый тип породил бы безымянную модель в кодогенерации (элементы массивов, параметры пути); в скалярных полях объектов паттерн остаётся записанным на месте

header Parameters
Idempotency-Key
required
string [ 8 .. 128 ] characters

Уникальный ключ запроса (рекомендуется UUID v4). Действует 24 часа.

Request Body schema: application/json
required
outcome
required
string
Enum: "succeed" "authorize" "decline" "expire" "three_ds_fail" "provider_timeout" "late_webhook" "duplicate_webhook"
delay_seconds
integer [ 0 .. 300 ]

Responses

Request samples

Content type
application/json
{
  • "outcome": "succeed",
  • "delay_seconds": 0
}

Response samples

Content type
application/json
{
  • "type": "error",
  • "code": "invalid_request",
  • "description": "string",
  • "parameter": "string",
  • "request_id": "string"
}