{"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, and deposits\nand 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## 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 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 can use webhook\nsubscriptions for supported lifecycle notifications, and should continue to treat the read endpoints\nas the source of truth for current resource state.\n\nThis is version v1 of this API documentation. Last update on June 15, 2026.\n","contact":{"name":"Lume Forge"},"version":"v1"},"servers":[{"url":"/"}],"tags":[{"name":"Beneficiaries","description":"Beneficiary 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":"Webhooks","description":"Webhook event catalog and subscription management 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/webhooks/subscriptions":{"get":{"tags":["Webhooks"],"summary":"List webhook subscriptions","description":"Returns webhook subscriptions owned by the authenticated API key owner.","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"}}}}},"403":{"$ref":"#/components/responses/ForbiddenError"},"500":{"$ref":"#/components/responses/InternalServerError"},"401":{"$ref":"#/components/responses/UnauthorizedError"},"400":{"$ref":"#/components/responses/BadRequestError"}}},"post":{"tags":["Webhooks"],"summary":"Create webhook subscription","description":"Creates a pending webhook subscription for the authenticated API key owner. The target URL must be a public HTTPS callback URL and at least one supported event type is required.","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"},"403":{"$ref":"#/components/responses/ForbiddenError"},"500":{"$ref":"#/components/responses/InternalServerError"},"401":{"$ref":"#/components/responses/UnauthorizedError"}}}},"/api/v1/webhooks/subscriptions/{subscriptionId}/verify":{"post":{"tags":["Webhooks"],"operationId":"verifySubscription","parameters":[{"name":"subscriptionId","in":"path","required":true,"schema":{"type":"string"}},{"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":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookSubscriptionResponse"}}}},"403":{"$ref":"#/components/responses/ForbiddenError"},"500":{"$ref":"#/components/responses/InternalServerError"},"401":{"$ref":"#/components/responses/UnauthorizedError"},"400":{"$ref":"#/components/responses/BadRequestError"}}}},"/api/v1/webhooks/subscriptions/{subscriptionId}/deactivate":{"post":{"tags":["Webhooks"],"summary":"Deactivate webhook subscription","description":"Deactivates a webhook subscription owned by the authenticated API key owner.","operationId":"deactivateSubscription","parameters":[{"name":"subscriptionId","in":"path","description":"Webhook subscription id returned when the subscription was created.","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"},"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 owned by the authenticated API key owner.","operationId":"activateSubscription","parameters":[{"name":"subscriptionId","in":"path","description":"Webhook subscription id returned when the subscription was created.","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"},"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"}}}}},"403":{"$ref":"#/components/responses/ForbiddenError"},"500":{"$ref":"#/components/responses/InternalServerError"},"401":{"$ref":"#/components/responses/UnauthorizedError"},"400":{"$ref":"#/components/responses/BadRequestError"}}},"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"},"403":{"$ref":"#/components/responses/ForbiddenError"},"500":{"$ref":"#/components/responses/InternalServerError"},"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 when the subscription was created.","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"},"403":{"$ref":"#/components/responses/ForbiddenError"},"500":{"$ref":"#/components/responses/InternalServerError"},"401":{"$ref":"#/components/responses/UnauthorizedError"},"400":{"$ref":"#/components/responses/BadRequestError"}}}},"/api/v1/webhooks/events":{"get":{"tags":["Webhooks"],"summary":"List webhook events","description":"Returns the active webhook event types the authenticated API key owner can subscribe to.","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"}}}}},"403":{"$ref":"#/components/responses/ForbiddenError"},"500":{"$ref":"#/components/responses/InternalServerError"},"401":{"$ref":"#/components/responses/UnauthorizedError"},"400":{"$ref":"#/components/responses/BadRequestError"}}}},"/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}]}}}}},"403":{"$ref":"#/components/responses/ForbiddenError"},"500":{"$ref":"#/components/responses/InternalServerError"},"401":{"$ref":"#/components/responses/UnauthorizedError"},"400":{"$ref":"#/components/responses/BadRequestError"}}}},"/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"},"403":{"$ref":"#/components/responses/ForbiddenError"},"500":{"$ref":"#/components/responses/InternalServerError"},"401":{"$ref":"#/components/responses/UnauthorizedError"},"400":{"$ref":"#/components/responses/BadRequestError"}}}},"/api/v1/deposits":{"get":{"tags":["Deposits"],"summary":"List deposits","description":"Returns the authenticated user's deposit 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":"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"},"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"}}}}},"403":{"$ref":"#/components/responses/ForbiddenError"},"500":{"$ref":"#/components/responses/InternalServerError"},"401":{"$ref":"#/components/responses/UnauthorizedError"},"400":{"$ref":"#/components/responses/BadRequestError"}}}},"/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"},"403":{"$ref":"#/components/responses/ForbiddenError"},"500":{"$ref":"#/components/responses/InternalServerError"},"401":{"$ref":"#/components/responses/UnauthorizedError"},"400":{"$ref":"#/components/responses/BadRequestError"}}}},"/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"}}}}},"403":{"$ref":"#/components/responses/ForbiddenError"},"500":{"$ref":"#/components/responses/InternalServerError"},"401":{"$ref":"#/components/responses/UnauthorizedError"},"400":{"$ref":"#/components/responses/BadRequestError"}}}},"/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"}}}}},"403":{"$ref":"#/components/responses/ForbiddenError"},"500":{"$ref":"#/components/responses/InternalServerError"},"401":{"$ref":"#/components/responses/UnauthorizedError"},"400":{"$ref":"#/components/responses/BadRequestError"}}}},"/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"},"403":{"$ref":"#/components/responses/ForbiddenError"},"500":{"$ref":"#/components/responses/InternalServerError"},"401":{"$ref":"#/components/responses/UnauthorizedError"},"400":{"$ref":"#/components/responses/BadRequestError"}}}},"/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"},"403":{"$ref":"#/components/responses/ForbiddenError"},"500":{"$ref":"#/components/responses/InternalServerError"},"401":{"$ref":"#/components/responses/UnauthorizedError"},"400":{"$ref":"#/components/responses/BadRequestError"}}}},"/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"},"403":{"$ref":"#/components/responses/ForbiddenError"},"500":{"$ref":"#/components/responses/InternalServerError"},"401":{"$ref":"#/components/responses/UnauthorizedError"},"400":{"$ref":"#/components/responses/BadRequestError"}}}}},"components":{"schemas":{"WebhookSubscriptionCreateRequest":{"type":"object","properties":{"name":{"type":"string"},"targetUrl":{"type":"string"},"eventTypes":{"type":"array","items":{"type":"string"},"minItems":1,"uniqueItems":true}}},"WebhookEventResponse":{"type":"object","properties":{"eventType":{"type":"string"},"resourceType":{"type":"string"},"event":{"type":"string"},"displayName":{"type":"string"},"description":{"type":"string"}}},"WebhookSubscriptionResponse":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"targetUrl":{"type":"string"},"status":{"type":"string"},"events":{"type":"array","items":{"$ref":"#/components/schemas/WebhookEventResponse"}},"verifiedAt":{"type":"string","format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"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.0},"lockedBalance":{"type":"number","description":"Locked account balance.","example":0.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"]},"long":{"type":"boolean"},"floatingPointNumber":{"type":"boolean"},"integralNumber":{"type":"boolean"},"valueNode":{"type":"boolean"},"missingNode":{"type":"boolean"},"string":{"type":"boolean"},"boolean":{"type":"boolean"},"textual":{"type":"boolean","deprecated":true},"short":{"type":"boolean"},"container":{"type":"boolean"},"object":{"type":"boolean"},"binary":{"type":"boolean"},"number":{"type":"boolean"},"array":{"type":"boolean"},"empty":{"type":"boolean"},"null":{"type":"boolean"},"float":{"type":"boolean"},"embeddedValue":{"type":"boolean"}}},"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.0},"fee":{"type":"number","description":"Deposit fee.","example":0.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":{"NotFoundError":{"description":"Resource was not found for the authenticated API key owner","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse"},"example":{"errors":[],"timestamp":"2026-01-01T00:00:00Z","code":404,"message":"Resource was not found for the authenticated API key owner","requestId":"req_01HY0000000000000000000000","httpStatus":404}}}},"ForbiddenError":{"description":"Authenticated API key is not allowed to perform this action","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse"},"example":{"errors":[],"timestamp":"2026-01-01T00:00:00Z","code":403,"message":"Authenticated API key is not allowed to perform this action","requestId":"req_01HY0000000000000000000000","httpStatus":403}}}},"InternalServerError":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse"},"example":{"errors":[],"timestamp":"2026-01-01T00:00:00Z","code":500,"message":"Unexpected server error","requestId":"req_01HY0000000000000000000000","httpStatus":500}}}},"UnauthorizedError":{"description":"API key authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse"},"example":{"errors":[],"timestamp":"2026-01-01T00:00:00Z","code":401,"message":"API key authentication failed","requestId":"req_01HY0000000000000000000000","httpStatus":401}}}},"BadRequestError":{"description":"Request validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse"},"example":{"errors":[],"timestamp":"2026-01-01T00:00:00Z","code":400,"message":"Request validation failed","requestId":"req_01HY0000000000000000000000","httpStatus":400}}}},"ConflictError":{"description":"Request conflicts with current resource or money movement state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse"},"example":{"errors":[],"timestamp":"2026-01-01T00:00:00Z","code":409,"message":"Request conflicts with current resource or money movement state","requestId":"req_01HY0000000000000000000000","httpStatus":409}}}}}}}