Списания
Списание с привязанной карты, подтверждение и статусы
Откуда система знает, с какой карты списывать
Из поля card — идентификатора карты, который вы получили при привязке
и сохранили у себя рядом со своим пользователем. Больше ничего передавать
не нужно: ни телефон, ни имя, ни номер карты.
Платформа находит карту, проверяет, что она принадлежит вашему продукту и активна, достаёт токен банка и отправляет списание. В банк уходят только токен, сумма и идентификатор операции.
Разбор всей цепочки — в разделе «Как это устроено».
Списание
Сумма — в тийинах, целым числом. Карта должна быть в статусе ACTIVE. Кода
из СМС клиент не вводит: согласие он дал при привязке.
Создание и списание — один вызов. Разбивать его надвое имело бы смысл там, где между шагами человек вводит карту; здесь между ними не происходит ничего.
В metadata положите свои идентификаторы: они вернутся во всех ответах
и помогут связать платёж с заказом.
/subscribe/v1/chargescurl -X POST https://api.assalam.uz/subscribe/v1/charges \
-H "Authorization: Bearer sk_test_..." \
-H "Idempotency-Key: order-1024" \
-H "Content-Type: application/json" \
-d '{
"amount": 5000000,
"card": "cmsr…",
"description": "Полис ОСАГО",
"metadata": {"orderId": "A-1024"}
}'{
"id": "cmsr1a2b",
"object": "payment_intent",
"amount": 5000000,
"fee": 0,
"currency": "UZS",
"status": "SUCCEEDED",
"rail": "openbank",
"description": "Полис ОСАГО",
"metadata": {"orderId": "A-1024"},
"created": "2026-08-14T10:00:00.000Z"
}{
"id": "cmsr1a2b",
"status": "FAILED",
"failureCode": "INSUFFICIENT_FUNDS"
}Прежние адреса продолжают работать
Пара POST /v1/payment_intents и POST /v1/payment_intents/{id}/confirm
никуда не делась и ведёт в тот же код. Новый способ короче на один вызов;
переходить на него можно не спеша.
Статусы платежа
| Статус | Что значит |
|---|---|
REQUIRES_PAYMENT | Создан, ждёт подтверждения. Деньги не тронуты. |
PROCESSING | В обработке. Может остаться в этом статусе, если банк не ответил однозначно — см. ниже. |
SUCCEEDED | Деньги списаны. |
FAILED | Отказ. Причина — в failureCode. |
CANCELED | Отменён до подтверждения. |
PROCESSING — это не отказ
Если банк оборвал связь, мы не объявляем платёж неуспешным: деньги могли
уйти. Платёж остаётся в PROCESSING до выяснения. Не создавайте новый —
дождитесь финального статуса, он появится после сверки.
Баланс и история
GET /v1/balance — сколько собрано продуктом.
GET /subscribe/v1/charges — последние платежи. Баланс считается из проводок,
а не из отдельного счётчика, поэтому не может разойтись с историей.
curl https://api.assalam.uz/subscribe/v1/charges/cmsr1a2b \
-H "Authorization: Bearer sk_test_..."curl "https://api.assalam.uz/subscribe/v1/charges?limit=20" \
-H "Authorization: Bearer sk_test_..."
# следующая страница: id последнего полученного платежа
curl "https://api.assalam.uz/subscribe/v1/charges?limit=20&starting_after=cmsr1a2b" \
-H "Authorization: Bearer sk_test_..."{
"available": 4900000,
"pending": 0,
"currency": "UZS",
"livemode": false
}Возвраты
Возврат работает, но только на всю сумму платежа. POST /v1/refunds
возвращает деньги на карту клиента.
Частичный возврат невозможен: банк принимает в запросе только идентификатор операции, суммы в нём нет вовсе. Поэтому запрос на часть суммы получит явную ошибку до того, как у нас появится запись о возврате, — а не мнимый успех, от которого ваш учёт разошёлся бы с реальностью.
Срок, в течение которого возврат возможен, банк пока не назвал: отдельного метода возврата у него нет, возврат делается отменой самой операции. Если возврат по старому платежу важен для вашего сценария, спросите нас заранее. Подробнее и про остальные пределы — «Чего пока нельзя».