# Lumepay API

OpenAPI file: https://docs.lumepay.com/source.json

## Description

This is version `v1` of this API documentation. Last update on Jul 3, 2026.
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:

```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 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.


## Servers

- http://api.example.com: http://api.example.com ()



## Groups and operations

### [Beneficiaries](https://docs.lumepay.com/group/endpoint-beneficiaries.md)

- [List beneficiaries](https://docs.lumepay.com/operation/operation-getbeneficiaries.md)

- [Get beneficiary](https://docs.lumepay.com/operation/operation-getbeneficiary.md)

### [Accounts](https://docs.lumepay.com/group/endpoint-accounts.md)

- [List accounts](https://docs.lumepay.com/operation/operation-getaccounts.md)

- [Create account](https://docs.lumepay.com/operation/operation-createaccount.md)

- [Get account](https://docs.lumepay.com/operation/operation-getaccount.md)

- [Get account by currency](https://docs.lumepay.com/operation/operation-getaccountbycurrency.md)

### [Deposits](https://docs.lumepay.com/group/endpoint-deposits.md)

- [List deposits](https://docs.lumepay.com/operation/operation-deposithistory.md)

- [Get deposit](https://docs.lumepay.com/operation/operation-getdeposit.md)

### [Webhooks](https://docs.lumepay.com/group/endpoint-webhooks.md)

- [List webhook subscriptions](https://docs.lumepay.com/operation/operation-listsubscriptions.md)

- [Create webhook subscription](https://docs.lumepay.com/operation/operation-createsubscription.md)

- [Verify subscription](https://docs.lumepay.com/operation/operation-verifysubscription.md)

- [Deactivate webhook subscription](https://docs.lumepay.com/operation/operation-deactivatesubscription.md)

- [Activate webhook subscription](https://docs.lumepay.com/operation/operation-activatesubscription.md)

- [Get webhook subscription](https://docs.lumepay.com/operation/operation-getsubscription.md)

- [List webhook events](https://docs.lumepay.com/operation/operation-listevents.md)

### [Wallets](https://docs.lumepay.com/group/endpoint-wallets.md)

- [List wallets](https://docs.lumepay.com/operation/operation-getwallets.md)

- [Get wallet](https://docs.lumepay.com/operation/operation-getwallet.md)

### [Currencies](https://docs.lumepay.com/group/endpoint-currencies.md)

- [List currencies](https://docs.lumepay.com/operation/operation-getcurrencies.md)



[Powered by Bump.sh](https://bump.sh)