How It Works

This page explains the core concepts behind Lira. Read it before writing any code to understand how verifications, authentication, environments, and webhooks fit together.

Verifications

A verification is a request to confirm the existence and details of a bank account or phone number. You submit an identifier (an account number or phone number) along with the country and relevant metadata. Lira queries the official registry and returns the verified details, or a failure reason if the account or number could not be confirmed.

Verifications run in one of two modes:

Sync mode: Lira queries the registry and returns the result immediately in the same HTTP response. Use this for real-time checks at the point of payment.

Async mode: Lira queues the verification and returns a pending status immediately. The result is delivered to your registered webhook endpoint when processing completes. Use this for high-throughput batch flows or when upstream response times are unpredictable.

Verification lifecycle

flowchart TD
    A[You submit a request] --> B{Mode}
    B -->|sync| C[Result returned immediately in the HTTP response]
    B -->|async| D["status: pending, Lira queues the request and returns immediately"]
    D --> E[Lira queries the registry]
    E -->|success| F["status: success, verified data returned"]
    E -->|failure| G["status: failed, error.code explains why"]
    E -->|error| H["status: error, upstream or system fault (retry)"]
    F --> I["Webhook delivered to your endpoint (async mode only)"]
    G --> I
    H --> I

Authentication

Every request to the Lira verification API is authenticated with an API key, sent in the X-API-Key header.

The flow is:

1. Create an API key in the dashboard — see API Keys.
2. Store it securely (for example, as an environment variable) in your application.
3. Send it in the X-API-Key header on every verification call, never in client-side code.

API keys are the only credential you need to call the verification API — there is no login or token exchange. Everything else — creating and revoking keys, registering webhooks, and viewing usage and audit logs — is managed from the dashboard.

Environments

The only difference between sandbox and live is the API key you use. No code changes are required when switching environments: swap the key in your environment variables and everything else stays the same.

See Environments for the full list of sandbox test data and expected outcomes.

API keys

API keys follow the format lira_{environment}_{32-byte hex}:

lira_sandbox_a3f08c1d4e2b9f3c1e5d7a8b2c4f6e0d1a3b5c7d9e1f3a5b7c9d1e3f5a7b9c

Keys are shown only once at creation time. Store the full key immediately in a secrets manager or environment variable. The keyPrefix field (e.g. lira_sandbox_a3f0...) is retained for display and identification purposes, but the full key cannot be retrieved again.

Webhooks

For async verifications, Lira delivers the result to a registered HTTPS endpoint (your webhook URL) once processing completes.

Every delivery includes an X-Signature header computed as HMAC-SHA256 over the raw request body using your webhook secret. Your endpoint must verify this signature before processing the payload. Reject anything that fails verification with a 401.

Lira retries failed deliveries with exponential backoff for up to 5 attempts. If all attempts are exhausted, the webhook status is set to failed and deliveries stop. You can re-enable the webhook by updating its status back to active.

Next steps