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_xyz5. Smart routing
Pass rail: "auto" and Bila picks the best rail in this order:
- Carrier prefix on the MSISDN (e.g. 77 → WaafiPay, 64 → eDahab).
- Your merchant rail-preference list (configurable in the dashboard).
- Bila's global default (waafipay → edahab → sahal → mybank → amal).