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:
- 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.
- 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_infoformat (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
- 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.
- 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).
- 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). - Every deduction by the bank is declared explicitly in
recipient_fee, not hidden in a worse rate. The sender sees each component separately. - The response must arrive within the timeout. The default is 30 seconds; it is configurable per bank to accommodate long sanctions checks.
- When
expires_atis 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 thanmin(expires_at, Operator lifetime); the Operator lifetime defaults to 120 seconds.
4. Receiving-bank fee¶
- The receiving-bank fee is always paid by the beneficiary (BEN model). It is deducted from the payout.
- 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.
- 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.
- 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.
- the send currency (
- 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.
- If the fee would leave the beneficiary no positive amount, the transfer is rejected.
- 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 provisionalamount_credit. - If the bank can quote by payout amount, it answers with the rate and fee for it.
Otherwise it quotes by
amount_creditas 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
- Credit exactly
amount_debit. It is already net of every fee. Do not deduct anything further, and do not recompute the amount fromamount_credit. - Idempotency by
id. Instructions are delivered with an at-least-once guarantee, so the sameidmay arrive more than once. The bank must not credit twice. It answers "payment already exists" or returns the result of the first call. - 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.
- Errors are either permanent or transient.
- Permanent errors cannot succeed on retry: beneficiary not found, compliance refusal, invalid data. Milkyway does not retry them.
- 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
- For the final statuses
3and2the bank provides a reason (error). Milkyway stores it for its operators; the sender sees only its meaning (for example "rejected"), never the text. - For status
1the 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. - The bank sends only codes
0–4. Any other code is ignored and logged. - 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.
- 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)¶
- The polling interval and the maximum wait are configurable per bank and service.
- 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¶
- When to send. On every payout status change. It is mandatory on transitions to
1,2and3, and optional for0and4. - Where.
POST /payments/v1/payout-statuson the Milkyway partner API. The base URL is the same as for the partner API and is issued at onboarding (section 11). - What. The same fields as the Postcheck response, plus a unique
event_idand the event timeoccurred_at. - 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. - Acknowledgement. Milkyway answers
2xxonce 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. - Duplicates and ordering. The same notification may arrive more than once and out of
order. Milkyway processes them idempotently: duplicates by
event_idare ignored, and an intermediate status never overwrites a final one already received. - 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) or4(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_idandclient_secret, and Milkyway sendsAuthorization: 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 /paymentscarries anIdempotency-Keyheader 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_infoand the document kinds accepted (Planet9 publishes the service profile from them).datafields 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.