Bill payments setup and configuration

​

Credentials and accounts

• active, and debitable
• NGN — no other currency is accepted
• one of your own — a customer wallet is refused

​

The catalog

​

The ten-minute window

// Wrong: the enquiry ages while the user reads the screen.
const enquiry = await enquire(meterNumber);
await showConfirmationScreen(enquiry);        // user goes to make tea
await pay(enquiry.id);                        // 409 bill_enquiry_expired

// Right: enquire, confirm, pay — and re-enquire if the user was slow.
let enquiry = await enquire(meterNumber);
const confirmed = await showConfirmationScreen(enquiry);
if (Date.parse(enquiry.expiresAt) - Date.now() < 60_000) {
  enquiry = await enquire(meterNumber);       // fresh price, fresh name
}
await pay(enquiry.id);

​

Idempotency

`bill_${orderId}_a${attempt}`   // distinguishes a retry from a repeat

​

Rate limits

​

Pending payments resolve themselves

• A pending payment is being worked on. Do not resubmit it.
• Do not poll it aggressively. Once a minute is plenty; the webhook is better.
• A failure after retries reverses the debit like any other failure, with the retry count noted in failureReason.

# Anything still unresolved.
curl --silent --url "$SAKAWAVE_BASE_URL/v1/bill-payments?status=pending&pageSize=100" \
  --header "Authorization: Bearer $SAKAWAVE_API_KEY" | jq '.items[] | {id, createdAt, vendStatus}'

​

Webhooks

​

Failures refund themselves

​

Configuration checklist

• An eligible NGN account identified before you start
• Decimal amounts used throughout — this service does not use minor units
• The enquiry made immediately before the payment, and re-made when close to expiry
• customer.customerName shown to the payer before taking money
• totalDebit shown, not amount
• externalReference namespaced per attempt, since retries need a new one
• confirmed treated as success — not completed
• tokenData stored on receipt; it is not re-issued
• A customer-facing notification wired to bills_payment.failed