Subscription Gateway API

The Subscription Gateway is the source of truth for whether a tenant may use a paid product. Requests and responses are JSON under /api/v1.

Create a project in the operator dashboard. That screen shows client_id, client_secret, and the webhook secret once. Store them on your server. The browser and the Android app never see them.

Exchange the project credentials for a short-lived JWT, then send it as a bearer token. The default lifetime is 3600 seconds. Request a new token when it expires.

Authorization: Bearer <access_token>

Call POST /api/v1/customers/sync with the id you already store. The pair of project and external_customer_id is the customer. Email and phone can change later.

Optional fields are display_name, email, and phone. After an identity is locked, later syncs keep the stored name, email, and phone.

Read entitled from GET /api/v1/customers/{external_customer_id}/subscription. Open the paid screen only when it is true. A local database flag cannot grant access.

Paid window

A successful payment lasts 31 calendar days, counted with day arithmetic. A renewal before expiry extends from the current end_at. A renewal after expiry starts at the new activation time. Approval of a proof while the provisional window is still open starts the 31 days at the provisional start.

When entitled is false, create a billing session and send the person to pay_url. They pay as a guest. They do not create an account on this gateway.

Register each return URL on the project first. The gateway compares scheme, host, and path, and ignores one trailing slash. Any other URL is rejected with invalid_return_url.

The code lasts 10 minutes and works once. When the browser returns to your app, read the subscription again. The redirect itself is a navigation event.

Failures use one envelope.

{
  "error": {
    "code": "not_found",
    "message": "Customer was not found."
  }
}

POST /api/v1/auth/token allows 30 attempts per minute. A throttled response asks you to wait and try again.

Public probes. No authentication.

{ "status": "ok" }

/ready checks the database connection and returns the same body when the API can serve traffic.

POST /api/v1/customers/sync
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "external_customer_id": "123",
  "display_name": "Acme Stores",
  "email": "billing@acme.example",
  "phone": "0999123456"
}

{
  "customer_id": "4f1c0e3a-6b2d-4a7e-9c11-2d8e5a0b7f64",
  "external_customer_id": "123"
}

Call this before you ask for the subscription, and again when the name, email, or phone changes.

{
  "external_customer_id": "123",
  "subscription_id": "9c2e1a44-1b77-4d0a-8f55-0a6d2c8e91ab",
  "status": "active",
  "entitled": true,
  "payment_required": false,
  "start_at": "2026-10-01T08:00:00+00:00",
  "end_at": "2026-11-01T08:00:00+00:00",
  "amount": "50000.00",
  "currency": "MWK",
  "is_provisional": false,
  "plan_name": "Monthly"
}

A customer with no subscription returns status pending_payment, entitled false, and payment_required true. Amounts are decimal strings.

When a project has a webhook URL, this gateway POSTs events to it. Respond with a 2xx status. Delivery retries, then stops after 8 attempts.

X-Subscription-Signature: t=1760112000,v1=<hex>

v1 is HMAC-SHA256 of timestamp + "." + raw body, using the project webhook secret. Compare against the raw bytes before you parse JSON. Ignore a repeat of the same event id.

{
  "id": "b7e1c2d0-4a55-4e18-9f20-6c0a1d8e33aa",
  "type": "subscription.activated",
  "created_at": "2026-10-10T17:00:00+00:00",
  "project_id": "1a9c4e22-0b31-4f77-8d10-55e2a0c91f08",
  "data": {
    "subscription_id": "9c2e1a44-1b77-4d0a-8f55-0a6d2c8e91ab",
    "external_customer_id": "123"
  }
}

How a payment is confirmed

The customer pays on pay_url with Airtel Money, TNM Mpamba, a bank transfer, a proof upload, or Wallet. Proof files are stored in the Files gateway. This API keeps the file id.

Airtel, Mpamba, and Standard Bank alerts arrive from Relay. The customer enters the name on the account. A phone number is compared only when both the payment and the SMS include one. A bank alert with no payer name matches only a single waiting bank payment for that amount. The Relay reference can pay once.

Uploading a proof opens review and, while the provisional window is open, temporary access. The payment becomes paid when a reviewer approves it or links an unused Relay reference. Wallet charges are confirmed by reading the charge from Wallet after its signed webhook.