Перейти к содержанию

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. См. раздел Интерфейс банка-получателя.