Skip to main content

​
Overview

PATCH /v1/payouts/destinations/{destination_id} is the one update this API has. What it does depends on what you send:
  • Send only name and/or is_default and nothing changes about where money lands. This is the safe edit: it never touches review status.
  • Send any routing detail (currency, type, or an account, wallet, or phone field) and the destination is restated in full, the same shape as Create Destination. Fields you omit fall back to what is already stored, so you only need to send what’s changing.
Setting is_default promotes one of your own already-approved destinations and demotes whichever one held the flag for that currency; false clears it, which leaves a payout schedule with nowhere to send that currency and so skips it. Deleting a destination clears the flag too, because an inactive destination cannot receive a scheduled payout. Why a rename alone cannot move money: a destination’s approval is granted for a specific account or wallet. If you could quietly swap the account number on an already-approved destination without review, the destination would keep an approval that was never actually granted for its new destination. That is why a routing change always resets status, even through this endpoint.

​
Authentication

Type: API Key (required)

​
Request

​
Method & Path

​
Path parameters

​
string
required
The ID of the destination to update.

​
Request examples

​
Request fields

​
string
The new name for the destination, 1 to 255 characters.
​
boolean
Make this the destination a payout schedule pays out to for its currency. Setting it demotes the previous default; false clears it. The destination must be approved and active. Ignored if a routing change in the same request sends the destination back for review.
​
string
The currency this destination accepts. Only needed when changing it; defaults to the currency already stored.
​
string
bank_account, mobile_money, or crypto_wallet. destination_type is accepted as a legacy alias. Only needed when changing rail; defaults to the type already stored.
​
string
Bank account number. Required, together with bank_code, for a bank-rail destination that omits it and has none stored.
​
string
Account holder name. Unlike Create Destination, an update trusts the name it is given rather than resolving it from the bank.
​
string
Bank code. Required, together with account_number, for a bank-rail destination that omits it and has none stored. Get valid codes from List Banks.
​
string
Bank name.
​
string
Phone number, for a mobile-money-rail destination.
​
string
Mobile money provider, for a mobile-money-rail destination.
​
string
Destination wallet address, for a crypto-rail destination.
​
string
Blockchain network. Optional for a currency that names its own network (e.g. USDT_TRC20).
​
object
Arbitrary key-value data. Merged over what is already stored on the destination; a partial payload never wipes keys you don’t mention.
At least one field is required.

​
Response

​
200 - Success

Returns the updated destination in full. See Create Destination for the field reference. name, is_default, and updated_at change on a safe edit; a routing change can also change status, status_reason, is_usable, reviewed_at, and any of the account/wallet fields you sent.

​
Error responses

Cause: No fields were sent, name was empty, or the payload is invalid for the resolved destination type.Resolution: Send at least one field, and use a non-empty name.
Cause: A routing change left a required field for the resolved rail missing, for example account_number without bank_code for a bank-rail destination.Resolution: Send the pair of fields together, or omit both to leave the stored routing unchanged.
Cause: The requested destination type and currency have no configured payout rail. See the withdrawal currency and method table. International bank routing details must match the destination’s currency and scheme.Resolution: Use a supported destination type and currency pair.
Cause: is_default was true on a destination that has not cleared review, including one this same request just sent back for review.Resolution: Wait for the destination to reach approved, then retry with only is_default.
Cause: is_default was true on a destination that has been deleted.Resolution: Register the account again with Create Destination and promote the new one.
Cause: API key is missing, invalid, or revoked.Resolution: Use a valid API key in the Authorization header.
Cause: destination_id does not exist, or belongs to another organization.Resolution: Verify the destination ID and retry. You can still update a destination that has been deleted; it stays not-usable regardless.