Bila← Docs

Collecting payments

Bila charges flow through three states: requires_action → pending → succeeded (or failed/canceled). This guide walks you through the lifecycle for every rail Bila supports.

1. Create the charge

Every payment starts with a POST /v1/charges. Amounts are in the currency's minor unit (cents).

curl https://api.bila.so/v1/charges \
  -u sk_live_xxx: \
  -H "Idempotency-Key: $(uuidgen)" \
  -d amount=10000 \
  -d currency=USD \
  -d rail=auto \
  -d identifier=+252611234567 \
  -d description="Order #1234"

2. Watch for requires_action

Mobile-money rails (WaafiPay, eDahab, eBirr, Sahal) push a USSD prompt to the payer's phone. POST /v1/charges answers 201 with status: "requires_action" as soon as the charge exists (within a few seconds, before the payer has answered) and you wait for the webhook; if the payer approves quickly the 201 already says succeeded. Never retry with a new key while a charge is requires_action — retry with the same Idempotency-Key and you get the same charge back. Card rails (Premier MC) return a requires_action_payload.redirect_to URL — redirect the payer there.

3. Listen for the webhook

The terminal state — succeeded, failed, or canceled — arrives on your webhook endpoint. Don't poll; webhooks are the canonical signal.

4. Saved payment methods

To bill the same customer twice, save the method once and reuse the id:

# First charge — store the identifier
curl https://api.bila.so/v1/payment_methods -u sk_live_xxx: \
  -d kind=mobile_wallet -d rail=waafipay \
  -d identifier=+252611234567 -d customer=cus_abc

# Subsequent charges — reference the PM, no identifier needed
curl https://api.bila.so/v1/charges -u sk_live_xxx: \
  -d amount=10000 -d currency=USD -d rail=auto \
  -d payment_method=pm_xyz

5. Smart routing

Pass rail: "auto" and Bila picks the best rail in this order:

  1. Carrier prefix on the MSISDN (e.g. 77 → WaafiPay, 64 → eDahab).
  2. Your merchant rail-preference list (configurable in the dashboard).
  3. Bila's global default (waafipay → edahab → sahal → mybank → amal).