Developers
Decaf Disbursements API
Send money to anyone with a phone number. Recipients claim funds directly on WhatsApp.
Error Reference
{
"error": "machine_readable_code",
"message": "Human-readable description",
"details": {}
}HTTP Status Codes
| status | meaning |
|---|---|
| 400 | Bad request |
| 401 | Auth failed |
| 402 | Insufficient balance |
| 404 | Not found |
| 409 | Idempotency conflict |
| 422 | Unprocessable request |
| 429 | Rate limit exceeded |
| 500 | Internal error |
| 502/504 | Upstream timeout |
Common Error Codes
| code | meaning |
|---|---|
| insufficient_balance | Not enough balance |
| invalid_phone | Invalid E.164 phone format |
| recipient_country_unsupported | No payout method for recipient country |
| amount_below_minimum | Amount below $1.00 |
| idempotency_conflict | Same key with different params |
| disbursement_already_claimed | Cannot cancel claimed disbursement |
| virtual_account_not_found | Virtual account ID not found |
Rate Limits
| endpoint | limit |
|---|---|
| POST /v1/disbursements | 100 req/min |
| POST /v1/disbursements/batch | 10 req/min |
| GET endpoints | 300 req/min |
| All endpoints | 1,000 req/min (org total) |
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1741219260Idempotency
For POST requests, pass idempotencyKey to safely retry without duplicate sends.
- Same key + same params: returns original response
- Same key + different params: returns 409 idempotency_conflict
- Key expiration: 24 hours
Compliance & Limits
| scenario | limit |
|---|---|
| Minimum disbursement | $1.00 USD |
| Maximum single disbursement | No limit |
| MoneyGram cash pickup | $2,500 USD/day per recipient |
| Daily disbursements (org) | No cap (subject to balance) |
Decaf applies AML/KYC checks at claim time. You do not need to build KYC flow in your integration.