Payins

A payin collects money from your customer into your One Pay balance.

Method	Country	How the customer pays
`mobile_money`	Cameroon	A prompt on their phone (MTN or Orange), confirmed with their PIN
`bank_transfer`	Nigeria	A bank transfer to a one-time account, on a payment page

The life of a payin

pending → processing → succeeded → (settled)
                    ↘ failed

Status	Meaning
`pending`	Created, not yet with the operator
`processing`	The customer has been asked to pay
`succeeded`	Paid. `net_amount` is credited to your pending balance
`failed`	Not paid: `failure.code` and `failure.message` say why
`reversed`	Paid, then taken back (rare: a dispute or an operator error)

settled_at is set when the money becomes available for payouts: in live mode once the partner’s records confirm it, usually within minutes; in test mode at once.

Rely on the payin.succeeded webhook to deliver an order, never on the customer coming back to your site.

Mobile money (Cameroon)

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",
    "metadata": { "cart_id": "c_123" }
  }'

Field	Required	Rules
`amount`	Yes	Whole francs; more than the fee
`currency`	Yes	`XAF`
`method`	Yes	`mobile_money`
`customer.phone`	Yes	Cameroon mobile number, international format: `+2376…`
`reference`	No	Your own reference, up to 255 characters
`description`	No	Up to 500 characters; the customer sees it
`metadata`	No	Up to 20 keys of your own, returned as sent

The operator is chosen from the number (MTN or Orange): you do not send it. What the customer sees. The prompt on the customer’s phone names your business, then the description: Kola Trade: Order 1042. The name is your account’s name, or the name customers see you set for the app in the dashboard (API keys & webhooks → Apps → Edit). Accents are removed, as many phones cannot show them.

Bank transfer (Nigeria)

curl https://onepay-api-eiy9.onrender.com/v1/payins \
  -H "Authorization: Bearer $ONEPAY_KEY" \
  -H "Idempotency-Key: order-77" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 7500000,
    "currency": "NGN",
    "method": "bank_transfer",
    "customer": { "email": "ada@example.com", "name": "Ada Obi" },
    "return_url": "https://adastores.ng/thanks"
  }'

amount is in kobo: 7500000 is ₦75 000. customer is optional; the payment page asks for anything missing. return_url (https) is where the customer lands after paying. The answer has a next_action. Send your customer to its url: the page shows a one-time bank account to transfer to.

"next_action": {
  "type": "redirect_to_url",
  "url": "https://checkout.onepay.test/sim_26752679b1814a60a77d386003fdaa21"
}

next_action becomes null once the payin is finished. If the customer transfers a different amount than asked, the payin is held for review instead of succeeding.

Reading payins

GET /v1/payins/{id}: one payin.
GET /v1/payins: newest first, a page at a time.

A payin of another account, or of the other mode, answers 404 payin_not_found.

Get started

Essentials

Guides

The life of a payin

Mobile money (Cameroon)

Bank transfer (Nigeria)

Reading payins

​The life of a payin

​Mobile money (Cameroon)

​Bank transfer (Nigeria)

​Reading payins

The life of a payin

Mobile money (Cameroon)

Bank transfer (Nigeria)

Reading payins