Lumepay API

v1

Lumepay API documentation.

The Lumepay API gives third-party partners secure server-to-server access to accounts, wallets, currencies, beneficiaries, and deposits and review payment activity. Use this API to build operational dashboards, initiate supported money movement workflows, reconcile transactions, and surface account or wallet information in your own internal systems.

This documentation describes the external v1 API contract and the conventions your integration should follow from its first request through production use.

Authentication and access

API requests must include both X-API-KEY and X-API-SECRET headers. API keys are created through the authenticated user's API key management flow. The same user can revoke or rotate those credentials when needed. Treat the API secret as a server-side credential only; never expose it in browser, mobile, or other client-side code.

Authentication and access failures are handled consistently across the external API:

• 401 means the request could not be authenticated because API key headers are missing, invalid, revoked, or expired.
• 403 means the request was authenticated, but the API key owner is not allowed to perform the action because of permissions, account state, or access rules.

Individual endpoint documentation does not repeat these responses unless an endpoint has authentication or access behavior that differs from the standard API key flow.

Currencies and payment routes

Supported currencies and payment routes are configuration-driven. When building forms or validation rules, use the relevant external, public, or user currency endpoints instead of hard-coding supported currency lists from this document. External account and currency endpoints are scoped to the API key owner's effective jurisdiction.

Security

Production and staging integrations must use HTTPS. Rotate API keys immediately if you suspect a secret has been exposed. Store secrets in a vault or server-side secret manager, and do not log full API secrets.

Error model

Error responses use Lumepay's standard error envelope:

{
  "code": 1133,
  "message": "Validation error: amount is required",
  "httpStatus": 400,
  "requestId": "req_01HY...",
  "timestamp": "2026-01-01T00:00:00Z",
  "errors": [
    {
      "field": "amount",
      "message": "must be greater than 0"
    }
  ]
}

Common non-authentication error classes include 400 validation failures, 404 resources not found for the authenticated owner, 409 insufficient funds or conflicting money movement state, and 500 unexpected server errors.

Pagination and filtering

Current list endpoints may expose reserved query parameters for page, size, sort, date range, and status filters. Unless an endpoint explicitly says otherwise, current responses are unpaginated arrays and your integration should not depend on server-side pagination behavior yet.

Transaction lifecycle

Deposits move through domain statuses such as pending, processing, completed, failed, cancelled, or reversed depending on the resource type. A status is final only when the specific endpoint and business flow represent it as terminal. Your integration can use webhook subscriptions for supported lifecycle notifications, and should continue to treat the read endpoints as the source of truth for current resource state.

This is version v1 of this API documentation. Last update on June 15, 2026.

This is version v1 of this API documentation. Last update on Jul 3, 2026.