FAQ — Payments
Frequently asked questions about collections, Mobile Money, bank cards, transaction statuses, and refunds.
General
What payment methods are accepted?
Mobile Money (MTN MoMo, Orange Money, Wave, Airtel), bank cards (Visa, Mastercard), and bank transfers. Exact availability depends on the country and provider.
How long does a Mobile Money payment stay pending?
An unconfirmed Mobile Money payment expires after 24 hours by default (configurable per
request between 5 minutes and 30 days via the expires_in parameter). Beyond that time, the
transaction moves to expired status and the customer must start over.
In which currency unit should I send the amount?
Always in the major unit of the currency: 25000 for 25,000 XAF, 500 for 500 NGN. Do not
convert to subunits (no centimes).
Can the customer pay for the same order multiple times?
The reference field has no uniqueness constraint — reusing it does not prevent a second
payment. To avoid duplicate charges on retry, send an Idempotency-Key header (see
Idempotency): the same key reused within 24h with
the same payload returns the original payment instead of creating a new one.
Use a unique Idempotency-Key per attempt
Generate one Idempotency-Key per checkout attempt (e.g. derived from your internal order ID)
and send it on every POST /payments call for that attempt.
Statuses and lifecycle
What are the possible payment statuses?
| Status | Meaning |
|---|---|
pending | Payment initiated, waiting for customer action |
processing | Confirmed with the provider, settlement in progress |
partial | Some but not all of the amount was captured (split payments) |
succeeded | Payment confirmed, funds collected |
failed | Payment failed (insufficient funds, declined…) |
cancelled | Cancelled by the customer or merchant |
expired | Not completed before the payment window closed |
refunded | Fully refunded after succeeding |
partially_refunded | Partially refunded after succeeding |
How do I know if a payment succeeded?
Never rely solely on the browser return. The source of truth is:
- The
payment.succeededwebhook received on your server. - The
GET /payments/{id}verification which returns the current status.
Can I cancel a pending payment?
Yes — DELETE /payments/{id} cancels a payment still in pending status. Once it's
succeeded, use a refund instead. A pending payment also expires automatically (see above).
Refunds
How long does a refund take?
In sandbox, the refund is processed immediately. In production, the delay depends on the Mobile Money operator or banking network, usually between a few minutes and 24 hours.
Can I do a partial refund?
Yes. Specify an amount lower than the original transaction's amount when calling POST /refunds.
reason is required and must be one of a fixed set of values.
https://api.wajub.com/refundscurl https://api.wajub.com/refunds \
-H "Authorization: sk_test.xxxx" \
-d '{ "payment": "trx_01JXXXXXXXXXXXXX", "amount": 5000, "reason": "requested_by_customer" }'{
"status": "Created",
"code": 201,
"refund": { "id": "rfd_01JXXXXXXXXXXXXX", "status": "pending", "amount": 5000 }
}reason must be one of: duplicate, fraudulent, requested_by_customer,
service_not_delivered, product_not_received, wrong_amount, network_error,
transaction_error, customer_complaint, merchant_error, reconciliation.
Are there fees on refunds?
The initial transaction fees are not refunded. Check your contract for applicable fee details.
Mobile Money
What happens if the Mobile Money network is unavailable?
Our orchestrator detects the unavailability and automatically falls back to another provider if you have configured fallback rules. The customer sees an alternative payment method without any action on your part.
Why isn't my customer receiving the payment notification?
The USSD/Push notification is sent by the telecom operator, not by Wajub. If the customer doesn't receive it, they can manually dial the USSD code shown on the hosted payment page.