Skip to main content
POST
Create a payee

Authorizations

Authorization
string
header
required

Your secret key: sk_test_… on the sandbox host, sk_live_… on live. A key on the wrong host gets a 401 wrong_environment. Keys are secret. Keep them on your server, never in a browser or app.

Headers

Idempotency-Key
string

Optional. Makes a retry safe, as on money-moving creates.

Maximum string length: 255

Body

application/json
first_name
string
required
Maximum string length: 100
Example:

"Maria"

last_name
string
required
Maximum string length: 100
Example:

"Lopez"

email
string<email>
required

Unique within your account.

Maximum string length: 255
Example:

"maria@example.com"

send_invite
boolean
default:true

true: we email the payee their onboarding link. false: we never email them, and you get the onboarding_url instead.

reference
string

Your own id for this payee. It doesn't have to be unique.

Maximum string length: 100
Example:

"vendor-829"

metadata
object

Up to 20 key-value pairs of your own. Keys up to 40 characters, values up to 500, strings only.

Example:

Response

The new payee. onboarding_url is set only when send_invite is false.

id
string
required
Example:

"payee_c8pnahcrxqzd3z8d"

first_name
string
required
Example:

"Maria"

last_name
string
required
Example:

"Lopez"

email
string
required
Example:

"maria@example.com"

currency
string | null
required

The payee's payout currency once it's known: set by their address, or by their first payout on hold. Always inr on accounts enabled for India.

Example:

"eur"

status
enum<string>
required
  • invited: created; hasn't signed up yet.
  • details_pending: signed up; hasn't sent bank details yet.
  • verifying: details sent; checks are running.
  • active: can be paid.
  • inactive: can't be paid.
Available options:
invited,
details_pending,
verifying,
active,
inactive
Example:

"invited"

send_invite
boolean
required

false means we never email this payee.

Example:

false

onboarding_url
string | null
required

The link where the payee enters their own bank details. Only in the create and resend-invite responses, and only when send_invite is false.

Example:

"https://…"

reference
string | null
required
Example:

"vendor-829"

metadata
object
required

Up to 20 key-value pairs of your own. Keys up to 40 characters, values up to 500, strings only.

Example:
created_at
string<date-time>
required
Example:

"2026-10-26T10:00:00Z"

updated_at
string<date-time>
required
Example:

"2026-10-26T10:00:00Z"