Skip to content

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 breakdown estimate (the bank's rate, our markup, every fee, the exact payout) and a quote_id.
  • Receive amount: send amount_debit + currency_debit instead of amount_credit and the beneficiary receives exactly that; the send amount is solved for you.
  • Pay with the quote_id executes exactly the quoted breakdown (valid until expires_at, for one transfer only).
  • The payer and the beneficiary are passed in the sender_info and recipient_info objects (see below) — the same for every partner and service.
  • The data object 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.