POST
Create a payment
This sends a payment out of the account. Use it for normal payments, and for future or repeating payments.

Scheduling

To schedule instead of sending now, add scheduledDate (and frequency for a repeating payment) to the same request:
frequency sets the repeat interval — one of DAILY, WEEKLY, FORTNIGHTLY, or MONTHLY. Omit it (or send NEVER) for a one-off scheduled payment. For MONTHLY, the day is taken from scheduledDate; months without that day fall back to the last day of the month. Manage the result with Scheduled payments.

Retry safely

Send an Idempotency-Key header (a UUID) and reuse the same key on every retry of the same payment. If a response is lost, retrying with that key returns the original payment instead of sending the money twice. It works the same for scheduled payments.
The header is optional today but will be required in a future release. Start sending it now — it’s one header, and until then it’s your only protection against a duplicate payment.

Tracking the payment

The response confirms acceptance, not settlement. To follow it through:
  1. In flight — it appears in payment requests (PENDING, or PENDING_TM while held for compliance review).
  2. Settled — it lands in transactions; failed ones show there with a FAILURE status.
Watch the reference length. The field allows up to 140 characters, but some programs accept fewer (as low as 35). If you go over your program’s limit, the payment is rejected. See Program capabilities.
Do not send programId or sandbox — we read them from your token. Send either a beneficiaryId or a cryptoQuote.

Authorizations

Authorization
string
header
required

The user's id_token from authentication — the ID token, not the access_token. The program and environment come from the token.

Headers

Idempotency-Key
string<uuid>

Optional. Makes the request retry-safe: a retry with the same key resolves to the same resource instead of creating a duplicate. Must be a UUID, and is scoped to the authenticated customer. Preferred over any idempotencyKey body field (a header value wins if both are sent). Optional today, but will be required in a future release — send one on every create now so a retry can never produce a duplicate.

Path Parameters

customerId
string
required

Customer identifier.

accountId
string
required

Account identifier. The account determines which optional features and limits apply.

Body

application/json
amount
string
required

Decimal string, max 2 dp.

Pattern: ^\d+(\.\d{1,2})?$
Example:

"150.00"

purpose
string
required

Purpose code.

Minimum string length: 1
Example:

"PP001"

currency
string

ISO 4217. Defaults to the account currency if omitted.

Required string length: 3
reference
string

Statement reference. The field allows up to 140 characters, but some programs accept fewer (as low as 35). Stay within your program's limit.

Maximum string length: 140
beneficiaryId
string

Saved beneficiary. Required unless cryptoQuote is supplied.

chargeBearer
enum<string>
Available options:
SHA,
OUR,
BEN
debtorViban
string

Specific source virtual IBAN. For domestic GBP must start with GB.

scheduledDate
string<date-time>

Future date (UTC) to schedule the payment.

frequency
enum<string>

Repeat interval for a recurring scheduled payment. Omit (or send NEVER) for a one-off. MONTHLY uses the day from scheduledDate.

Available options:
NEVER,
DAILY,
WEEKLY,
FORTNIGHTLY,
MONTHLY
waiveFee
boolean

Admin-only.

cryptoQuote
object | null

Provide instead of beneficiaryId for crypto-funded payments.

idempotencyKey
string<uuid>

Optional. Idempotency key for retry-safety (parity with batch payments). The Idempotency-Key header is preferred and overrides this field. Reusing a key with different amount/accountId/beneficiaryId returns 400; a key whose payment is still being claimed returns 409.

Response

Payment accepted

success
boolean
Example:

true

data
object

The payment result (e.g. bankTransfer with its status).