Go Live Checklist
Everything you need to do before switching from sandbox to production.
Sandbox vs production — the differences in one table
| Surface | Sandbox | Production |
|---|---|---|
| Hostname | sandbox.api.billerapi.com | api.billerapi.com |
| API key prefix | bak_test_* | bak_live_* |
| Webhook signing secret | Per-environment. The sandbox secret does not verify production deliveries. | Register a fresh secret for production; store it in your prod env vars. |
| Bill IDs | sandbox_bill_* | bill_* |
| Link IDs | sb_link_* | link_* |
| ID portability | IDs are not portable between environments. Don't persist sandbox IDs into your production database. | |
| Request / response shapes | Identical. The same client code talks to both; only the hostname and credentials change. | |
| Data persistence | In-memory; evaporates on service restart. Magic account numbers are deterministic. | Durable DynamoDB. |
| Link flow | Driven by magic account numbers (e.g. 4242424242 = success, 4000000003 = MFA). | Real biller credentials. |
| MFA codes | Only 123456 verifies. | Real one-time codes from the biller. |
Checklist
Get production API keys
Production access is granted, not self-served. Complete all four steps on /go-live, in order:
- Verify your email address.
- Verify your business — submit the business details form.
- Add a payment method (billing setup must be complete).
- Request production access. All three prerequisites above are enforced server-side; the request is rejected until they are done.
A BillerAPI operator then reviews the business details you submitted. Approvals usually land within one business day and we email you when access is granted. Until an operator approves, minting a production-tier secret fails with OPERATOR_VERIFICATION_REQUIRED. Once approved, mint the secret from /developer/keys. Production keys use the prefix bak_live_*.
Update base URL
Change from sandbox.api.billerapi.com to api.billerapi.com. See Environments.
Re-register webhooks for production
Webhook subscriptions and signing secrets are per-environment: the sandbox secret you registered does not verify production deliveries. Register a fresh production webhook URL with a new signing secret, then update your production env vars. See Set Up Webhooks.
Implement error handling
Ensure your app handles all error codes and implements retry logic with backoff. See Error Handling and Rate Limits.
Test the full flow
Run through the complete user journey: create link session, connect a biller account, exchange token, retrieve bills, and receive webhook events.
Use idempotency keys
Add Idempotency-Key headers to all POST requests to prevent duplicates during retries. See Idempotency.
Prove biller-message display
If your product connects biller accounts, displaying accepted biller messages is a production requirement. In sandbox, demonstrate signed-webhook verification and deduplication, dropped-event recovery from the canonical feed, biller and account attribution, persisted read state, marketing consent, and reporting. This evidence is reviewed separately from the automated setup count.
Display biller messages guideNote