curl -X POST https://api.zbdpay.com/api/v1/payouts \
-H "x-api-key: YOUR_API_KEY" \
-H "Idempotency-Key: 6b1d3f0e-2a7c-4e19-9d51-0c8f4a2e7b13" \
-H "Content-Type: application/json" \
-d '{
"user_id": "4ac4fd8a-cc2c-4d03-af09-a76f4e89d652",
"payment_method_id": "pm_1c7e9a20-5d4b-4f3a-8e62-7b0d2f91c3a8",
"amount": 2500,
"currency": "USD",
"reference_id": "creator_payout_2026_10"
}'
{
"success": true,
"message": "Payout initiated.",
"data": {
"payout_id": "po_8f2c41d7-3b9e-4a10-b6f2-91de0c7a5e44",
"status": "INITIATED",
"user_id": "4ac4fd8a-cc2c-4d03-af09-a76f4e89d652",
"payment_method_id": "pm_1c7e9a20-5d4b-4f3a-8e62-7b0d2f91c3a8",
"amount": 2500,
"currency": "USD",
"fee_amount": 50,
"net_amount": 2450,
"reference_id": "creator_payout_2026_10",
"project_id": null,
"treasury_balance": 997500
},
"error": null
}
Payouts
Create a Payout
Send money from your pool to a user’s payment method.
POST
/
api
/
v1
/
payouts
curl -X POST https://api.zbdpay.com/api/v1/payouts \
-H "x-api-key: YOUR_API_KEY" \
-H "Idempotency-Key: 6b1d3f0e-2a7c-4e19-9d51-0c8f4a2e7b13" \
-H "Content-Type: application/json" \
-d '{
"user_id": "4ac4fd8a-cc2c-4d03-af09-a76f4e89d652",
"payment_method_id": "pm_1c7e9a20-5d4b-4f3a-8e62-7b0d2f91c3a8",
"amount": 2500,
"currency": "USD",
"reference_id": "creator_payout_2026_10"
}'
{
"success": true,
"message": "Payout initiated.",
"data": {
"payout_id": "po_8f2c41d7-3b9e-4a10-b6f2-91de0c7a5e44",
"status": "INITIATED",
"user_id": "4ac4fd8a-cc2c-4d03-af09-a76f4e89d652",
"payment_method_id": "pm_1c7e9a20-5d4b-4f3a-8e62-7b0d2f91c3a8",
"amount": 2500,
"currency": "USD",
"fee_amount": 50,
"net_amount": 2450,
"reference_id": "creator_payout_2026_10",
"project_id": null,
"treasury_balance": 997500
},
"error": null
}
Sends a payout to one user’s payment method. ZBD checks the user’s verification, screening, limits, and, for US bank payouts, the Electronic Funds Transfer disclosure. If every check passes, the amount comes out of your pool and the call returns
The response includes the fee for the user’s payment method and the net amount they receive. A webhook fires on every status change. See Webhook Events.
202 with the payout in INITIATED. If a check fails, the call returns a 4xx and nothing is debited.
What else the payout debits depends on how you track earnings:
| You track earnings | ZBD tracks earnings | |
|---|---|---|
| Debits | Your pool only | The user’s earnings on ZBD, then your pool funds the payout |
On FAILED or RETURNED | The amount goes back to your pool, and you add it back in your own system | The amount goes back to your pool and to the user’s earnings |
Configuration
Header Parameters
string
required
Your ZBD API key.
string
required
A UUID you generate for this payout. Retrying with the same key returns the original payout instead of sending a second one.
string
Content Type
Body Parameters
string
required
The ZBD user ID returned by Create a User.
string
required
The payment method to pay, from List Payment Methods. It has to belong to the user in
user_id, or the call returns 404 payment_method_not_found.integer
required
Amount in the currency’s smallest unit. For USD,
2500 is $25.00. The fee comes out of this amount.string
required
USD or EUR.string
Your own ID for this payout. It’s returned in webhooks and in List Payouts, for reconciliation.
string
The project the payout belongs to, so you can filter payouts and webhooks by project.
curl -X POST https://api.zbdpay.com/api/v1/payouts \
-H "x-api-key: YOUR_API_KEY" \
-H "Idempotency-Key: 6b1d3f0e-2a7c-4e19-9d51-0c8f4a2e7b13" \
-H "Content-Type: application/json" \
-d '{
"user_id": "4ac4fd8a-cc2c-4d03-af09-a76f4e89d652",
"payment_method_id": "pm_1c7e9a20-5d4b-4f3a-8e62-7b0d2f91c3a8",
"amount": 2500,
"currency": "USD",
"reference_id": "creator_payout_2026_10"
}'
{
"success": true,
"message": "Payout initiated.",
"data": {
"payout_id": "po_8f2c41d7-3b9e-4a10-b6f2-91de0c7a5e44",
"status": "INITIATED",
"user_id": "4ac4fd8a-cc2c-4d03-af09-a76f4e89d652",
"payment_method_id": "pm_1c7e9a20-5d4b-4f3a-8e62-7b0d2f91c3a8",
"amount": 2500,
"currency": "USD",
"fee_amount": 50,
"net_amount": 2450,
"reference_id": "creator_payout_2026_10",
"project_id": null,
"treasury_balance": 997500
},
"error": null
}
Response
The payout is indata.
string
ZBD’s ID for the payout. Use it with Get a Payout.
string
Where the payout is:
INITIATED, PROCESSING, COMPLETED, FAILED, or RETURNED. A new payout is always INITIATED. See Payout statuses.string
api for payouts your backend sent and widget for cash outs from the widget. Returned by Get a Payout and List Payouts.string
The user being paid.
string
The payment method being paid.
integer
The amount you sent, in the currency’s smallest unit. This is what comes out of your pool.
string
Currency code for all amounts in the payout, for example
USD.integer
The fee for the payment method, in the smallest unit. By default it comes out of
amount.integer
What the user receives, in the smallest unit. By default this is
amount minus fee_amount.string | null
Your own ID for the payout, if you sent one.
string | null
The project the payout belongs to, if you sent one.
integer
What’s left in your pool after this payout, in the smallest unit. Only returned when you create a payout.
Errors
| HTTP | code | When |
|---|---|---|
400 | idempotency_key_required | No Idempotency-Key header |
400 | validation_failed | A required field is missing or malformed |
404 | user_not_found · payment_method_not_found | The user doesn’t exist, or the payment method doesn’t belong to the user |
409 | idempotency_key_reused | The same key was sent with a different body |
422 | insufficient_funds | Your pool, or the user’s earnings if ZBD tracks them, doesn’t cover the amount |
422 | kyc_required · disclosure_required · screening_blocked | The user isn’t cleared for this payout |
422 | limit_exceeded | The amount is over the user’s limit |
422 | payment_method_inactive · unsupported_currency | The payment method can’t be used, or the currency can’t be paid on that rail |
Was this page helpful?