API Reference
Complete reference documentation for all ZoPay API endpoints. All endpoints require authentication using API keys and HMAC signatures.
Base URLs: Sandbox: http://localhost:9000 | Production: https://api.zopay.com. All /api/v1/* endpoints require the 6 authentication headers. See Using the API for details.
Authentication
All /api/v1/* endpoints require the following headers:
x-zo-key- Your API keyx-zo-timestamp- Unix timestamp in secondsx-zo-nonce- Unique random string (UUID recommended)x-zo-origin- Your verified domain or allowed IPx-zo-signature- HMAC-SHA256 signaturex-zo-version- API version ("1.0")
For detailed authentication instructions, see Using the API.
Collections
Disbursements
/api/v1/disbursements/executeExecute a disbursement (send payment to recipient)
/api/v1/disbursements/:idGet disbursement status and details
/api/v1/disbursementsList all disbursements with filters and pagination
/api/v1/disbursements/bulkProcess multiple disbursements from a CSV file
Refunds
Wallet
/wallet/summaryGet wallet balance summary and overview
/wallet/activityGet recent wallet activity and transactions
Response Codes
| Code | Description |
|---|---|
200 OK | Request successful |
201 Created | Resource created successfully |
202 Accepted | Request accepted for processing |
400 Bad Request | Invalid request parameters |
401 Unauthorized | Authentication failed |
403 Forbidden | IP/domain not allowlisted or access denied |
404 Not Found | Resource not found |
409 Conflict | Resource already exists or conflict |
429 Too Many Requests | Rate limit exceeded |
500 Internal Server Error | Server error |
Rate Limiting
The default rate limit is 100 requests per minute per merchant. When exceeded, you'll receive a 429 Too Many Requests response with a retry_after header indicating how many seconds to wait.
Rate Limit Best Practice: Implement exponential backoff when handling 429 responses. Wait for the duration specified in the retry_after header before retrying your request.
Detailed Documentation
For detailed endpoint documentation with request/response examples, see:
- Collections Documentation - Complete guide for receiving payments
- Disbursements Documentation - Complete guide for sending payments
- Refunds Documentation - Complete guide for processing refunds
- Webhooks Documentation - Real-time event notifications