Skip to main content
POST
https://apis.hopnow.io
/
v1
/
accounts
/
{account_id}
/
beneficiaries
/
{beneficiary_id}
/
payout-destinations
Create Payout Destination
curl --request POST \
  --url https://apis.hopnow.io/v1/accounts/{account_id}/beneficiaries/{beneficiary_id}/payout-destinations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "country": "<string>",
  "type": "<string>",
  "currency": "<string>",
  "label": "<string>",
  "network": "<string>",
  "account_number": "<string>",
  "account_name": "<string>",
  "routing_number": "<string>",
  "account_type": "<string>",
  "iban": "<string>",
  "swift_code": "<string>",
  "wallet_address": "<string>",
  "is_default": true
}
'
{
  "id": "<string>",
  "object": "<string>",
  "beneficiary_id": "<string>",
  "country": "<string>",
  "payout_method": "<string>",
  "type": "<string>",
  "label": "<string>",
  "currency": "<string>",
  "network": "<string>",
  "status": "<string>",
  "account_number_last4": "<string>",
  "routing_number": "<string>",
  "account_type": "<string>",
  "clabe_last4": "<string>",
  "iban_masked": "<string>",
  "swift_code": "<string>",
  "wallet_address_masked": "<string>",
  "is_default": true,
  "created": "<string>",
  "updated": "<string>"
}

​
Path Parameters

​
account_id
string
required
The account’s external ID (starts with acc_)
​
beneficiary_id
string
required
The beneficiary’s external ID (starts with ben_)

​
Request Body

​
country
string
required
Payout country code (ISO 3166-1 alpha-2)
​
type
string
required
Destination type: bank_account, wallet, or card
​
currency
string
required
Currency for payouts (ISO 4217 code)
​
label
string
Custom label for this destination
​
network
string
Blockchain network (required for crypto destinations, e.g., ethereum, bitcoin)

​
Bank Account Fields

​
account_number
string
Bank account number
​
account_name
string
Bank account name
​
routing_number
string
Bank routing number
​
account_type
string
Account type: checking or savings
​
iban
string
IBAN (max 34 characters)
​
swift_code
string
SWIFT/BIC code (max 11 characters)

​
Crypto Wallet Fields

​
wallet_address
string
Blockchain wallet address
​
is_default
boolean
default:"false"
Set as default destination for this beneficiary

​
Response

​
id
string
Payout destination identifier (starts with dest_)
​
object
string
Always returns "payout_destination"
​
beneficiary_id
string
Parent beneficiary external ID
​
country
string
Payout country
​
payout_method
string
Payout method (e.g., ach, wire, spei)
​
type
string
Destination type
​
label
string
Destination label
​
currency
string
Currency
​
network
string
Blockchain network (for crypto only)
​
status
string
Destination status: active, disabled, or inactive
​
account_number_last4
string
Last 4 digits of account number (masked for security)
​
routing_number
string
Bank routing number
​
account_type
string
Account type
​
clabe_last4
string
Last 4 digits of CLABE (Mexico SPEI)
​
iban_masked
string
Masked IBAN
​
swift_code
string
SWIFT/BIC code
​
wallet_address_masked
string
Masked wallet address
​
is_default
boolean
Whether this is the default destination
​
created
string
ISO 8601 timestamp when created
​
updated
string
ISO 8601 timestamp when last updated

​
Response Example

{
  "id": "dest_1234567890abcdef",
  "object": "payout_destination",
  "beneficiary_id": "ben_1234567890abcdef",
  "country": "US",
  "payout_method": "ach",
  "type": "bank_account",
  "label": null,
  "currency": "USD",
  "network": null,
  "status": "active",
  "account_number_last4": "7890",
  "routing_number": "021000021",
  "account_type": "checking",
  "is_default": true,
  "created": "2024-01-15T10:00:00Z",
  "updated": "2024-01-15T10:00:00Z"
}