POST
Create a payment

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