Skip to main content
POST
/
v1
/
accounts
/
{account_id}
/
payouts
Create Payout
curl --request POST \
  --url https://api.hopnow.io/v1/accounts/{account_id}/payouts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "beneficiary_id": "<string>",
  "payout_destination_id": "<string>",
  "amount": "<string>",
  "currency": "<string>",
  "note": "<string>"
}
'
{
  "id": "<string>",
  "object": "<string>",
  "account_id": "<string>",
  "beneficiary_id": "<string>",
  "payout_destination_id": "<string>",
  "amount": "<string>",
  "currency": "<string>",
  "amount_in_usd": "<string>",
  "status": "<string>",
  "provider": "<string>",
  "provider_reference_id": "<string>",
  "initiated_at": "<string>",
  "submitted_at": "<string>",
  "completed_at": "<string>",
  "failed_at": "<string>",
  "failed_reason": "<string>",
  "note": "<string>",
  "created": "<string>",
  "updated": "<string>"
}
This endpoint requires an Idempotency-Key header to prevent duplicate payouts.

​
Path Parameters

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

​
Headers

​
Idempotency-Key
string
required
Unique key to prevent duplicate payouts (e.g., UUID v4)

​
Request Body

​
beneficiary_id
string
required
Beneficiary external ID (starts with bene_)
​
payout_destination_id
string
required
Payout destination external ID (starts with dest_)
​
amount
string
required
Payout amount (decimal string, must be positive)
​
currency
string
required
ISO 4217 currency code
​
note
string
Optional internal note (max 500 characters)

​
Response

​
id
string
Payout identifier (starts with po_)
​
object
string
Always returns "payout"
​
account_id
string
Account ID
​
beneficiary_id
string
Beneficiary ID
​
payout_destination_id
string
Payout destination ID
​
amount
string
Payout amount (decimal)
​
currency
string
Currency code
​
amount_in_usd
string
Amount converted to USD
​
status
string
Payout status: pending_approval, pending, processing, completed, or failed
​
provider
string
Payment provider (null until submitted)
​
provider_reference_id
string
Provider reference ID
​
initiated_at
string
ISO 8601 timestamp when payout was initiated
​
submitted_at
string
ISO 8601 timestamp when payout was submitted to provider
​
completed_at
string
ISO 8601 timestamp when payout completed
​
failed_at
string
ISO 8601 timestamp when payout failed
​
failed_reason
string
Reason for failure
​
note
string
Optional note
​
created
string
ISO 8601 timestamp when created
​
updated
string
ISO 8601 timestamp when last updated

​
Response Example

{
  "id": "po_1234567890abcdef",
  "object": "payout",
  "account_id": "acc_1234567890abcdef",
  "beneficiary_id": "bene_1234567890abcdef",
  "payout_destination_id": "dest_1234567890abcdef",
  "amount": "100.00",
  "currency": "USD",
  "amount_in_usd": "100.00",
  "status": "pending_approval",
  "provider": null,
  "provider_reference_id": null,
  "initiated_at": "2024-01-15T10:00:00Z",
  "submitted_at": null,
  "completed_at": null,
  "failed_at": null,
  "failed_reason": null,
  "note": "Monthly payment",
  "created": "2024-01-15T10:00:00Z",
  "updated": "2024-01-15T10:00:00Z"
}