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. |
| IP whitelist | When enabled for the merchant, the request source IP must be allowed. |
| 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 in ISO-8601 format, for example 2026-07-16T12:00:00Z. Default allowed skew is ±60 seconds; UNIX timestamps are not accepted. |
| 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 other than transaction history, the body is an empty string. |
| 3 | Concatenate timestamp + body. GET /api/v1/transactions instead uses its fixed canonical payload. |
| 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 (standard)
timestamp = "2025-12-05T10:00:00Z"
body = '{"external_id":"PAY-ARS-001","amount":"5000.00","currency":"ARS"}'
message = timestamp + body
signature = hmac_sha256(api_secret, message)
X-Signature: signature
GET /api/v1/transactions does not use the formula below. Use the Transaction History canonical signature.
timestamp = "2025-12-05T10:00:00Z"
body = ""
message = timestamp + body
signature = hmac_sha256(api_secret, message)
X-Signature: signature
Transaction history signatures
GET /api/v1/transactions uses a fixed canonical signature that also covers the request path and query filters and requires a unique request ID. See Transaction History for the exact payload.