Changelog

All notable changes to the Lira API are documented here. Breaking changes are marked explicitly. Dates follow ISO 8601 (YYYY-MM-DD).

2026-05-30

Added

• United Kingdom (GB) and China (CN) bank account verification. Both are name-match corridors: you supply the account details plus the accountName you expect, and the bank confirms whether the name matches the account on record. See Bank Account in the United Kingdom and Bank Account in China.
  • United Kingdom: 8-digit account number with a 6-digit sort code supplied in bankCode. accountName is required.
  • China: select the account type with accountHolderType. INDIVIDUAL accounts use the UnionPay card number; BUSINESS accounts use the bank's BIC in bankCode plus an 18-character Uniform Credit Code supplied as a BUSINESS_REGISTRATION entry in identifiers. accountName is required.
  • Both corridors are synchronous only. mode: "async" is not supported.

Changed

• Unified routing code field. The receiving institution's routing code is now always supplied in the single bankCode field, whatever its local form: the African bank/clearing code, the UK 6-digit sort code, or the bank's BIC/SWIFT code for China business accounts. There is no separate sortCode or bic field.
• Typed account-holder identifiers. Corridor-specific identity codes are now supplied through an identifiers array of { "type": ..., "value": ... } entries. China business accounts carry their Uniform Credit Code as a BUSINESS_REGISTRATION identifier.
• Name-match response shape. For GB and CN, a successful verification (verified: true) echoes back the accountName you submitted, confirmed to match the bank's record. These corridors do not disclose a separately sourced account name. When verified is false, accountName is omitted.

2026-05-28

Address verification SDK 1.0.2

All-platform release of the Uselira address-verification SDK. iOS, Android, and React Native all bump to 1.0.2; native iOS and Android also bump from 1.0.1 since their SdkConfig signatures change.

Fixed

• React Native iOS bridge build failure. @uselira/core@1.0.1 shipped with an incorrect import Uselira in the iOS bridge. The published pod exposes the module as UseliraCore (the Swift class is Uselira, living inside that module). Every iOS build of 1.0.1 failed with Unable to find module dependency: 'Uselira'. Fixed in 1.0.2 by changing the import to UseliraCore.

Breaking changes (all three platforms)

• SdkConfig.environment is now REQUIRED. No default. Host apps must explicitly pick sandbox or production so a sandbox build cannot accidentally ship to production.
  • Swift: SdkConfig(... duration: 14, environment: .sandbox, ...)
  • Kotlin: SdkConfig(... duration = 14, environment = LiraEnvironment.SANDBOX, ...)
  • React Native: { ... duration: 14, environment: 'sandbox', ... }
• Recovery paths are stricter too: iOS Uselira.restoreIfNeeded() and Android Uselira.start(context) refuse to restore from a corrupt or missing stored environment instead of silently falling back to sandbox. iOS Uselira.cancelVerification(...) returns .invalidConfig(reason:) when no environment is stored.

Documentation

• The React Native SDK README iOS Setup section now puts the two required Podfile edits up front:
  • platform :ios, '16.0': UseliraCore requires iOS 16; the RN scaffold default min_ios_version_supported resolves to ~13.4 and fails pod install with a platform-mismatch error.
  • use_frameworks! :linkage => :dynamic: UseliraCore ships as a binary .xcframework that is not consumable under static linking; without dynamic linking the Swift import fails with No such module 'UseliraCore'.
• This page (Address verification) was updated for the new requirements: the Configuration reference table marks environment required, the React Native example passes environment, and the iOS install section spells out the two Podfile edits with the specific failure each prevents.
• New section: Best practice: don't start a second verification while one is in flight, covering host-side gating with the persisted jobId + Uselira.status API. Includes React Native, iOS Swift, and Android Kotlin sketches.
• Error-handling section updated: LiraSetupError.server now carries a parsed detail (code, message, actionType, actionHint). The SDK's in-flow retry banner shows actionHint when present; hosts should branch on actionType (FIX_INPUT / CONTACT_ADMIN won't be resolved by a retry).
• React Native: documented the two new event subscriptions: addSetupFailedListener (with the SetupFailure discriminated union) and addUploadAttemptedListener ({ success, count, error? } per batch).
• Behaviour-guarantees section: updated the idempotency-key description to reflect that the key is now derived from (customerRef, lat, lng, consent-minute UTC) rather than (customerRef, lat, lng, UTC day). Same-minute double-taps still collapse; cross-flow retries get a fresh key and reach the validation layer instead of replaying a cached failure.

Migration

Existing call sites won't compile until environment is added to every SdkConfig(...). The compiler will flag every missed call on iOS (SdkConfig requires 'environment:') and Android (No value passed for parameter 'environment'); React Native rejects at runtime with INVALID_CONFIG.

iOS host apps additionally need the two Podfile edits described above.

2026-05-07

Added

• Actionable error responses: All API error responses now include an optional action field with a machine-readable type and a human-readable hint. When present, action.type tells your application what the caller should do to resolve the error, for example CONTACT_ADMIN when a service is not enabled, TOP_UP_WALLET when the wallet balance is insufficient, or WAIT_AND_RETRY when a rate limit is active. See Errors → Actionable errors for the full type list and a handling example.

Changed

• 402 Payment Required is now returned when a verification cannot be billed: either because the organization's wallet has insufficient funds (INSUFFICIENT_FUNDS), the account has been auto-suspended (WALLET_SUSPENDED), or the service has no price configured (SERVICE_PRICE_NOT_CONFIGURED). Previously these conditions returned a 500 or a generic 422. All 402 responses include an action field.
• 403 Forbidden now covers service-not-enabled errors in addition to permission errors. If a verification service is not enabled for your organization, you receive a 403 with code: SERVICE_NOT_ENABLED and action.type: CONTACT_ADMIN.

2026-04-24

Added

• Francophone Africa coverage: Bank account and phone number verification now supported for Côte d'Ivoire (CI), Senegal (SN), Cameroon (CM), Burkina Faso (BF), Mali (ML), Benin (BJ), and Togo (TG). Tanzania (TZ) is also added. All phone verifications for the new markets require a networkCode. Contact support for the carrier code list per country.

2026-03-09

Added

• Ghana phone number verification: POST /verify/phone now supports Ghana (GH) in addition to Nigeria. Ghana verifications require a networkCode (MTN, Vodafone, or AirtelTigo). Omitting networkCode for a GH request returns NETWORK_CODE_REQUIRED.
• Webhook delivery history: New endpoints to inspect webhook delivery attempts:
  • GET /client/webhooks/:id/deliveries: list recent deliveries with status and response details
  • GET /client/webhooks/:id/deliveries/:deliveryId: get a specific delivery record
• Async verification mode: All verification endpoints now accept "mode": "async". The API returns status: pending immediately and delivers the result via webhook when processing completes.
• lastUsedAt on API keys: GET /client/api-keys responses now include a lastUsedAt timestamp showing when each key was most recently used.
• expiresAt on API keys: API key list responses include an expiresAt field. Currently null for all keys; expiry configuration will be supported in a future release.

Changed

• Webhook retry schedule updated: Retry delays changed from fixed 5-minute intervals to exponential backoff: immediate → 1 min → 3 min → 9 min → 27 min. Total retry window is approximately 40 minutes (previously 25 minutes). No action required for existing webhooks.

• X-Signature header format: Webhook signature headers now use the sha256=<hex> prefix format. Previously the raw hex digest was sent without a prefix. Update your signature verification logic to strip the sha256= prefix before comparing.

  Migration: If you were comparing the header directly against a computed hex digest, update to:

  JavaScript

  const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(rawBody).digest('hex');

Fixed

• Resolved an issue where GET /verify with status=pending returned completed verifications in some edge cases.
• PATCH /client/webhooks/:id no longer requires all fields to be present; partial updates work as documented.

2026-02-15

Added

• Webhook management API: New endpoints for registering and managing webhook endpoints:
  • POST /client/webhooks: register an endpoint
  • GET /client/webhooks: list all webhooks, with optional status and event filters
  • GET /client/webhooks/:id: get a single webhook
  • PATCH /client/webhooks/:id: update URL, events, status, or signing secret
  • DELETE /client/webhooks/:id: delete a webhook
• Verification list endpoint: GET /verify returns a paginated list of past verifications. Supports type, status, limit, and offset query parameters.
• Verification retrieve endpoint: GET /verify/:id retrieves the result of a specific verification by ID. Useful as a polling fallback when a webhook delivery is missed.

Changed

• API key header renamed: The authentication header for verification endpoints changed from X-Lira-Key to X-API-Key. The old header will continue to work until 2026-05-15; update before that date to avoid disruption. (Breaking change, grace period active)

2026-01-20

Added

• Phone number verification: POST /verify/phone verifies that a mobile number is registered with a carrier and returns the subscriber's name and date of birth. Supported country: Nigeria (NG).
• DEVELOPER role: New organization role with access to verification endpoints and webhook management. Cannot create or revoke API keys.

Changed

• Verification response shape: Responses from POST /verify/account now include a top-level verified boolean field (in addition to status) for quick checks. verified: true is equivalent to status: "success".

2026-01-05: Initial release

Added

• Bank account verification: POST /verify/account verifies a Nigerian bank account against official records and returns the account holder's name and address.
• Authentication: POST /auth/login, POST /auth/refresh, POST /auth/logout for JWT-based session management.
• API key management: POST /client/api-keys, GET /client/api-keys, DELETE /client/api-keys/:id for creating and revoking API keys scoped to sandbox or live environments.
• Sandbox environment: All endpoints are available in sandbox with deterministic test data. No real external queries are made and no charges are incurred.
• Supported countries: Nigeria (NG) for bank account verification.