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 a provider 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 provider 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 provider response times are unpredictable.

Verification lifecycle

You submit a request
       │
       ▼
  [sync mode] ──────────────────► Result returned immediately in HTTP response
       │
  [async mode]
       │
       ▼
  status: pending ◄─── Lira queues the request and returns immediately
       │
       ▼
  Lira queries provider
       │
       ├── success → status: success + verified data returned
       └── failure → status: failed + error.code explains why
       │
       └── error   → status: error + provider/system fault (retry)
              │
              ▼
       Webhook delivered to your endpoint (async mode only)

Note: A 200 OK HTTP response does not mean the verification succeeded. Always check the status field in the response body. failed is a valid outcome — it means the account or number was not found, not that the API call itself failed.

Authentication

Lira uses two authentication methods depending on what you are doing:

The intended flow is:

1. Your team logs in once with email and password to obtain a Bearer token.
2. Use the Bearer token to generate API keys for your application.
3. Your application uses an API key on every verification call — never a Bearer token.

Bearer tokens are short-lived. When a request returns 401 with "token expired", use your refresh token to obtain a new access token silently, without requiring the user to log in again. See Authentication for the full refresh flow.

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.

Important: Never use a live API key in test or development code. Keep sandbox and live keys in separate environment variables.

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

• Authentication — log in, refresh tokens, roles and permissions
• Environments — sandbox test data, switching to production
• Verify a Bank Account — your first real verification call