> ## Documentation Index
> Fetch the complete documentation index at: https://public-openfx.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Payouts to the UK

> Pay a UK bank account in GBP over Faster Payments: register the sort code and account number, read the UK name check, then price, create, and confirm the payout.

Pay a UK bank account in pounds sterling (GBP) over Faster Payments (FPS).

This guide covers only what's specific to GBP. For the general flow, see [Payouts](https://public-openfx.mintlify.site/v3/payouts). [Supported payout currencies](https://public-openfx.mintlify.site/v3/payouts#supported-payout-currencies) compares every payout currency side by side.

## Before you start

* Your organization must be enabled for GBP. Until it is, [`GET /v3/common/financial-accounts`](https://public-openfx.mintlify.site/v3/api-reference/payments/accounts/list-financial-accounts) fails with `403` PAYOUT\_CURRENCY\_NOT\_ENABLED, and a quote or payout fails with `409` PAYOUT\_NOT\_ENABLED, or with `409` CAPABILITY\_NOT\_ACTIVE while the capability never activates.
* The recipient's account needs the GBP-receiving capability, ACTIVE before you pay. [Capabilities](https://public-openfx.mintlify.site/v3/capabilities.md#the-capability-catalog) lists the id, and [Be paid in pounds sterling](https://public-openfx.mintlify.site/v3/capabilities.md#be-paid-in-pounds-sterling) lists the identity the recipient owes.
* GBP has no sending capability. A `sender` on a quote or an INLINE payout fails with `422` SENDER\_NOT\_SUPPORTED. A FROM\_QUOTE payout has no `sender` field, so sending one fails with `400` VALIDATION\_BODY\_FAILED.
* Every `POST` needs an `Idempotency-Key` header. See [Idempotency](https://public-openfx.mintlify.site/v3/idempotency.md#payments-endpoints).

## 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](https://public-openfx.mintlify.site/v3/account-model.md#the-shared-state-machine) explains each status. You do this once. If the account and address already exist, skip to [pricing the payout](#price-and-create-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`](https://public-openfx.mintlify.site/v3/webhooks/payments/accounts-webhooks/account-capability-activated). You don't need to wait to create the payout address, so do both at the same time.

```bash cURL theme={"theme":{"light":"poimandres","dark":"poimandres"}}
curl -X POST https://api.openfx.com/v3/common/accounts \
  -H "Authorization: Bearer $OPENFX_JWT" \
  -H "X-Request-Signature: $OPENFX_SIGNATURE" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "capabilities": ["cap_CgLwtEvHBaWUixEMH8RK7"],
    "identity": {
      "identityType": "ORGANIZATION",
      "organization": {
        "legalName": "Harbourline Analytics Ltd",
        "registeredAddress": { "country": "GB" }
      }
    }
  }'
```

**2. Create the payout address**

Create a `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.

```bash cURL theme={"theme":{"light":"poimandres","dark":"poimandres"}}
curl -X POST https://api.openfx.com/v3/payments/payout-addresses \
  -H "Authorization: Bearer $OPENFX_JWT" \
  -H "X-Request-Signature: $OPENFX_SIGNATURE" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "payoutAddressType": "BANK_ACCOUNT",
    "accountId": "acc_E9SH9LAmymn9qyhYszweYn",
    "bankAccount": { "routingFamily": "GB_LOCAL", "sortCode": "12-34-56", "accountNumber": "1234567" }
  }'
```

The UK name check runs during the call, so the response already shows its result in `verifications[]`, with `mode` COP\_GB. [Read the UK name check](#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`](https://public-openfx.mintlify.site/v3/webhooks/payments/addresses-webhooks/payout-address-activated) or [`payments.payout_address.rejected`](https://public-openfx.mintlify.site/v3/webhooks/payments/addresses-webhooks/payout-address-rejected), and continue only once the address is ACTIVE. [`payments.payout_address.verification_resolved`](https://public-openfx.mintlify.site/v3/webhooks/payments/addresses-webhooks/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's `accountHolderName` 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.

| `result` | On the payout address | On a payout |
| - | - | - |
| MATCH | Payable | Reused. The payout doesn't check again |
| CLOSE\_MATCH | Payable | Checked again. You accept the new result when you confirm the payout |
| UNAVAILABLE | Payable. The check got no answer, so it says nothing about the name, and `verifiedAt` is null | Checked again. You accept the new result when you confirm the payout |
| NO\_MATCH | REJECTED. Create a new address in the name the account is held in | Refused with `409` ACCOUNT\_HOLDER\_MISMATCH, and the address becomes REJECTED |
| BANK\_ACCOUNT\_NOT\_FOUND | REJECTED. No account exists at that sort code and account number, so the name was never compared. Create a new address with the corrected details | Refused with `409` PAYOUT\_ADDRESS\_BANK\_ACCOUNT\_NOT\_FOUND, and the address becomes REJECTED |

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.

```bash cURL theme={"theme":{"light":"poimandres","dark":"poimandres"}}
curl "https://api.openfx.com/v3/common/financial-accounts?receiveCurrency=GBP" \
  -H "Authorization: Bearer $OPENFX_JWT" \
  -H "X-Request-Signature: $OPENFX_SIGNATURE"
```

**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.

```bash cURL theme={"theme":{"light":"poimandres","dark":"poimandres"}}
curl -X POST https://api.openfx.com/v3/payments/payout-quotes \
  -H "Authorization: Bearer $OPENFX_JWT" \
  -H "X-Request-Signature: $OPENFX_SIGNATURE" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "financialAccountId": "finacc_SnLywp9FK9cyGuGE2H5nUU",
    "receiver": { "payoutAddressId": "pytadd_KkvrkAMeCNypkGVz69bVLb" },
    "sendAmount": "1000.00",
    "receiveCurrency": "GBP"
  }'
```

**3. Create the payout from the quote**

Create the payout with `type: "FROM_QUOTE"` and the `pytqte_` id. The payout keeps the quote's rate and rail. [`type: "INLINE"`](https://public-openfx.mintlify.site/v3/api-reference/payments/payouts/create-payout) 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](#memos) covers `receiverMemo`.

```bash cURL theme={"theme":{"light":"poimandres","dark":"poimandres"}}
curl -X POST https://api.openfx.com/v3/payments/payouts \
  -H "Authorization: Bearer $OPENFX_JWT" \
  -H "X-Request-Signature: $OPENFX_SIGNATURE" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "type": "FROM_QUOTE", "quoteId": "pytqte_Ez9FrrRTnELFSSWTDem5mT", "receiverMemo": "Invoice 4012" }'
```

Besides the QUOTE entry, `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](https://public-openfx.mintlify.site/v3/api-reference/payments/payouts/confirm-payout.md) to accept everything in `confirmations[]` and move it to ACCEPTED. [Payouts](https://public-openfx.mintlify.site/v3/payouts) covers confirming and cancelling in more detail.

```bash cURL theme={"theme":{"light":"poimandres","dark":"poimandres"}}
curl -X POST https://api.openfx.com/v3/payments/payouts/pyt_Y6ZrY1JJvFqzaP3VsNojWN/confirm \
  -H "Authorization: Bearer $OPENFX_JWT" \
  -H "X-Request-Signature: $OPENFX_SIGNATURE" \
  -H "Idempotency-Key: $(uuidgen)"
```

## Memos

On FPS, a `receiverMemo` 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](https://public-openfx.mintlify.site/v3/payouts#send-the-payout) for each status and webhook.

On an FPS payout, `settlementTraceId.status` reads UNSUPPORTED. [Trace a payout with the receiving bank](https://public-openfx.mintlify.site/v3/payouts#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's `accountHolderName`, 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.

| Word in the name | `result` |
| - | - |
| None of the words below | MATCH |
| "NOMATCH" | NO\_MATCH |
| "CLOSEMATCH" | CLOSE\_MATCH |
| "UNAVAILABLE" | UNAVAILABLE |
| "INVALID" | 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 `sender` or sending a `purpose`.** A GBP payout takes neither. Remove them from the quote and from an INLINE payout; a FROM\_QUOTE payout has no `sender` field, so one there is a `400` VALIDATION\_BODY\_FAILED rather than a `422`.
* **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

> [card] [Payouts](https://public-openfx.mintlify.site/v3/payouts)
>
> The general payout flow.

> [card] [Capabilities](https://public-openfx.mintlify.site/v3/capabilities.md#be-paid-in-pounds-sterling)
>
> What the GBP-receiving capability requires.

> [card] [Payouts in EUR](https://public-openfx.mintlify.site/v3/eur-payout-integration.md)
>
> Paying euro accounts over SEPA or SWIFT.

> [card] [Payment Webhooks](https://public-openfx.mintlify.site/v3/webhooks/payments/payouts-webhooks/payout-created.md)
>
> Every payout and address event.
