1. Authentication and Security
- Requirements
- Headers
- Signature
- Auth errors
| Requirement | Description |
|---|---|
| HTTPS | All requests must be sent over HTTPS. |
| JSON | Requests and responses use JSON. |
| API key | A valid API key issued to the merchant is required. |
| API prefix | External endpoints use the /api/v1 prefix. |
| Money format | Monetary fields use decimal strings, for example "5000.00". |
| Changelog | Contract changes are recorded in the API changelog. |
| Header | Description |
|---|---|
| X-API-Key | API key issued to the merchant. |
| X-Timestamp | Request time: ISO-8601 UTC or UNIX timestamp in seconds. Allowed skew is ±60 seconds. |
| X-Signature | HMAC-SHA256 request signature. |
| Content-Type | For requests with a body: application/json. |
| Step | Description |
|---|---|
| 1 | Take the X-Timestamp header value exactly as sent. |
| 2 | Take the raw request body. For GET requests, the body is an empty string. |
| 3 | Concatenate timestamp + body. |
| 4 | Compute HMAC-SHA256 using the secret key. |
| 5 | Send the result in X-Signature. |
| HTTP | Message | Cause |
|---|---|---|
| 401 | API key required | Missing X-API-Key header. |
| 401 | Invalid API key | Invalid or inactive API key. |
| 401 | Timestamp required | Missing X-Timestamp. |
| 401 | Signature required | Missing X-Signature. |
| 401 | Invalid timestamp format | Invalid time format. |
| 401 | Timestamp window exceeded | Request time outside allowed window. |
| 401 | Invalid signature | Signature does not match the computed value. |
Signature examples
- POST
- GET
timestamp = "2025-12-05T10:00:00Z"
body = '{"external_id":"PAY-BDT-001","amount":"5000.00","currency":"BDT"}'
message = timestamp + body
signature = hmac_sha256(api_secret, message)
X-Signature: signature
timestamp = "2025-12-05T10:00:00Z"
body = ""
message = timestamp + body
signature = hmac_sha256(api_secret, message)
X-Signature: signature