Skip to content

Receiving bank interface

This section is for receiving banks: the banks that pay out Milkyway transfers to their customers in local currency. It defines the standard contract:

  • which operations the bank supports;
  • what data it exchanges with Milkyway;
  • the rules for the rate, fees and payout amount.

The contract has two parts:

  1. Logical contract (sections 1–10). It is mandatory for every receiving bank and independent of transport. If the bank already has its own API, Planet9 writes an adapter to it, and that adapter must honour the logical contract.
  2. Reference REST API (section 11). It is given as an example and a reference. A bank without its own API, or one willing to follow the standard format, can implement it as-is. Onboarding is then configuration only, with no bespoke adapter to build.

Compatibility

The fields recipient_fee, recipient_fee_currency, expires_at (Precheck), the amount_debit in the Precheck request, and the status webhook are optional and backward-compatible. A bank that does not use them works as before: no fee, the Operator's quote lifetime, and status by polling.

1. Parties and flow of funds

Party Role
Sending bank Accepts the transfer from its customer and pays in the send currency (USD).
Milkyway (Operator) Validates and prices the transfer, issues instructions, records obligations, computes netting. Holds no participant funds.
Settlement Center Performs final settlement between participants on net positions.
Receiving bank Validates the beneficiary, sets the rate, and credits the beneficiary in local currency from its own liquidity.
Beneficiary The receiving bank's customer.
flowchart LR
    S[Sending bank] -- "instruction (USD)" --> M[Milkyway]
    M -- "Precheck / Pay" --> R[Receiving bank]
    R -- "payout (TJS)" --> B[Beneficiary]
    S -. "net settlement S (USD)" .-> C[Settlement Center]
    C -. "net settlement S (USD)" .-> R

Key rules:

  • The send currency is the settlement currency. Today this is USD. The receiving bank's obligations are recorded and netted in it.
  • The payout currency is the beneficiary's local currency (e.g. TJS). The bank pays it out itself and is reimbursed in the settlement currency through the Settlement Center.
  • For each transfer the receiving bank receives the amount S (section 5) as part of its net position. There is no per-transfer funding.

2. Operations

Operation Mandatory Purpose Moves money
HealthCheck yes Availability of the bank's service. no
Precheck yes Beneficiary and sender checks (KYC/sanctions); quote of the rate and the bank's fee. no
Pay yes Credit the transfer to the beneficiary. yes
Postcheck yes Status of a previously sent payout. no
Cancel no Cancel (reverse) a payout. yes
Status webhook no, recommended The bank notifies Milkyway itself when a payout status changes. Direction: bank → Milkyway. no

Milkyway calls every operation except the webhook. The bank calls the webhook.

The following are agreed at onboarding and published under Services:

  • the bank's services (wallet, card, …);
  • payout currencies;
  • the payer and beneficiary profile: which fields of the shared sender_info / recipient_info format (section 3) the bank requires and which it uses.

Milkyway passes the payer and beneficiary in that one format, the same for every sending bank, and checks the profile before calling the bank. A service that needs fields unrelated to identity takes them in data, described by a JSON Schema.

sequenceDiagram
    autonumber
    participant S as Sending bank
    participant M as Milkyway
    participant R as Receiving bank

    S->>M: Precheck
    M->>R: Precheck (beneficiary, amount, sender_info, recipient_info)
    R-->>M: rate R, [bank fee], [validity]
    M-->>S: full cost breakdown + quote_id
    S->>M: Pay (quote_id)
    M->>R: Pay (transfer id, amount to credit)
    R-->>M: accepted (bank payment id)
    alt Webhook (the bank notifies)
        R->>M: webhook: status
        M-->>R: 200 OK
    else Polling (Milkyway asks)
        loop until final status
            M->>R: Postcheck
            R-->>M: status
        end
    end

3. Precheck: validation and quote

Precheck runs before every transfer and may be repeated any number of times. It moves no money and reserves nothing.

Request, Milkyway → bank

Field (business) Milkyway field Description
Service service_id The bank's service code, e.g. wallet or card.
Beneficiary recipient_id Beneficiary identifier at the bank (phone, card number, account).
Send amount amount_credit Full (gross) transfer amount A in the send currency.
Send currency currency_credit E.g. USD.
Payer sender_info The sending customer in the shared format: name, date of birth, document kind, number and country, country of residence, address. Fields below; which ones the bank always receives follows the service profile.
Beneficiary (person) recipient_info The beneficiary in the same format.
Extra data data Service fields unrelated to identity, if agreed. Usually empty.
Amount to credit amount_debit Receive-amount mode only (section 5.3).
Payout currency currency_debit Sent together with amount_debit.

sender_info / recipient_info format (FATF Travel Rule / ISO 20022 / IVMS101 model)

Field Format
party_type natural — a person.
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).
date_of_birth YYYY-MM-DD.
identity_document_type passport, national_id, driver_license, residence_permit, tax_id, social_security, other (IVMS101 codes CCPT, IDCD, DRLC, ARNU, TXID, SOCS, MISC).
identity_document_number Document series and number.
identity_document_country, country_of_residence ISO 3166-1 alpha-2.
address country, city, street, building, postal_code, line[].

Milkyway checks the format and values before calling the bank. The bank receives only the fields the sending bank provided; the fields its service profile requires are always present.

Response, bank → Milkyway

Field (business) Milkyway field Required Description
Payout currency currency_debit yes Currency of the payout.
Rate rate yes R: how many payout-currency units 1 send-currency unit buys.
Payout amount amount_debit no Informational: A × R. Milkyway computes the payout itself (section 5).
Bank fee recipient_fee no Section 4.
Fee currency recipient_fee_currency no The send currency or the payout currency.
Validity expires_at no Until when the bank guarantees the rate and fee (ISO 8601, UTC).

Rules

  1. The bank checks that the beneficiary exists and can receive the payout, and that the sender details pass its KYC and sanctions screening. On refusal it returns an error from section 9.
  2. The receiving bank sets the rate. Milkyway does not cap or adjust the bank's rate. The Operator applies its tariff markup on top (section 5).
  3. The rate must apply to any amount up to the quoted one. The quote is requested for the gross amount A, but a smaller amount is actually converted: net of the Operator's commission and markup, and of the bank's fee. The payout is computed as amount × R. If the bank's rate depends on the amount, it quotes the rate for the quoted amount, and Milkyway re-quotes when needed (section 5.3).
  4. Every deduction by the bank is declared explicitly in recipient_fee, not hidden in a worse rate. The sender sees each component separately.
  5. The response must arrive within the timeout. The default is 30 seconds; it is configurable per bank to accommodate long sanctions checks.
  6. When expires_at is given, the bank commits to execute Pay on that quote until that instant: it credits the computed amount without re-quoting. Milkyway accepts an instruction on the quote no later than min(expires_at, Operator lifetime); the Operator lifetime defaults to 120 seconds.

4. Receiving-bank fee

  1. The receiving-bank fee is always paid by the beneficiary (BEN model). It is deducted from the payout.
  2. A receiving bank can never charge the sending bank. There are no OUR or SHA models. No value in the bank's response increases what the sender pays.
  3. The fee does not pass through netting or the Operator's books. The bank retains it locally: it receives the same settlement amount S, and pays the beneficiary less by the fee.
  4. The fee is stated in exactly one currency:
    • the send currency (F_s), deducted before conversion; or
    • the payout currency (F_p), deducted after conversion.
  5. The fee is non-negative and stated in its currency's minor units (at most two decimals for USD and TJS). An invalid value rejects the transfer at Precheck.
  6. If the fee would leave the beneficiary no positive amount, the transfer is rejected.
  7. The sending bank sees the receiving-bank fee as a separate line in the cost breakdown before it sends the transfer.

5. Payout calculation

5.1 Notation

Symbol Set by Meaning
A sending bank Transfer amount in the send currency.
R receiving bank Bank rate: 1 send-currency unit = R payout-currency units.
C Operator tariff Operator commission (bps of A, with floor and cap), deducted from the transfer.
M Operator tariff Operator FX markup (bps of A), deducted from the transfer.
p Operator tariff Processing fee, billed to the sending bank separately; does not affect the payout.
F_s / F_p receiving bank Receiving-bank fee in the send or payout currency.
S computed Amount the receiving bank receives in net settlement (send currency).
B computed Amount credited to the beneficiary (payout currency).

5.2 Formulas (send-amount mode)

C  = min( max( round(A·c/10000), L ), U )    Operator commission
M  = round( A·m/10000 )                      Operator FX markup
S  = A − C − M                               received by the receiving bank (USD)
B  = ⌊ R · (S − F_s) ⌋ − F_p                 credited to the beneficiary (TJS)
R' = R · (A − C − M) / (A − C)               customer rate, shown to the sender
  • Send-currency amounts round half-up to the cent. B is rounded once, down to the payout currency's minor unit.
  • The rounding remainder of B (fractions of a minor unit) stays with the receiving bank.
  • In Pay the bank receives the already-computed B and credits exactly that.

Example. A = 1000.00 USD, Operator commission 20 bps, markup 100 bps, R = 10.905, bank fee F_p = 5.00 TJS.

Step Value
C = 1000 × 0.0020 2.00 USD
M = 1000 × 0.0100 10.00 USD
S = 1000 − 2 − 10 988.00 USD, the bank's net-settlement amount
⌊10.905 × 988.00⌋ 10,774.14 TJS
B = 10,774.14 − 5.00 10,769.14 TJS, credited to the beneficiary
R' = 10.905 × 988 / 998 ≈ 10.7957, the customer rate

5.3 Receive-amount mode

The sending bank may specify the amount the beneficiary must receive, B*, instead of the send amount. Milkyway finds the smallest send amount A for which the beneficiary receives exactly B*:

S* = ⌈ (B* + F_p) / R ⌉ + F_s       (rounded up to the cent)
A  = the smallest amount with A − C(A) − M(A) ≥ S*

Example. B* = 10,000.00 TJS, R = 10.905, no bank fee: S* = ⌈917.0105…⌉ = 917.02 USD. The bank receives 917.02 USD and credits exactly 10,000.00 TJS. The remainder (under 0.11 TJS) stays with the bank, as in the normal mode.

What this means for the bank:

  • The bank receives a Precheck with amount_debit = B* and a provisional amount_credit.
  • If the bank can quote by payout amount, it answers with the rate and fee for it. Otherwise it quotes by amount_credit as usual.
  • Milkyway solves for A and, if needed, repeats Precheck at the final A. It makes at most three requests in total. If the rate or fee keeps moving so that B* cannot be met, the transfer is rejected.
  • In Pay the bank, as always, receives exactly the amount it must credit.

6. Pay: crediting the beneficiary

Request, Milkyway → bank

Field (business) Milkyway field Description
Transfer ID id Unique transfer identifier in Milkyway. Idempotency key.
Service service_id Service code.
Beneficiary external_id_debit Beneficiary identifier (as in Precheck).
Amount to credit amount_debit B, to be credited to the beneficiary exactly.
Payout currency currency_debit E.g. TJS.
Send amount amount_credit A, gross. Informational, not the amount to credit.
Send currency currency_credit E.g. USD.
Rate rate Customer rate R' (informational).
Operator commission commission C (informational).
Bank fee recipient_fee, recipient_fee_currency The locked bank fee, already reflected in amount_debit.
Bank rate base_rate The locked rate R from the quote.
Payer, beneficiary sender_info, recipient_info The same details that passed Precheck (section 3).
Extra data data Service fields unrelated to identity, if agreed.
Created at created_at ISO 8601.

Response, bank → Milkyway: the bank-side payment identifier (external_payment_id), if any.

Rules

  1. Credit exactly amount_debit. It is already net of every fee. Do not deduct anything further, and do not recompute the amount from amount_credit.
  2. Idempotency by id. Instructions are delivered with an at-least-once guarantee, so the same id may arrive more than once. The bank must not credit twice. It answers "payment already exists" or returns the result of the first call.
  3. Never credit a different amount. If the bank cannot execute on the locked terms (the rate changed, the quote expired), it refuses with an error rather than crediting another amount.
  4. Errors are either permanent or transient.
  5. Permanent errors cannot succeed on retry: beneficiary not found, compliance refusal, invalid data. Milkyway does not retry them.
  6. Transient errors are things like unavailability or a timeout. Milkyway retries delivery.

The adapter itself reports a permanent refusal of Pay to Milkyway, and the transfer becomes status 3 (failed) with the reason at once: a bank that refused a transfer when it was created answers Postcheck with "not found", which Milkyway reads as "not arrived yet". When the bank records a refusal later, after accepting the transfer, it must report status 3 with the reason via the webhook or on Postcheck. Otherwise the transfer goes to manual review on timeout (section 7). 5. Execution may be synchronous (final status at once) or asynchronous. Either way the outcome is confirmed via the webhook or Postcheck (section 7).

7. Status: polling and webhook

Milkyway learns the outcome of a payout in two ways:

  • Polling (Postcheck). Milkyway periodically asks for the status. Mandatory for every bank.
  • Webhook. The bank notifies Milkyway as soon as the status changes. Optional but recommended: the outcome is known immediately rather than at the next poll.

Both carry the same data and follow the same rules. The webhook does not replace Postcheck: polling remains the safety net for a lost notification, and the Operator needs it for manual rechecks. For banks with a webhook, the polling interval is lengthened.

Code Status Meaning
0 pending The bank has not finished the payout yet.
1 done Funds credited to the beneficiary. Final.
2 cancelled The payout was cancelled (section 8). Final.
3 failed The payout was not made; no funds moved. Final.
4 cancel pending Cancellation requested, not yet complete.

Common rules

  1. For the final statuses 3 and 2 the bank provides a reason (error). Milkyway stores it for its operators; the sender sees only its meaning (for example "rejected"), never the text.
  2. For status 1 the bank may report the amount actually credited (credited_amount, credited_currency; optional). It must equal the payout amount (section 6). Milkyway records it, and the Operator compares it with the instruction when checking the credited amount (Annex 5 §5.10.4); a bank that does not report it confirms the credited amounts with a statement instead.
  3. The bank sends only codes 0–4. Any other code is ignored and logged.
  4. A final status is irreversible. "Done" can only be changed by an explicit cancellation (section 8). A notification or answer that contradicts an already recorded final status is not applied and is investigated by the Operator.
  5. If no final status arrives within the maximum wait (by default up to 24 hours), the transfer goes to manual review by the Operator. Milkyway keeps rechecking it every 15 minutes for up to 3 days after creation.

7.1 Polling (Postcheck)

  1. The polling interval and the maximum wait are configurable per bank and service.
  2. A "payment not found" answer is not a refusal. The instruction may not have reached the bank yet, so Milkyway keeps polling.

7.2 Webhook

  1. When to send. On every payout status change. It is mandatory on transitions to 1, 2 and 3, and optional for 0 and 4.
  2. Where. POST /payments/v1/payout-status on the Milkyway partner API. The base URL is the same as for the partner API and is issued at onboarding (section 11).
  3. What. The same fields as the Postcheck response, plus a unique event_id and the event time occurred_at.
  4. Authentication. The bank obtains client credentials in Planet9 Keycloak, as for the partner API, and sends Authorization: Bearer <token>. Notifications without a valid token are rejected. A bank may only notify about its own transfers.
  5. Acknowledgement. Milkyway answers 2xx once it has durably stored the notification. On any other answer or a timeout, the bank retries with increasing delays. Recommended schedule: 1 min, 5 min, 15 min, then hourly, for at least 24 hours.
  6. Duplicates and ordering. The same notification may arrive more than once and out of order. Milkyway processes them idempotently: duplicates by event_id are ignored, and an intermediate status never overwrites a final one already received.
  7. Verification. Milkyway applies a notification by the same rules as a Postcheck answer, and may additionally confirm it with a Postcheck request.

8. Cancel (optional)

  • A cancellation is possible only for a done transfer, within the window (3 hours from creation by default), and only before the transfer is included in netting.
  • The bank answers with status 2 (cancelled synchronously) or 4 (cancel pending; the outcome is confirmed via the webhook or Postcheck).
  • If the bank does not support cancellation, Milkyway refuses cancellation requests for that bank's transfers.

9. Errors

Code Kind When
recipient_not_found permanent The beneficiary does not exist or cannot receive the payout.
unsupported_currency permanent The send or payout currency is not supported.
validation_error permanent Invalid or incomplete payer or beneficiary details (or data), or an amount outside limits.
compliance_rejected permanent KYC or sanctions refusal.
limit_exceeded permanent Beneficiary or bank limits exceeded.
duplicate — A payment with this id already exists (repeated Pay delivery).
rate_changed permanent The rate changed; cannot execute on the quote.
quote_expired permanent The quote has expired.
not_found — Postcheck or Cancel: no payment with this id.
service_unavailable transient The bank's service is temporarily unavailable.
internal_error transient Internal bank error.

The sender learns only what the code means: the bank is unavailable (retry later), the payment was rejected, or the request must be corrected. The error text (message) is stored for Milkyway's operators and is never shown to the sender; it still must not contain personal data.

10. Settlement and reconciliation

  • Each completed transfer gives the receiving bank a claim for S in the settlement currency. Cancelled transfers are excluded.
  • Claims are netted per currency between participants according to the agreed cut-off time. The resulting net amounts are moved through the Settlement Center on Milkyway's instructions.
  • Milkyway reconciles the bank's statements against the instructions. Discrepancies are investigated by the Operator together with the bank.

11. Reference REST API

Below is a standard HTTP interface the bank can implement. The full reference is on the docs portal: Receiving Bank API (OpenAPI 3 source: receiving-bank-api.yaml).

General rules

  • Transport. HTTPS (TLS 1.2+); mTLS is recommended.
  • Authentication. OAuth 2.0 client credentials. The bank issues Planet9 a client_id and client_secret, and Milkyway sends Authorization: Bearer <token>. Another scheme can be agreed.
  • Format.
  • JSON, UTF-8.
  • Amounts are numbers with the currency's minor-unit precision.
  • Times are ISO 8601 in UTC.
  • Currencies are ISO 4217.
  • Idempotency. POST /payments carries an Idempotency-Key header equal to the transfer ID.
  • Errors. An HTTP status plus a body {"code": "...", "message": "..."} with the codes from section 9.
Method Path Operation
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 (optional)

The webhook works in the opposite direction: the bank calls it and Milkyway receives it. The Milkyway partner API base URL is issued at onboarding.

Method Path (Milkyway side) Operation
POST /payments/v1/payout-status 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 is the beneficiary's masked name, for the sender's confirmation. It is optional.

Pay: POST /v1/payments with the header 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"
}

The response is 202 Accepted, or 200 OK for synchronous execution:

{ "transaction_id": "42", "payment_id": "SPT-778812", "status": 0 }

A retry with the same Idempotency-Key returns the same response. The same key with a different body gets 409 duplicate.

Postcheck: GET /v1/payments/42

{ "transaction_id": "42", "payment_id": "SPT-778812", "status": 1, "error": "",
  "credited_amount": 10769.14, "credited_currency": "TJS" }

If the payment is not found, the bank returns 404 with {"code": "not_found"}.

Cancel: POST /v1/payments/42/cancel

{ "transaction_id": "42", "status": 4 }

Status webhook: bank → POST /payments/v1/payout-status

Send the header Authorization: Bearer <token> (a Planet9 Keycloak token).

{
  "event_id": "b7f1c2e0-5a7d-4c1e-9d1a-3f2e8c6b9a01",
  "occurred_at": "2026-10-10T09:30:41Z",
  "transaction_id": "42",
  "payment_id": "SPT-778812",
  "status": 1,
  "error": ""
}

A 200 OK answer means the notification was accepted; the body is the transfer's resulting status, e.g. {"transaction_id": 42, "status": 1}. 400 means the notification is malformed (retrying will not help), and 404 means the transfer is not found or belongs to another bank. On any other answer, the bank must retry.

12. Onboarding checklist

  • [ ] The list of services (wallet, card, …), send and payout currencies.
  • [ ] Which payer and beneficiary details each service needs: required and used fields of sender_info / recipient_info and the document kinds accepted (Planet9 publishes the service profile from them). data fields only if a service needs more.
  • [ ] How the rate is formed and for how long it is guaranteed.
  • [ ] The bank fee: amount, currency, conditions. It is borne by the beneficiary only.
  • [ ] Per-beneficiary and per-transaction limits.
  • [ ] Cancellation support and its conditions.
  • [ ] Precheck and Pay response times, and the recommended status-polling interval.
  • [ ] How status is delivered: polling, or polling plus webhook. For the webhook: Planet9 Keycloak credentials and the Milkyway partner API base URL.
  • [ ] Test environment and access: URL, credentials, test beneficiaries.
  • [ ] Escalation contacts for incidents.