Before you start
- Your organization must be enabled for GBP. Until it is,
GET /v3/common/financial-accountsfails with403PAYOUT_CURRENCY_NOT_ENABLED, and a quote or payout fails with409PAYOUT_NOT_ENABLED, or with409CAPABILITY_NOT_ACTIVE while the capability never activates. - The recipient’s account needs the GBP-receiving capability, ACTIVE before you pay. Capabilities lists the id, and Be paid in pounds sterling lists the identity the recipient owes.
- GBP has no sending capability. A
senderon a quote or an INLINE payout fails with422SENDER_NOT_SUPPORTED. A FROM_QUOTE payout has nosenderfield, so sending one fails with400VALIDATION_BODY_FAILED. - Every
POSTneeds anIdempotency-Keyheader. See Idempotency.
Set up the account and payout address
Before you can pay, three things must be ACTIVE: the account you’re paying, its GBP-receiving capability, and the payout address for their bank account. Account model explains each status. You do this once. If the account and address already exist, skip to pricing the payout.1
Create the account
Create the account you’re paying, with the GBP-receiving capability, and keep the returned
acc_ id. An organization owes its legal name and registered country; an individual owes their name and country of residence. The capability starts PENDING; wait for common.account.capability_activated. You don’t need to wait to create the payout address, so do both at the same time.cURL
2
Create the payout address
Create a The UK name check runs during the call, so the response already shows its result in
BANK_ACCOUNT payout address for that acc_, with routingFamily set to GB_LOCAL, the sortCode, and the accountNumber. Send accountHolderName only if the bank account is in a different name from the account’s. The address always carries one: OpenFX copies the account’s legal name when you create it, freezes it, and every read returns it under bankAccount.accountHolderName.You can send both numbers as people usually write them. Spaces and hyphens are stripped, so the sort code 12-34-56 comes back as 123456. A six- or seven-digit account number is zero-padded to eight digits, so 1234567 comes back as 01234567. Any other length fails with 400 VALIDATION_BODY_FAILED, including the nine- and ten-digit numbers some banks issue, and details.issues[] names the field.cURL
verifications[], with mode COP_GB. Read the UK name check explains each result. If it’s NO_MATCH or BANK_ACCOUNT_NOT_FOUND, the address is already REJECTED. Otherwise it comes back PENDING while OpenFX finishes its own setup. Wait for payments.payout_address.activated or payments.payout_address.rejected, and continue only once the address is ACTIVE. payments.payout_address.verification_resolved also fires whenever a check reaches a result, including one that changes verifications[] without moving the status.Read the UK name check
The UK name check, Confirmation of Payee, compares the address’saccountHolderName with the name the receiving bank holds for the sort code and account number. It never returns the bank’s name, so registeredName is always null.
A REJECTED address can’t back a payout: quoting one fails with
409 PAYOUT_ADDRESS_REJECTED. An address still PENDING is quotable.
Price and create the payout
1
(Optional) List the financial accounts that can fund a GBP payout
Skip this if you already know the
finacc_ id. A GBP payout is funded from a GBP, USD, USDC, USDT, or EURC balance. A GBP balance pays without conversion, and the others are converted. Any other send currency fails with 422 QUOTE_SEND_CURRENCY_UNAVAILABLE.cURL
2
Quote the payout
Get a price before you create the payout. A quote moves no money. It returns a
pytqte_ id and, when the send currency differs from GBP, a rate locked until fxRates.expiresAt. A quote funded from your GBP balance is like for like: it carries no fxRates.expiresAt and doesn’t expire. Its rail is FPS.A single payout can receive at most £1,000,000. A larger receiveAmount is refused when you quote, with 422 AMOUNT_OUT_OF_RANGE, and error.details carries the bound.cURL
3
Create the payout from the quote
Create the payout with Besides the QUOTE entry,
type: "FROM_QUOTE" and the pytqte_ id. The payout keeps the quote’s rate and rail. type: "INLINE" is supported for GBP too: it prices and creates the payout in one call, taking the same fields the quote does. Don’t send a purpose: a GBP payout takes none, and sending one fails with 422 PURPOSE_INVALID. Memos covers receiverMemo.cURL
confirmations[] holds an AccountHolderNameConfirmation, whose type is ACCOUNT_HOLDER_NAME, with mode COP_GB. If the address’s latest check is a MATCH, the payout reuses it, so its verifiedAt is when the address was checked. Otherwise the check runs again and the entry shows the new result.A NO_MATCH or PENDING refuses the payout with 409 ACCOUNT_HOLDER_MISMATCH, as does any other blocking result the check can return. A BANK_ACCOUNT_NOT_FOUND refuses it with 409 PAYOUT_ADDRESS_BANK_ACCOUNT_NOT_FOUND, and the address becomes REJECTED. Either refusal records the payout FAILED with no confirmations[], returns no pyt_ id, and spends the quote: retrying that quote fails with 409 QUOTE_ALREADY_CONSUMED, so quote again.Confirming accepts a CLOSE_MATCH or an UNAVAILABLE. Cancel to decline it.4
Confirm the payout
Confirm the payout to accept everything in
confirmations[] and move it to ACCEPTED. Payouts covers confirming and cancelling in more detail.cURL
Memos
On FPS, areceiverMemo is 1 to 18 ASCII letters, digits, and spaces, the length of the Faster Payments reference. A memo of spaces alone is accepted. An empty string, a memo that is too long, and one that holds any other character each fail with 400 RECEIVER_MEMO_INVALID; an empty string is refused rather than replaced by the default. OpenFX never truncates it.
If you leave receiverMemo out, the payout uses the last 18 characters of its id. The payout pyt_Y6ZrY1JJvFqzaP3VsNojWN, for example, carries the memo Y1JJvFqzaP3VsNojWN.
Track settlement
After ACCEPTED, the payout settles in the background. See Payouts for each status and webhook. On an FPS payout,settlementTraceId.status reads UNSUPPORTED. Trace a payout with the receiving bank lists the key for every rail.
Testing in sandbox
In Sandbox, a GBP payout settles through a simulated provider, and you choose each outcome with a word in a name. Choose the name check result. Put one of these words in the payout address’saccountHolderName, or in the account’s name if you don’t send one. The check strips every character that isn’t a letter and compares what’s left, ignoring case, so “Bruno Match Ltd” is a NO_MATCH and “Invalid Partners” is a BANK_ACCOUNT_NOT_FOUND.
When a name holds more than one word, the first in this order wins: “NOMATCH”, then “CLOSEMATCH”, then “UNAVAILABLE”, then “INVALID”.
Every check also takes 1 to 5 seconds, and the create call waits for it. Add “SLOW” to make it take about 10 seconds longer, for example “CLOSEMATCH SLOW Ltd”; unlike the other words, “SLOW” is case-sensitive and must be uppercase. The result is the same each time the check runs, so a payout to the address gets the same result as its setup.
Reject the capability. An account whose name contains “REJECTED” has its GBP-receiving capability rejected instead of activated. Otherwise the capability activates within a few seconds.
Settle a payout. A confirmed payout moves to PROCESSING once it’s debited, then to PROCESSED 10 to 60 seconds later.
Common mistakes
- Sending a nine- or ten-digit account number. Only six- to eight-digit account numbers are accepted, and OpenFX doesn’t shorten longer ones.
- Naming a
senderor sending apurpose. A GBP payout takes neither. Remove them from the quote and from an INLINE payout; a FROM_QUOTE payout has nosenderfield, so one there is a400VALIDATION_BODY_FAILED rather than a422. - Sending a memo longer than 18 characters. It fails instead of being truncated. Shorten it, or leave it out to get the default.
- Expecting
registeredName. The UK name check never returns the bank’s name, so it’s always null. A NO_MATCH address can’t be fixed, only replaced. - Changing the name after BANK_ACCOUNT_NOT_FOUND. The sort code and account number reach no account, so check the numbers with the account holder, not the name.
- Confirming without reading
confirmations[]. A CLOSE_MATCH or UNAVAILABLE doesn’t block confirmation. The decision is yours.
What’s next
Payouts
The general payout flow.
Capabilities
What the GBP-receiving capability requires.
Payouts in EUR
Paying euro accounts over SEPA or SWIFT.
Payment Webhooks
Every payout and address event.