Payouts
Withdrawals to bank accounts or USDT wallets.
Payouts withdraw your balance (in USDT) to a bank beneficiary or a wallet. Every payout created via API enters pending_approval. Payouts above 1,000 USD require the merchant’s dual signature. Scope payouts:write to create (limit 10 per minute). The JSON body uses camelCase (destinationType, beneficiaryId, cryptoBeneficiaryId, purposeDetail). Bank payouts require the supporting document as a multipart file field named file.
- pending_approval → dispatching: Approved
- pending_approval → rejected: Rejected
- dispatching → processing: Accepted by the provider
- dispatching → pending: In provider review
- dispatching → dispatch_unknown: Result unconfirmed
- dispatching → failed: Failed
- dispatch_unknown → dispatching: Verify
- dispatch_unknown → processing: Accepted by the provider
- dispatch_unknown → pending: In provider review
- dispatch_unknown → failed: Failed
- pending → processing: Accepted by the provider
- pending → failed: Failed
- processing → completed: Completed
- processing → failed: Failed
Payout configuration
/api/v1/payouts/config
Methods, dual-signature threshold and purposes.
Parameters
AuthorizationstringRequiredBearer $CLOBEPAY_API_KEY. X-API-Key with the same value is also accepted. Do not send both.
Responses
- HTTP 200Configuration.
Errors
- HTTP 400
ambiguous_credentialsAuthorization: Bearer and X-API-Key carry different keys. - HTTP 401
missing_credentialsNo key was sent (Authorization: Bearer or X-API-Key). - HTTP 401
invalid_api_keyThe key does not exist, is malformed or does not match. - HTTP 401
api_key_revokedThe key was revoked. - HTTP 401
api_key_expiredThe key expired. - HTTP 401
api_key_wrong_environmentThe key belongs to another environment (test key in live, or the other way around). - HTTP 403
insufficient_scopeThe key does not have the scope for this route. - HTTP 429
rate_limitedToo many requests. Honour Retry-After.
curl -X GET "$CLOBEPAY_API_BASE/payouts/config" \ -H "Authorization: Bearer $CLOBEPAY_API_KEY"Response
HTTP 200{
"dualApprovalThresholdUsd": "1000.00",
"methods": [
"ach",
"wire",
"crypto"
]
}Quote a payout
/api/v1/payouts/quote
Fee, reference FX rate and whether the balance is enough.
Parameters
AuthorizationstringRequiredBearer $CLOBEPAY_API_KEY. X-API-Key with the same value is also accepted. Do not send both.
amountstringRequiredAmount the beneficiary receives.
methodstringOptionalach, wire or crypto.
ach · wire · crypto
destinationstringOptionalbank or crypto.
bank · crypto
chainstringOptionalChain if the destination is crypto.
tron · eth · polygon
Responses
- HTTP 200Quote. Fields in camelCase (receiveAmount, totalDebit, requiredApprovals).
Errors
- HTTP 400
ambiguous_credentialsAuthorization: Bearer and X-API-Key carry different keys. - HTTP 401
missing_credentialsNo key was sent (Authorization: Bearer or X-API-Key). - HTTP 401
invalid_api_keyThe key does not exist, is malformed or does not match. - HTTP 401
api_key_revokedThe key was revoked. - HTTP 401
api_key_expiredThe key expired. - HTTP 401
api_key_wrong_environmentThe key belongs to another environment (test key in live, or the other way around). - HTTP 403
insufficient_scopeThe key does not have the scope for this route. - HTTP 429
rate_limitedToo many requests. Honour Retry-After. - HTTP 400
invalid_amountInvalid amount or method.
curl -X GET "$CLOBEPAY_API_BASE/payouts/quote?amount=100.00&method=ach&destination=bank" \ -H "Authorization: Bearer $CLOBEPAY_API_KEY"Response
HTTP 200{
"destinationType": "bank",
"method": "ach",
"receiveAmount": "100.00",
"receiveCurrency": "USD",
"convertAmount": "100.00",
"fee": {
"amount": "1.50",
"currency": "USDT"
},
"totalDebit": "101.50",
"debitAsset": "USDT",
"sufficientBalance": true,
"requiredApprovals": 1,
"dualApprovalThresholdUsd": "1000.00"
}Create a payout
/api/v1/payouts
Enters pending_approval. Scope payouts:write. Bank requires file.
Parameters
AuthorizationstringRequiredBearer $CLOBEPAY_API_KEY. X-API-Key with the same value is also accepted. Do not send both.
Idempotency-KeystringRequired1–255 characters. Required on this POST. The same key and body replay the original response (Idempotent-Replayed: true). A different body returns 422 idempotency_key_reuse.
destinationTypestringOptionalbank (default) or crypto.
bank · crypto
beneficiaryIduuidOptionalUS bank beneficiary. Required if destinationType is bank.
cryptoBeneficiaryIduuidOptionalUSDT wallet. Required if destinationType is crypto.
amountstringRequiredAmount the beneficiary receives (USD for bank, USDT for crypto).
purposestringOptionalRequired for bank (e.g. Invoice_Payment). Optional for crypto.
purposeDetailstringOptionalOnly when purpose is Other (max 140).
descriptionstringOptionalMemo (max 140).
filefileOptionalSupporting document required for bank payouts (multipart). Not used for crypto.
Responses
- HTTP 201Request created in pending_approval.
Errors
- HTTP 400
ambiguous_credentialsAuthorization: Bearer and X-API-Key carry different keys. - HTTP 401
missing_credentialsNo key was sent (Authorization: Bearer or X-API-Key). - HTTP 401
invalid_api_keyThe key does not exist, is malformed or does not match. - HTTP 401
api_key_revokedThe key was revoked. - HTTP 401
api_key_expiredThe key expired. - HTTP 401
api_key_wrong_environmentThe key belongs to another environment (test key in live, or the other way around). - HTTP 403
insufficient_scopeThe key does not have the scope for this route. - HTTP 429
rate_limitedToo many requests. Honour Retry-After. - HTTP 400
idempotency_key_requiredThe Idempotency-Key header is missing. - HTTP 422
insufficient_balanceThe balance does not cover the amount and the fee. - HTTP 422
invalid_purposepurpose is missing on a bank payout or is not an allowed value, or purposeDetail exceeds 140 characters. - HTTP 422
supporting_document_requiredThe file field is missing on a bank payout.
curl -X POST "$CLOBEPAY_API_BASE/payouts" \ -H "Idempotency-Key: payout-10042" \ -H "Authorization: Bearer $CLOBEPAY_API_KEY" \ -F "destinationType=bank" \ -F "beneficiaryId=a41c82e7-3b6d-4c90-9e2a-5f17d0b8c4e3" \ -F "amount=100.00" \ -F "purpose=Invoice_Payment" \ -F "file=@invoice.pdf"Response
HTTP 201{
"id": "e2a9c4d1-6f38-4b7e-a015-c8d94e2b70aa",
"destinationType": "bank",
"amount": "100.00",
"currency": "USD",
"method": "ach",
"status": "pending_approval",
"totalDebit": "101.50",
"debitAsset": "USDT",
"requiredApprovals": 1
}List payouts
/api/v1/payouts
Withdrawal history. Scope payouts:read.
Parameters
AuthorizationstringRequiredBearer $CLOBEPAY_API_KEY. X-API-Key with the same value is also accepted. Do not send both.
statusstringOptionalFilter by status.
pagenumberOptionalPage (from 1).
Responses
- HTTP 200List.
Errors
- HTTP 400
ambiguous_credentialsAuthorization: Bearer and X-API-Key carry different keys. - HTTP 401
missing_credentialsNo key was sent (Authorization: Bearer or X-API-Key). - HTTP 401
invalid_api_keyThe key does not exist, is malformed or does not match. - HTTP 401
api_key_revokedThe key was revoked. - HTTP 401
api_key_expiredThe key expired. - HTTP 401
api_key_wrong_environmentThe key belongs to another environment (test key in live, or the other way around). - HTTP 403
insufficient_scopeThe key does not have the scope for this route. - HTTP 429
rate_limitedToo many requests. Honour Retry-After.
curl -X GET "$CLOBEPAY_API_BASE/payouts?status=pending_approval" \ -H "Authorization: Bearer $CLOBEPAY_API_KEY"Response
HTTP 200{
"items": [],
"page": 1
}Retrieve a payout
/api/v1/payouts/{payoutId}
Detail by UUID. Scope payouts:read.
Parameters
AuthorizationstringRequiredBearer $CLOBEPAY_API_KEY. X-API-Key with the same value is also accepted. Do not send both.
payoutIduuidRequiredPayout UUID.
Responses
- HTTP 200Detail in camelCase (destinationType, totalDebit, requiredApprovals).
Errors
- HTTP 400
ambiguous_credentialsAuthorization: Bearer and X-API-Key carry different keys. - HTTP 401
missing_credentialsNo key was sent (Authorization: Bearer or X-API-Key). - HTTP 401
invalid_api_keyThe key does not exist, is malformed or does not match. - HTTP 401
api_key_revokedThe key was revoked. - HTTP 401
api_key_expiredThe key expired. - HTTP 401
api_key_wrong_environmentThe key belongs to another environment (test key in live, or the other way around). - HTTP 403
insufficient_scopeThe key does not have the scope for this route. - HTTP 429
rate_limitedToo many requests. Honour Retry-After. - HTTP 404
not_foundIt does not exist or is not yours. Also if payoutId is not a UUID.
curl -X GET "$CLOBEPAY_API_BASE/payouts/e2a9c4d1-6f38-4b7e-a015-c8d94e2b70aa" \ -H "Authorization: Bearer $CLOBEPAY_API_KEY"Response
HTTP 200Detail in camelCase (destinationType, totalDebit, requiredApprovals).