# Lumepay API OpenAPI file: https://docs.staging.lumepay.com/source.json ## Description This is version `v1` of this API documentation. Last update on Jul 20, 2026. Lumepay API documentation. The Lumepay API gives third-party partners secure server-to-server access to accounts, wallets, currencies, beneficiaries, deposits, withdrawals, and conversions initiate currency conversions 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. ## Rate limiting External API traffic is rate limited at Cloudflare before it reaches Neptune. Requests to `api.staging.lumetrade.com`, `api.lumetrade.com`, `api.staging.lumepay.com`, and `api.lumepay.com` under `/api/v1/**` are limited to 33 requests per 10 seconds per client IP and Cloudflare data center. Requests above that limit receive HTTP `429` with `{"error":"rate_limit_exceeded","message":"API rate limit exceeded"}`. Neptune does not currently emit `X-RateLimit-*` quota headers, so clients should still use conservative retry and backoff behavior. ## 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: ```json { "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, withdrawals, and conversions 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 may poll the read endpoints and may subscribe to the documented webhook events for supported deposit, withdrawal, conversion, and test lifecycle notifications. Webhooks are delivered at least once; consumers must deduplicate using the webhook and delivery identifiers sent with each callback. ## Webhooks The active v1 webhook catalog is available from `GET /api/v1/webhooks/events`. Use this endpoint as the source of truth for event types supported by the current environment. Do not assume unlisted events are emitted. Create subscriptions in `PENDING_VERIFICATION`, call the verify endpoint until the callback target has returned a successful `webhook.verification` response, then activate the subscription. The same subscription can be deactivated and its event list can be updated. Customer-facing secret rotation and customer re-enable of system-disabled subscriptions are not supported in v1. Webhook signing secrets are platform-managed per-subscription configuration distributed to customers out-of-band by Lume. Delivery callbacks include `X-Lume-Webhook-Id`, `X-Lume-Webhook-Delivery-Id`, `X-Lume-Webhook-Event`, `X-Lume-Webhook-Timestamp`, and `X-Lume-Webhook-Signature`. The signature is `v1=` plus lowercase hex HMAC-SHA256 over `.` using the active Lume-provisioned per-subscription webhook signing secret. Verification challenges use the same signed callback header contract. Any `2xx` callback response is success. Non-`2xx`, timeout, transport, and security validation failures are failed attempts. Neptune retries failed deliveries using the configured retry schedule and disables the subscription after the configured maximum failed attempts for a single outbox row. Financial lifecycle payloads are minimal: they contain the webhook id, event type, and resource type/id. Payloads do not expose Sumsub, KYC, KYT, provider ids, wallet metadata, bank details, internal reconciliation fields, remediation reasons, or internal case state. Neptune does not promise static outbound source IPs for v1 webhook delivery. This is version v1 of this API documentation. Last update on June 15, 2026. ## Servers - https://api.staging.lumepay.com: https://api.staging.lumepay.com () ## Topics ## Endpoints ### [Beneficiaries](https://docs.staging.lumepay.com/group/endpoint-beneficiaries.md) - [Create beneficiary withdrawal](https://docs.staging.lumepay.com/operation/operation-createwithdrawalwithpaymentreasondocuments_1.md) - [List beneficiaries](https://docs.staging.lumepay.com/operation/operation-getbeneficiaries.md) - [Get beneficiary](https://docs.staging.lumepay.com/operation/operation-getbeneficiary.md) ### [Withdrawals](https://docs.staging.lumepay.com/group/endpoint-withdrawals.md) - [Create beneficiary withdrawal](https://docs.staging.lumepay.com/operation/operation-createwithdrawalwithpaymentreasondocuments.md) - [List withdrawals](https://docs.staging.lumepay.com/operation/operation-getwithdrawhistory.md) - [Get withdrawal](https://docs.staging.lumepay.com/operation/operation-getwithdraw.md) ### [Accounts](https://docs.staging.lumepay.com/group/endpoint-accounts.md) - [List accounts](https://docs.staging.lumepay.com/operation/operation-getaccounts.md) - [Create account](https://docs.staging.lumepay.com/operation/operation-createaccount.md) - [Get account](https://docs.staging.lumepay.com/operation/operation-getaccount.md) - [Get account by currency](https://docs.staging.lumepay.com/operation/operation-getaccountbycurrency.md) ### [Deposits](https://docs.staging.lumepay.com/group/endpoint-deposits.md) - [List deposits](https://docs.staging.lumepay.com/operation/operation-deposithistory.md) - [Get deposit](https://docs.staging.lumepay.com/operation/operation-getdeposit.md) ### [Payment reasons](https://docs.staging.lumepay.com/group/endpoint-payment-reasons.md) - [List payment reasons](https://docs.staging.lumepay.com/operation/operation-getpaymentreasons.md) ### [Conversions](https://docs.staging.lumepay.com/group/endpoint-conversions.md) - [Get conversion quote](https://docs.staging.lumepay.com/operation/operation-getquote.md) - [Confirm conversion quote](https://docs.staging.lumepay.com/operation/operation-confirmquote.md) ### [Webhooks](https://docs.staging.lumepay.com/group/endpoint-webhooks.md) - [Trigger webhook test event](https://docs.staging.lumepay.com/operation/operation-triggertestevent.md) - [List webhook subscriptions](https://docs.staging.lumepay.com/operation/operation-listsubscriptions.md) - [Create webhook subscription](https://docs.staging.lumepay.com/operation/operation-createsubscription.md) - [Verify webhook subscription](https://docs.staging.lumepay.com/operation/operation-verifysubscription.md) - [Add webhook subscription events](https://docs.staging.lumepay.com/operation/operation-addsubscriptionevents.md) - [Remove webhook subscription events](https://docs.staging.lumepay.com/operation/operation-removesubscriptionevents.md) - [Deactivate webhook subscription](https://docs.staging.lumepay.com/operation/operation-deactivatesubscription.md) - [Activate webhook subscription](https://docs.staging.lumepay.com/operation/operation-activatesubscription.md) - [Get webhook subscription](https://docs.staging.lumepay.com/operation/operation-getsubscription.md) - [List webhook events](https://docs.staging.lumepay.com/operation/operation-listevents.md) ### [Wallets](https://docs.staging.lumepay.com/group/endpoint-wallets.md) - [List wallets](https://docs.staging.lumepay.com/operation/operation-getwallets.md) - [Get wallet](https://docs.staging.lumepay.com/operation/operation-getwallet.md) ### [Currencies](https://docs.staging.lumepay.com/group/endpoint-currencies.md) - [List currencies](https://docs.staging.lumepay.com/operation/operation-getcurrencies.md) [Powered by Bump.sh](https://bump.sh)