Milkyway — обзор¶
Milkyway — платформа трансграничных переводов. Банки-отправители интегрируются с платформой один раз и получают доступ ко всем подключённым банкам-получателям (партнёрам) через единый интерфейс: Milkyway сам взаимодействует с выбранным партнёром и приводит ответ к общему формату.
Список партнёров, услуг и их условий — в разделе Услуги.
Аутентификация¶
Доступ к Milkyway защищён по OAuth 2.0. Банк-отправитель получает access token в
Keycloak Planet9 (по client credentials, выданным при подключении), а затем
передаёт его в каждом запросе к Milkyway в заголовке Authorization: Bearer <token>.
Как получить токен в окружениях stage и production (realm'ы, token endpoint, примеры запросов) — см. раздел Аутентификация.
Жизненный цикл перевода¶
Каждый перевод проходит: Precheck (проверка получателя и расчёт курса) и Pay (исполнение). Статус затем можно опрашивать (Postcheck) или получать вебхуком от Milkyway — выберите удобный способ.
sequenceDiagram
autonumber
participant S as Банк-отправитель
participant O as Keycloak
participant M as Milkyway
Note over S,O: Аутентификация
S->>O: Запрос токена (client credentials)
O-->>S: Access token
Note over S,M: Precheck — проверка получателя и расчёт курса
S->>M: Precheck + Bearer token
M-->>S: amount_debit, currency_debit, rate
Note over S,M: Pay — исполнение перевода
S->>M: Pay (+ sender_info, recipient_info)
M-->>S: Принят в обработку
Получение статуса¶
Статус перевода — двумя способами на выбор:
Вариант 1 — опрос (Postcheck)
sequenceDiagram
participant S as Банк-отправитель
participant M as Milkyway
S->>M: GET postcheck + Bearer token
M-->>S: transaction_id, status, error
Вариант 2 — вебхук (push от Milkyway)
sequenceDiagram
participant M as Milkyway
participant S as Банк-отправитель
M->>S: POST callback (transaction_id, status, error)
S-->>M: 200 OK
Оба способа несут одинаковую полезную нагрузку — ту же, что отдаёт
GET /payments/v1/postcheck:
{
"transaction_id": 42,
"status": 1,
"error": ""
}
Статусы: 0 — в обработке, 1 — выполнен, 2 — отменён, 3 — ошибка,
4 — отмена в процессе.
Вебхук избавляет от опроса: при смене статуса Milkyway сам отправляет этот POST на
callback URL, согласованный при подключении; ожидается ответ 2xx, иначе — повтор с
экспоненциальной паузой. Если вебхук недоступен — всегда остаётся опрос через Postcheck.
Статус функциональности
Опрос (Postcheck) доступен сейчас. Вебхук — в планах; контракт payload приведён выше и совпадёт с Postcheck.
Единый интерфейс¶
Запросы и ответы одинаковы для всех партнёров и услуг; полная схема — в OpenAPI-спеке
milkyway core (ветка dev) и здесь не дублируется. Ключевые поля:
- Precheck:
recipient_id,amount_credit,currency_credit→amount_debit,currency_debit,rate, полная калькуляцияestimate(курс банка, наша наценка, все комиссии, итог к зачислению) иquote_id. - Сумма к зачислению: вместо
amount_creditможно передатьamount_debit+currency_debit— получатель получит ровно эту сумму, а сумма отправки будет подобрана. - Pay с
quote_idисполняет ровно показанную калькуляцию (котировка действует доexpires_atи только для одного перевода). - Отправитель и получатель передаются в объектах
sender_infoиrecipient_info(см. ниже) — одинаково для всех партнёров и услуг. - Объект
data— только для дополнительных полей услуги, не связанных с личностью отправителя или получателя. Большинству услуг он не нужен; где нужен, поля указаны в разделе Услуги.
Сведения об отправителе и получателе¶
Сведения о клиенте-отправителе (sender_info) и о получателе (recipient_info)
передаются в Precheck и Pay в едином формате для всех банков-получателей и услуг.
Формат построен на модели данных FATF Travel Rule / ISO 20022 / IVMS101: вы один раз
приводите данные клиента к этому формату, а Milkyway сам переводит их в формат
выбранного банка. Номер телефона, карты или счёта по-прежнему передаётся в
sender_id / recipient_id; sender_info / recipient_info описывают человека.
| Поле | Формат |
|---|---|
party_type |
natural — физическое лицо. Обязательно в каждом объекте. Юридические лица (legal) пока не принимаются. |
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. Обязателен вместе с номером документа. |
identity_document_number |
Серия и номер документа, как в документе. |
identity_document_country, country_of_residence |
Страна выдачи документа и страна проживания: ISO 3166-1 alpha-2 заглавными (TJ). |
address |
country (alpha-2; обязательна, если передан адрес), city, street, building, postal_code, line — до 7 строк, если адрес хранится одной строкой. |
"sender_info": {
"party_type": "natural",
"name": { "first": "Ivan", "last": "Petrov", "full": "Petrov Ivan Sergeevich" },
"date_of_birth": "1990-04-18",
"identity_document_type": "passport",
"identity_document_number": "AB1234567",
"identity_document_country": "TJ"
},
"recipient_info": {
"party_type": "natural",
"name": { "first": "Ali", "last": "Karimov" }
}
Какие поля нужны — определяет банк-получатель. Для каждой услуги это указано в
разделе Услуги и в ответе GET /payments/v1/discovery (поле party_profile:
обязательные и используемые поля, а также принимаемые виды документа). Передавайте
сведения, которые у вас есть: поля, не нужные банку, игнорируются.
Ошибки. Неизвестный ключ, значение неверного типа или формата отклоняются с 400,
где field — путь к полю, например sender_info.identity_document_type. Если нет поля,
обязательного для банка, ответ тоже 400, например
sender_info.date_of_birth: is required by the receiving bank for this service. Ответ
никогда не повторяет переданное значение.
Сведения о личности в data не читаются
Поля вроде sender_fio, id_series_number или sender_birthday в data больше не
передаются банку. Без sender_info / recipient_info перевод в банк, которому они
нужны, будет отклонён на Precheck.
Банкам-получателям¶
Банк, который хочет зачислять переводы Milkyway своим клиентам, подключается по типовому контракту. В нём описаны операции, правила курса и комиссий, статусы и референсный REST API. См. раздел Интерфейс банка-получателя.