Интерфейс банка-получателя¶
Этот раздел предназначен для банков-получателей, то есть банков, которые зачисляют переводы Milkyway своим клиентам в местной валюте. Здесь описан типовой контракт: какие операции банк поддерживает, какими данными обменивается с Milkyway и по каким правилам считаются курс, комиссии и сумма к выплате.
Контракт состоит из двух частей:
- Логический контракт (разделы 1–10) обязателен для всех банков-получателей. Он не зависит от транспорта. Если у банка уже есть свой API, Planet9 пишет к нему адаптер, и этот адаптер обязан соблюдать логический контракт.
- Референсный REST API (раздел 11) приведён как пример и образец. Банк без своего API или банк, готовый следовать типовому формату, может реализовать его как есть. Тогда подключение сводится к настройке, без разработки отдельного адаптера.
Совместимость
Поля recipient_fee, recipient_fee_currency, expires_at (Precheck), amount_debit
в запросе Precheck и webhook статуса необязательны и обратно совместимы. Банк, который
их не использует, работает как раньше: без комиссии, со сроком котировки Оператора и
с опросом статуса.
1. Участники и движение денег¶
| Участник | Роль |
|---|---|
| Банк-отправитель | Принимает перевод от клиента и платит в валюте отправки (USD). |
| Milkyway (Оператор) | Проверяет и тарифицирует перевод, передаёт распоряжения, ведёт учёт обязательств, рассчитывает неттинг. Денег участников не держит. |
| Расчётный центр | Проводит итоговые расчёты между участниками по нетто-позициям. |
| Банк-получатель | Проверяет получателя, задаёт курс, зачисляет получателю сумму в местной валюте из собственной ликвидности. |
| Получатель | Клиент банка-получателя. |
flowchart LR
S[Банк-отправитель] -- "распоряжение (USD)" --> M[Milkyway]
M -- "Precheck / Pay" --> R[Банк-получатель]
R -- "зачисление (TJS)" --> B[Получатель]
S -. "нетто-расчёт S (USD)" .-> C[Расчётный центр]
C -. "нетто-расчёт S (USD)" .-> R
Ключевые правила:
- Валюта отправки равна валюте расчёта. Сегодня это USD. Обязательства банка- получателя учитываются и неттингуются в ней.
- Валюта выплаты — местная валюта получателя (например, TJS). Банк выплачивает её сам, а возмещение получает в валюте расчёта через Расчётный центр.
- По каждому переводу банк-получатель получает сумму S (раздел 5) в составе нетто-позиции. Отдельной оплаты по каждому переводу нет.
2. Операции¶
| Операция | Обязательна | Назначение | Деньги двигает |
|---|---|---|---|
| HealthCheck | да | Доступность сервиса банка. | нет |
| Precheck | да | Проверка получателя и отправителя (KYC/санкции), котировка курса и комиссии банка. | нет |
| Pay | да | Зачисление перевода получателю. | да |
| Postcheck | да | Статус ранее отправленного зачисления. | нет |
| Cancel | нет | Отмена (возврат) зачисления. | да |
| Webhook статуса | нет, рекомендуется | Банк сам сообщает Milkyway об изменении статуса зачисления. Направление: банк → Milkyway. | нет |
Все операции, кроме webhook, вызывает Milkyway. Webhook вызывает банк.
Список услуг банка (wallet, card и т. п.), валют выплаты и профиль сведений об
отправителе и получателе согласуются при подключении и публикуются в разделе Услуги.
Сведения о сторонах Milkyway передаёт в едином формате sender_info / recipient_info
(раздел 3) — одинаковом для всех банков-отправителей. Профиль говорит, какие поля этого
формата банку обязательны и какие он использует; Milkyway проверяет профиль до вызова
банка. Если услуге нужны поля, не относящиеся к личности, они передаются в data и
описываются JSON Schema.
sequenceDiagram
autonumber
participant S as Банк-отправитель
participant M as Milkyway
participant R as Банк-получатель
S->>M: Precheck
M->>R: Precheck (получатель, сумма, sender_info, recipient_info)
R-->>M: курс R, [комиссия банка], [срок действия]
M-->>S: полная калькуляция + quote_id
S->>M: Pay (quote_id)
M->>R: Pay (id перевода, сумма к зачислению)
R-->>M: принят (id платежа банка)
alt Webhook (банк сообщает сам)
R->>M: webhook: статус
M-->>R: 200 OK
else Опрос (Milkyway спрашивает)
loop до финального статуса
M->>R: Postcheck
R-->>M: статус
end
end
3. Precheck: проверка и котировка¶
Precheck выполняется перед каждым переводом и может повторяться многократно. Он не двигает деньги и ничего не резервирует.
Запрос Milkyway → банк
| Поле (бизнес) | Поле Milkyway | Описание |
|---|---|---|
| Услуга | service_id |
Код услуги банка, например wallet или card. |
| Получатель | recipient_id |
Идентификатор получателя в банке (телефон, номер карты, счёт). |
| Сумма отправки | amount_credit |
Полная (брутто) сумма перевода A в валюте отправки. |
| Валюта отправки | currency_credit |
Например USD. |
| Отправитель | sender_info |
Клиент-отправитель в едином формате: ФИО, дата рождения, вид, номер и страна документа, страна проживания, адрес. Поля — ниже; какие из них банк получает обязательно — по профилю услуги. |
| Получатель (лицо) | recipient_info |
Получатель в том же формате. |
| Доп. данные | data |
Поля услуги, не относящиеся к личности, если они согласованы. Обычно пусто. |
| Сумма к зачислению | amount_debit |
Только в режиме «сумма к зачислению» (раздел 5.3). |
| Валюта выплаты | currency_debit |
Передаётся вместе с amount_debit. |
Формат sender_info / recipient_info (модель FATF Travel Rule / ISO 20022 / IVMS101)
| Поле | Формат |
|---|---|
party_type |
natural — физическое лицо. |
name.first, name.last, name.full |
Имя, фамилия; name.full — полное имя как в документе (фамилия первой, с отчеством). |
date_of_birth |
YYYY-MM-DD. |
identity_document_type |
passport, national_id, driver_license, residence_permit, tax_id, social_security, other (коды IVMS101 CCPT, IDCD, DRLC, ARNU, TXID, SOCS, MISC). |
identity_document_number |
Серия и номер документа. |
identity_document_country, country_of_residence |
ISO 3166-1 alpha-2. |
address |
country, city, street, building, postal_code, line[]. |
Формат и значения Milkyway проверяет до вызова банка. Банк получает только поля, которые передал банк-отправитель; поля, обязательные по профилю услуги, присутствуют всегда.
Ответ банк → Milkyway
| Поле (бизнес) | Поле Milkyway | Обязательно | Описание |
|---|---|---|---|
| Валюта выплаты | currency_debit |
да | Валюта, в которой будет зачисление. |
| Курс | rate |
да | R: сколько единиц валюты выплаты даёт 1 единица валюты отправки. |
| Сумма выплаты | amount_debit |
нет | Справочно: A × R. Milkyway рассчитывает выплату сам (раздел 5). |
| Комиссия банка | recipient_fee |
нет | Раздел 4. |
| Валюта комиссии | recipient_fee_currency |
нет | Валюта отправки или валюта выплаты. |
| Срок действия | expires_at |
нет | До какого момента банк гарантирует курс и комиссию (ISO 8601, UTC). |
Правила
- Банк проверяет, что получатель существует и может принять зачисление, а сведения об отправителе проходят его KYC и санкционный контроль. При отказе возвращается ошибка из раздела 9.
- Курс задаёт банк-получатель. Milkyway не ограничивает и не корректирует курс банка. Поверх него Оператор применяет свою тарифную наценку (раздел 5).
- Курс должен быть применим к любой сумме не больше котируемой. Котировка
запрашивается на брутто-сумму A, а фактически конвертируется меньшая сумма: после
комиссии и наценки Оператора, а также комиссии банка. Выплата считается как
сумма × R. Если курс банка зависит от суммы, он указывает курс для котируемой суммы, и Milkyway при необходимости запрашивает котировку повторно (раздел 5.3). - Все удержания банка указываются явно в поле
recipient_fee, а не закладываются в ухудшение курса. Отправитель видит каждую составляющую отдельно. - Ответ должен прийти за время ожидания. По умолчанию это 30 секунд; значение настраивается для банка и учитывает длительные санкционные проверки.
- Если указан
expires_at, банк обязуется исполнить Pay по этой котировке до указанного момента: зачислить рассчитанную сумму без перезапроса курса. Milkyway принимает распоряжение по котировке не позжеmin(expires_at, срок Оператора); срок Оператора по умолчанию 120 секунд.
4. Комиссия банка-получателя¶
- Комиссию банка-получателя всегда платит получатель (модель BEN). Она удерживается из суммы выплаты.
- Банк-получатель не может выставить комиссию банку-отправителю. Моделей OUR и SHA нет. Никакое значение в ответе банка не увеличивает сумму, которую платит отправитель.
- Комиссия не проходит через неттинг и учёт Оператора. Банк удерживает её у себя: получает в расчёте ту же сумму S, а получателю выплачивает на величину комиссии меньше.
- Комиссия задаётся в одной валюте:
- в валюте отправки (
F_s) — удерживается до конвертации; - в валюте выплаты (
F_p) — удерживается после конвертации.
- в валюте отправки (
- Комиссия неотрицательна и указывается в минимальных единицах своей валюты: не больше двух знаков после запятой для USD и TJS. Некорректное значение отклоняет перевод на Precheck.
- Если комиссия не оставляет получателю положительной суммы, перевод отклоняется.
- Банк-отправитель видит комиссию банка-получателя отдельной строкой в калькуляции до отправки перевода.
5. Расчёт суммы к выплате¶
5.1 Обозначения¶
| Обозначение | Кто задаёт | Смысл |
|---|---|---|
| A | банк-отправитель | Сумма перевода в валюте отправки. |
| R | банк-получатель | Курс банка: 1 единица валюты отправки = R единиц валюты выплаты. |
| C | тариф Оператора | Комиссия Оператора (б. п. от A, с минимумом и максимумом), удерживается из перевода. |
| M | тариф Оператора | FX-наценка Оператора (б. п. от A), удерживается из перевода. |
| p | тариф Оператора | Сбор за обработку. Выставляется банку-отправителю отдельно и на выплату не влияет. |
| F_s / F_p | банк-получатель | Комиссия банка-получателя в валюте отправки или выплаты. |
| S | расчёт | Сумма, которую банк-получатель получает в нетто-расчёте (валюта отправки). |
| B | расчёт | Сумма к зачислению получателю (валюта выплаты). |
5.2 Формулы (режим «сумма отправки»)¶
C = min( max( round(A·c/10000), L ), U ) комиссия Оператора
M = round( A·m/10000 ) FX-наценка Оператора
S = A − C − M получает банк-получатель (USD)
B = ⌊ R · (S − F_s) ⌋ − F_p зачисляется получателю (TJS)
R' = R · (A − C − M) / (A − C) клиентский курс, показывается отправителю
- Суммы в валюте отправки округляются до цента (half-up). B округляется один раз вниз до минимальной единицы валюты выплаты.
- Остаток от округления B (доли минимальной единицы) остаётся у банка-получателя.
- В Pay банк получает уже рассчитанную B и зачисляет ровно её.
Пример. A = 1000.00 USD, комиссия Оператора 20 б. п., наценка 100 б. п., R = 10.905, комиссия банка F_p = 5.00 TJS.
| Шаг | Значение |
|---|---|
| C = 1000 × 0.0020 | 2.00 USD |
| M = 1000 × 0.0100 | 10.00 USD |
| S = 1000 − 2 − 10 | 988.00 USD, сумма в нетто-расчёте банка |
| ⌊10.905 × 988.00⌋ | 10 774.14 TJS |
| B = 10 774.14 − 5.00 | 10 769.14 TJS, зачисляется получателю |
| R' = 10.905 × 988 / 998 | ≈ 10.7957, клиентский курс |
5.3 Режим «сумма к зачислению»¶
Банк-отправитель может задать не сумму отправки, а сумму, которую получатель должен получить: B*. Milkyway подбирает минимальную сумму отправки A так, чтобы получатель получил ровно B*:
S* = ⌈ (B* + F_p) / R ⌉ + F_s (округление вверх до цента)
A = минимальная сумма, при которой A − C(A) − M(A) ≥ S*
Пример. B* = 10 000.00 TJS, R = 10.905, без комиссии банка: S* = ⌈917.0105…⌉ = 917.02 USD. Банк получает 917.02 USD и зачисляет ровно 10 000.00 TJS. Остаток меньше 0.11 TJS, как и в обычном режиме, остаётся у банка.
Как это выглядит для банка:
- Банк получает Precheck с
amount_debit= B* и предварительнойamount_credit. - Если банк умеет котировать по сумме выплаты, он отвечает курсом и комиссией для неё.
Если не умеет, он котирует по
amount_creditкак обычно. - Milkyway решает задачу и при необходимости повторяет Precheck с итоговой A. Всего делается не больше трёх запросов. Если курс или комиссия «плавают» и B* не сходится, перевод отклоняется.
- В Pay банк, как всегда, получает ровно ту сумму к зачислению, которую должен выплатить.
6. Pay: зачисление¶
Запрос Milkyway → банк
| Поле (бизнес) | Поле Milkyway | Описание |
|---|---|---|
| ID перевода | id |
Уникальный идентификатор перевода в Milkyway. Ключ идемпотентности. |
| Услуга | service_id |
Код услуги. |
| Получатель | external_id_debit |
Идентификатор получателя (как в Precheck). |
| Сумма к зачислению | amount_debit |
B, которую нужно зачислить получателю ровно. |
| Валюта выплаты | currency_debit |
Например TJS. |
| Сумма отправки | amount_credit |
A, брутто. Справочно, не для зачисления. |
| Валюта отправки | currency_credit |
Например USD. |
| Курс | rate |
Клиентский курс R' (справочно). |
| Комиссия Оператора | commission |
C (справочно). |
| Комиссия банка | recipient_fee, recipient_fee_currency |
Зафиксированная комиссия банка (уже учтена в amount_debit). |
| Курс банка | base_rate |
Зафиксированный курс R из котировки. |
| Отправитель, получатель | sender_info, recipient_info |
Те же сведения, что прошли Precheck (раздел 3). |
| Доп. данные | data |
Поля услуги, не относящиеся к личности, если они согласованы. |
| Время создания | created_at |
ISO 8601. |
Ответ банк → Milkyway: идентификатор платежа на стороне банка (external_payment_id),
если он есть.
Правила
- Зачислить ровно
amount_debit. Это сумма уже за вычетом всех комиссий. Ничего дополнительно не удерживать и не пересчитывать сумму изamount_credit. - Идемпотентность по
id. Распоряжение доставляется гарантированно, поэтому повторная доставка с тем жеidвозможна. Банк не должен зачислять повторно. Он отвечает «платёж уже существует» либо возвращает результат первого вызова. - Нельзя зачислять другую сумму. Если банк не может исполнить по зафиксированным условиям (курс изменился, котировка истекла), он отказывает с ошибкой, а не зачисляет иную сумму.
- Ошибки делятся на постоянные (повтор не поможет: получатель не найден, отказ
комплаенса, неверные данные) и временные (недоступность, таймаут). По временным
Milkyway повторяет доставку, по постоянным не повторяет. Постоянный отказ в ответ на
Pay адаптер сам сообщает Milkyway, и перевод сразу получает статус
3(failed) с причиной: банк, отказавший при создании перевода, на Postcheck отвечает «не найден», а это Milkyway читает как «ещё не дошло». Если банк зарегистрировал отказ позже, уже приняв перевод, он сообщает статус3с причиной через webhook или на Postcheck. Иначе перевод уйдёт на ручной разбор по таймауту (раздел 7). - Исполнение может быть синхронным (финальный статус сразу) или асинхронным. В обоих случаях итог подтверждается через webhook или Postcheck (раздел 7).
7. Статус: опрос и webhook¶
Milkyway узнаёт итог зачисления двумя способами:
- Опрос (Postcheck). Milkyway сам периодически запрашивает статус. Обязателен для всех банков.
- Webhook. Банк сам отправляет Milkyway уведомление, как только статус изменился. Необязателен, но рекомендуется: итог становится известен сразу, а не к следующему опросу.
Оба способа передают одинаковые данные и работают по одинаковым правилам. Webhook не заменяет Postcheck: опрос остаётся страховкой на случай потерянного уведомления, а Оператору нужен для ручной перепроверки. Для банков с webhook интервал опроса увеличивается.
| Код | Статус | Смысл |
|---|---|---|
0 |
в обработке | Банк ещё не завершил зачисление. |
1 |
выполнен | Деньги зачислены получателю. Финальный. |
2 |
отменён | Зачисление отменено (раздел 8). Финальный. |
3 |
ошибка | Зачисление не выполнено, деньги не двигались. Финальный. |
4 |
отмена в процессе | Отмена запрошена, ещё не завершена. |
Общие правила
- Для финальных статусов
3и2банк передаёт причину (error). Milkyway хранит её для своих операторов, а отправитель видит только её смысл (например, «отклонён»), но не текст. - Для статуса
1банк может сообщить фактически зачисленную сумму (credited_amount,credited_currency; необязательно). Она должна совпадать с суммой зачисления (раздел 6). Milkyway сохраняет её, и Оператор сверяет её с распоряжением при проверке суммы зачисления (Приложение 5 §5.10.4); банк, который её не сообщает, подтверждает зачисленные суммы выпиской. - Банк передаёт только коды
0–4. Любой другой код игнорируется и записывается в журнал. - Финальный статус необратим. «Выполнен» можно изменить только явной отменой (раздел 8). Уведомление или ответ, противоречащие уже зафиксированному финальному статусу, не применяются и разбираются Оператором.
- Если финальный статус не получен за предельное время (по умолчанию до 24 часов), перевод уходит на ручной разбор Оператором. При этом Milkyway продолжает проверять его каждые 15 минут ещё до 3 суток с момента создания.
7.1 Опрос (Postcheck)¶
- Интервал опроса и предельное время ожидания настраиваются для банка и услуги.
- Ответ «платёж не найден» не означает отказ. Распоряжение могло ещё не дойти до банка, поэтому Milkyway продолжает опрос.
7.2 Webhook¶
- Когда отправлять. При каждом изменении статуса зачисления: обязательно при
переходе в
1,2и3; при желании и в0и4. - Куда.
POST /payments/v1/payout-statusпартнёрского API Milkyway. Базовый адрес тот же, что для партнёрского API, и выдаётся при подключении (раздел 11). - Что. Те же поля, что и в ответе Postcheck, плюс уникальный
event_idи время событияoccurred_at. - Аутентификация. Банк получает учётные данные (client credentials) в Keycloak
Planet9, как и для партнёрского API, и передаёт
Authorization: Bearer <token>. Уведомления без валидного токена отклоняются. Банк может отправлять уведомления только о своих переводах. - Подтверждение. Milkyway отвечает
2xx, когда надёжно сохранил уведомление. При любом другом ответе или таймауте банк повторяет отправку с нарастающей паузой (рекомендуется: 1 мин, 5 мин, 15 мин, далее каждый час, не менее 24 часов). - Повторы и порядок. Одно и то же уведомление может прийти несколько раз и не по
порядку. Milkyway обрабатывает их идемпотентно: дубликаты по
event_idигнорируются, а промежуточный статус не перезаписывает уже полученный финальный. - Проверка. Milkyway применяет уведомление по тем же правилам, что и ответ Postcheck, и может дополнительно подтвердить его запросом Postcheck.
8. Cancel: отмена (необязательно)¶
- Отмена возможна только для выполненного перевода, в пределах окна (по умолчанию 3 часа с момента создания) и только до включения перевода в неттинг.
- Банк отвечает статусом
2(отменён синхронно) или4(отмена в процессе, итог подтверждается через webhook или Postcheck). - Если банк не поддерживает отмену, Milkyway отклоняет запросы на отмену переводов этого банка.
9. Ошибки¶
| Код | Тип | Когда |
|---|---|---|
recipient_not_found |
постоянная | Получатель не существует или не может принять зачисление. |
unsupported_currency |
постоянная | Валюта отправки или выплаты не поддерживается. |
validation_error |
постоянная | Неверные или неполные сведения об отправителе или получателе (или data), сумма вне лимитов. |
compliance_rejected |
постоянная | Отказ KYC или санкционного контроля. |
limit_exceeded |
постоянная | Превышены лимиты получателя или банка. |
duplicate |
— | Платёж с этим id уже существует (повторная доставка Pay). |
rate_changed |
постоянная | Курс изменился, исполнить по котировке нельзя. |
quote_expired |
постоянная | Котировка истекла. |
not_found |
— | Postcheck или Cancel: платёж с этим id не найден. |
service_unavailable |
временная | Сервис банка временно недоступен. |
internal_error |
временная | Внутренняя ошибка банка. |
Отправитель узнаёт только смысл кода: банк недоступен (повторить позже), платёж отклонён
или запрос нужно исправить. Текст ошибки (message) хранится для операторов Milkyway и
отправителю не показывается никогда; персональных данных в нём всё равно быть не должно.
10. Расчёты и сверка¶
- По каждому выполненному переводу у банка-получателя возникает требование на S в валюте расчёта. Отменённые переводы в расчёт не входят.
- Требования неттингуются по каждой валюте между участниками в соответствии с установленным временем отсечки (cut-off). Итоговые нетто-суммы переводятся через Расчётный центр по распоряжениям Milkyway.
- Milkyway сверяет выписки банка с распоряжениями. Расхождения разбираются Оператором вместе с банком.
11. Референсный REST API¶
Ниже приведён типовой HTTP-интерфейс, который банк может реализовать у себя. Полное
описание — на портале документации:
Receiving Bank API
(исходный файл OpenAPI 3: receiving-bank-api.yaml).
Общие правила
- Транспорт: HTTPS (TLS 1.2+), рекомендуется mTLS.
- Аутентификация: OAuth 2.0 client credentials. Банк выдаёт Planet9
client_idиclient_secret, Milkyway передаётAuthorization: Bearer <token>. Другая схема допускается по согласованию. - Формат: JSON, UTF-8. Суммы — числа с точностью до минимальной единицы валюты. Время — ISO 8601 в UTC. Валюты — ISO 4217.
- Идемпотентность:
POST /paymentsнесёт заголовокIdempotency-Key, равный ID перевода. - Ошибки: HTTP-код плюс тело
{"code": "...", "message": "..."}с кодами из раздела 9.
| Метод | Путь | Операция |
|---|---|---|
GET |
/v1/health |
HealthCheck |
POST |
/v1/quotes |
Precheck |
POST |
/v1/payments |
Pay |
GET |
/v1/payments/{transaction_id} |
Postcheck |
POST |
/v1/payments/{transaction_id}/cancel |
Cancel (необязательно) |
Webhook работает в обратную сторону: его вызывает банк, а принимает Milkyway. Базовый адрес партнёрского API Milkyway выдаётся при подключении.
| Метод | Путь (на стороне Milkyway) | Операция |
|---|---|---|
POST |
/payments/v1/payout-status |
Webhook статуса |
Precheck: POST /v1/quotes
{
"service_id": "wallet",
"recipient_id": "992901234567",
"send_amount": 1000.00,
"send_currency": "USD",
"payout_currency": "TJS",
"sender_info": {
"party_type": "natural",
"name": { "first": "IVAN", "last": "IVANOV", "full": "IVANOV IVAN IVANOVICH" },
"date_of_birth": "1990-01-31",
"identity_document_type": "passport",
"identity_document_number": "AB1234567",
"identity_document_country": "TJ"
},
"recipient_info": {
"party_type": "natural",
"name": { "first": "ALI", "last": "KARIMOV" }
}
}
{
"recipient_name": "ИВАНОВ И.",
"payout_currency": "TJS",
"rate": 10.905,
"payout_amount": 10905.00,
"recipient_fee": 5.00,
"recipient_fee_currency": "TJS",
"expires_at": "2026-10-10T09:32:00Z"
}
recipient_name — маскированное имя получателя для подтверждения отправителем;
необязательно.
Pay: POST /v1/payments с заголовком Idempotency-Key: 42
{
"transaction_id": "42",
"service_id": "wallet",
"recipient_id": "992901234567",
"payout_amount": 10769.14,
"payout_currency": "TJS",
"send_amount": 1000.00,
"send_currency": "USD",
"base_rate": 10.905,
"recipient_fee": 5.00,
"recipient_fee_currency": "TJS",
"sender_info": { "party_type": "natural", "name": { "first": "IVAN", "last": "IVANOV" },
"date_of_birth": "1990-01-31", "identity_document_type": "passport",
"identity_document_number": "AB1234567" },
"recipient_info": { "party_type": "natural", "name": { "first": "ALI", "last": "KARIMOV" } },
"created_at": "2026-10-10T09:30:12Z"
}
Ответ 202 Accepted (или 200 OK при синхронном исполнении):
{ "transaction_id": "42", "payment_id": "SPT-778812", "status": 0 }
Повтор с тем же Idempotency-Key возвращает тот же ответ. Повтор с тем же ключом, но
другим телом даёт 409 duplicate.
Postcheck: GET /v1/payments/42
{ "transaction_id": "42", "payment_id": "SPT-778812", "status": 1, "error": "",
"credited_amount": 10769.14, "credited_currency": "TJS" }
Если платёж не найден: 404 с {"code": "not_found"}.
Cancel: POST /v1/payments/42/cancel
{ "transaction_id": "42", "status": 4 }
Webhook статуса: банк → POST /payments/v1/payout-status
Заголовок Authorization: Bearer <token> (токен Keycloak Planet9).
{
"event_id": "b7f1c2e0-5a7d-4c1e-9d1a-3f2e8c6b9a01",
"occurred_at": "2026-10-10T09:30:41Z",
"transaction_id": "42",
"payment_id": "SPT-778812",
"status": 1,
"error": ""
}
Ответ 200 OK означает, что уведомление принято; в теле — итоговый статус перевода,
например {"transaction_id": 42, "status": 1}. 400 — уведомление некорректно (повтор не
поможет), 404 — перевод не найден или принадлежит другому банку. На любой другой ответ
отправку нужно повторить.
12. Чек-лист подключения¶
- [ ] Перечень услуг (
wallet,card, …), валют отправки и выплаты. - [ ] Какие сведения об отправителе и получателе нужны по каждой услуге: обязательные и
используемые поля из
sender_info/recipient_info, принимаемые виды документа (по ним Planet9 публикует профиль услуги). Поляdata— только если услуге нужно что-то сверх этого. - [ ] Порядок формирования курса и срок, в течение которого он гарантирован.
- [ ] Комиссия банка: размер, валюта, условия. Удерживается только с получателя.
- [ ] Лимиты на получателя и на операцию.
- [ ] Поддержка отмены и её условия.
- [ ] Время ответа Precheck и Pay, рекомендуемый интервал опроса статуса.
- [ ] Способ получения статуса: опрос или опрос + webhook. Для webhook — учётные данные Keycloak Planet9 и базовый адрес партнёрского API Milkyway.
- [ ] Тестовый стенд и доступы: адрес, учётные данные, тестовые получатели.
- [ ] Контакты для эскалации инцидентов.