Payments

Start a checkout, get a URL, send your customer to it. One call.

#Start a payment

POSThttps://api.paymonetra.com/v1/paymentsSecret key

Starts a checkout and returns a URL to send the customer to.

Terminal

curl https://api.paymonetra.com/v1/payments \
  -H "Authorization: Bearer sk_live_..." \
  -d amount=45000 \
  -d reference=SF-10482 \
  -d customer_reference=cus_9f52 \
  -d customer_name="Ngozi Nwosu" \
  -d description="Ankara bundle"

JSON

{
  "reference": "ef8e7ff7078b893d03",
  "merchant_reference": "SF-10482",
  "status": "pending",
  "amount": 45000.70,
  "amount_requested": 45000,
  "account_number": "8021234701",
  "account_name": "MONETRA - Ngozi Nwosu",
  "checkout_url": "https://pay.paymonetra.com/ef8e7ff7078b893d03",
  "collects": ["bank_transfer"]
}

amount is not amount_requested. We add a kobo suffix, and the payer must send the exact figure. See below for why.

reference is the merchant's own order id and makes this idempotent: calling it again with the same one returns the same session rather than quoting a second amount for one order. Sending it is strongly recommended.

Sending customer_reference changes which account the payer sees. They get that customer's own permanent number, so their bank statement says the same thing every time they pay you. Without it they get your collection account. A reference we have not seen issues a new account on the spot, so no separate call is needed first; customer_name is required that first time.

Without any customer details, the checkout page collects a name and email before it shows an account, because a receipt has to go somewhere. Send them and the payer is never asked.

amount_over_limit is refused here rather than at the payer's bank, so the merchant finds out instead of the customer watching a transfer bounce.

#amount is not amount_requested

amount_requested is what you asked for. amount is what the payer must send. They differ whenever the session carries a kobo suffix.

field	what it is	what to do with it
`amount_requested`	what you passed in	reconcile your own order against it
`amount`	what the payer must transfer	never display this yourself: send them to `checkout_url` and let the page say it
`reference`	our id for the session	store it; it comes back on the webhook as `checkout_reference`
`merchant_reference`	the `reference` you sent	your own order id, echoed
`checkout_url`	the page to send the payer to	on `pay.paymonetra.com`, deliberately not on your domain or ours

#Idempotency

Send reference, your own order id. Asking again with the same one returns the same session rather than quoting a second amount for one order. It is what makes a retry safe.

#Limits are checked here, not at the bank

A payment above what the account can take is refused with amount_over_limit, so you find out instead of your customer watching a transfer bounce.

#Confirming it

Two signals, and you want both: the redirect names the payment, the webhook proves it. How to confirm a payment is the whole pattern.

#Fetch a payment

GEThttps://api.paymonetra.com/v1/payments/{reference}Secret key

The session, scoped to the caller's own merchant and mode.

Scoped to your merchant and mode. For the payer-facing view of the same session, with the instruction and countdown, see GET /checkout/{reference}.