Skip to main content
POST
Update a payout on hold

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.

Path Parameters

id
string
required
Example:

"payout_4kz9xq7m2w8dn3ra"

Body

application/json
amount
string

The same rules as on create.

Example:

"650.00"

currency
string

Same rail only, and only while the payee has no address and no other payouts on hold.

Example:

"eur"

Response

The updated payout.

id
string
required
Example:

"payout_4kz9xq7m2w8dn3ra"

batch_id
string
required
Example:

"batch_fcb4cuwtd6fcbmwr"

wallet_id
string
required

The wallet that paid.

Example:

"wallet_7t4m9k2qx8d3hn5r"

payee_id
string
required
Example:

"payee_c8pnahcrxqzd3z8d"

amount
string
required

What you entered.

Example:

"500.00"

currency
string
required

The currency of amount. usd on INR accounts.

Example:

"eur"

debit_amount
string | null
required

What left your balance, fee included.

Example:

"568.35"

debit_currency
string
required

The currency of the paying wallet.

Example:

"usd"

fee
string | null
required

In debit_currency.

Example:

"10.00"

fee_bearer
enum<string>
required
Available options:
account,
payee
rate
string | null
required

From debit_currency to payee_currency. null until it's known (INR before settlement).

Example:

"0.8955"

payee_amount
string | null
required

What the payee receives. An estimate until paid, then the actual. On INR payouts it's null until paid.

Example:

"500.00"

payee_currency
string
required
Example:

"eur"

status
enum<string>
required
  • awaiting_payee: money reserved, waiting for the payee to finish onboarding.
  • awaiting_funds: the payee is ready, but the balance was too low at release.
  • pending: created and handed to the payout network.
  • processing: accepted and on its way.
  • paid: delivered.
  • failed: not delivered; failure_code says why.
  • returned: delivered, then sent back by the payee's bank.
  • canceled: canceled by you while held.
  • expired: the hold ran out before the payee was ready.
Available options:
awaiting_payee,
awaiting_funds,
pending,
processing,
paid,
failed,
returned,
canceled,
expired
Example:

"pending"

failure_code
enum<string> | null
required

Why a payout failed or was returned. New codes can be added.

Available options:
below_minimum,
insufficient_funds,
bank_account_missing,
bank_details_invalid,
rate_changed,
returned_by_bank,
undeliverable,
refunded,
refund_failed,
canceled,
processing_error,
null
Example:

null

failure_message
string | null
required

A fixed sentence for each failure_code.

Example:

null

hold_expires_at
string<date-time> | null
required

Set if the payout was ever held.

Example:

null

description
string | null
required

Shared by every payout in a batch.

Example:

"October invoice"

reference
string | null
required
Example:

"inv-1042"

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:05:00Z"

updated_at
string<date-time>
required
Example:

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