Milkyway — overview¶
Milkyway is a cross-border transfer platform. Sending banks integrate with the platform once and gain access to every connected receiving bank (partner) through a single interface: Milkyway talks to the chosen partner itself and normalizes the response to a common format.
The list of partners, services and their terms is in the Services section.
Authentication¶
Access to Milkyway is protected with OAuth 2.0. The sending bank obtains an access
token from Planet9's Keycloak (via the client credentials issued at onboarding),
then passes it on every request to Milkyway in the Authorization: Bearer <token>
header.
How to obtain a token in the stage and production environments (realms, token endpoint, request examples) — see the Authentication section.
Transfer lifecycle¶
Every transfer goes through: Precheck (recipient validation and rate calculation) and Pay (execution). The status can then be polled (Postcheck) or delivered via a webhook from Milkyway — pick whichever suits you.
sequenceDiagram
autonumber
participant S as Sending bank
participant O as Keycloak
participant M as Milkyway
Note over S,O: Authentication
S->>O: Token request (client credentials)
O-->>S: Access token
Note over S,M: Precheck — recipient validation and rate calculation
S->>M: Precheck + Bearer token
M-->>S: amount_debit, currency_debit, rate
Note over S,M: Pay — transfer execution
S->>M: Pay (+ sender_info, recipient_info)
M-->>S: Accepted for processing
Getting the status¶
The transfer status — two ways, your choice:
Option 1 — polling (Postcheck)
sequenceDiagram
participant S as Sending bank
participant M as Milkyway
S->>M: GET postcheck + Bearer token
M-->>S: transaction_id, status, error
Option 2 — webhook (push from Milkyway)
sequenceDiagram
participant M as Milkyway
participant S as Sending bank
M->>S: POST callback (transaction_id, status, error)
S-->>M: 200 OK
Both ways carry the same payload — the one returned by
GET /payments/v1/postcheck:
{
"transaction_id": 42,
"status": 1,
"error": ""
}
Statuses: 0 — processing, 1 — done, 2 — cancelled, 3 — failed,
4 — cancellation in progress.
The webhook removes the need to poll: on a status change Milkyway sends this POST
to the callback URL agreed at onboarding; a 2xx response is expected, otherwise it
retries with exponential backoff. If the webhook is unavailable, polling via
Postcheck always remains.
Feature status
Polling (Postcheck) is available now. The webhook is planned; the payload contract is shown above and will match Postcheck.
Unified interface¶
Requests and responses are the same for every partner and service; the full schema
is in the milkyway core OpenAPI spec (branch dev) and is not duplicated here. Key
fields:
- Precheck:
recipient_id,amount_credit,currency_credit→amount_debit,currency_debit,rate, the full cost breakdownestimate(the bank's rate, our markup, every fee, the exact payout) and aquote_id. - Receive amount: send
amount_debit+currency_debitinstead ofamount_creditand the beneficiary receives exactly that; the send amount is solved for you. - Pay with the
quote_idexecutes exactly the quoted breakdown (valid untilexpires_at, for one transfer only). - The payer and the beneficiary are passed in the
sender_infoandrecipient_infoobjects (see below) — the same for every partner and service. - The
dataobject is only for a service's extra fields that are not about the payer's or beneficiary's identity. Most services do not need it; where one does, its fields are listed in the Services section.
Payer and beneficiary details¶
Your customer (sender_info) and the beneficiary (recipient_info) are passed in
Precheck and Pay in one format for every receiving bank and service. The format
follows the FATF Travel Rule / ISO 20022 / IVMS101 data model: you map your customer
data to it once, and Milkyway converts it to the chosen bank's own format. The phone,
card or account number still goes in sender_id / recipient_id;
sender_info / recipient_info describe the person.
| Field | Format |
|---|---|
party_type |
natural — a person. Required in each object. Legal entities (legal) are not accepted yet. |
name.first, name.last, name.full |
First and family name; name.full is the name as in the document, family name first, with a patronymic if any. |
date_of_birth |
Date of birth, YYYY-MM-DD. |
identity_document_type |
Document kind: passport, national_id, driver_license, residence_permit, tax_id, social_security, other. Required with the document number. |
identity_document_number |
Document series and number, as in the document. |
identity_document_country, country_of_residence |
Issuing country and country of residence: ISO 3166-1 alpha-2, upper case (TJ). |
address |
country (alpha-2; required when an address is sent), city, street, building, postal_code, line — up to 7 lines for an address held as one string. |
"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" }
}
Which fields are needed is up to the receiving bank. Each service lists them in the
Services section and in GET /payments/v1/discovery (the party_profile field:
required and used fields, and the document kinds accepted). Send the details you have:
fields the bank does not use are ignored.
Errors. An unknown key, a value of the wrong type or format is refused with 400,
field naming the path, e.g. sender_info.identity_document_type. A field the bank
requires and the request lacks is a 400 too, e.g.
sender_info.date_of_birth: is required by the receiving bank for this service. The
answer never repeats the value you sent.
Identity in data is not read
Fields such as sender_fio, id_series_number or sender_birthday in data are
no longer passed to the bank. Without sender_info / recipient_info, a transfer to
a bank that needs them is refused at Precheck.
For receiving banks¶
A bank that wants to pay out Milkyway transfers to its customers connects under a standard contract. It covers the operations, the rate and fee rules, the statuses, and a reference REST API. See Receiving bank interface.