{ "openapi": "3.1.0", "info": { "title": "Lumepay API", "description": "Lumepay API documentation.\n\nThe Lumepay API gives third-party partners secure server-to-server access to accounts, wallets, currencies, beneficiaries, deposits, withdrawals, and conversions\ninitiate currency conversions and review payment activity. Use this API\nto build operational dashboards, initiate supported money movement workflows, reconcile\ntransactions, and surface account or wallet information in your own internal systems.\n\nThis documentation describes the external `v1` API contract and the conventions your integration\nshould follow from its first request through production use.\n\n## Authentication and access\n\nAPI requests must include both `X-API-KEY` and `X-API-SECRET` headers. API keys are created\nthrough the authenticated user's API key management flow. The same user can revoke or rotate those\ncredentials when needed. Treat the API secret as a server-side credential only; never expose it in\nbrowser, mobile, or other client-side code.\n\nAuthentication and access failures are handled consistently across the external API:\n\n- `401` means the request could not be authenticated because API key headers are missing, invalid,\n revoked, or expired.\n- `403` means the request was authenticated, but the API key owner is not allowed to perform the\n action because of permissions, account state, or access rules.\n\nIndividual endpoint documentation does not repeat these responses unless an endpoint has\nauthentication or access behavior that differs from the standard API key flow.\n\n## Rate limiting\n\nExternal API traffic is rate limited at Cloudflare before it reaches Neptune. Requests to\n`api.staging.lumetrade.com`, `api.lumetrade.com`, `api.staging.lumepay.com`, and `api.lumepay.com`\nunder `/api/v1/**` are limited to 33 requests per 10 seconds per client IP and Cloudflare data\ncenter. Requests above that limit receive HTTP `429` with\n`{\"error\":\"rate_limit_exceeded\",\"message\":\"API rate limit exceeded\"}`. Neptune does not currently\nemit `X-RateLimit-*` quota headers, so clients should still use conservative retry and backoff\nbehavior.\n\n## Currencies and payment routes\n\nSupported currencies and payment routes are configuration-driven. When building forms or validation\nrules, use the relevant external, public, or user currency endpoints instead of hard-coding supported\ncurrency lists from this document. External account and currency endpoints are scoped to the API key\nowner's effective jurisdiction.\n\n\n## Security\n\nProduction and staging integrations must use HTTPS. Rotate API keys immediately if you suspect a\nsecret has been exposed. Store secrets in a vault or server-side secret manager, and do not log full\nAPI secrets.\n\n## Error model\n\nError responses use Lumepay's standard error envelope:\n\n```json\n{\n \"code\": 1133,\n \"message\": \"Validation error: amount is required\",\n \"httpStatus\": 400,\n \"requestId\": \"req_01HY...\",\n \"timestamp\": \"2026-01-01T00:00:00Z\",\n \"errors\": [\n {\n \"field\": \"amount\",\n \"message\": \"must be greater than 0\"\n }\n ]\n}\n```\n\nCommon non-authentication error classes include `400` validation failures, `404` resources not found\nfor the authenticated owner, `409` insufficient funds or conflicting money movement state, and `500`\nunexpected server errors.\n\n## Pagination and filtering\n\nCurrent list endpoints may expose reserved query parameters for page, size, sort, date range, and\nstatus filters. Unless an endpoint explicitly says otherwise, current responses are unpaginated arrays\nand your integration should not depend on server-side pagination behavior yet.\n\n## Transaction lifecycle\n\nDeposits, withdrawals, and conversions move through domain statuses such as pending, processing,\ncompleted, failed, cancelled, or reversed depending on the resource type. A status is final only when\nthe specific endpoint and business flow represent it as terminal. Your integration may poll the read\nendpoints and may subscribe to the documented webhook events for supported deposit, withdrawal, conversion, and test lifecycle notifications.\nWebhooks are delivered at least once; consumers must deduplicate\nusing the webhook and delivery identifiers sent with each callback.\n\n## Webhooks\n\nThe 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\nunlisted events are emitted.\n\nCreate subscriptions in `PENDING_VERIFICATION`, call the verify endpoint until the callback target has\nreturned a successful `webhook.verification` response, then activate the subscription. The same\nsubscription can be deactivated and its event list can be updated. Customer-facing secret rotation and\ncustomer re-enable of system-disabled subscriptions are not supported in v1. Webhook signing secrets are\nplatform-managed per-subscription configuration distributed to customers out-of-band by Lume.\n\nDelivery callbacks include `X-Lume-Webhook-Id`, `X-Lume-Webhook-Delivery-Id`,\n`X-Lume-Webhook-Event`, `X-Lume-Webhook-Timestamp`, and `X-Lume-Webhook-Signature`. The signature is\n`v1=` plus lowercase hex HMAC-SHA256 over `\u003CX-Lume-Webhook-Timestamp\u003E.\u003Craw JSON request body\u003E` using the\nactive Lume-provisioned per-subscription webhook signing secret. Verification challenges use the same\nsigned callback header contract. Any `2xx` callback response is success. Non-`2xx`, timeout, transport, and\nsecurity validation failures are failed attempts. Neptune retries failed deliveries using the configured\nretry schedule and disables the subscription after the configured maximum failed attempts for a single\noutbox row.\n\nFinancial lifecycle payloads are minimal: they contain the webhook id, event type, and resource type/id.\nPayloads do not expose Sumsub, KYC, KYT, provider ids, wallet metadata, bank details, internal\nreconciliation fields, remediation reasons, or internal case state. Neptune does not promise static\noutbound source IPs for v1 webhook delivery.\n\nThis is version v1 of this API documentation. Last update on June 15, 2026.\n", "contact": { "name": "Lume Forge" }, "version": "v1" }, "servers": [ { "url": "https://api.staging.lumepay.com" } ], "tags": [ { "name": "Beneficiaries", "description": "Beneficiary endpoints for the authenticated API key owner." }, { "name": "Withdrawals", "description": "Withdrawal history endpoints for the authenticated API key owner." }, { "name": "Accounts", "description": "Account endpoints for the authenticated API key owner." }, { "name": "Deposits", "description": "Deposit history endpoints for the authenticated API key owner." }, { "name": "Payment reasons", "description": "Public payment reason catalogue for API consumers." }, { "name": "Conversions", "description": "Currency conversion quote and confirmation endpoints." }, { "name": "Webhooks", "description": "Webhook event discovery, subscription lifecycle, verification, and test delivery endpoints." }, { "name": "Wallets", "description": "Wallet endpoints for the authenticated API key owner." }, { "name": "Currencies", "description": "Currency catalog endpoints for the authenticated API key owner." } ], "paths": { "/api/v1/withdrawals/beneficiaries/{beneficiaryId}": { "post": { "tags": [ "Withdrawals" ], "summary": "Create beneficiary withdrawal", "description": "Creates a withdrawal using only the saved details from an existing confirmed beneficiary. Call GET /api/v1/payment-reasons, then submit its id and required text fields together in the flat paymentReasons object.", "operationId": "createWithdrawalWithPaymentReasonDocuments", "parameters": [ { "name": "beneficiaryId", "in": "path", "description": "Beneficiary id returned by the beneficiary endpoints.", "required": true, "schema": { "type": "string" }, "example": "ben_7K9Q2M" }, { "name": "X-API-KEY", "in": "header", "description": "Public API key issued from the Lumepay API key management flow.", "required": true, "schema": { "type": "string" } }, { "name": "X-API-SECRET", "in": "header", "description": "API secret paired with the public API key.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "request": { "$ref": "#/components/schemas/CreateWithdrawalFromBeneficiaryRequest" } }, "required": [ "request" ] } }, "application/json": { "schema": { "$ref": "#/components/schemas/CreateWithdrawalFromBeneficiaryRequest" } } }, "required": true }, "responses": { "201": { "description": "Withdrawal created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWithdrawalResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "429": { "$ref": "#/components/responses/RateLimitError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" } } } }, "/api/v1/webhooks/test-event": { "post": { "tags": [ "Webhooks" ], "summary": "Trigger webhook test event", "description": "Queues a `test.event` delivery for active subscriptions owned by the authenticated API key owner. This event is a no-op health check and does not represent money movement.", "operationId": "triggerTestEvent", "parameters": [ { "name": "X-API-KEY", "in": "header", "description": "Public API key issued from the Lumepay API key management flow.", "required": true, "schema": { "type": "string" } }, { "name": "X-API-SECRET", "in": "header", "description": "API secret paired with the public API key.", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "description": "Test event accepted and matching outbox rows queued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookTestEventResponse" } } } }, "429": { "$ref": "#/components/responses/RateLimitError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" } } } }, "/api/v1/webhooks/subscriptions": { "get": { "tags": [ "Webhooks" ], "summary": "List webhook subscriptions", "description": "Returns webhook subscriptions owned by the authenticated API key owner, including their subscribed events.", "operationId": "listSubscriptions", "parameters": [ { "name": "X-API-KEY", "in": "header", "description": "Public API key issued from the Lumepay API key management flow.", "required": true, "schema": { "type": "string" } }, { "name": "X-API-SECRET", "in": "header", "description": "API secret paired with the public API key.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Webhook subscriptions returned successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookSubscriptionResponse" } } } } }, "429": { "$ref": "#/components/responses/RateLimitError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" } } }, "post": { "tags": [ "Webhooks" ], "summary": "Create webhook subscription", "description": "Creates a PENDING_VERIFICATION webhook subscription for a public HTTPS callback URL. Each API user may have only one non-deleted subscription for a given targetUrl.", "operationId": "createSubscription", "parameters": [ { "name": "X-API-KEY", "in": "header", "description": "Public API key issued from the Lumepay API key management flow.", "required": true, "schema": { "type": "string" } }, { "name": "X-API-SECRET", "in": "header", "description": "API secret paired with the public API key.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSubscriptionCreateRequest" } } }, "required": true }, "responses": { "201": { "description": "Webhook subscription created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSubscriptionResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "429": { "$ref": "#/components/responses/RateLimitError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" } } } }, "/api/v1/webhooks/subscriptions/{subscriptionId}/verify": { "post": { "tags": [ "Webhooks" ], "summary": "Verify webhook subscription", "description": "Sends a `webhook.verification` challenge to the subscription targetUrl. The callback must return any 2xx response. Verification challenges use the same signed callback header contract as deliveries. Unverified subscriptions can retry this endpoint after the verification cooldown. Verified subscriptions return their current details.", "operationId": "verifySubscription", "parameters": [ { "name": "subscriptionId", "in": "path", "description": "Webhook subscription id.", "required": true, "schema": { "type": "string" }, "example": "whsub_5e737a5abaee46568bd8d530b9b3521a" }, { "name": "X-API-KEY", "in": "header", "description": "Public API key issued from the Lumepay API key management flow.", "required": true, "schema": { "type": "string" } }, { "name": "X-API-SECRET", "in": "header", "description": "API secret paired with the public API key.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Webhook subscription verified or already verified", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSubscriptionResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "429": { "$ref": "#/components/responses/RateLimitError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" } } } }, "/api/v1/webhooks/subscriptions/{subscriptionId}/events": { "post": { "tags": [ "Webhooks" ], "summary": "Add webhook subscription events", "description": "Adds supported event types to a mutable webhook subscription. Existing event links are left unchanged.", "operationId": "addSubscriptionEvents", "parameters": [ { "name": "subscriptionId", "in": "path", "description": "Webhook subscription id.", "required": true, "schema": { "type": "string" }, "example": "whsub_5e737a5abaee46568bd8d530b9b3521a" }, { "name": "X-API-KEY", "in": "header", "description": "Public API key issued from the Lumepay API key management flow.", "required": true, "schema": { "type": "string" } }, { "name": "X-API-SECRET", "in": "header", "description": "API secret paired with the public API key.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSubscriptionEventsUpdateRequest" } } }, "required": true }, "responses": { "200": { "description": "Webhook subscription events updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSubscriptionResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "429": { "$ref": "#/components/responses/RateLimitError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" } } }, "delete": { "tags": [ "Webhooks" ], "summary": "Remove webhook subscription events", "description": "Removes event types from a mutable webhook subscription. The subscription must retain at least one event.", "operationId": "removeSubscriptionEvents", "parameters": [ { "name": "subscriptionId", "in": "path", "description": "Webhook subscription id.", "required": true, "schema": { "type": "string" }, "example": "whsub_5e737a5abaee46568bd8d530b9b3521a" }, { "name": "X-API-KEY", "in": "header", "description": "Public API key issued from the Lumepay API key management flow.", "required": true, "schema": { "type": "string" } }, { "name": "X-API-SECRET", "in": "header", "description": "API secret paired with the public API key.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSubscriptionEventsUpdateRequest" } } }, "required": true }, "responses": { "200": { "description": "Webhook subscription events updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSubscriptionResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "429": { "$ref": "#/components/responses/RateLimitError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" } } } }, "/api/v1/webhooks/subscriptions/{subscriptionId}/deactivate": { "post": { "tags": [ "Webhooks" ], "summary": "Deactivate webhook subscription", "description": "Marks a non-disabled webhook subscription INACTIVE. Inactive subscriptions do not receive new deliveries.", "operationId": "deactivateSubscription", "parameters": [ { "name": "subscriptionId", "in": "path", "description": "Webhook subscription id.", "required": true, "schema": { "type": "string" }, "example": "whsub_5e737a5abaee46568bd8d530b9b3521a" }, { "name": "X-API-KEY", "in": "header", "description": "Public API key issued from the Lumepay API key management flow.", "required": true, "schema": { "type": "string" } }, { "name": "X-API-SECRET", "in": "header", "description": "API secret paired with the public API key.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Webhook subscription deactivated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSubscriptionResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "429": { "$ref": "#/components/responses/RateLimitError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" } } } }, "/api/v1/webhooks/subscriptions/{subscriptionId}/activate": { "post": { "tags": [ "Webhooks" ], "summary": "Activate webhook subscription", "description": "Activates a verified webhook subscription. Activation is rejected until `verifiedAt` is set.", "operationId": "activateSubscription", "parameters": [ { "name": "subscriptionId", "in": "path", "description": "Webhook subscription id.", "required": true, "schema": { "type": "string" }, "example": "whsub_5e737a5abaee46568bd8d530b9b3521a" }, { "name": "X-API-KEY", "in": "header", "description": "Public API key issued from the Lumepay API key management flow.", "required": true, "schema": { "type": "string" } }, { "name": "X-API-SECRET", "in": "header", "description": "API secret paired with the public API key.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Webhook subscription activated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSubscriptionResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "429": { "$ref": "#/components/responses/RateLimitError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" } } } }, "/api/v1/conversions/quote": { "post": { "tags": [ "Conversions" ], "summary": "Get conversion quote", "description": "Requests a currency conversion quote for the authenticated API key owner.", "operationId": "getQuote", "parameters": [ { "name": "X-API-KEY", "in": "header", "description": "Public API key issued from the Lumepay API key management flow.", "required": true, "schema": { "type": "string" } }, { "name": "X-API-SECRET", "in": "header", "description": "API secret paired with the public API key.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversionQuoteRequest" }, "examples": { "Quote by send amount": { "summary": "Request a quote using fromAmount, for example spend 1850 ZAR", "description": "Quote by send amount", "value": { "fromAmount": 1850, "fromCurrency": "ZAR", "toCurrency": "USD", "quoteIntent": "client_linked" } }, "Quote by receive amount": { "summary": "Request a quote using toAmount, for example receive 100 USD", "description": "Quote by receive amount", "value": { "toAmount": 100, "fromCurrency": "ZAR", "toCurrency": "USD", "quoteIntent": "client_linked" } } } } }, "required": true }, "responses": { "200": { "description": "Conversion quote returned successfully", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "429": { "$ref": "#/components/responses/RateLimitError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" } } } }, "/api/v1/conversions/quote/confirm": { "post": { "tags": [ "Conversions" ], "summary": "Confirm conversion quote", "description": "Confirms a previously issued currency conversion quote for the authenticated API key owner.", "operationId": "confirmQuote", "parameters": [ { "name": "X-API-KEY", "in": "header", "description": "Public API key issued from the Lumepay API key management flow.", "required": true, "schema": { "type": "string" } }, { "name": "X-API-SECRET", "in": "header", "description": "API secret paired with the public API key.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmConversionRequest" }, "examples": { "Confirm by send amount": { "summary": "Confirm using fromAmount", "description": "Confirm by send amount", "value": { "fromAmount": 1850, "fromCurrency": "ZAR", "toCurrency": "USD", "quoteStr": "rfq_quote_7K9Q2M" } }, "Confirm by receive amount": { "summary": "Confirm using toAmount", "description": "Confirm by receive amount", "value": { "toAmount": 100, "fromCurrency": "ZAR", "toCurrency": "USD", "quoteStr": "rfq_quote_7K9Q2M" } } } } }, "required": true }, "responses": { "200": { "description": "Conversion quote confirmed successfully", "content": { "application/json": { "examples": { "Confirmed conversion by send amount": { "summary": "Conversion response returned after confirming a fromAmount quote", "description": "Confirmed conversion by send amount", "value": { "fromCurrency": "ZAR", "toCurrency": "USD", "fromAmount": 1850, "toAmount": 100, "rate": 0.0541, "isRateInverted": false, "status": "COMPLETED", "transactionId": "TID4J7K2N", "createdAt": "2026-05-11T10:15:30Z", "completedAt": "2026-05-11T10:15:35" } } } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "429": { "$ref": "#/components/responses/RateLimitError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" } } } }, "/api/v1/beneficiaries/withdrawals": { "post": { "tags": [ "Beneficiaries" ], "summary": "Create beneficiary withdrawal", "description": "Creates a withdrawal using the saved details from the beneficiary identified in the body. Call GET /api/v1/payment-reasons, then submit its id and required text fields together in the flat paymentReasons object.", "operationId": "createWithdrawalWithPaymentReasonDocuments_1", "parameters": [ { "name": "X-API-KEY", "in": "header", "description": "Public API key issued from the Lumepay API key management flow.", "required": true, "schema": { "type": "string" } }, { "name": "X-API-SECRET", "in": "header", "description": "API secret paired with the public API key.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "request": { "$ref": "#/components/schemas/CreateBeneficiaryWithdrawalRequest" } }, "required": [ "request" ] } }, "application/json": { "schema": { "$ref": "#/components/schemas/CreateBeneficiaryWithdrawalRequest" } } }, "required": true }, "responses": { "201": { "description": "Withdrawal created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWithdrawalResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "429": { "$ref": "#/components/responses/RateLimitError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" } } } }, "/api/v1/accounts": { "get": { "tags": [ "Accounts" ], "summary": "List accounts", "description": "Returns accounts belonging to the authenticated API key owner for currencies enabled in the owner's effective jurisdiction.", "operationId": "getAccounts", "parameters": [ { "name": "X-API-KEY", "in": "header", "description": "Public API key issued from the Lumepay API key management flow.", "required": true, "schema": { "type": "string" } }, { "name": "X-API-SECRET", "in": "header", "description": "API secret paired with the public API key.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Accounts returned successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ExternalAccountResponse" } } } } }, "429": { "$ref": "#/components/responses/RateLimitError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" } } }, "post": { "tags": [ "Accounts" ], "summary": "Create account", "description": "Creates an account for the authenticated API key owner only when the requested currency is enabled in the owner's effective jurisdiction.", "operationId": "createAccount", "parameters": [ { "name": "X-API-KEY", "in": "header", "description": "Public API key issued from the Lumepay API key management flow.", "required": true, "schema": { "type": "string" } }, { "name": "X-API-SECRET", "in": "header", "description": "API secret paired with the public API key.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalCreateAccountRequest" } } }, "required": true }, "responses": { "201": { "description": "Account created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalAccountResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "409": { "$ref": "#/components/responses/ConflictError" }, "429": { "$ref": "#/components/responses/RateLimitError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" } } } }, "/api/v1/withdrawals": { "get": { "tags": [ "Withdrawals" ], "summary": "List withdrawals", "description": "Returns the authenticated user's withdrawal history. Pagination, sorting, date filtering, and status filtering parameters are reserved for this list endpoint; current responses remain unpaginated until server-side pagination is enabled.", "operationId": "getWithdrawHistory", "parameters": [ { "name": "page", "in": "query", "description": "Page number, zero-based.", "required": false, "schema": { "type": "integer", "format": "int32" }, "example": 0 }, { "name": "size", "in": "query", "description": "Page size. Planned maximum: 100.", "required": false, "schema": { "type": "integer", "format": "int32" }, "example": 50 }, { "name": "sort", "in": "query", "description": "Sort expression: field,direction.", "required": false, "schema": { "type": "string" }, "example": "completedAt,desc" }, { "name": "dateFrom", "in": "query", "description": "Reserved inclusive lower timestamp bound.", "required": false, "schema": { "type": "string", "format": "date-time" }, "example": "2026-01-01T00:00:00Z" }, { "name": "dateTo", "in": "query", "description": "Reserved inclusive upper timestamp bound.", "required": false, "schema": { "type": "string", "format": "date-time" }, "example": "2026-01-31T23:59:59Z" }, { "name": "status", "in": "query", "description": "Reserved withdrawal status filter.", "required": false, "schema": { "type": "string" }, "example": "COMPLETED" }, { "name": "X-API-KEY", "in": "header", "description": "Public API key issued from the Lumepay API key management flow.", "required": true, "schema": { "type": "string" } }, { "name": "X-API-SECRET", "in": "header", "description": "API secret paired with the public API key.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Withdrawals returned successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/WithdrawResponse" } } } } }, "429": { "$ref": "#/components/responses/RateLimitError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" } } } }, "/api/v1/withdrawals/{transactionId}": { "get": { "tags": [ "Withdrawals" ], "summary": "Get withdrawal", "description": "Returns a single withdrawal belonging to the authenticated API key owner.", "operationId": "getWithdraw", "parameters": [ { "name": "transactionId", "in": "path", "description": "Withdrawal transaction id returned by the withdrawal list endpoint.", "required": true, "schema": { "type": "string" }, "example": "wd_5M8Q1P" }, { "name": "X-API-KEY", "in": "header", "description": "Public API key issued from the Lumepay API key management flow.", "required": true, "schema": { "type": "string" } }, { "name": "X-API-SECRET", "in": "header", "description": "API secret paired with the public API key.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Withdrawal returned successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WithdrawResponse" } } } }, "404": { "$ref": "#/components/responses/NotFoundError" }, "429": { "$ref": "#/components/responses/RateLimitError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" } } } }, "/api/v1/webhooks/subscriptions/{subscriptionId}": { "get": { "tags": [ "Webhooks" ], "summary": "Get webhook subscription", "description": "Returns one webhook subscription owned by the authenticated API key owner.", "operationId": "getSubscription", "parameters": [ { "name": "subscriptionId", "in": "path", "description": "Webhook subscription id returned by create/list endpoints.", "required": true, "schema": { "type": "string" }, "example": "whsub_5e737a5abaee46568bd8d530b9b3521a" }, { "name": "X-API-KEY", "in": "header", "description": "Public API key issued from the Lumepay API key management flow.", "required": true, "schema": { "type": "string" } }, { "name": "X-API-SECRET", "in": "header", "description": "API secret paired with the public API key.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Webhook subscription returned successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSubscriptionResponse" } } } }, "404": { "$ref": "#/components/responses/NotFoundError" }, "429": { "$ref": "#/components/responses/RateLimitError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" } } } }, "/api/v1/webhooks/events": { "get": { "tags": [ "Webhooks" ], "summary": "List webhook events", "description": "Returns the active v1 webhook event catalog. Subscribe with the customer-facing `eventType` value, for example `deposit.completed`.", "operationId": "listEvents", "parameters": [ { "name": "X-API-KEY", "in": "header", "description": "Public API key issued from the Lumepay API key management flow.", "required": true, "schema": { "type": "string" } }, { "name": "X-API-SECRET", "in": "header", "description": "API secret paired with the public API key.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Webhook events returned successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEventResponse" } } } } }, "429": { "$ref": "#/components/responses/RateLimitError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" } } } }, "/api/v1/wallets": { "get": { "tags": [ "Wallets" ], "summary": "List wallets", "description": "Returns wallets belonging to the authenticated API key owner.", "operationId": "getWallets", "parameters": [ { "name": "paymentMethodType", "in": "query", "description": "Optional payment method type filter for fiat wallets.", "required": false, "schema": { "type": "string" }, "example": "EFT" }, { "name": "networkName", "in": "query", "description": "Optional network name filter for crypto wallets.", "required": false, "schema": { "type": "string" }, "example": "Ethereum (ETH)" }, { "name": "X-API-KEY", "in": "header", "description": "Public API key issued from the Lumepay API key management flow.", "required": true, "schema": { "type": "string" } }, { "name": "X-API-SECRET", "in": "header", "description": "API secret paired with the public API key.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Wallets returned successfully", "content": { "application/json": { "examples": { "Fiat virtual EFT wallet": { "summary": "Fiat wallet with user-specific EFT bank account details", "description": "Fiat virtual EFT wallet", "value": [ { "id": "wal_3Q8M1K", "currency": "ZAR", "depositDetails": { "bankName": "Nedbank", "accountName": "Example Customer", "accountNumber": "9876543210", "accountType": "Current", "branchCode": "198765" }, "networkName": null, "paymentMethodType": "EFT" } ] }, "Crypto wallet": { "summary": "Crypto wallet with blockchain address deposit details", "description": "Crypto wallet", "value": [ { "id": "wal_7K9Q2M", "currency": "BTC", "depositDetails": { "address": "bc1qexample...", "address_tag": "123456" }, "networkName": "Bitcoin", "paymentMethodType": null } ] } } } } }, "429": { "$ref": "#/components/responses/RateLimitError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" } } } }, "/api/v1/wallets/{walletId}": { "get": { "tags": [ "Wallets" ], "summary": "Get wallet", "description": "Returns one wallet belonging to the authenticated API key owner.", "operationId": "getWallet", "parameters": [ { "name": "walletId", "in": "path", "description": "Wallet id returned by the wallet list endpoint.", "required": true, "schema": { "type": "string" }, "example": "wal_3Q8M1K" }, { "name": "X-API-KEY", "in": "header", "description": "Public API key issued from the Lumepay API key management flow.", "required": true, "schema": { "type": "string" } }, { "name": "X-API-SECRET", "in": "header", "description": "API secret paired with the public API key.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Wallet returned successfully", "content": { "application/json": { "examples": { "Fiat virtual EFT wallet": { "summary": "Fiat wallet with user-specific EFT bank account details", "description": "Fiat virtual EFT wallet", "value": { "id": "wal_3Q8M1K", "currency": "ZAR", "depositDetails": { "bankName": "Nedbank", "accountName": "Example Customer", "accountNumber": "9876543210", "accountType": "Current", "branchCode": "198765" }, "networkName": null, "paymentMethodType": "EFT" } }, "Crypto wallet": { "summary": "Crypto wallet with blockchain address deposit details", "description": "Crypto wallet", "value": { "id": "wal_7K9Q2M", "currency": "BTC", "depositDetails": { "address": "bc1qexample...", "address_tag": "123456" }, "networkName": "Bitcoin", "paymentMethodType": null } } } } } }, "404": { "$ref": "#/components/responses/NotFoundError" }, "429": { "$ref": "#/components/responses/RateLimitError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" } } } }, "/api/v1/payment-reasons": { "get": { "tags": [ "Payment reasons" ], "summary": "List payment reasons", "description": "Returns configured payment reasons. Put the selected id in paymentReasons.paymentReasonId when creating a beneficiary withdrawal. requiredTextFields describes the additional flat paymentReasons fields; requiredUploadFile describes required documents and their allowedFileTypes.", "operationId": "getPaymentReasons", "responses": { "200": { "description": "Payment reasons returned successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentReasonResponse" } } } } }, "429": { "$ref": "#/components/responses/RateLimitError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "400": { "$ref": "#/components/responses/BadRequestError" } } } }, "/api/v1/deposits": { "get": { "tags": [ "Deposits" ], "summary": "List deposits", "description": "Returns the authenticated user's deposit history. The status parameter filters deposits by their exact status. Pagination, sorting, and date filtering parameters are reserved; current responses remain unpaginated until server-side pagination is enabled.", "operationId": "depositHistory", "parameters": [ { "name": "page", "in": "query", "description": "Page number, zero-based.", "required": false, "schema": { "type": "integer", "format": "int32" }, "example": 0 }, { "name": "size", "in": "query", "description": "Page size. Planned maximum: 100.", "required": false, "schema": { "type": "integer", "format": "int32" }, "example": 50 }, { "name": "sort", "in": "query", "description": "Sort expression: field,direction.", "required": false, "schema": { "type": "string" }, "example": "completedAt,desc" }, { "name": "dateFrom", "in": "query", "description": "Lower timestamp bound.", "required": false, "schema": { "type": "string", "format": "date-time" }, "example": "2026-01-01T00:00:00Z" }, { "name": "dateTo", "in": "query", "description": "Upper timestamp bound.", "required": false, "schema": { "type": "string", "format": "date-time" }, "example": "2026-01-31T23:59:59Z" }, { "name": "status", "in": "query", "description": "Deposit status filter.", "required": false, "schema": { "type": "string", "enum": [ "SUBMITTED", "PENDING", "PROCESSING", "COMPLIANCE_PENDING", "COMPLETED", "FAILED", "CANCELLED", "REVERSED" ] }, "example": "COMPLETED" }, { "name": "X-API-KEY", "in": "header", "description": "Public API key issued from the Lumepay API key management flow.", "required": true, "schema": { "type": "string" } }, { "name": "X-API-SECRET", "in": "header", "description": "API secret paired with the public API key.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Deposits returned successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/DepositResponse" } } } } }, "429": { "$ref": "#/components/responses/RateLimitError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" } } } }, "/api/v1/deposits/{transactionId}": { "get": { "tags": [ "Deposits" ], "summary": "Get deposit", "description": "Returns a single deposit belonging to the authenticated API key owner.", "operationId": "getDeposit", "parameters": [ { "name": "transactionId", "in": "path", "description": "Deposit Transaction id returned by the deposit list endpoint.", "required": true, "schema": { "type": "string" }, "example": "dep_9H2K7P" }, { "name": "X-API-KEY", "in": "header", "description": "Public API key issued from the Lumepay API key management flow.", "required": true, "schema": { "type": "string" } }, { "name": "X-API-SECRET", "in": "header", "description": "API secret paired with the public API key.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Deposit returned successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DepositResponse" } } } }, "404": { "$ref": "#/components/responses/NotFoundError" }, "429": { "$ref": "#/components/responses/RateLimitError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" } } } }, "/api/v1/currencies": { "get": { "tags": [ "Currencies" ], "summary": "List currencies", "description": "Returns enabled currencies for the authenticated API key owner's effective jurisdiction.", "operationId": "getCurrencies", "parameters": [ { "name": "X-API-KEY", "in": "header", "description": "Public API key issued from the Lumepay API key management flow.", "required": true, "schema": { "type": "string" } }, { "name": "X-API-SECRET", "in": "header", "description": "API secret paired with the public API key.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Currencies returned successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ExternalCurrencyResponse" } } } } }, "429": { "$ref": "#/components/responses/RateLimitError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" } } } }, "/api/v1/beneficiaries": { "get": { "tags": [ "Beneficiaries" ], "summary": "List beneficiaries", "description": "Returns confirmed beneficiaries belonging to the authenticated API key owner.", "operationId": "getBeneficiaries", "parameters": [ { "name": "currency", "in": "query", "description": "Optional beneficiary currency code filter.", "required": false, "schema": { "type": "string" }, "example": "ZAR" }, { "name": "X-API-KEY", "in": "header", "description": "Public API key issued from the Lumepay API key management flow.", "required": true, "schema": { "type": "string" } }, { "name": "X-API-SECRET", "in": "header", "description": "API secret paired with the public API key.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Beneficiaries returned successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/BeneficiaryResponse" } } } } }, "429": { "$ref": "#/components/responses/RateLimitError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" } } } }, "/api/v1/beneficiaries/{beneficiaryId}": { "get": { "tags": [ "Beneficiaries" ], "summary": "Get beneficiary", "description": "Returns a confirmed beneficiary belonging to the authenticated API key owner.", "operationId": "getBeneficiary", "parameters": [ { "name": "beneficiaryId", "in": "path", "description": "Beneficiary id returned by the beneficiary list endpoint.", "required": true, "schema": { "type": "string" }, "example": "ben_7K9Q2M" }, { "name": "X-API-KEY", "in": "header", "description": "Public API key issued from the Lumepay API key management flow.", "required": true, "schema": { "type": "string" } }, { "name": "X-API-SECRET", "in": "header", "description": "API secret paired with the public API key.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Beneficiary returned successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BeneficiaryResponse" } } } }, "404": { "$ref": "#/components/responses/NotFoundError" }, "429": { "$ref": "#/components/responses/RateLimitError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" } } } }, "/api/v1/accounts/{accountId}": { "get": { "tags": [ "Accounts" ], "summary": "Get account", "description": "Returns one account belonging to the authenticated API key owner when its currency is enabled in the owner's effective jurisdiction.", "operationId": "getAccount", "parameters": [ { "name": "accountId", "in": "path", "description": "Account id returned by the account list endpoint.", "required": true, "schema": { "type": "string" }, "example": "acc_8F4J2N" }, { "name": "X-API-KEY", "in": "header", "description": "Public API key issued from the Lumepay API key management flow.", "required": true, "schema": { "type": "string" } }, { "name": "X-API-SECRET", "in": "header", "description": "API secret paired with the public API key.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Account returned successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalAccountResponse" } } } }, "404": { "$ref": "#/components/responses/NotFoundError" }, "429": { "$ref": "#/components/responses/RateLimitError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" } } } }, "/api/v1/accounts/currency/{currency}": { "get": { "tags": [ "Accounts" ], "summary": "Get account by currency", "description": "Returns one account belonging to the authenticated API key owner for the requested currency when that currency is enabled in the owner's effective jurisdiction.", "operationId": "getAccountByCurrency", "parameters": [ { "name": "currency", "in": "path", "description": "Currency for the account lookup.", "required": true, "schema": { "type": "string" }, "example": "ZAR" }, { "name": "X-API-KEY", "in": "header", "description": "Public API key issued from the Lumepay API key management flow.", "required": true, "schema": { "type": "string" } }, { "name": "X-API-SECRET", "in": "header", "description": "API secret paired with the public API key.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Account returned successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalAccountResponse" } } } }, "404": { "$ref": "#/components/responses/NotFoundError" }, "429": { "$ref": "#/components/responses/RateLimitError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" } } } } }, "components": { "schemas": { "CreateWithdrawalFromBeneficiaryRequest": { "type": "object", "description": "Request to create a withdrawal from the beneficiary identified in the request path.", "properties": { "amount": { "type": "number", "description": "Withdrawal amount in the beneficiary currency.", "example": 101 }, "paymentReasons": { "type": "object", "additionalProperties": { "type": "object" }, "description": "Flat payment reason object. Include paymentReasonId and values keyed by requiredTextFields from GET /api/v1/payment-reasons.", "example": { "paymentReasonId": 18, "regulatoryBodyName": "Financial Sector Conduct Authority", "licenceRegistrationReference": "FSP-123456" } } }, "required": [ "amount" ] }, "CreateWithdrawalResponse": { "type": "object", "description": "Withdrawal creation response returned by the API.", "properties": { "transactionId": { "type": "string", "description": "Created withdrawal transaction id.", "example": "WD5M8Q1P" }, "status": { "type": "string", "description": "Created withdrawal status.", "enum": [ "PENDING", "ACCEPTED", "AWAITING_CONFIRMATION", "PROCESSING", "COMPLIANCE_PENDING", "COMPLETED", "FAILED", "CANCELLED", "REVERSED" ], "example": "PENDING" } } }, "WebhookTestEventResponse": { "type": "object", "description": "Result of queuing a no-op webhook test event.", "properties": { "eventType": { "type": "string", "description": "Queued event type.", "example": "test.event" }, "resourceInternalTransactionId": { "type": "string", "description": "Synthetic resource id for this test event.", "example": "test_96e3d0fb6f7445098ec197bb4350e993" }, "matchedSubscriptionCount": { "type": "integer", "format": "int32", "description": "Number of active subscriptions matched by the test event.", "example": 1 }, "queuedOutboxCount": { "type": "integer", "format": "int32", "description": "Number of outbox rows queued for delivery.", "example": 1 }, "outboxIds": { "type": "array", "items": { "example": "evt_8410b4d047d44572b09f2e828c3ccb5a" } } } }, "WebhookSubscriptionCreateRequest": { "type": "object", "description": "Request to create a webhook subscription for the authenticated API key owner.", "properties": { "name": { "type": "string", "description": "Optional customer label for the subscription.", "example": "Ops webhook alerts" }, "targetUrl": { "type": "string", "description": "Public HTTPS callback URL. Private, loopback, link-local, metadata, and internal service destinations are rejected.", "example": "https://example.com/webhooks" }, "eventTypes": { "type": "array", "items": { "description": "Webhook event type.", "example": "deposit.completed" }, "minItems": 1, "uniqueItems": true } }, "required": [ "targetUrl" ] }, "WebhookEventResponse": { "type": "object", "description": "Customer-facing webhook event catalog entry.", "properties": { "eventType": { "type": "string", "description": "Customer-facing event key used in subscription requests.", "example": "deposit.completed" }, "resourceType": { "type": "string", "description": "Resource category for the event.", "example": "deposit" }, "event": { "type": "string", "description": "Event name within the resource category.", "example": "completed" }, "displayName": { "type": "string", "description": "Human-readable event name.", "example": "Deposit completed" }, "description": { "type": "string", "description": "Short description of when the event is emitted.", "example": "Deposit has completed." } } }, "WebhookSubscriptionResponse": { "type": "object", "description": "Webhook subscription owned by the authenticated API key owner.", "properties": { "id": { "type": "string", "description": "Public webhook subscription id.", "example": "whsub_5e737a5abaee46568bd8d530b9b3521a" }, "name": { "type": "string", "description": "Optional customer label.", "example": "Ops webhook alerts" }, "targetUrl": { "type": "string", "description": "Public HTTPS callback URL.", "example": "https://example.com/webhooks" }, "status": { "type": "string", "description": "Subscription status. PENDING_VERIFICATION requires verify before activation. INACTIVE subscriptions receive no new deliveries. DISABLED subscriptions are not customer re-enabled in v1.", "enum": [ "PENDING_VERIFICATION", "ACTIVE", "INACTIVE", "DISABLED" ], "example": "PENDING_VERIFICATION" }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEventResponse" } }, "verifiedAt": { "type": "string", "format": "date-time", "description": "UTC timestamp when the callback endpoint was last verified.", "example": "2026-06-12T15:03:23Z" }, "createdAt": { "type": "string", "format": "date-time", "description": "UTC creation timestamp.", "example": "2026-06-12T15:01:00Z" }, "updatedAt": { "type": "string", "format": "date-time", "description": "UTC last update timestamp.", "example": "2026-06-12T15:03:23Z" } } }, "WebhookSubscriptionEventsUpdateRequest": { "type": "object", "description": "Request to add or remove event types on an existing webhook subscription.", "properties": { "eventTypes": { "type": "array", "items": { "description": "Webhook event type.", "example": "deposit.completed" }, "minItems": 1, "uniqueItems": true } } }, "ConversionQuoteRequest": { "type": "object", "properties": { "fromAmount": { "type": "number", "description": "How much the customer wants to send or pay. Provide either fromAmount or toAmount, not both.", "example": 1850 }, "toAmount": { "type": "number", "description": "How much the customer wants to receive. Provide either toAmount or fromAmount, not both.", "example": 100 }, "fromCurrency": { "type": "string", "description": "Currency the customer sends or pays with.", "example": "ZAR" }, "toCurrency": { "type": "string", "description": "Currency the customer wants to receive.", "example": "USD" }, "quoteIntent": { "type": "string", "description": "Use client_linked when the customer may confirm this quote. Use indicative when the customer only needs a preview price.", "enum": [ "indicative", "client_linked" ], "example": "client_linked", "pattern": "(?i)indicative|client_linked" } } }, "ConfirmConversionRequest": { "type": "object", "properties": { "fromAmount": { "type": "number", "description": "Amount the customer sends or pays from the quote response. Provide either fromAmount or toAmount, not both.", "example": 1850 }, "toAmount": { "type": "number", "description": "Amount the customer receives from the quote response. Provide either toAmount or fromAmount, not both.", "example": 100 }, "fromCurrency": { "type": "string", "description": "Currency the customer sends or pays with.", "example": "ZAR" }, "quoteStr": { "type": "string", "description": "Quote reference returned by /api/v1/conversions/quote.", "example": "rfq_quote_7K9Q2M" }, "toCurrency": { "type": "string", "description": "Currency the customer receives.", "example": "USD" } } }, "CreateBeneficiaryWithdrawalRequest": { "type": "object", "description": "Request to create a withdrawal from a beneficiary.", "properties": { "beneficiaryId": { "type": "string", "description": "Beneficiary id returned by the beneficiary endpoints.", "example": "ben_7K9Q2M" }, "amount": { "type": "number", "description": "Withdrawal amount in the beneficiary currency.", "example": 101 }, "paymentReasons": { "type": "object", "additionalProperties": { "type": "object" }, "description": "Flat payment reason object. Include paymentReasonId and values keyed by requiredTextFields from GET /api/v1/payment-reasons.", "example": { "paymentReasonId": 18, "regulatoryBodyName": "Financial Sector Conduct Authority", "licenceRegistrationReference": "FSP-123456" } } }, "required": [ "amount" ] }, "ExternalCreateAccountRequest": { "type": "object", "properties": { "currency": { "type": "string", "description": "Currency code for the account to create.", "example": "ZAR" } } }, "ExternalAccountResponse": { "type": "object", "properties": { "id": { "type": "string", "description": "Account id used by external account endpoints.", "example": "acc_8F4J2N" }, "currency": { "type": "string", "description": "Account currency.", "example": "ZAR" }, "balance": { "type": "number", "description": "Available account balance.", "example": 2500 }, "lockedBalance": { "type": "number", "description": "Locked account balance.", "example": 0 } } }, "JsonNode": { "type": "object", "additionalProperties": true, "description": "Raw withdrawal details stored as JSON object.", "example": { "bankName": "FNB", "accountNumber": "1234567890" }, "properties": { "pojo": { "type": "boolean" }, "int": { "type": "boolean" }, "double": { "type": "boolean" }, "bigDecimal": { "type": "boolean" }, "bigInteger": { "type": "boolean" }, "nodeType": { "type": "string", "enum": [ "ARRAY", "BINARY", "BOOLEAN", "MISSING", "NULL", "NUMBER", "OBJECT", "POJO", "STRING" ] }, "container": { "type": "boolean" }, "short": { "type": "boolean" }, "binary": { "type": "boolean" }, "long": { "type": "boolean" }, "integralNumber": { "type": "boolean" }, "floatingPointNumber": { "type": "boolean" }, "missingNode": { "type": "boolean" }, "string": { "type": "boolean" }, "boolean": { "type": "boolean" }, "number": { "type": "boolean" }, "object": { "type": "boolean" }, "textual": { "type": "boolean", "deprecated": true }, "valueNode": { "type": "boolean" }, "array": { "type": "boolean" }, "empty": { "type": "boolean" }, "null": { "type": "boolean" }, "float": { "type": "boolean" }, "embeddedValue": { "type": "boolean" } } }, "WithdrawResponse": { "type": "object", "description": "Withdrawal transaction returned by the API.", "properties": { "amount": { "type": "number", "description": "Withdrawal amount.", "example": 101 }, "fee": { "type": "number", "description": "Withdrawal fee.", "example": 1 }, "currency": { "type": "string", "description": "Withdrawal currency code.", "example": "ZAR" }, "withdrawDetails": { "$ref": "#/components/schemas/JsonNode", "additionalProperties": true, "description": "Raw withdrawal details stored as JSON object.", "example": { "bankName": "FNB", "accountNumber": "1234567890" } }, "status": { "type": "string", "description": "Withdrawal status.", "enum": [ "PENDING", "ACCEPTED", "AWAITING_CONFIRMATION", "PROCESSING", "COMPLIANCE_PENDING", "COMPLETED", "FAILED", "CANCELLED", "REVERSED" ], "example": "COMPLETED" }, "transactionId": { "type": "string", "description": "Transaction id for withdrawal lookups.", "example": "wd_5M8Q1P" }, "createdAt": { "type": "string", "format": "date-time", "description": "Withdrawal creation timestamp.", "example": "2026-05-11T10:15:30Z" }, "completedAt": { "type": "string", "format": "date-time", "description": "Completion timestamp.", "example": "2026-05-11T10:20:30" }, "isFiat": { "type": "boolean", "description": "Whether this withdrawal used a fiat route.", "example": true } } }, "PaymentReasonResponse": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64", "description": "Payment reason id to submit as paymentReasonId.", "example": 1 }, "reason": { "type": "string", "description": "Consumer-facing payment reason.", "example": "Payment for goods" }, "requiredTextFields": { "type": "object", "additionalProperties": { "type": "object" }, "description": "Text inputs required in paymentReasonTextValues, keyed by input name." }, "requiredUploadFile": { "type": "object", "additionalProperties": { "type": "object" }, "description": "Required upload inputs keyed by document name, including allowedFileTypes metadata." } } }, "DepositResponse": { "type": "object", "description": "Deposit transaction returned by the API.", "properties": { "currency": { "type": "string", "description": "Deposit currency code.", "example": "USDT" }, "transactionId": { "type": "string", "description": "Transaction id for deposit lookups.", "example": "DP9H2K7P" }, "amount": { "type": "number", "description": "Deposit amount.", "example": 100 }, "fee": { "type": "number", "description": "Deposit fee.", "example": 0 }, "status": { "type": "string", "description": "Deposit status.", "enum": [ "SUBMITTED", "PENDING", "PROCESSING", "COMPLIANCE_PENDING", "COMPLETED", "FAILED", "CANCELLED", "REVERSED" ], "example": "COMPLETED" }, "completedAt": { "type": "string", "format": "date-time", "description": "Completion timestamp.", "example": "2026-05-11T10:15:30" } } }, "ExternalCurrencyResponse": { "type": "object", "properties": { "currency": { "type": "string", "description": "Currency code.", "example": "ZAR" }, "name": { "type": "string", "description": "Currency display name.", "example": "South African Rand" } } }, "BeneficiaryResponse": { "type": "object", "description": "Beneficiary available to the authenticated API key user.", "properties": { "id": { "type": "string", "description": "Beneficiary id used by external beneficiary endpoints.", "example": "ben_7K9Q2M" }, "currency": { "type": "string", "description": "Saved beneficiary currency.", "example": "ZAR" }, "nickname": { "type": "string", "description": "Beneficiary nickname.", "example": "FNB Savings" }, "withdrawFormDetails": { "$ref": "#/components/schemas/JsonNode", "additionalProperties": true, "description": "Saved withdrawal form details for the beneficiary.", "example": { "bankName": "FNB", "accountNumber": "1234567890", "accountHolderName": "Jane Example" } }, "createdAt": { "type": "string", "format": "date-time", "description": "Beneficiary creation timestamp.", "example": "2026-05-11T10:15:30Z" } } }, "ApiResponse": { "type": "object", "properties": { "code": { "type": "integer", "format": "int32", "example": 400 }, "message": { "type": "string", "example": "Request validation failed" }, "httpStatus": { "type": "integer", "format": "int32", "example": 400 }, "requestId": { "type": "string", "example": "req_01HY0000000000000000000000" }, "timestamp": { "type": "string", "format": "date-time", "example": "2026-01-01T00:00:00Z" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string", "example": "amount" }, "message": { "type": "string", "example": "must be greater than 0" } } } } } } }, "responses": { "BadRequestError": { "description": "Request validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" }, "example": { "httpStatus": 400, "requestId": "req_01HY0000000000000000000000", "message": "Request validation failed", "code": 400, "timestamp": "2026-01-01T00:00:00Z", "errors": [] } } } }, "UnauthorizedError": { "description": "API key authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" }, "example": { "httpStatus": 401, "requestId": "req_01HY0000000000000000000000", "message": "API key authentication failed", "code": 401, "timestamp": "2026-01-01T00:00:00Z", "errors": [] } } } }, "RateLimitError": { "description": "Cloudflare API rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "rate_limit_exceeded" }, "message": { "type": "string", "example": "API rate limit exceeded" } } }, "example": { "error": "rate_limit_exceeded", "message": "API rate limit exceeded" } } } }, "ForbiddenError": { "description": "Authenticated API key is not allowed to perform this action", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" }, "example": { "httpStatus": 403, "requestId": "req_01HY0000000000000000000000", "message": "Authenticated API key is not allowed to perform this action", "code": 403, "timestamp": "2026-01-01T00:00:00Z", "errors": [] } } } }, "NotFoundError": { "description": "Resource was not found for the authenticated API key owner", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" }, "example": { "httpStatus": 404, "requestId": "req_01HY0000000000000000000000", "message": "Resource was not found for the authenticated API key owner", "code": 404, "timestamp": "2026-01-01T00:00:00Z", "errors": [] } } } }, "ConflictError": { "description": "Request conflicts with current resource or money movement state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" }, "example": { "httpStatus": 409, "requestId": "req_01HY0000000000000000000000", "message": "Request conflicts with current resource or money movement state", "code": 409, "timestamp": "2026-01-01T00:00:00Z", "errors": [] } } } }, "InternalServerError": { "description": "Unexpected server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" }, "example": { "httpStatus": 500, "requestId": "req_01HY0000000000000000000000", "message": "Unexpected server error", "code": 500, "timestamp": "2026-01-01T00:00:00Z", "errors": [] } } } } } } }