API Reference

One REST API for all three rails. Every request is authenticated with a Bearer

key, versioned by an optional date header, and returns JSON errors from a

closed set. This page covers the platform-wide concepts; each resource has its

own page:

  • Payment intents — create, confirm, and simulate payments across M-PAiSA, MyCash, and cards.
  • Payment links — shareable hosted-checkout URLs, single-use or reusable.
  • Webhook endpoints — register endpoints and verify signed event deliveries.
  • API keys — secret and publishable keys, scoped to test or live mode.

The machine-readable contract is /docs/openapi.yaml —

the single source of truth (ADR-0006).

Base URL


https://api.transxact.io

Authentication


Authorization: Bearer <key>

Two key types, each scoped to a mode (test or live):

  • Secret key (sk_test_… / sk_live_…) — full account access, server-side only.
  • Publishable key (pk_test_… / pk_live_…) — may only create payment intents and drive the hosted checkout; forbidden everywhere else (permission_error / publishable_key_forbidden).

Rate limits apply per key on payment-intent creation: secret keys 10,000

requests/min, publishable keys 120 requests/min; over the limit returns

rate_limit_error / rate_limited with HTTP 429.

See API keys for creating and rotating keys.

Idempotency

Send an Idempotency-Key header on create requests: a retried request with the

same key (same merchant) returns the original response instead of creating a

duplicate. Keys are honored for 24 hours.

Versioning

  • Pin a version with the Transxact-Version: YYYY-MM-DD request header.
  • Omitting the header pins to the current default (2026-08-16).
  • New fields are additive only — they never break a pinned integration.
  • Any past or current date remains valid (additive-only contract, ADR-0006).

Error object

Every API error is a JSON body with a closed type set and a machine-readable

code:

  • type ∈ invalid_request | authentication_error | permission_error | idempotency_error | rate_limit_error | api_error | payment_error.
  • code is stable and machine-readable (e.g. amount_too_small, intent_already_succeeded, otp_incorrect).
  • message is human-readable and may change. Receivers must not reject unknown fields (additive-only contract, ADR-0013).

{
  "type": "invalid_request",
  "code": "amount_too_small",
  "message": "Amount must be at least FJ$0.01"
}

SDKs

Twelve first-party, maintained client libraries wrap the API with typed

requests/responses, idempotency handling, retries, webhook signature

verification, and test-mode magic-value helpers (ADR-0010). Each code example

in this reference links to the corresponding SDK for the complete runnable

version.