Baton Developer API

1. How it works

1. Create a business account and wait for Baton to approve it.
2. Fund your wallet by transferring to your dedicated account number.
3. Create an API key in your dashboard.
4. Call the transactions endpoint. Each sale debits your wallet instantly.
5. Receive a webhook when the sale settles, or poll the transaction.

2. Funding your wallet

Your dashboard shows an account number that belongs only to your business. Any transfer into it credits your wallet automatically, usually within seconds, and appears in your wallet history. A sale is declined with 402 when the balance is short.

3. Authentication

Pass your key id and secret as a bearer token, separated by a colon.

Authorization: Bearer pk_xxx:sk_yyy

Requests are rate limited per key (120 per minute by default). On overflow you get 429 with Retry-After and X-RateLimit-* headers.

4. Base URL

https://batonbills.com/api/public/partners/v1

5. List products

curl https://batonbills.com/api/public/partners/v1/products \
  -H "Authorization: Bearer pk_xxx:sk_yyy"

{
  "products": [
    { "slug": "mtn-airtime", "name": "MTN Airtime", "pricing_mode": "variable", "category": "airtime", "price_kobo": null }
  ]
}

Only categories enabled for API sales are returned. Today that is airtime.

6. Check your wallet

curl https://batonbills.com/api/public/partners/v1/balance \
  -H "Authorization: Bearer pk_xxx:sk_yyy"

7. Sell airtime

Send an Idempotency-Key unique to your order. Replaying the same key with the same body returns the original sale; a different body returns 409.

curl -X POST https://batonbills.com/api/public/partners/v1/transactions \
  -H "Authorization: Bearer pk_xxx:sk_yyy" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-12345" \
  -d '{
    "product_slug": "mtn-airtime",
    "recipient": "08012345678",
    "amount_kobo": 50000,
    "reference": "order-12345"
  }'

{
  "transaction": {
    "reference": "BTN-...",
    "partner_reference": "order-12345",
    "status": "success",
    "recipient": "08012345678",
    "amount_kobo": 50000
  }
}

8. Fetch one transaction

curl https://batonbills.com/api/public/partners/v1/transactions/BTN-XXXX \
  -H "Authorization: Bearer pk_xxx:sk_yyy"

9. Webhooks

Register an https endpoint in your dashboard. Each delivery is signed with your webhook secret; verify the signature header before trusting the payload. Failed deliveries can be replayed from the dashboard.

10. Errors

• 400 validation problem or unknown product
• 401 missing or invalid key
• 402 not enough wallet balance
• 403 key missing a scope, business not approved, or category not enabled
• 409 idempotency key reused with a different body
• 429 rate limited