Skip to main content
POST
Create Beneficiary

Headers

Idempotency-Key
string
required

Unique key for one canonical mutation request.

Required string length: 16 - 200

Body

application/json
country
string
required
Required string length: 2
currency
string
required
Required string length: 3
details
Details · object
required
name
string
required
Required string length: 1 - 200
payout_schema_id
string
required
Required string length: 1 - 100
is_external
boolean
default:true
nickname
string | null
Maximum string length: 80
purpose_code
string | null
Maximum string length: 80

Response

Successful Response

created_at
string<date-time>
required
failure_code
string | null
required
failure_detail
string | null
required
id
string
required
kind
enum<string>
required
Available options:
beneficiary_create,
card_close,
card_create,
card_freeze,
card_unfreeze,
mandate_create,
mandate_revoke,
mandate_suspend,
mandate_transfer,
transfer,
transfer_grant_revoke
next_reconcile_at
string<date-time> | null
required
resource_id
string | null
required
resource_type
string | null
required
state
enum<string>
required
Available options:
requires_action,
accepted,
submitting,
submitted,
succeeded,
failed,
indeterminate,
cancelled
submission_uncertain
boolean
required
updated_at
string<date-time>
required
upstream_reference
string | null
required
action_required
RedirectAction · object | null

A hosted provider hand-off: open url, optionally before expires_at, optionally polling for the outcome after poll_after_ms milliseconds.

card_reveal, grant_approval, and connect actions always carry expires_at, and grant_approval actions a positive poll_after_ms; a null expires_at occurs only on kyc_session, and a null poll_after_ms means no polling applies.