Moja Switch Partner API (1.0.0-draft)

Corridor on the transacting routes. This was a closed enum (CA-TZ) and is now the same pattern-constrained string as CorridorCode.

It had to change. A closed enum in the contract is the same defect as a hardcoded corridor in a client: the corridor set is per-tenant entitlement data, it moves, and an enum makes every move a contract change and a client release. Published as an enum, a quote on any newer corridor was a schema violation rather than an entitlement question — which is not something the contract should have an opinion about.

Entitlement is the authority on what a given tenant may actually use (GET /corridors, which will list it, is planned). A corridor you are not entitled to is 403 corridor_not_entitled; a syntactically valid code that does not exist is 422 unsupported_corridor. Treat the value as an opaque server-supplied string: do not enumerate it, do not switch on it beyond what discovery told you, and do not ship a build that breaks when the set changes.

Decimal-string amount, used by the original partner operations (POST /quotes, POST /payments, GET /payments/{payment_id}). Its value pattern caps the world at two decimal places, which is why the newer end-user operations use MinorUnitAmount instead. Unchanged here: swapping the representation on an existing operation would be a breaking /v1 change.

The locked payout amount. Echoes the partner's fx.receive_amount when supplied, otherwise derived from send_amount × the partner's fx.rate (BYO-FX).

The partner's locked send→receive rate, echoed back (receive units per 1 send unit). Not a Moja-computed or marked-up rate. Off-production, when the partner omitted fx, this is the Moja-derived sandbox/dev rate (never production pricing).

Quote cost breakdown, always denominated in the SEND currency (what the quote costs the sender). Both fields are always present and may be zero amounts. platform_fee is the flat platform fee (may be zero). fx_markup is the margin inside fx_rate on a Moja Switch FX quote; it is zero on a BYO-FX quote, where the partner owns the customer-facing rate and Moja adds no spread. For your systems, not for an end user.

Required. The cost disclosure for this quote. Required so that a client cannot render a quote without it.

When the locked rate stops being valid. A platform_priced rate MUST NOT be displayed to an end customer after this instant; re-quote instead of extending it client-side.

Who priced this quote. Absent on quotes issued before this field existed; treat an absent value as client_provided.

Partner-facing payment lifecycle status. PROCESSING is a safe generic "in progress" value: the platform presents any internal-only substate (e.g. a compensation state) that is not one of the enumerated lifecycle stages as PROCESSING, so a partner never observes a raw internal state. For a transfer, PROCESSING is non-terminal and transient: a subsequent poll or webhook will report a terminal status. Clients should treat any unrecognised value as a non-terminal state. Collection statuses are published but not emitted yet. CANCEL_REQUESTED, COLLECTED, PAYOUT_SCHEDULED, PAID_OUT and REVERSED belong to the kind: collection lifecycle. The platform records them, but the partner status mapping does not pass them through yet; each reads PROCESSING. A collection reports CREATED, VALIDATING, COMPLIANCE_CHECK, COLLECTING, FAILED and CANCELLED verbatim. A collection that is paid, scheduled into a payout, paid out or reversed reads PROCESSING and today never reaches a later terminal status. Reconcile collected funds from GET /payouts (each payout member carries the collection reference). Accept all five values now so that enabling them is not a client release.

Decimal-string amount, used by the original partner operations (POST /quotes, POST /payments, GET /payments/{payment_id}). Its value pattern caps the world at two decimal places, which is why the newer end-user operations use MinorUnitAmount instead. Unchanged here: swapping the representation on an existing operation would be a breaking /v1 change.

Corridor on the transacting routes. This was a closed enum (CA-TZ) and is now the same pattern-constrained string as CorridorCode.

It had to change. A closed enum in the contract is the same defect as a hardcoded corridor in a client: the corridor set is per-tenant entitlement data, it moves, and an enum makes every move a contract change and a client release. Published as an enum, a quote on any newer corridor was a schema violation rather than an entitlement question — which is not something the contract should have an opinion about.

Entitlement is the authority on what a given tenant may actually use (GET /corridors, which will list it, is planned). A corridor you are not entitled to is 403 corridor_not_entitled; a syntactically valid code that does not exist is 422 unsupported_corridor. Treat the value as an opaque server-supplied string: do not enumerate it, do not switch on it beyond what discovery told you, and do not ship a build that breaks when the set changes.

The locked payout amount, echoing the partner's client-provided FX (BYO-FX). Present once FX is locked.

The partner's locked send→receive rate, echoed back (not Moja-computed or marked up). Present once FX is locked.

The partner's declared-rate identifier (fx.rate_id), echoed back for reconciliation. Present only when the partner supplied it at create. Pure metadata — it never affected how the payment was priced or executed.

The quote this payment was priced on (for a Moja Switch FX tenant, the single-use quote it paid on), for reconciliation. Absent when the payment carried no quote.

FX provenance: which FX model priced this payment, and what Moja Switch applied. Present whenever the tenant has an FX model configured. It answers two questions from a single record:

1. Was the FX Moja Switch's (internal) or the client's own (external)? — model.
2. What margin did Moja Switch apply? — margin_bps / margin_minor for Moja Switch FX; nothing for BYO-FX, because Moja Switch adds no margin to a client's own FX.

For MOJA_SWITCH_FX Moja Switch itself obtained the reference rate and applied the tenant's commercial margin for the corridor; every figure comes from the quote Moja Switch priced, not from the client. For BYO_FX the client owns its FX lifecycle and only model is recorded — the margin, reference and rate fields are absent by construction (and forbidden by a database constraint).

⛔ For your systems and Moja staff only — never render to an end user. The end user is shown the amount to send and the all-in rate; the margin percentage is never disclosed to them.

The end user this payment was originated for. Present only when the payment was created with end_user_id; absent for payments created with an inline sender. It is the filter key for GET /payments?end_user_id=.

The saved recipient this payment was sent to. Present only when the payment was created with recipient_id. payout is still returned in full, resolved from that recipient — the response shape does not change with the request shape.

⛔ Integrator-only — never render to an end user. The rail identities behind a payment. A rail name tells a customer which provider handled their money, which is not theirs to know, changes without notice, and turns a routing decision into a support conversation. Use it for reconciliation and diagnostics; do not pass it to a consumer surface, a push payload or a receipt.

Why a payment failed, for the integrator. ⛔ message and stage are integrator-only and must never reach an end user. stage names an internal processing stage — including compliance — and telling a customer their payment failed at the compliance stage both discloses a control and, where the control is a sanctions or fraud rule, may be unlawful to say. Use funds_taken and return_state to tell a customer what happened to their money, and a generic did-not-complete message for the rest.

How the sender is funding this payment, as requested at create. Present for INTERAC_REQUEST payments.

What the sender must do to pay. Present for INTERAC_REQUEST payments; reference is the Interac reference once the request is made.

Present for INTERAC_REQUEST payments. Not reliable on a kind: collection today: it reads false even after the payer's funds were collected; use GET /payouts for a collection. Whether the sender's money left their account. Consumer-safe and the only correct basis for telling someone what happened to their funds:

• false — nothing was collected. "Your money was not taken."
• true — funds were collected. If the payment did not complete, they are being returned; read return_state for where that is.

A terminal status alone cannot answer this question, which is why this field exists. Do not derive it from failure.stage — that field names an internal stage, it is integrator-only, and inferring consumer copy from it is precisely the leak this contract forbids.

🔲 Planned — not emitted. Whether collected funds are on their way back to the sender. Absent or NONE when nothing was collected or nothing is being returned.

🔲 Planned — not emitted. An attention signal, deliberately with no cause attached. true means this payment has been in progress longer than it should be and warrants telling the customer so — and it means nothing else.

It is a boolean rather than a reason code on purpose: a boolean cannot leak which internal state, rail, counterparty or compliance step produced it, so a client cannot accidentally build copy that does. The platform derives it from dwell time against the expected duration of whatever stage the payment is in; the stage itself is not exposed and will not be.

Pair it with a support entry point. Do not present it as a failure, do not promise a completion time, and do not ask the customer to do anything — there is nothing for them to do.

🔲 Planned — not emitted. Whether POST /payments/{payment_id}/cancel would be accepted right now. Read this rather than inferring eligibility from status: the rule is a platform decision that has already changed once, and a client that re-implements it will offer a cancel button that fails, or hide one that would have worked. It is a point-in-time answer — a cancel may still return 409 if the payment advances between the read and the call, which a client must handle rather than treat as a bug.

Partner-facing payment lifecycle status. PROCESSING is a safe generic "in progress" value: the platform presents any internal-only substate (e.g. a compensation state) that is not one of the enumerated lifecycle stages as PROCESSING, so a partner never observes a raw internal state. For a transfer, PROCESSING is non-terminal and transient: a subsequent poll or webhook will report a terminal status. Clients should treat any unrecognised value as a non-terminal state. Collection statuses are published but not emitted yet. CANCEL_REQUESTED, COLLECTED, PAYOUT_SCHEDULED, PAID_OUT and REVERSED belong to the kind: collection lifecycle. The platform records them, but the partner status mapping does not pass them through yet; each reads PROCESSING. A collection reports CREATED, VALIDATING, COMPLIANCE_CHECK, COLLECTING, FAILED and CANCELLED verbatim. A collection that is paid, scheduled into a payout, paid out or reversed reads PROCESSING and today never reaches a later terminal status. Reconcile collected funds from GET /payouts (each payout member carries the collection reference). Accept all five values now so that enabling them is not a client release.

Decimal-string amount, used by the original partner operations (POST /quotes, POST /payments, GET /payments/{payment_id}). Its value pattern caps the world at two decimal places, which is why the newer end-user operations use MinorUnitAmount instead. Unchanged here: swapping the representation on an existing operation would be a breaking /v1 change.

Corridor on the transacting routes. This was a closed enum (CA-TZ) and is now the same pattern-constrained string as CorridorCode.

It had to change. A closed enum in the contract is the same defect as a hardcoded corridor in a client: the corridor set is per-tenant entitlement data, it moves, and an enum makes every move a contract change and a client release. Published as an enum, a quote on any newer corridor was a schema violation rather than an entitlement question — which is not something the contract should have an opinion about.

Entitlement is the authority on what a given tenant may actually use (GET /corridors, which will list it, is planned). A corridor you are not entitled to is 403 corridor_not_entitled; a syntactically valid code that does not exist is 422 unsupported_corridor. Treat the value as an opaque server-supplied string: do not enumerate it, do not switch on it beyond what discovery told you, and do not ship a build that breaks when the set changes.

The locked payout amount, echoing the partner's client-provided FX (BYO-FX). Present once FX is locked.

The partner's locked send→receive rate, echoed back (not Moja-computed or marked up). Present once FX is locked.

The partner's declared-rate identifier (fx.rate_id), echoed back for reconciliation. Present only when the partner supplied it at create. Pure metadata — it never affected how the payment was priced or executed.

The quote this payment was priced on (for a Moja Switch FX tenant, the single-use quote it paid on), for reconciliation. Absent when the payment carried no quote.

FX provenance: which FX model priced this payment, and what Moja Switch applied. Present whenever the tenant has an FX model configured. It answers two questions from a single record:

1. Was the FX Moja Switch's (internal) or the client's own (external)? — model.
2. What margin did Moja Switch apply? — margin_bps / margin_minor for Moja Switch FX; nothing for BYO-FX, because Moja Switch adds no margin to a client's own FX.

For MOJA_SWITCH_FX Moja Switch itself obtained the reference rate and applied the tenant's commercial margin for the corridor; every figure comes from the quote Moja Switch priced, not from the client. For BYO_FX the client owns its FX lifecycle and only model is recorded — the margin, reference and rate fields are absent by construction (and forbidden by a database constraint).

⛔ For your systems and Moja staff only — never render to an end user. The end user is shown the amount to send and the all-in rate; the margin percentage is never disclosed to them.

The end user this payment was originated for. Present only when the payment was created with end_user_id; absent for payments created with an inline sender. It is the filter key for GET /payments?end_user_id=.

The saved recipient this payment was sent to. Present only when the payment was created with recipient_id. payout is still returned in full, resolved from that recipient — the response shape does not change with the request shape.

⛔ Integrator-only — never render to an end user. The rail identities behind a payment. A rail name tells a customer which provider handled their money, which is not theirs to know, changes without notice, and turns a routing decision into a support conversation. Use it for reconciliation and diagnostics; do not pass it to a consumer surface, a push payload or a receipt.

Why a payment failed, for the integrator. ⛔ message and stage are integrator-only and must never reach an end user. stage names an internal processing stage — including compliance — and telling a customer their payment failed at the compliance stage both discloses a control and, where the control is a sanctions or fraud rule, may be unlawful to say. Use funds_taken and return_state to tell a customer what happened to their money, and a generic did-not-complete message for the rest.

How the sender is funding this payment, as requested at create. Present for INTERAC_REQUEST payments.

What the sender must do to pay. Present for INTERAC_REQUEST payments; reference is the Interac reference once the request is made.

Present for INTERAC_REQUEST payments. Not reliable on a kind: collection today: it reads false even after the payer's funds were collected; use GET /payouts for a collection. Whether the sender's money left their account. Consumer-safe and the only correct basis for telling someone what happened to their funds:

• false — nothing was collected. "Your money was not taken."
• true — funds were collected. If the payment did not complete, they are being returned; read return_state for where that is.

A terminal status alone cannot answer this question, which is why this field exists. Do not derive it from failure.stage — that field names an internal stage, it is integrator-only, and inferring consumer copy from it is precisely the leak this contract forbids.

🔲 Planned — not emitted. Whether collected funds are on their way back to the sender. Absent or NONE when nothing was collected or nothing is being returned.

🔲 Planned — not emitted. An attention signal, deliberately with no cause attached. true means this payment has been in progress longer than it should be and warrants telling the customer so — and it means nothing else.

It is a boolean rather than a reason code on purpose: a boolean cannot leak which internal state, rail, counterparty or compliance step produced it, so a client cannot accidentally build copy that does. The platform derives it from dwell time against the expected duration of whatever stage the payment is in; the stage itself is not exposed and will not be.

Pair it with a support entry point. Do not present it as a failure, do not promise a completion time, and do not ask the customer to do anything — there is nothing for them to do.

🔲 Planned — not emitted. Whether POST /payments/{payment_id}/cancel would be accepted right now. Read this rather than inferring eligibility from status: the rule is a platform decision that has already changed once, and a client that re-implements it will offer a cancel button that fails, or hide one that would have worked. It is a point-in-time answer — a cancel may still return 409 if the payment advances between the read and the call, which a client must handle rather than treat as a bug.

Payments, ordered created_at DESC, id DESC.

Whether a further page exists. The only correct pagination predicate — an empty data array is not the terminator, and neither is a short page.

Partner-facing payment lifecycle status. PROCESSING is a safe generic "in progress" value: the platform presents any internal-only substate (e.g. a compensation state) that is not one of the enumerated lifecycle stages as PROCESSING, so a partner never observes a raw internal state. For a transfer, PROCESSING is non-terminal and transient: a subsequent poll or webhook will report a terminal status. Clients should treat any unrecognised value as a non-terminal state. Collection statuses are published but not emitted yet. CANCEL_REQUESTED, COLLECTED, PAYOUT_SCHEDULED, PAID_OUT and REVERSED belong to the kind: collection lifecycle. The platform records them, but the partner status mapping does not pass them through yet; each reads PROCESSING. A collection reports CREATED, VALIDATING, COMPLIANCE_CHECK, COLLECTING, FAILED and CANCELLED verbatim. A collection that is paid, scheduled into a payout, paid out or reversed reads PROCESSING and today never reaches a later terminal status. Reconcile collected funds from GET /payouts (each payout member carries the collection reference). Accept all five values now so that enabling them is not a client release.

Decimal-string amount, used by the original partner operations (POST /quotes, POST /payments, GET /payments/{payment_id}). Its value pattern caps the world at two decimal places, which is why the newer end-user operations use MinorUnitAmount instead. Unchanged here: swapping the representation on an existing operation would be a breaking /v1 change.

Corridor on the transacting routes. This was a closed enum (CA-TZ) and is now the same pattern-constrained string as CorridorCode.

It had to change. A closed enum in the contract is the same defect as a hardcoded corridor in a client: the corridor set is per-tenant entitlement data, it moves, and an enum makes every move a contract change and a client release. Published as an enum, a quote on any newer corridor was a schema violation rather than an entitlement question — which is not something the contract should have an opinion about.

Entitlement is the authority on what a given tenant may actually use (GET /corridors, which will list it, is planned). A corridor you are not entitled to is 403 corridor_not_entitled; a syntactically valid code that does not exist is 422 unsupported_corridor. Treat the value as an opaque server-supplied string: do not enumerate it, do not switch on it beyond what discovery told you, and do not ship a build that breaks when the set changes.

The locked payout amount, echoing the partner's client-provided FX (BYO-FX). Present once FX is locked.

The partner's locked send→receive rate, echoed back (not Moja-computed or marked up). Present once FX is locked.

The partner's declared-rate identifier (fx.rate_id), echoed back for reconciliation. Present only when the partner supplied it at create. Pure metadata — it never affected how the payment was priced or executed.

The quote this payment was priced on (for a Moja Switch FX tenant, the single-use quote it paid on), for reconciliation. Absent when the payment carried no quote.

FX provenance: which FX model priced this payment, and what Moja Switch applied. Present whenever the tenant has an FX model configured. It answers two questions from a single record:

1. Was the FX Moja Switch's (internal) or the client's own (external)? — model.
2. What margin did Moja Switch apply? — margin_bps / margin_minor for Moja Switch FX; nothing for BYO-FX, because Moja Switch adds no margin to a client's own FX.

For MOJA_SWITCH_FX Moja Switch itself obtained the reference rate and applied the tenant's commercial margin for the corridor; every figure comes from the quote Moja Switch priced, not from the client. For BYO_FX the client owns its FX lifecycle and only model is recorded — the margin, reference and rate fields are absent by construction (and forbidden by a database constraint).

⛔ For your systems and Moja staff only — never render to an end user. The end user is shown the amount to send and the all-in rate; the margin percentage is never disclosed to them.

The end user this payment was originated for. Present only when the payment was created with end_user_id; absent for payments created with an inline sender. It is the filter key for GET /payments?end_user_id=.

The saved recipient this payment was sent to. Present only when the payment was created with recipient_id. payout is still returned in full, resolved from that recipient — the response shape does not change with the request shape.

⛔ Integrator-only — never render to an end user. The rail identities behind a payment. A rail name tells a customer which provider handled their money, which is not theirs to know, changes without notice, and turns a routing decision into a support conversation. Use it for reconciliation and diagnostics; do not pass it to a consumer surface, a push payload or a receipt.

Why a payment failed, for the integrator. ⛔ message and stage are integrator-only and must never reach an end user. stage names an internal processing stage — including compliance — and telling a customer their payment failed at the compliance stage both discloses a control and, where the control is a sanctions or fraud rule, may be unlawful to say. Use funds_taken and return_state to tell a customer what happened to their money, and a generic did-not-complete message for the rest.

How the sender is funding this payment, as requested at create. Present for INTERAC_REQUEST payments.

What the sender must do to pay. Present for INTERAC_REQUEST payments; reference is the Interac reference once the request is made.

Present for INTERAC_REQUEST payments. Not reliable on a kind: collection today: it reads false even after the payer's funds were collected; use GET /payouts for a collection. Whether the sender's money left their account. Consumer-safe and the only correct basis for telling someone what happened to their funds:

• false — nothing was collected. "Your money was not taken."
• true — funds were collected. If the payment did not complete, they are being returned; read return_state for where that is.

A terminal status alone cannot answer this question, which is why this field exists. Do not derive it from failure.stage — that field names an internal stage, it is integrator-only, and inferring consumer copy from it is precisely the leak this contract forbids.

🔲 Planned — not emitted. Whether collected funds are on their way back to the sender. Absent or NONE when nothing was collected or nothing is being returned.

🔲 Planned — not emitted. An attention signal, deliberately with no cause attached. true means this payment has been in progress longer than it should be and warrants telling the customer so — and it means nothing else.

It is a boolean rather than a reason code on purpose: a boolean cannot leak which internal state, rail, counterparty or compliance step produced it, so a client cannot accidentally build copy that does. The platform derives it from dwell time against the expected duration of whatever stage the payment is in; the stage itself is not exposed and will not be.

Pair it with a support entry point. Do not present it as a failure, do not promise a completion time, and do not ask the customer to do anything — there is nothing for them to do.

🔲 Planned — not emitted. Whether POST /payments/{payment_id}/cancel would be accepted right now. Read this rather than inferring eligibility from status: the rule is a platform decision that has already changed once, and a client that re-implements it will offer a cancel button that fails, or hide one that would have worked. It is a point-in-time answer — a cancel may still return 409 if the payment advances between the read and the call, which a client must handle rather than treat as a bug.

Partner-facing payment lifecycle status. PROCESSING is a safe generic "in progress" value: the platform presents any internal-only substate (e.g. a compensation state) that is not one of the enumerated lifecycle stages as PROCESSING, so a partner never observes a raw internal state. For a transfer, PROCESSING is non-terminal and transient: a subsequent poll or webhook will report a terminal status. Clients should treat any unrecognised value as a non-terminal state. Collection statuses are published but not emitted yet. CANCEL_REQUESTED, COLLECTED, PAYOUT_SCHEDULED, PAID_OUT and REVERSED belong to the kind: collection lifecycle. The platform records them, but the partner status mapping does not pass them through yet; each reads PROCESSING. A collection reports CREATED, VALIDATING, COMPLIANCE_CHECK, COLLECTING, FAILED and CANCELLED verbatim. A collection that is paid, scheduled into a payout, paid out or reversed reads PROCESSING and today never reaches a later terminal status. Reconcile collected funds from GET /payouts (each payout member carries the collection reference). Accept all five values now so that enabling them is not a client release.

Decimal-string amount, used by the original partner operations (POST /quotes, POST /payments, GET /payments/{payment_id}). Its value pattern caps the world at two decimal places, which is why the newer end-user operations use MinorUnitAmount instead. Unchanged here: swapping the representation on an existing operation would be a breaking /v1 change.

Corridor on the transacting routes. This was a closed enum (CA-TZ) and is now the same pattern-constrained string as CorridorCode.

It had to change. A closed enum in the contract is the same defect as a hardcoded corridor in a client: the corridor set is per-tenant entitlement data, it moves, and an enum makes every move a contract change and a client release. Published as an enum, a quote on any newer corridor was a schema violation rather than an entitlement question — which is not something the contract should have an opinion about.

Entitlement is the authority on what a given tenant may actually use (GET /corridors, which will list it, is planned). A corridor you are not entitled to is 403 corridor_not_entitled; a syntactically valid code that does not exist is 422 unsupported_corridor. Treat the value as an opaque server-supplied string: do not enumerate it, do not switch on it beyond what discovery told you, and do not ship a build that breaks when the set changes.

The locked payout amount, echoing the partner's client-provided FX (BYO-FX). Present once FX is locked.

The partner's locked send→receive rate, echoed back (not Moja-computed or marked up). Present once FX is locked.

The partner's declared-rate identifier (fx.rate_id), echoed back for reconciliation. Present only when the partner supplied it at create. Pure metadata — it never affected how the payment was priced or executed.

The quote this payment was priced on (for a Moja Switch FX tenant, the single-use quote it paid on), for reconciliation. Absent when the payment carried no quote.

FX provenance: which FX model priced this payment, and what Moja Switch applied. Present whenever the tenant has an FX model configured. It answers two questions from a single record:

1. Was the FX Moja Switch's (internal) or the client's own (external)? — model.
2. What margin did Moja Switch apply? — margin_bps / margin_minor for Moja Switch FX; nothing for BYO-FX, because Moja Switch adds no margin to a client's own FX.

For MOJA_SWITCH_FX Moja Switch itself obtained the reference rate and applied the tenant's commercial margin for the corridor; every figure comes from the quote Moja Switch priced, not from the client. For BYO_FX the client owns its FX lifecycle and only model is recorded — the margin, reference and rate fields are absent by construction (and forbidden by a database constraint).

⛔ For your systems and Moja staff only — never render to an end user. The end user is shown the amount to send and the all-in rate; the margin percentage is never disclosed to them.

The end user this payment was originated for. Present only when the payment was created with end_user_id; absent for payments created with an inline sender. It is the filter key for GET /payments?end_user_id=.

The saved recipient this payment was sent to. Present only when the payment was created with recipient_id. payout is still returned in full, resolved from that recipient — the response shape does not change with the request shape.

⛔ Integrator-only — never render to an end user. The rail identities behind a payment. A rail name tells a customer which provider handled their money, which is not theirs to know, changes without notice, and turns a routing decision into a support conversation. Use it for reconciliation and diagnostics; do not pass it to a consumer surface, a push payload or a receipt.

Why a payment failed, for the integrator. ⛔ message and stage are integrator-only and must never reach an end user. stage names an internal processing stage — including compliance — and telling a customer their payment failed at the compliance stage both discloses a control and, where the control is a sanctions or fraud rule, may be unlawful to say. Use funds_taken and return_state to tell a customer what happened to their money, and a generic did-not-complete message for the rest.

How the sender is funding this payment, as requested at create. Present for INTERAC_REQUEST payments.

What the sender must do to pay. Present for INTERAC_REQUEST payments; reference is the Interac reference once the request is made.

Present for INTERAC_REQUEST payments. Not reliable on a kind: collection today: it reads false even after the payer's funds were collected; use GET /payouts for a collection. Whether the sender's money left their account. Consumer-safe and the only correct basis for telling someone what happened to their funds:

• false — nothing was collected. "Your money was not taken."
• true — funds were collected. If the payment did not complete, they are being returned; read return_state for where that is.

A terminal status alone cannot answer this question, which is why this field exists. Do not derive it from failure.stage — that field names an internal stage, it is integrator-only, and inferring consumer copy from it is precisely the leak this contract forbids.

🔲 Planned — not emitted. Whether collected funds are on their way back to the sender. Absent or NONE when nothing was collected or nothing is being returned.

🔲 Planned — not emitted. An attention signal, deliberately with no cause attached. true means this payment has been in progress longer than it should be and warrants telling the customer so — and it means nothing else.

It is a boolean rather than a reason code on purpose: a boolean cannot leak which internal state, rail, counterparty or compliance step produced it, so a client cannot accidentally build copy that does. The platform derives it from dwell time against the expected duration of whatever stage the payment is in; the stage itself is not exposed and will not be.

Pair it with a support entry point. Do not present it as a failure, do not promise a completion time, and do not ask the customer to do anything — there is nothing for them to do.

🔲 Planned — not emitted. Whether POST /payments/{payment_id}/cancel would be accepted right now. Read this rather than inferring eligibility from status: the rule is a platform decision that has already changed once, and a client that re-implements it will offer a cancel button that fails, or hide one that would have worked. It is a point-in-time answer — a cancel may still return 409 if the payment advances between the read and the call, which a client must handle rather than treat as a bug.

Human-quotable reference for this receipt. Stable for the life of the payment — a re-fetch returns the same number, so a user reading it to support and a user reading it from a saved PDF agree.

The payment status at issue time. A receipt is only issued from COMPLETED, SETTLED or RECONCILED.

A corridor identifier, <send ISO 3166-1 alpha-2>-<receive ISO 3166-1 alpha-2>. Treat it as an opaque server-supplied string: the set is data (GET /corridors) and per-partner entitlement, not a constant your client enumerates, so a client that renders whatever discovery returns gains a corridor without a release. The Corridor schema used on the transacting routes is now this same shape — the two agree, and neither is a closed set.

What the sender paid, in integer minor units of the send currency.

The beneficiary.

The partner's own reference for the payment, echoed back.

Present when the payment was originated by an end user.

The amount delivered, in integer minor units of the receive currency, with that currency's exponent carried alongside it. A zero-decimal receive currency therefore cannot arrive here with cents attached.

The rate applied to this payment, echoed back.

What the transfer cost the sender, denominated in the SEND currency. The same breakdown as QuoteFees — platform fees only, no FX markup under BYO-FX — expressed in integer minor units. It is a separate schema rather than a reuse of QuoteFees because QuoteFees is part of the existing POST /quotes response and changing its representation would be a breaking /v1 change.

Display name of the originator, as held by the platform. Present only where the tenant supplied one.

A corridor identifier, <send ISO 3166-1 alpha-2>-<receive ISO 3166-1 alpha-2>. Treat it as an opaque server-supplied string: the set is data (GET /corridors) and per-partner entitlement, not a constant your client enumerates, so a client that renders whatever discovery returns gains a corridor without a release. The Corridor schema used on the transacting routes is now this same shape — the two agree, and neither is a closed set.

Receive-currency units per one send-currency unit.

The reference-data provider.

When false, the client SHALL disable every send affordance and SHALL keep read and support surfaces reachable. A customer with a transfer in flight still needs to see it and still needs to reach support.

How long this answer may be cached. A short value is the point: this is the control that has to arrive quickly when it changes.

Consumer-safe text to show when money operations are disabled. Set by the platform so the wording is not invented per client. It SHALL NOT name a rail, a provider, a compliance stage, or a cause.

The lowest client version permitted to move money, as the client's own version string. A client below it SHALL disable money operations and prompt the customer to update, independently of money_operations_enabled.