API Documentation

Getting started

The API is served from https://api.trite.tech. Create an API key in the dashboard under Settings → Integrations → API Management.

Authentication

Pass your key as a bearer token on every request. Your merchant account is derived from the key — there is no merchant ID parameter.

Authorization: Bearer trite_sk_...

Merchant verification

API access requires your merchant account to be fully verified. This means:

1. Email verified — confirm your email address via the link sent at registration.
2. KYC approved — submit identity verification documents in the merchant portal under Settings and receive approval.

If either requirement is not met, all payment API calls will return 403 with a machine-readable code field:

{
  "error": "Merchant account email is not verified. Please verify your email in the merchant portal.",
  "code": "EMAIL_NOT_VERIFIED"
}

{
  "error": "Merchant KYC verification is required. Please complete identity verification in the merchant portal.",
  "code": "KYC_NOT_APPROVED",
  "kyc_status": "PENDING"
}

Create a payment session

Creates a checkout session and returns a payment_url to hand to your customer. Sessions expire after 24 hours.

curl https://api.trite.tech/api/v1/payments/initiate \
  -H "Authorization: Bearer trite_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 25.50,
    "currency": "GHS",
    "description": "Order #1234",
    "redirect_url": "https://yourstore.com/thank-you"
  }'

{
  "session_id": "3f6b1c9e-...",
  "payment_url": "https://pay.trite.tech/pay/3f6b1c9e-...",
  "amount": 25.5,
  "currency": "GHS",
  "expires_at": "2026-07-08T12:00:00.000Z"
}

Check session status

Returns the session and its latest transaction. Prefer webhooks over polling for real-time updates.

curl https://api.trite.tech/api/v1/payments/3f6b1c9e-.../status \
  -H "Authorization: Bearer trite_sk_..."

{
  "session_id": "3f6b1c9e-...",
  "status": "COMPLETED",
  "amount": 25.5,
  "currency": "GHS",
  "description": "Order #1234",
  "expires_at": "2026-07-08T12:00:00.000Z",
  "created_at": "2026-07-07T12:00:00.000Z",
  "transaction": {
    "transaction_id": "9a2d...",
    "tx_id_display": "TX-8F3K2M",
    "status": "SETTLED",
    "method": "MOBILE_MONEY",
    "amount": 25.5,
    "currency": "GHS",
    "failure_reason": null
  }
}

Webhooks

Configure your endpoint URL and event subscriptions in Settings → Integrations → Webhook Configuration. Events are delivered as POST requests with a JSON envelope:

{
  "id": "evt_5c1a...",
  "type": "payment.success",
  "created_at": "2026-07-07T12:03:41.000Z",
  "data": {
    "tx_id_display": "TX-8F3K2M",
    "session_id": "3f6b1c9e-...",
    "amount": 25.5,
    "currency": "GHS",
    "method": "MOBILE_MONEY",
    "status": "SETTLED"
  }
}

Verifying signatures

Every delivery carries an X-Trite-Signature header: t=<unix>,v1=<hex>. Compute HMAC-SHA256 of `${t}.${rawBody}` with your signing secret (Settings → Integrations), compare timing-safely, and reject if the timestamp is more than 5 minutes old.

import crypto from "crypto";

function verifyTriteSignature(rawBody, header, secret) {
  const { t, v1 } = Object.fromEntries(
    header.split(",").map((p) => p.split("="))
  );
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${t}.${rawBody}`)
    .digest("hex");
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
}

Rate limits

60 requests per minute per merchant per endpoint. Exceeding the limit returns 429 with a Retry-After header (seconds). Back off and retry after that interval.

Deprecations

SDKs