Quickstart

Everything here runs in test mode: no real money moves and no real phone is asked to pay.

Get a test API key

Sign in to the dashboard, open API keys & webhooks and create a test key. It starts with sk_test_ and is shown once: store it on your server, for example in an environment variable.

export ONEPAY_KEY=sk_test_...

Collect a payment

Ask a customer for 10 000 XAF by mobile money. The Idempotency-Key makes the request safe to retry: use your own order id.

curl https://onepay-api-eiy9.onrender.com/v1/payins \
  -H "Authorization: Bearer $ONEPAY_KEY" \
  -H "Idempotency-Key: order-1042" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 10000,
    "currency": "XAF",
    "method": "mobile_money",
    "customer": { "phone": "+237650000001" },
    "reference": "order-1042",
    "description": "Order 1042"
  }'

const res = await fetch('https://onepay-api-eiy9.onrender.com/v1/payins', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.ONEPAY_KEY}`,
    'Idempotency-Key': 'order-1042',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    amount: 10000,
    currency: 'XAF',
    method: 'mobile_money',
    customer: { phone: '+237650000001' },
    reference: 'order-1042',
    description: 'Order 1042',
  }),
});
const payin = await res.json();

import os, requests

payin = requests.post(
    "https://onepay-api-eiy9.onrender.com/v1/payins",
    headers={
        "Authorization": f"Bearer {os.environ['ONEPAY_KEY']}",
        "Idempotency-Key": "order-1042",
    },
    json={
        "amount": 10000,
        "currency": "XAF",
        "method": "mobile_money",
        "customer": {"phone": "+237650000001"},
        "reference": "order-1042",
        "description": "Order 1042",
    },
).json()

The answer is the payin, waiting for the customer:

{
  "id": "pay_ec9175c124d840169818b5cee976fc2b",
  "status": "processing",
  "amount": 10000,
  "fee": 300,
  "net_amount": 9700,
  "currency": "XAF",
  "method": "mobile_money",
  "customer": { "phone": "+237650000001", "email": null, "name": null },
  "reference": "order-1042",
  "description": "Order 1042",
  "metadata": {},
  "failure": null,
  "next_action": null,
  "mode": "test",
  "created_at": "2026-10-29T09:51:36.516Z",
  "updated_at": "2026-10-29T09:51:36.544Z",
  "succeeded_at": null,
  "failed_at": null,
  "settled_at": null
}

Play the customer

In live mode the customer approves on their phone. In test mode you do it:

curl -X POST https://onepay-api-eiy9.onrender.com/v1/test_helpers/payins/pay_ec9175c124d840169818b5cee976fc2b/succeed \
  -H "Authorization: Bearer $ONEPAY_KEY"

The payin is now succeeded, and 9 700 XAF (10 000 minus the 300 fee) is in your test balance: check with GET /v1/balances.

Hear about it by webhook

Polling works, but webhooks are better: One Pay calls your server the moment a payment succeeds or fails. Add an endpoint in the dashboard, or:

curl https://onepay-api-eiy9.onrender.com/v1/webhook_endpoints \
  -H "Authorization: Bearer $ONEPAY_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://yourshop.cm/onepay/webhooks" }'

Keep the secret from the answer (whsec_...): it is shown once, and you need it to check each webhook’s signature.

Payins

Mobile money in Cameroon, bank transfers in Nigeria.

Webhooks

Signatures, retries and duplicates.

Payouts

Pay suppliers, riders and partners.

Going live

Verification, live keys and the checklist.

Get started

Essentials

Guides

Next

Payins

Webhooks

Payouts

Going live

​Next

Payins

Webhooks

Payouts

Going live

Next