Back to the reference

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.

Payout statuses
  • 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
GET

Payout configuration

/api/v1/payouts/config

Methods, dual-signature threshold and purposes.

Parameters

Authorization
header
stringRequired

Bearer $CLOBEPAY_API_KEY. X-API-Key with the same value is also accepted. Do not send both.

Responses

  • HTTP 200Configuration.

Errors

  • HTTP 400ambiguous_credentialsAuthorization: Bearer and X-API-Key carry different keys.
  • HTTP 401missing_credentialsNo key was sent (Authorization: Bearer or X-API-Key).
  • HTTP 401invalid_api_keyThe key does not exist, is malformed or does not match.
  • HTTP 401api_key_revokedThe key was revoked.
  • HTTP 401api_key_expiredThe key expired.
  • HTTP 401api_key_wrong_environmentThe key belongs to another environment (test key in live, or the other way around).
  • HTTP 403insufficient_scopeThe key does not have the scope for this route.
  • HTTP 429rate_limitedToo many requests. Honour Retry-After.
GET/payouts/config
curl -X GET "$CLOBEPAY_API_BASE/payouts/config" \  -H "Authorization: Bearer $CLOBEPAY_API_KEY"

Response

HTTP 200
{
  "dualApprovalThresholdUsd": "1000.00",
  "methods": [
    "ach",
    "wire",
    "crypto"
  ]
}

GET

Quote a payout

/api/v1/payouts/quote

Fee, reference FX rate and whether the balance is enough.

Parameters

Authorization
header
stringRequired

Bearer $CLOBEPAY_API_KEY. X-API-Key with the same value is also accepted. Do not send both.

amount
query
stringRequired

Amount the beneficiary receives.

method
query
stringOptional

ach, wire or crypto.

ach · wire · crypto

destination
query
stringOptional

bank or crypto.

bank · crypto

chain
query
stringOptional

Chain if the destination is crypto.

tron · eth · polygon

Responses

  • HTTP 200Quote. Fields in camelCase (receiveAmount, totalDebit, requiredApprovals).

Errors

  • HTTP 400ambiguous_credentialsAuthorization: Bearer and X-API-Key carry different keys.
  • HTTP 401missing_credentialsNo key was sent (Authorization: Bearer or X-API-Key).
  • HTTP 401invalid_api_keyThe key does not exist, is malformed or does not match.
  • HTTP 401api_key_revokedThe key was revoked.
  • HTTP 401api_key_expiredThe key expired.
  • HTTP 401api_key_wrong_environmentThe key belongs to another environment (test key in live, or the other way around).
  • HTTP 403insufficient_scopeThe key does not have the scope for this route.
  • HTTP 429rate_limitedToo many requests. Honour Retry-After.
  • HTTP 400invalid_amountInvalid amount or method.
GET/payouts/quote
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"
}

POST

Create a payout

/api/v1/payouts

Enters pending_approval. Scope payouts:write. Bank requires file.

Parameters

Authorization
header
stringRequired

Bearer $CLOBEPAY_API_KEY. X-API-Key with the same value is also accepted. Do not send both.

Idempotency-Key
header
stringRequired

1–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.

destinationType
form
stringOptional

bank (default) or crypto.

bank · crypto

beneficiaryId
form
uuidOptional

US bank beneficiary. Required if destinationType is bank.

cryptoBeneficiaryId
form
uuidOptional

USDT wallet. Required if destinationType is crypto.

amount
form
stringRequired

Amount the beneficiary receives (USD for bank, USDT for crypto).

purpose
form
stringOptional

Required for bank (e.g. Invoice_Payment). Optional for crypto.

purposeDetail
form
stringOptional

Only when purpose is Other (max 140).

description
form
stringOptional

Memo (max 140).

file
form
fileOptional

Supporting document required for bank payouts (multipart). Not used for crypto.

Responses

  • HTTP 201Request created in pending_approval.

Errors

  • HTTP 400ambiguous_credentialsAuthorization: Bearer and X-API-Key carry different keys.
  • HTTP 401missing_credentialsNo key was sent (Authorization: Bearer or X-API-Key).
  • HTTP 401invalid_api_keyThe key does not exist, is malformed or does not match.
  • HTTP 401api_key_revokedThe key was revoked.
  • HTTP 401api_key_expiredThe key expired.
  • HTTP 401api_key_wrong_environmentThe key belongs to another environment (test key in live, or the other way around).
  • HTTP 403insufficient_scopeThe key does not have the scope for this route.
  • HTTP 429rate_limitedToo many requests. Honour Retry-After.
  • HTTP 400idempotency_key_requiredThe Idempotency-Key header is missing.
  • HTTP 422insufficient_balanceThe balance does not cover the amount and the fee.
  • HTTP 422invalid_purposepurpose is missing on a bank payout or is not an allowed value, or purposeDetail exceeds 140 characters.
  • HTTP 422supporting_document_requiredThe file field is missing on a bank payout.
POST/payouts
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
}

GET

List payouts

/api/v1/payouts

Withdrawal history. Scope payouts:read.

Parameters

Authorization
header
stringRequired

Bearer $CLOBEPAY_API_KEY. X-API-Key with the same value is also accepted. Do not send both.

status
query
stringOptional

Filter by status.

page
query
numberOptional

Page (from 1).

Responses

  • HTTP 200List.

Errors

  • HTTP 400ambiguous_credentialsAuthorization: Bearer and X-API-Key carry different keys.
  • HTTP 401missing_credentialsNo key was sent (Authorization: Bearer or X-API-Key).
  • HTTP 401invalid_api_keyThe key does not exist, is malformed or does not match.
  • HTTP 401api_key_revokedThe key was revoked.
  • HTTP 401api_key_expiredThe key expired.
  • HTTP 401api_key_wrong_environmentThe key belongs to another environment (test key in live, or the other way around).
  • HTTP 403insufficient_scopeThe key does not have the scope for this route.
  • HTTP 429rate_limitedToo many requests. Honour Retry-After.
GET/payouts
curl -X GET "$CLOBEPAY_API_BASE/payouts?status=pending_approval" \  -H "Authorization: Bearer $CLOBEPAY_API_KEY"

Response

HTTP 200
{
  "items": [],
  "page": 1
}

GET

Retrieve a payout

/api/v1/payouts/{payoutId}

Detail by UUID. Scope payouts:read.

Parameters

Authorization
header
stringRequired

Bearer $CLOBEPAY_API_KEY. X-API-Key with the same value is also accepted. Do not send both.

payoutId
path
uuidRequired

Payout UUID.

Responses

  • HTTP 200Detail in camelCase (destinationType, totalDebit, requiredApprovals).

Errors

  • HTTP 400ambiguous_credentialsAuthorization: Bearer and X-API-Key carry different keys.
  • HTTP 401missing_credentialsNo key was sent (Authorization: Bearer or X-API-Key).
  • HTTP 401invalid_api_keyThe key does not exist, is malformed or does not match.
  • HTTP 401api_key_revokedThe key was revoked.
  • HTTP 401api_key_expiredThe key expired.
  • HTTP 401api_key_wrong_environmentThe key belongs to another environment (test key in live, or the other way around).
  • HTTP 403insufficient_scopeThe key does not have the scope for this route.
  • HTTP 429rate_limitedToo many requests. Honour Retry-After.
  • HTTP 404not_foundIt does not exist or is not yours. Also if payoutId is not a UUID.
GET/payouts/{payoutId}
curl -X GET "$CLOBEPAY_API_BASE/payouts/e2a9c4d1-6f38-4b7e-a015-c8d94e2b70aa" \  -H "Authorization: Bearer $CLOBEPAY_API_KEY"

Response

HTTP 200
Detail in camelCase (destinationType, totalDebit, requiredApprovals).