Build on the Unified Payment Gateway

Introduction

Overview

The Unified Payment Gateway gives your systems one integration for Malawian payment providers. You create a payment with one request, the gateway routes it to PayChangu, OneKhusa, and you receive a signed webhook when it settles. No separate account or code per provider.

It is built for Cool Enterprises projects and their clients. Accounts are reviewed and approved by a platform administrator before they can create payments.

Quickstart

1. Create API credentials

Once your account is approved, open Developer / API access in the console, name the integration (for example “ERPNext Production”) and choose Generate credentials. You get an API key (pk_…) and an API secret (sk_…). The secret is shown once, so store both in your server's environment as GATEWAY_API_KEY and GATEWAY_API_SECRET. Your own email and password are not involved.

2. Get an access token

Exchange the key and secret for a token that lasts 15 minutes. Do this from your server, not from a browser or app.

curl -X POST https://upg-api.coolenterprisesmw.com/api/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{"apiKey":"'"$GATEWAY_API_KEY"'","apiSecret":"'"$GATEWAY_API_SECRET"'"}'
# -> { "status": "success", "data": { "accessToken": "eyJ…", "tokenType": "Bearer", "expiresIn": 900 } }

3. Create a payment

Send the access token as a Bearer token with the gateway, method, amount and customer. Always include an Idempotency-Key so a retry can never create a second payment.

curl -X POST https://upg-api.coolenterprisesmw.com/api/v1/payments/initialize \
  -H "Authorization: Bearer $GATEWAY_ACCESS_TOKEN" \
  -H "Idempotency-Key: order-1001" \
  -H "Content-Type: application/json" \
  -d '{"gateway":"paychangu","method":"mobile_money","operator":"airtel","amount":5000,"currency":"MWK","customer":{"name":"Chikondi Banda","phone":"0999123456"},"reference":"ORDER-1001"}'

The response's next_action tells you what the customer must do (approve a prompt, send money to an account number, or open a payment page). When the token expires you get 401 TOKEN_EXPIRED: request a new one and retry. API authentication shows a helper that does this for you.

4. Receive the result

Set your webhook URL under Settings. When the payment succeeds, fails, expires or is refunded, the gateway sends a signed event to it. Verify the signature, then mark your order as paid. See Webhooks for the exact steps.

API authentication

How it works

Your ERP, POS, website or mobile backend authenticates with an API key and secret, created in the console. The pair is exchanged for a short-lived access token that you send with every request.

Behind the scenes the gateway holds the PayChangu and OneKhusa credentials itself. Your system never needs them: it only ever talks to the gateway.

Five steps

• Generate credentials. In the console open Developer / API access and create one credential per system.
• Store the secret on your server. It is shown once and only a one-way hash of it is kept, so it cannot be recovered. Put it in an environment variable or secret manager.
• Exchange them for a token. POST /api/v1/auth/token with apiKey and apiSecret. You get accessToken and expiresIn (900 seconds).
• Call the API with the token. Send Authorization: Bearer <accessToken>.
• Re-authenticate when it expires. Request a new token shortly before expiresIn runs out, or when you receive 401 TOKEN_EXPIRED.

Complete example

# 1. Exchange the credentials (once every ~15 minutes)
curl -X POST https://upg-api.coolenterprisesmw.com/api/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{"apiKey":"pk_live_xxxxx","apiSecret":"sk_live_xxxxx"}'

# 2. Use the accessToken from the response
curl -X POST https://upg-api.coolenterprisesmw.com/api/v1/payments/initialize \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"gateway":"paychangu","method":"mobile_money","operator":"airtel","amount":5000,"currency":"MWK","customer":{"name":"Chikondi Banda","phone":"0999123456"},"reference":"ORDER-1001"}'

Token expiry

Access tokens last expiresIn seconds (900, so 15 minutes). There is no refresh token for integrations: you simply repeat the exchange with your key and secret. Cache the token and reuse it until about a minute before it expires; do not request a new token for every payment. An expired token returns 401 TOKEN_EXPIRED. A token also stops working immediately if its credential is rotated, disabled or revoked.

Scopes

Each credential carries scopes, and its tokens can do only what they allow. Choose the narrowest set the integration needs. An API token can never reach console or admin endpoints, whatever its scopes.

Sandbox and production

Credentials are created for one environment and say so in their prefix: pk_test_… / sk_test_… for sandbox and pk_live_… / sk_live_… for production. A gateway serves one environment, so a sandbox credential is refused by the production gateway (403 WRONG_ENVIRONMENT) and the other way round. Use the base URL of the environment that matches your credentials.

Rotation and revocation

• Rotate issues a new secret for the same key. The old secret and all tokens made with it stop working immediately, so deploy the new secret first or accept a short outage.
• Disable pauses a credential; Enable resumes it. Tokens from before the pause stay invalid.
• Revoke is permanent. Use it when a secret may have leaked, then create a new credential.
• Every create, rotate, disable, revoke, token issue and failed attempt is recorded in the credential audit trail.

Authentication errors

{
  "status": "error",
  "code": "TOKEN_EXPIRED",
  "message": "Access token has expired.",
  "requestId": "0b6f7a3e-…"
}

Rate limits

• POST /auth/token: only failed attempts count. After 20 failures in 15 minutes from one address you get 429 RATE_LIMITED. Successful exchanges are not throttled.
• Payment creation: 60 requests per minute per company.
• All endpoints share a general per-address limit. On 429, back off and retry with the same Idempotency-Key.

Security best practices

• Keep the API secret on a server you control, in an environment variable or secret manager. Never in a website, mobile app, browser code, repository, log or support ticket.
• A mobile or web front end should call your backend, and your backend calls the gateway.
• One credential per system, with the fewest scopes it needs, so you can revoke one without touching the rest.
• Treat access tokens as secrets too: do not log them or pass them in URLs.
• Rotate secrets on a schedule and immediately if a person with access leaves or a leak is suspected.
• Always use HTTPS.

Moving off the raw secret

Sending the sk_… secret on every request is retired: it now answers 401 SECRET_NOT_ACCEPTED_AS_BEARER. The same key pair is still exchanged at POST /api/v1/auth/token, so migrating needs no new credentials - fetch a token and send it as the Bearer token.

Access tokens

Conventions

Base URL

All paths are relative to the gateway host you were given, for example https://upg-api.coolenterprisesmw.com. Use HTTPS only.

Authentication

Exchange your API key and secret at POST /api/v1/auth/token, then send Authorization: Bearer <accessToken> on every payment and read endpoint. See API authentication. Use Try it on any endpoint to run a request straight from this page.

Idempotency

Send Idempotency-Key (8 to 120 characters) on POST /api/v1/payments/initialize. Repeating a request with the same key returns the original payment with status 200 instead of creating another. Reusing a key with a different amount, gateway or method returns 409 IDEMPOTENCY_KEY_REUSED. Use one key per order, such as your order id.

Responses

Successful responses look like { "status": "success", "data": … }. Lists add a pagination block. Failures use the error shape described under Errors.

Pagination

List endpoints accept page (from 1) and pageSize (1 to 100, default 20) and return pagination.total and pagination.totalPages.

Dates and amounts

• Timestamps are ISO 8601 in UTC, e.g. 2026-09-30T10:04:12.000Z.
• Date filters (from, to) are YYYY-MM-DD days in Malawi time (UTC+2) and inclusive.
• Amounts are plain numbers in the major unit (25000 means MWK 25,000), with at most two decimals. Always read the currency next to an amount.

Payments

Webhooks

Set the endpoint

Save a public HTTPS URL under Settings in the console (or PUT /api/v1/api-keys/webhook). Use Send test event to confirm your server answers with a 2xx status. A single payment can override the address with callback_url.

Events

{
  "id": "evt_5c1e…",
  "type": "payment.successful",
  "created_at": "2026-09-30T10:04:13.000Z",
  "data": {
    "id": "6f1b2c1e-8e0a-4b8e-9d3c-2f0a5e7c1a11",
    "status": "successful",
    "gateway": "onekhusa",
    "amount": 25000,
    "currency": "MWK",
    "reference": "INV-2044",
    "fee": 500
  }
}

Verify the signature

Each request has X-UPG-Signature: t=<unix>,v1=<hex>. Compute HMAC-SHA256 over the string "<t>.<raw body>" using your account signing secret (the secret of the original account key under Developer / API access, not an integration credential) and compare it to v1 in constant time. Reject the event if it does not match or if t is more than five minutes old.

import crypto from "node:crypto";

// Use express.raw({ type: "application/json" }) so the body is the untouched bytes.
export function verify(rawBody, header, apiSecret) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const expected = crypto.createHmac("sha256", apiSecret).update(`${parts.t}.${rawBody}`).digest("hex");
  const fresh = Math.abs(Date.now() / 1000 - Number(parts.t)) < 300;
  const a = Buffer.from(expected);
  const b = Buffer.from(parts.v1 ?? "");
  return fresh && a.length === b.length && crypto.timingSafeEqual(a, b);
}

Retries

Answer with any 2xx status within 10 seconds. Otherwise the gateway retries after 1, 5, 15 and 60 minutes, then 4 and 12 hours, and stops after six attempts. Make your handler idempotent: a retry resends the same bytes with the same event id, so dedupe on it rather than on arrival order.

Every attempt is recorded under Settings in the console - the event, the address it went to, how many times we tried, the HTTP status your server returned and the error when there was one. Records are kept for 90 days. Only the company owner account can read them.

Gateways

PayChangu

• mobile_money - the customer gets a prompt on their phone and approves it with their PIN. Needs operator (see the providers list, e.g. airtel) and a Malawian customer.phone. Amounts are whole MWK.
• bank_transfer - returns a dedicated account number in next_action; the customer transfers the exact amount to it. PayChangu enables this for banks and financial institutions, so it may be unavailable to your account.
• Status is confirmed by asking PayChangu directly, both on a schedule and whenever you fetch the payment.

OneKhusa

• timed_transfer - returns a one-time account number in next_action. The customer sends exactly the amount from any supported bank or mobile money wallet within 15 minutes. After that the payment becomes cancelled.
• hosted_checkout - returns a redirect URL to OneKhusa's payment page. Set return_url to bring the customer back to your site.
• OneKhusa confirms payments by signed webhook. The gateway rejects events with a bad signature and holds any event whose amount differs from the payment for review.

Credentials & webhooks

Transactions

Errors

Error shape

Failed requests return a non-2xx status and this body:

{
  "status": "error",
  "code": "VALIDATION_ERROR",
  "message": "Please correct the highlighted fields.",
  "requestId": "0b6f7a3e-…",
  "errors": { "email": "Enter a valid email address." }
}

• code - a stable identifier. Branch on this, not on message.
• message - a readable explanation you can show to users.
• requestId - quote this to support when reporting a problem.
• errors - optional per-field messages.

Error codes

Handling errors

const res = await fetch(url, options);
const body = await res.json().catch(() => null);

if (!res.ok) {
  if (body?.code === "MERCHANT_NOT_APPROVED") return showPendingApproval();
  throw new Error(body?.message ?? "The request failed.");
}

Payment statuses

Payment statuses