Tranzak Docs
tranzak.co Dashboard
Docs  /  Get started

API conventions

Base URL, request and response format, amounts, currencies, identifiers, timestamps and rate limits for the Tranzak API.

These rules apply to every endpoint of the Tranzak API.

Base URL

https://api.tranzak.co/api/gateway/v1

Every endpoint in this documentation is relative to that URL. The path is /api/gateway/v1/…, not /v1/… and not /api/v1/….

Requests

Item Value
Authentication X-Api-Key: <your key> on every request. See Authentication.
Body JSON, with Content-Type: application/json.
Accept Accept: application/json.

Responses

Most responses use this envelope:

{ "success": true, "data": { } }

Note POST /payments is the exception: it returns its fields at the root of the JSON. Every other endpoint wraps the result in data. Failed requests return { "success": false, "error": "…", "message": "…" }.

Amounts and currencies

  • Amounts are in the currency's real unit: 500 means 500 gourdes, not cents.
  • Amounts are returned as strings ("250.00"). Parse them as decimals and never compare them with floating-point numbers.
  • Supported currencies are HTG and USD.
  • MonCash and NatCash are paid in gourdes. A USD amount is converted to HTG at the Tranzak rate before the payment is created. See Currencies and exchange rate.

Identifiers and dates

Item Format
transaction_id A numeric string, for example "17843268616389".
reference Your own order identifier, up to you. It is not enforced as unique.
Timestamps ISO 8601 in UTC, for example 2026-10-04T14:00:00.000000Z.

Rate limits

  • 60 requests per minute per IP address. Beyond that the API answers 429 with rate_limit_exceeded and a retry_after value in seconds.
  • 10 invalid-key attempts per hour per IP address answer 429 too_many_attempts.

Back off when you receive a 429. Never retry an invalid key in a loop.

No idempotency key

The API has no idempotency key, and reference is not enforced as unique. Retrying POST /payments after a timeout can create a second payment. To protect yourself:

  1. Send a unique reference for each order.
  2. Before creating again, call GET /payments/reference/{reference} and reuse an existing payment that is not final.
  3. Disable your pay button after the first click.