API reference

Base URL: https://api.patronise.me/v1 · Auth: Authorization: Bearer <key> · Format: JSON in, JSON out · Spec: openapi.json

The key decides the mode: sk_test_… sees only test objects, sk_live_… only live ones. Secret keys (sk_) can call everything; publishable keys (pk_) can only create checkout sessions and read fees, operators and their own checkout payments.

Endpoints

Method	Path	Description
`POST`	`/v1/payments`	Create a payment
`GET`	`/v1/payments`	List payments (`status`, `reference`, `limit`, `starting_after`)
`GET`	`/v1/payments/{id}`	Retrieve a payment
`POST`	`/v1/checkout-sessions`	Create a hosted checkout page
`GET`	`/v1/checkout-sessions/{id}`	Retrieve a checkout session
`POST`	`/v1/payment-links`	Create a payment link
`GET`	`/v1/payment-links`	List payment links
`GET`	`/v1/payment-links/{id}`	Retrieve a payment link
`PATCH`	`/v1/payment-links/{id}`	Turn a link on or off (`active`)
`POST`	`/v1/payouts`	Send a payout
`GET`	`/v1/payouts`	List payouts
`GET`	`/v1/payouts/{id}`	Retrieve a payout
`GET`	`/v1/balance`	Available and pending balance per currency
`GET`	`/v1/fees/quote`	Fee for an amount and operator (`amount`, `currency`, `operator`, `fee_bearer`, `direction`)
`GET`	`/v1/operators`	Payment methods and fees (`country`, `currency`)
`POST`	`/v1/operators/predict`	Find the operator of a phone number
`GET`	`/v1/events`	Recent events (`type`)
`GET`	`/v1/events/{id}`	Retrieve an event

Conventions

Amounts are integers in the currency's smallest unit. FCFA (XAF, XOF) and CDF have no decimals.
Dates are ISO 8601 strings in UTC.
IDs have a prefix: pay_ payment, cs_ checkout session, plink_ payment link, po_ payout, evt_ event.
Lists return { "object": "list", "data": [...], "has_more": bool }, newest first. Paginate with limit (1–100, default 20) and starting_after=<last id>.
Idempotency: send Idempotency-Key on every POST. Replays return the first response with Idempotent-Replayed: true. Keys last 24 hours.
Rate limit: 120 requests per minute per key (429 above).
Errors: see Errors.

The payment object

{
  "id": "pay_3hX9kQ2mVb8sLr4tN7wYc1Ze",
  "object": "payment",
  "livemode": false,
  "status": "succeeded",
  "amount": 5000,
  "charge": 5000,
  "fee": 138,
  "net": 4862,
  "fee_bearer": "merchant",
  "currency": "XAF",
  "country": "CM",
  "operator": "mtn_cm",
  "phone": "237670000000",
  "reference": "order-1042",
  "description": "Sneakers",
  "customer": { "email": null, "name": null },
  "metadata": { "cart": "42" },
  "next_action": null,
  "failure": null,
  "checkout_session": null,
  "payment_link": null,
  "created_at": "2026-11-02T10:15:00.000Z",
  "completed_at": "2026-11-02T10:15:05.000Z"
}

The payout object

{
  "id": "po_8sK2mX…",
  "object": "payout",
  "livemode": true,
  "status": "paid",
  "amount": 50000,
  "fee": 1150,
  "sent": 48850,
  "currency": "XAF",
  "destination": { "country": "CM", "operator": "mtn_cm", "phone": "237670000000", "account_name": "Awa Ngono" },
  "reference": "weekly-settlement",
  "failure": null,
  "created_at": "2026-11-02T10:15:00.000Z",
  "completed_at": "2026-11-02T10:16:12.000Z"
}

The checkout session object

{
  "id": "cs_gJandwH0lBjIBhrxdtzZ2p7L",
  "object": "checkout_session",
  "livemode": false,
  "status": "open",
  "url": "https://patronise.me/developers/pay/cs_gJandwH0lBjIBhrxdtzZ2p7L",
  "amount": 7500,
  "currency": "XAF",
  "description": "Order #77",
  "reference": null,
  "fee_bearer": "merchant",
  "customer_email": null,
  "metadata": {},
  "success_url": "https://shop.example.com/thanks",
  "cancel_url": null,
  "payment": null,
  "expires_at": "2026-11-02T11:30:20.819Z",
  "created_at": "2026-11-02T10:30:20.819Z"
}