GBP payouts

Send GBP to UK bank accounts over the Faster Payments rail, settled from your GBP international account. Recipients are identified by account number + sort code.

See the Payouts overview for common fields, customer attribution, and the shared payout object + management endpoints (documented on the NGN page).

Prerequisites

International accounts enabled on your merchant account.
An active GBP account to send from. In the individual flow this is the sender’s own virtual account (sender_account_not_provisioned if missing); in the business/treasury flow it’s your merchant international account (no_active_international_account if missing). See the error table.
A sender for compliance — pass sender_customer_id (preferred) or an inline sender block (see below).
For attribution reads on GET /v1/customers/{id}/transactions: the API key needs customer_transaction_view.

POSTSave a GBP beneficiary, then pay by reference

POST/v1/beneficiaries

The reliable path for FX is to save the recipient once via POST /v1/beneficiaries, then reference it by beneficiary_id on each payout. A saved GBP beneficiary captures the address the receiving network needs (the inline path below does not), so payouts settle cleanly.

Returns a beneficiary with an id (e.g. ben_…). Idempotent — re-saving the same recipient returns the existing record with created: false.

Request

curl https://api.swappr.me/api/v1/beneficiaries \
  -H "Authorization: Bearer sk_test_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "GBP",
    "name": "Jane Doe",
    "bank": {
      "account_number": "12345678",
      "sort_code": "200000",
      "bank_name": "Barclays"
    },
    "address": {
      "street": "10 Downing Street",
      "city": "London",
      "zip_code": "SW1A 2AA"
    },
    "external_reference": "supplier-42"
  }'

POSTCreate a GBP payout

POST/v1/payouts

amount_minor is in pence (150000 = £1,500.00). Prefer the by-beneficiary path; the inline recipient is soft-deprecated for FX and does not carry address details.

Required recipient fields

Path	Field	Required	Notes
Beneficiary	`bank.account_number`	yes	UK account number (8 digits).
Beneficiary	`bank.sort_code`	yes	6-digit sort code.
Beneficiary	`address.street` / `address.city` / `address.zip_code`	yes	Receiving-network compliance.
Beneficiary	`name`	yes	Recipient name.
Inline	`recipient.account_number`	yes	8 digits.
Inline	`recipient.sort_code`	yes	6 digits.
Inline	`recipient.name`	yes	Recipient name.

Sender attribution

GBP requires the sending customer to be identified for compliance. Pass sender_customer_id (the id of a customer created via POST /v1/customers) — Swappr resolves their stored KYC. Alternatively pass a full inline sender block. The two are complementary: if you pass both, inline sender fields win per-field and the customer’s stored KYC backfills any you omit.

customer_id (optional, for attribution) must match sender_customer_id if both are supplied, or the request is rejected with customer_id_mismatch.

Response

201 Created with the payout object (currency: "GBP"). Status is queued / processing, transitioning to paid when the network confirms — listen for the payout.paid webhook.

Errors

Code	HTTP	Cause
`fx_features_not_enabled`	403	International accounts not enabled for this merchant
`no_active_international_account`	403	(Business/treasury) No active merchant GBP international account
`sender_account_not_provisioned`	422	(Individual) The sending customer has no active GBP virtual account — issue one via `POST /v1/customers/{id}/virtual_accounts`
`missing_field`	400/422	Required recipient field absent (`recipient.account_number`, `recipient.sort_code`, `recipient.name`)
`beneficiary_not_found`	404	`beneficiary_id` unknown / not yours / wrong env
`beneficiary_currency_mismatch`	400	`beneficiary_id` is not a GBP beneficiary
`sender_info_required`	422	No `sender_customer_id` and no complete inline `sender` block
`customer_id_mismatch`	400	`customer_id` ≠ `sender_customer_id`
`idempotency_key_conflict`	409	Same `Idempotency-Key`, different body
`provider_error`	502	Downstream rail unreachable; safe to retry with the same key

Shared management endpoints (list / retrieve / requery / cancel) are on the NGN page.

Request — by beneficiary (preferred)

curl https://api.swappr.me/api/v1/payouts \
  -H "Authorization: Bearer sk_test_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "amount_minor": "150000",
    "currency": "GBP",
    "beneficiary_id": "ben_cmo8x2p9q0...",
    "sender_customer_id": "cust_cmoji8...",
    "customer_id": "cust_cmoji8...",
    "merchant_reference": "INV-2026-04"
  }'

Request — inline recipient (soft-deprecated for FX)

curl https://api.swappr.me/api/v1/payouts \
  -H "Authorization: Bearer sk_test_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "amount_minor": "150000",
    "currency": "GBP",
    "recipient": { "account_number": "12345678", "sort_code": "200000", "name": "Jane Doe" },
    "sender_customer_id": "cust_cmoji8...",
    "merchant_reference": "INV-2026-04"
  }'

Webhook events

payout.processing → payout.paid or payout.failed (and payout.reversed on a later reversal). customer_id / customer_reference are included when set. See Webhooks.

NGN USD