Infrastructure your technical team can trust.

The Payme API moves insurance money: premium collections in, claim and commission payouts out, with every record carrying your own policy or claim reference so reconciliation stays clean. It is a JSON over HTTPS API — no SDK required.

Base URL: https://paymeafrica.lovable.app/api/public/v1. Every response is either { data: ... } or { error: { code, message } }. Cross-origin requests are allowed and OPTIONS preflight is handled on every endpoint.

Send your key on every request: Authorization: Bearer <your Payme API key>. Create and revoke keys in the portal under Developers. Keys are stored hashed — the full value is shown once at creation, so save it in your secret manager immediately.

A key is bound to one account. Requests only ever see that account's records, and a key stops working the moment it is revoked or the account is suspended.

A payme_test_… key returns simulated, immediately completed results so you can build without moving money. A payme_live_… key settles real funds. Both accept identical requests, and sandbox records appear in the portal marked as sandbox.

Each key is limited to 120 requests per rolling minute. Over the limit you receive 429 with a Retry-After header in seconds.

Send an Idempotency-Key header on every POST. Reuse the same key when you retry a timed-out or failed request so a premium is never debited twice and a claim is never paid twice. A natural key works well — for example the policy number plus the instalment number.

Collect a premium from a mobile wallet:

curl -X POST https://paymeafrica.lovable.app/api/public/v1/collections \
  -H "Authorization: Bearer payme_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c8a20-premium-00412" \
  -d '{
    "method": "mobile_money",
    "amount": 120,
    "currency": "GHS",
    "mobile": "0244000000",
    "provider": "MTN",
    "description": "Policy MOT/2026/00412 premium"
  }'

Pay a claim to a bank account:

curl -X POST https://paymeafrica.lovable.app/api/public/v1/payouts \
  -H "Authorization: Bearer payme_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 91ab77c4-claim-00087" \
  -d '{
    "type": "bank",
    "amount": 5000,
    "currency": "GHS",
    "account_number": "0123456789",
    "bank_code": "GCB",
    "narration": "Claim CLM/2026/00087"
  }'

The same collection call from Node or any modern JavaScript runtime:

const res = await fetch("https://paymeafrica.lovable.app/api/public/v1/collections", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.PAYME_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": policyNumber + "-" + instalment,
  },
  body: JSON.stringify({
    method: "mobile_money",
    amount: 120,
    currency: "GHS",
    mobile: "0244000000",
    provider: "MTN",
    description: `Policy ${policyNumber} premium`,
  }),
});
const { data, error } = await res.json();
if (error) throw new Error(error.message);
console.log(data.reference, data.status);

Money movement settles asynchronously. Poll the transaction endpoint, or read the record in the portal.

Payme receives settlement callbacks from the payment partner and updates your collections and payouts automatically, then raises an in-app notification. You do not need to host an endpoint to stay in sync — polling the transaction endpoint is enough for most integrations.

If you want events pushed to your own systems, ask us to enable outbound webhooks for your account. Deliveries are signed with an HMAC-SHA256 signature over {timestamp}.{raw_body} and are at-least-once, so de-duplicate on the event id.

{
  "id": "evt_01J8...",
  "type": "payout.completed",
  "data": {
    "object": {
      "merchant_reference": "PAY-3J9QZ",
      "status": "completed",
      "amount": "5000.00",
      "fee_amount": "8.00"
    }
  }
}

Put your policy, claim or commission reference in description (collections) or narration (payouts). Payme returns its own reference for every record — store it against the policy in your core system so both sides can be matched line by line at settlement.

Bulk payouts submitted in the portal follow submit → approve → execute: nothing leaves the account until a second authorised person releases the batch. API payouts execute directly, so restrict live keys to systems that already apply your own approval controls.

Start in the sandbox, then request live keys once your flows pass. If a call fails with provider_unconfigured your account is not yet enabled for live money movement — contact us and we will switch it on.