Bill payment use cases

// 1. The customer picks a biller and package from your cached catalog,
//    and types their meter or account number.
const enquiry = await post('/v1/bill-payments/enquiries', {
  customerId: form.meterNumber,
  billerId: form.billerId,
  packageId: form.packageId,
  amount: form.amount,          // "5000.00" — decimals, not minor units
});

// 2. Show what the biller says. This is the step that prevents paying a
//    stranger's meter, and it costs one screen.
const confirmed = await confirm({
  name: enquiry.customer.customerName,
  address: enquiry.customer.address,
  amount: enquiry.totalDue ?? form.amount,
  charge: enquiry.charge,
  youPay: enquiry.totalDebit,
});
if (!confirmed) return;

// 3. Enquiries last ten minutes. If the user hesitated, ask again.
const fresh = Date.parse(enquiry.expiresAt) - Date.now() > 60_000
  ? enquiry
  : await post('/v1/bill-payments/enquiries', { /* same body */ });

// 4. Pay.
const payment = await post('/v1/bill-payments', {
  enquiryId: fresh.id,
  accountId: ngnAccountId,
  amount: form.amount,
  externalReference: `bill_${order.id}_a${order.attempt}`,
  customerName: form.customerName,
  phoneNumber: form.phoneNumber,
});

const enquiry = await post('/v1/bill-payments/enquiries', {
  customerId: '+2348012345678',      // the phone number is the customer id
  billerId: airtimeBillerId,         // an airtime biller has no packages
  amount: '1000.00',
});

await post('/v1/bill-payments', {
  enquiryId: enquiry.id,
  accountId: ngnAccountId,
  amount: '1000.00',
  externalReference: `airtime_${request.id}`,
  customerName: 'Ada Okafor',
  phoneNumber: '+2348012345678',
});

async function resolve(paymentId: string) {
  const payment = await get(`/v1/bill-payments/${paymentId}`);

  switch (payment.status) {
    case 'confirmed':
      await deliverToken(payment.tokenData);       // store it too
      return 'done';

    case 'failed':
      // Sakawave has already reversed the debit. Tell the customer —
      // a silent refund looks like a silent failure.
      await notifyReversed(payment.failureReason);
      return 'refunded';

    case 'pending':
    case 'submitted':
      // A reconciler is chasing it, up to five attempts. Do not resubmit.
      return 'waiting';
  }
}

onEvent('bills_payment.completed', (data) => deliverToken(data.relatedOperation.tokenData));
onEvent('bills_payment.failed', (data) => notifyReversed(data.relatedOperation.failureReason));

# Everything 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, biller: .biller.name, amount, vendStatus}'

# Everything that failed and was refunded.
curl --silent --url "$SAKAWAVE_BASE_URL/v1/bill-payments?status=failed&pageSize=100" \
  --header "Authorization: Bearer $SAKAWAVE_API_KEY" \
| jq '.items[] | {id, totalDebit, failureReason}'

const billers = await get(`/v1/bill-payments/groups/${dataGroupId}/billers`);
const mtn = billers.items.find((biller) => biller.name === 'MTN');
// mtn.id addresses MTN-under-Data only. The Airtime MTN has its own id.