Authentication
Webhook

Authentication

Transfaar’s external Business API uses HMAC-based authentication on top of API keys.
Every request to a /business endpoint must be signed with your secret key.

HMAC headers

Send these headers with every authenticated request:

X-API-Key: your_api_key_here
X-Signature: generated_signature_here
X-Timestamp: 2025-01-15T10:30:00Z
  • X-API-Key: the public identifier for your business API key.
  • X-Timestamp: RFC3339 UTC timestamp (e.g. 2025-01-15T10:30:00Z), used to prevent replay attacks (5‑minute freshness window, 1‑minute future tolerance).
  • X-Signature: hex-encoded HMAC-SHA256 of body + "|" + timestamp using your secret key.

The server recomputes the HMAC using the request body and timestamp; if anything has been tampered with (body or timestamp), the signature fails and the request is rejected.

Signing algorithm (conceptual)

  1. Serialize the JSON request body (empty string if there is no body).
  2. Generate an RFC3339 timestamp.
  3. Build the string: data_to_sign = body + "|" + timestamp.
  4. Compute HMAC-SHA256(secret_key, data_to_sign) and hex-encode the result.
  5. Send the signature as X-Signature with the same body and timestamp.

Refer to the internal HMAC API Authentication Guide (docs/hmac_authentication.md) in this repository for complete Go, cURL and Python examples.

Authentication errors

Common authentication failures return 401 Unauthorized or 403 Forbidden, for example:

  • Missing headers: x-api-key, x-signature or x-timestamp.
  • Invalid timestamp format or a timestamp that is too old / too far in the future.
  • Invalid signature (body or timestamp changed in transit).
  • Inactive or expired API key.

Business API key management (/business routes)

Business API keys are managed via dedicated /business endpoints. For example:

  • List business API keys
    • Method: GET
    • Path: /api/v1/business/api-keys
    • Description: Returns all active API keys associated with your business user, including metadata such as name, is_active, last_used_at, and expires_at. Secret keys are never returned once created.

Use these endpoints to rotate keys regularly, configure webhook URLs per key, and keep inactive keys disabled.

APIKyc