Skip to main content
POST
Create a beneficiary

Authorizations

DPoP
string
header
required

Per-request RFC 9449 DPoP proof signed with ES256. Protected requests use Authorization: DPoP your_access_token_here. Create a new proof for the exact method and normalized target URI, and include the server nonce when challenged.

Authorization
string
header
required

OAuth 2.0 with RFC 9700 security practices. Discover exact environment endpoints from /.well-known/openid-configuration and /.well-known/oauth-authorization-server, and discover the resource from /.well-known/oauth-protected-resource. Authorization-code clients use PKCE S256, the exact environment resource, nonce with openid, and DPoP binding. Confidential clients also require PAR and private_key_jwt. Access and refresh tokens are sender-constrained with DPoP. purchases:execute is unavailable and omitted from this scope registry.

Headers

confirmation-intent-id
string<uuid>
required

One-use confirmation intent identifier.

Pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
X-Request-Id
string

Optional caller request identifier. Unsafe values are replaced with a generated UUID.

Pattern: ^[A-Za-z0-9._~-]{8,128}$
Idempotency-Key
string
required

A new 256-bit random value encoded as 43 unpadded base64url characters. Reuse it only for the same request intent.

Pattern: ^[A-Za-z0-9_-]{43}$

Body

application/json

A request to create one provider beneficiary.

name
string
required

Beneficiary legal name.

Required string length: 1 - 200
country
string
required

Payout country.

Pattern: ^[A-Z]{2}$
currency
string
required

Payout currency.

Pattern: ^[A-Z]{3}$
payout_schema_id
string
required

Selected payout schema.

Required string length: 1 - 512
is_external
boolean
required

Whether this is a third-party payee.

details
object
required

Payout-schema answers.

nickname
string

Optional owner-private beneficiary nickname.

Required string length: 1 - 80
purpose_code
string

Optional provider purpose code.

Required string length: 1 - 128

Response

The beneficiary creation operation was admitted.

A durable financial operation projected without credentials, provider payloads, or identity fields.

id
string<uuid>
required

Stable identifier for one durable financial operation.

Pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
kind
string
required

Stable machine-readable financial operation kind.

Required string length: 1 - 100
Pattern: ^[a-z][a-z0-9_]*$
state
enum<string>
required

Current durable operation state.

Available options:
accepted,
submitting,
submitted,
succeeded,
failed,
indeterminate,
cancelled
submission_uncertain
boolean
required

Whether the provider may have accepted the mutation and the client must not resubmit it.

failure_code
string | null
required

Stable failure or submission-uncertainty code, or null when none is recorded.

Required string length: 1 - 100
Pattern: ^[a-z][a-z0-9_]*$
created_at
string<date-time>
required

RFC 3339 timestamp for durable operation evidence.

Pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
updated_at
string<date-time>
required

RFC 3339 timestamp for durable operation evidence.

Pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$