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
A UUID you generate for this payout. Retrying with the same key returns the original payout instead of sending a second one.
Body Parameters
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.Amount in the currency’s smallest unit. For USD,
2500 is $25.00. The fee comes out of this amount.Your own ID for this payout. It’s returned in webhooks and in List Payouts, for reconciliation.
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.
ZBD’s ID for the payout. Use it with Get a Payout.
Where the payout is:
INITIATED, PROCESSING, COMPLETED, FAILED, or RETURNED. A new payout is always INITIATED. See Payout statuses.api for payouts your backend sent and widget for cash outs from the widget. Returned by Get a Payout and List Payouts.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?