Key prefixes
sk_test_…— test mode. Hits the sandbox simulator. No real money moves.sk_live_…— production mode. Issued after KYC approval.
How to send the key
Bila accepts HTTP Basic auth (Stripe-compatible). Pass the secret as the username, leave the password empty.
# curl shorthand
curl -u sk_test_…: https://api.bila.so/v1/balance
# explicit Authorization header
curl -H "Authorization: Basic $(echo -n 'sk_test_…:' | base64)" https://api.bila.so/v1/balanceIdempotency
Every money-mutating request takes an Idempotency-Key header. Bila caches the response for 24h, so retrying after a network failure is safe — you'll get the original response, not a duplicate charge.
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=+252611234567Request IDs
Every response carries a Bila-Request-Id header. Errors also include request_id in the JSON body. Paste it into a support email and we'll find the request in seconds.
API versioning
Pin a date with the Bila-Version request header. Default is 2026-05-17. See the changelog for the version history and breaking-change policy.
Rotating + revoking keys
Issue new keys, mark old ones revoked at /dashboard/developers. Revocation takes effect within seconds.
Security tips
- Never expose
sk_*keys to a browser or mobile app. Keep them server-side only. - Use separate keys per service (one per microservice) so you can rotate granularly.
- Set
BILA_SECRET_KEYas an environment variable; never hard-code. - Bila's rate-limit responses return
429with aRetry-Afterheader. Back off + retry.