Bila← Docs

Quickstart

Accept your first sandbox payment in 5 minutes.

  1. 1 · Get a test key

    Create an account at bila.so/dashboard/signup. Copy the sk_test_… shown — it is displayed once.

  2. 2 · Create a charge

    curl -X POST https://api.bila.so/v1/charges \
      -H "Authorization: Bearer sk_test_…" \
      -H "Content-Type: application/json" \
      -H "Idempotency-Key: $(uuidgen)" \
      -d '{
        "amount": 4200,
        "currency": "USD",
        "rail": "sandbox",
        "identifier": "+252611234567",
        "description": "First Bila charge"
      }'
  3. 3 · Register a webhook

    curl -X POST https://api.bila.so/v1/webhook_endpoints \
      -H "Authorization: Bearer sk_test_…" \
      -H "Content-Type: application/json" \
      -d '{"url":"https://your-app.example.com/webhooks/bila"}'

    The response includes a signing_secret — store it; Bila signs every delivery with it (Bila-Signature: t=…,v1=…).

  4. 4 · Refund

    curl -X POST https://api.bila.so/v1/refunds \
      -H "Authorization: Bearer sk_test_…" \
      -H "Content-Type: application/json" \
      -d '{"charge":"ch_…","reason":"requested_by_customer"}'
  5. 5 · Go live

    Submit business KYC in the dashboard. On approval, a sk_live_… key is issued and you can switch "rail":"sandbox" → "rail":"waafipay" (or edahab, or premier_mc).

Sandbox identifier rules: ends in 0000 → declined · ends in 9999 → requires_action then succeeds · anything else → immediate success.