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

The direct charge endpoints move money on a payer's behalf, so they require 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, those calls 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",
    "customer_email": "ama@example.com",
    "customer_name": "Ama Serwaa",
    "customer_phone": "0244123456"
  }'

{
  "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
  }
}

Direct charge

Debit a mobile money wallet from your own backend, with no Trite-hosted checkout page. The payer approves the charge on their handset. Ghana mobile money only — GHS is the only supported currency.

curl https://api.trite.tech/api/v1/payments/charge \
  -H "Authorization: Bearer trite_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 200,
    "mobile_number": "0249713683",
    "provider": "MTN",
    "currency": "GHS",
    "description": "Order #1234"
  }'

{
  "reference": "TX-8F3K2M-A1B2C3D4",
  "transaction_id": "9a2d...",
  "session_id": "3f6b1c9e-...",
  "status": "INITIATED",
  "amount": 200,
  "currency": "GHS",
  "message": "Payment prompt sent to your phone. Please approve it."
}

When a charge returns OTP_REQUIRED, submit the code against the same reference. The response uses the shapes above.

curl https://api.trite.tech/api/v1/payments/charge/submit-otp \
  -H "Authorization: Bearer trite_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "TX-8F3K2M-A1B2C3D4",
    "otp": "123456"
  }'

To read a charge's current state, use its reference. Terminal states are SETTLED and FAILED.

curl https://api.trite.tech/api/v1/payments/charge/TX-8F3K2M-A1B2C3D4 \
  -H "Authorization: Bearer trite_sk_..."

{
  "reference": "TX-8F3K2M-A1B2C3D4",
  "transaction_id": "9a2d...",
  "session_id": "3f6b1c9e-...",
  "status": "SETTLED",
  "amount": 200,
  "currency": "GHS",
  "method": "MOBILE_MONEY",
  "failure_reason": null,
  "created_at": "2026-08-09T14:21:07.412Z",
  "updated_at": "2026-08-09T14:21:44.907Z"
}

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

Limits are per merchant, per bucket, in a fixed one-minute window. Exceeding one returns 429 with a Retry-After header (seconds). Back off and retry after that interval.

Deprecations

SDKs