Go Live

Complete this checklist before switching from sandbox to live traffic.

Work through every section below. Each item includes a brief explanation of why it matters. Skipping items is the most common cause of production incidents on launch day.

Authentication and credentials

Created a live API key (environment: live) — separate from your sandbox key. Live keys carry real charges and query real providers; they must be managed separately.
Live API key stored in environment variables, not hardcoded — the key must never appear in source code, config files checked into version control, or application logs. Use a secrets manager (AWS Secrets Manager, GCP Secret Manager, HashiCorp Vault) or at minimum an .env file excluded from git.
Sandbox keys removed from production config — confirm no lira_sandbox_... key appears in your production environment variables, deployment configs, or CI/CD pipelines.
Bearer token refresh logic implemented — access tokens expire (check expiresIn). When a management request returns 401 with "token expired", your code must call POST /auth/refresh and retry automatically rather than failing or prompting the user. See Authentication for the refresh flow.

Verification integration

Both success and failed responses handled — failed is a normal, expected outcome. Your code must handle it gracefully: surface a useful message to the user, log the error.code, and take the appropriate action (e.g. ask the user to recheck their account number).
status: error handled with retry logic — PROVIDER_ERROR and PROVIDER_TIMEOUT are transient. Implement exponential backoff with a maximum retry count. Do not surface these as permanent failures to end users.
Async verifications: webhook or polling fallback implemented — if you use mode: async, you must handle the result asynchronously. Ensure your webhook endpoint is registered, reachable, and processing events correctly. Optionally, implement a polling fallback using GET /verify/VERIFICATION_ID for cases where the webhook delivery fails.
VERIFICATION_ID stored for each async request — store the id from every pending response in your database so you can correlate the incoming webhook event with the original request and update your records accordingly.

Webhooks

Webhook URL uses HTTPS — HTTP endpoints are not accepted. The URL must begin with https://.
Webhook URL is publicly reachable — localhost, private IP ranges, and internal network addresses are not permitted. Confirm your endpoint is accessible from the public internet before registering it.
X-Signature verified on every incoming delivery before processing — compute HMAC-SHA256 over the raw request body using your webhook secret and compare it to the X-Signature header using a constant-time comparison. Reject any request that fails verification with 401. See Webhooks for code examples in Node.js and Python.
Webhook handler returns 200 immediately, processes events asynchronously — do not perform database writes, external API calls, or other slow operations in the synchronous request handler. Return 200 OK immediately and hand the payload off to a background job or queue. Long-running handlers cause timeouts that trigger unnecessary retries.
Duplicate delivery handling implemented — Lira may deliver the same event more than once when retrying. Store the delivery id and skip processing if you have already handled it.
Re-enable logic in place for when webhook status becomes failed — if all retry attempts are exhausted, Lira sets the webhook status to failed and stops delivering events. Implement monitoring to detect this state (e.g. alert when GET /client/webhooks returns a webhook with status: failed) and re-enable it via PATCH /client/webhooks/WEBHOOK_ID with { "status": "active" }.

Error handling

All HTTP status codes handled — your code must handle 400, 401, 403, 404, 422, 429, and 500. Do not treat all non-200 responses the same way.
Verification error codes handled per type — at minimum: ACCOUNT_NOT_FOUND, INVALID_BANK_CODE, INVALID_ACCOUNT_NUMBER, SUBSCRIBER_NOT_FOUND, INVALID_PHONE_NUMBER, INVALID_NETWORK_CODE, NETWORK_CODE_REQUIRED, PROVIDER_ERROR, PROVIDER_TIMEOUT. See Errors for the full reference.
429 rate limit handled with retry-after backoff — when you receive a 429, read the Retry-After response header and wait the specified number of seconds before retrying. Do not retry immediately in a tight loop.

Security

API keys not exposed in client-side code, logs, or version control — API keys in browser JavaScript, mobile app binaries, or git history can be extracted and abused. All verification calls must originate from your server side.
Webhook secret stored securely — store the webhook signing secret in an environment variable or secrets manager. It must not appear in source code or logs.
HTTPS used for all API requests — all requests to https://api.lira.com use TLS. Do not disable certificate verification in your HTTP client.

Go live

Once all items above are checked:

Swap YOUR_API_KEY to your live key. Update the environment variable in your production deployment — no code changes required.
Update your webhook URL if you registered a sandbox or tunnel URL (e.g. ngrok). Ensure the production URL is HTTPS and publicly reachable.
Make one real verification call to confirm everything works end-to-end. Use a known-good account number or phone number and verify the response is status: success with correct account details.
Monitor your first few live verifications in the dashboard. Check that webhook deliveries are succeeding and that your error handling is working as expected in production conditions.

Next steps

Errors — complete reference for all error codes and HTTP statuses
Webhooks — webhook management, signature verification, and troubleshooting
API Keys — key rotation and security best practices

Errors