Payment Solution — Client API (1.0.0)

A decimal money amount. Sent as a JSON number (a JSON string parses too); returned as a JSON number that preserves the stored scale (25.00, not 25). At most 17 integer digits and 2 fraction digits.

A client that does arithmetic on these should read them as decimal strings from the raw body rather than through a double — and must never re-serialize a callback body it intends to verify.

ISO-4217, uppercase.

A payment method token from GET /v1/payment-methods. The set is not fixed by the platform — it is whatever the brand's configured adapters drive (CARD, BANK_WIRE, BANK_TRANSFER, CRYPTO, …). Never hard-code it.

Pin the operation to one provider code. Omitted = the platform routes by the brand's method rules, which is the normal case.

Your end-user reference. The platform holds no user accounts, so this is the only identity a transaction carries. Echoed on every view and callback.

Your own reference for this operation, echoed back everywhere. Note that this is not the idempotency mechanism — it is not checked for uniqueness. Use Idempotency-Key for that.

ISO-3166-1 alpha-2. Required when requiredRequestFields.payin for the routed option contains country; otherwise it only narrows routing.

Where the PSP sends the end user back after the hosted page. Required when requiredRequestFields.payin contains returnUrl — several adapters cannot open a hosted page without one, and omitting it is refused with 400 MISSING_REQUEST_FIELDS rather than costing you a FAILED transaction.

A decimal money amount. Sent as a JSON number (a JSON string parses too); returned as a JSON number that preserves the stored scale (25.00, not 25). At most 17 integer digits and 2 fraction digits.

A client that does arithmetic on these should read them as decimal strings from the raw body rather than through a double — and must never re-serialize a callback body it intends to verify.

A method token from GET /v1/payment-methods whose row has supportsPayouts: true. A PSP's payin and payout method sets are often different.

The account being paid — an IBAN, a domestic account number, a wallet account, a crypto address. What it is for a given (method, currency) is published as destinationKind on GET /v1/payment-methods; label your form from that rather than assuming a shape.

Stored encrypted under the brand key; only destinationMasked (head + tail) is readable afterwards.

Omit it only for a method flagged hostedPayout, where the PSP collects the destination on its own page and answers with a redirectUrl. Any other method without one is refused (400 DESTINATION_REQUIRED); a hosted method with one is also refused (400 DESTINATION_NOT_ACCEPTED), because the adapter would drop it while the platform had already encrypted and stored whatever you sent.

The routing code that completes destination where the account number does not route itself — a UK sort code on Faster Payments. Digits, optionally separated by spaces or dashes as a human would type them (12-34-56); the adapter normalizes the separators away.

Send it exactly when requiresDestinationBankCode is true for this (method, currency). Missing where required is 400 DESTINATION_BANK_CODE_REQUIRED; present on a hosted method is 400 DESTINATION_NOT_ACCEPTED, since half a destination is still a destination.

Stored encrypted and never echoed back — a sort code names a branch, not an account, so there is nothing in it worth displaying.

Where the end user returns from a hosted payout page.

Public id of the COMPLETED payin to refund. Anything else — another type, another status, another brand — is refused.

Identical to the X-PS-Event header. Ignore events you do not know rather than failing — but do not silently funnel transaction.reversed into a status_changed handler.

The transaction this one derives from — the refunded payin, or the movement a reversal compensates. Present on every payload that has a parent, not only on reversals.

• PAYIN — money in, created by POST /v1/payins.
• PAYOUT — money out, created by POST /v1/payouts.
• REFUND — client-initiated return of a completed payin.
• REVERSAL — PSP-initiated compensation (returned payout, chargeback, recall, fraud claim, or a won chargeback moving the money back). The platform creates these on its own; a client can only observe them.

• CREATED — the row exists, the PSP has not answered yet. Almost never observed by a client, since a POST returns only after the PSP call; it survives only across a crash between persisting the row and applying the result.
• PENDING — waiting on the end user (a hosted page, or funds sent to a quoted address).
• PROCESSING — the PSP is executing it. Nothing for the client to do but wait for a callback.
• IN_DOUBT — an ambiguous provider failure: the PSP may or may not have accepted the operation. Never terminal. The platform reconciles it by querying the PSP, or a late webhook resolves it. Do not re-send the operation; retry the same Idempotency-Key or poll GET /v1/transactions/{publicId}.
• COMPLETED — settled. Terminal and final.
• FAILED — the PSP refused. Terminal.
• CANCELLED — cancelled before completion. Terminal and final.
• EXPIRED — the platform's housekeeping guess that an abandoned PENDING payin will never be paid. Terminal, but it is our guess rather than the PSP's answer, so a late PSP truth outranks it: EXPIRED may still become COMPLETED or FAILED.

The other exception to terminality: for some methods a PAYIN that FAILED on a PSP answer carries a provider-declared provisional window during which the PSP may still revise it to COMPLETED (slow open-banking rails do this). It is narrow on three axes at once — which adapter, which method, and for how long — and a client learns of it only by receiving the callback.

A decimal money amount. Sent as a JSON number (a JSON string parses too); returned as a JSON number that preserves the stored scale (25.00, not 25). At most 17 integer digits and 2 fraction digits.

A client that does arithmetic on these should read them as decimal strings from the raw body rather than through a double — and must never re-serialize a callback body it intends to verify.

Identical to the X-PS-Event header. Ignore events you do not know rather than failing — but do not silently funnel transaction.reversed into a status_changed handler.

The transaction this one derives from — the refunded payin, or the movement a reversal compensates. Present on every payload that has a parent, not only on reversals.

• PAYIN — money in, created by POST /v1/payins.
• PAYOUT — money out, created by POST /v1/payouts.
• REFUND — client-initiated return of a completed payin.
• REVERSAL — PSP-initiated compensation (returned payout, chargeback, recall, fraud claim, or a won chargeback moving the money back). The platform creates these on its own; a client can only observe them.

• CREATED — the row exists, the PSP has not answered yet. Almost never observed by a client, since a POST returns only after the PSP call; it survives only across a crash between persisting the row and applying the result.
• PENDING — waiting on the end user (a hosted page, or funds sent to a quoted address).
• PROCESSING — the PSP is executing it. Nothing for the client to do but wait for a callback.
• IN_DOUBT — an ambiguous provider failure: the PSP may or may not have accepted the operation. Never terminal. The platform reconciles it by querying the PSP, or a late webhook resolves it. Do not re-send the operation; retry the same Idempotency-Key or poll GET /v1/transactions/{publicId}.
• COMPLETED — settled. Terminal and final.
• FAILED — the PSP refused. Terminal.
• CANCELLED — cancelled before completion. Terminal and final.
• EXPIRED — the platform's housekeeping guess that an abandoned PENDING payin will never be paid. Terminal, but it is our guess rather than the PSP's answer, so a late PSP truth outranks it: EXPIRED may still become COMPLETED or FAILED.

The other exception to terminality: for some methods a PAYIN that FAILED on a PSP answer carries a provider-declared provisional window during which the PSP may still revise it to COMPLETED (slow open-banking rails do this). It is narrow on three axes at once — which adapter, which method, and for how long — and a client learns of it only by receiving the callback.

A decimal money amount. Sent as a JSON number (a JSON string parses too); returned as a JSON number that preserves the stored scale (25.00, not 25). At most 17 integer digits and 2 fraction digits.

A client that does arithmetic on these should read them as decimal strings from the raw body rather than through a double — and must never re-serialize a callback body it intends to verify.