# Zuba

> ## Agent Instructions
> Money amounts are always major-unit decimal strings (e.g. "1000.00"), never floats and never minor units, in every request, response, and webhook payload.
> Authentication is OAuth 2.0 client credentials: exchange the Client ID and Client Secret at the Token URL for a 24-hour JWT and cache it; do not request a token per call.
> Set a unique clientRef on every money-moving request; it is the idempotency key, and retries return the original resource.
> Quotes are single-use, intent-locked, and expire fast: always read expiresAt, consume the quote with the executor matching its intent, and re-quote on expiry instead of retrying.
> Prefer webhooks over polling for payout, order, application, and virtual-account status tracking.
> Use the sandbox (api.sandbox.zuba.com) with its deterministic magic values before touching production.

- [Introduction](https://docs.zuba.com/introduction.md): Zuba Payment Platform API: global payouts, payment acceptance, and multi-currency operations
- [Quickstart](https://docs.zuba.com/quickstart.md): Start building with Zuba in under 5 minutes
- [Authentication](https://docs.zuba.com/authentication.md): Learn how to authenticate with the Zuba API using OAuth 2.0
- [What Zuba Can Do Today](https://docs.zuba.com/what-zuba-can-do-today.md): Live currency coverage and rails, and what is coming next
- [MCP Server](https://docs.zuba.com/mcp-server.md): Connect Claude Code, Codex, Cursor, VS Code, and other AI coding tools to the Zuba docs over the Model Context Protocol
- [Platform Overview](https://docs.zuba.com/concepts/overview.md): Understanding the Zuba Payment Platform architecture
- [Payouts](https://docs.zuba.com/concepts/payouts.md): Send money globally with Zuba payouts
- [Payins](https://docs.zuba.com/concepts/payins.md): Fund your Zuba balance with bank transfers and crypto deposits
- [Ledger System](https://docs.zuba.com/concepts/ledger.md): Double-entry bookkeeping and transaction management
- [Your First Payout](https://docs.zuba.com/guides/first-payout.md): Step-by-step guide to sending your first payout with the Zuba API, from your EUR balance to a Nigerian bank account in NGN
- [Batch Payouts](https://docs.zuba.com/guides/batch-payouts.md): Process multiple payouts efficiently with batch operations
- [Trade Desk Orders](https://docs.zuba.com/guides/orders.md): End-to-end guide to the orders flow: quote, order creation, funding, manual desk execution, completion, cancellation, refunds, and sandbox testing
- [Webhook Notifications](https://docs.zuba.com/guides/webhooks.md): Set up real-time notifications for payment events using webhooks
- [Error Handling](https://docs.zuba.com/guides/error-handling.md): Handle errors and edge cases gracefully in your payment integration
- [Sandbox Testing](https://docs.zuba.com/guides/sandbox-testing.md): Play with the Zuba sandbox end-to-end: fund a workspace, register a webhook endpoint, trigger deterministic payout outcomes, receive the resulting webhooks, and price conversions, orders, and payouts with held quotes
- [API Reference](https://docs.zuba.com/api-reference/introduction.md): Complete API reference for the Zuba Payment Platform
- [List all API keys](https://docs.zuba.com/api-reference/api-keys/list-all-api-keys.md): Deprecated: use GET /v2/api-keys for bounded opaque cursor pagination.
- [Create a new API key](https://docs.zuba.com/api-reference/api-keys/create-a-new-api-key.md): Provisions a new M2M application in Auth0 and returns credentials. The client secret is only shown once.
- [Get API key details](https://docs.zuba.com/api-reference/api-keys/get-api-key-details.md): Get details of a specific API key (client secret will be hidden)
- [Delete an API key](https://docs.zuba.com/api-reference/api-keys/delete-an-api-key.md): Permanently delete an API key from Auth0 and mark as inactive in database.
- [Rotate client secret](https://docs.zuba.com/api-reference/api-keys/rotate-client-secret.md): Generate a new client secret for an API key. The old secret will be invalidated immediately.
- [Create account](https://docs.zuba.com/api-reference/accounts/create-account.md): Creates a `pending` sub-account (a master’s end-customer) under the caller’s master. The parent is resolved from the API key, never from the body. Pass `Idempotency-Key`; replaying the same key returns the original 201 instead of creating a duplicate. Emits the `account.created` webhook.
- [List accounts](https://docs.zuba.com/api-reference/accounts/list-accounts.md): Returns the accounts in the caller’s tree, newest-first, with opaque cursor pagination. Filter by `parent` (an account id, or `me` for the caller’s direct children) and `status`.
- [Get account](https://docs.zuba.com/api-reference/accounts/get-account.md): Returns a single account record owned by the caller, addressed by its id.
- [Update account](https://docs.zuba.com/api-reference/accounts/update-account.md): Suspend, close, or re-activate an account by transitioning its status. Allowed: active→suspended/closed, suspended→active (re-activate) or closed, pending→closed. The KYB-gated pending→active step is not settable here (activation happens after KYB approval); closed is terminal. A PATCH to the curren…
- [Create a KYB/KYC application](https://docs.zuba.com/api-reference/applications-v2/create-a-kybkyc-application.md): Supports both `business` (KYB) and `individual` (KYC) applications, in any corridor. Identity is verified from an uploaded government-ID document (`photo_id`): a business submits each director’s / applicant’s photo_id, an individual submits the applicant’s photo_id — uploaded via the /documents endp…
- [List applications](https://docs.zuba.com/api-reference/applications-v2/list-applications.md): With Zuba-Account-Id: the named sub-account’s application. Without it: every application the caller owns (self + each owned sub-account).
- [Get an application by id](https://docs.zuba.com/api-reference/applications-v2/get-an-application-by-id.md)
- [Update an application (draft data only; never changes status)](https://docs.zuba.com/api-reference/applications-v2/update-an-application-draft-data-only;-never-changes-status.md)
- [Submit (or resubmit) an application for review](https://docs.zuba.com/api-reference/applications-v2/submit-or-resubmit-an-application-for-review.md): The single explicit state transition: draft → under_review, or resubmit of a more_info_requested application. A workspace invited with additional information to answer and disclosures to sign submits its answers with its own application, and both go under review together.
- [Supply provider-required attributes for an application](https://docs.zuba.com/api-reference/applications-v2/supply-provider-required-attributes-for-an-application.md): Fills attributes a payment provider’s KYC requires that Zuba’s review does not assess: the applicant’s own attributes when the applicant is the beneficial owner, the business industry code, and the market the business primarily serves. Accepted in any application status, and only into a field the ap…
- [List persons on an application](https://docs.zuba.com/api-reference/applications-v2/list-persons-on-an-application.md)
- [Add a person to an application](https://docs.zuba.com/api-reference/applications-v2/add-a-person-to-an-application.md)
- [Update a person](https://docs.zuba.com/api-reference/applications-v2/update-a-person.md)
- [Remove a person (also soft-deletes that person’s documents)](https://docs.zuba.com/api-reference/applications-v2/remove-a-person-also-soft-deletes-that-person’s-documents.md)
- [Supply provider-required attributes for a person](https://docs.zuba.com/api-reference/applications-v2/supply-provider-required-attributes-for-a-person.md): Fills attributes a payment provider’s KYC requires that Zuba’s review does not assess, so they can be supplied after an application is approved. Accepted in any application status, and only into a field the person has no value for — correcting an existing value goes through PATCH while the applicati…
- [Request a pre-signed upload URL for a document](https://docs.zuba.com/api-reference/applications-v2/request-a-pre-signed-upload-url-for-a-document.md)
- [Confirm a document upload completed](https://docs.zuba.com/api-reference/applications-v2/confirm-a-document-upload-completed.md)
- [Soft-delete a document](https://docs.zuba.com/api-reference/applications-v2/soft-delete-a-document.md)
- [Get all accounts for current user (admin view)](https://docs.zuba.com/api-reference/ledger/get-all-accounts-for-current-user-admin-view.md): Retrieve a comprehensive list of all ledger accounts for the authenticated user. This admin-level view includes detailed account information for all currencies. Optionally include inactive accounts.
- [Get current user balances across all currencies](https://docs.zuba.com/api-reference/ledger/get-current-user-balances-across-all-currencies.md): Retrieve your account balances in all currencies. Shows available balance (funds you can use), pending incoming/outgoing amounts, and total balance for each currency account.
- [Get current user balance for a specific currency](https://docs.zuba.com/api-reference/ledger/get-current-user-balance-for-a-specific-currency.md): Retrieve balance details for a specific currency account. Currency code is case-insensitive (e.g., USD, usd, Usd all work).
- [Get closing balances across all currencies for a past date](https://docs.zuba.com/api-reference/ledger/get-closing-balances-across-all-currencies-for-a-past-date.md): Returns the end-of-day closing balance for each of your accounts as of the given UTC calendar date. The date must be in the past (yesterday or earlier); today and future dates are rejected because today is not yet closed. Backed by daily balance snapshots with transaction-replay fallback for dates w…
- [Get transaction history for current user](https://docs.zuba.com/api-reference/ledger/get-transaction-history-for-current-user.md): Deprecated: use GET /v2/ledger/transactions for stable opaque cursor pagination.
- [Generate account statement for a specific currency](https://docs.zuba.com/api-reference/ledger/generate-account-statement-for-a-specific-currency.md): Generate a detailed account statement for a currency account between two dates. The statement includes opening balance, all transactions (debits and credits), and closing balance for the specified period. Useful for reconciliation and accounting purposes.
- [Create a quote](https://docs.zuba.com/api-reference/quotes/create-a-quote.md): Mints a single-use held quote for the requested currency pair. `intent` selects the action: 'payout' prices a held cross-rate / fiat-source / same-currency quote (the corridor picks the engine), 'convert' prices an in-wallet conversion between the caller's own balances, and 'order' prices a trade-de…
- [Get a quote by ID](https://docs.zuba.com/api-reference/quotes/get-a-quote-by-id.md)
- [Execute a conversion (consume a quote, terminal state inline)](https://docs.zuba.com/api-reference/conversions/execute-a-conversion-consume-a-quote-terminal-state-inline.md)
- [Get a conversion by id](https://docs.zuba.com/api-reference/conversions/get-a-conversion-by-id.md)
- [List conversions (paginated)](https://docs.zuba.com/api-reference/conversions/list-conversions-paginated.md)
- [Convert corridors enabled for this client](https://docs.zuba.com/api-reference/conversions/convert-corridors-enabled-for-this-client.md)
- [List deposits](https://docs.zuba.com/api-reference/pay-ins/list-deposits.md): Deprecated: use GET /v2/deposits for opaque cursor pagination.
- [Create deposit](https://docs.zuba.com/api-reference/pay-ins/create-deposit.md): Create a new deposit. This endpoint supports various payment methods, including generating bank account details (IBAN and BIC) for manual bank transfers, or initiating other provider-specific payin flows based on the provided currency and user details. For NGN currency, additional user details (firs…
- [Get deposit status](https://docs.zuba.com/api-reference/pay-ins/get-deposit-status.md): Check the status of any deposit by ID, regardless of the payment method. Returns current status, bank account details, and transaction information. For NGN payins, includes the virtual account details in metadata.
- [Open a wallet](https://docs.zuba.com/api-reference/wallets/open-a-wallet.md): Opens an on-chain deposit wallet on the requested network for your master account, or for the sub-account named in `Zuba-Account-Id`, whose deposits then settle into that sub-account's balance. Idempotent per owner, network and `clientRef`: if the wallet already exists it is returned with `201 → 200…
- [List my wallets](https://docs.zuba.com/api-reference/wallets/list-my-wallets.md): Returns the wallets of the request owner, newest first, on the shared cursor contract: your master account's own wallets, or the sub-account's named by `Zuba-Account-Id`. Addresses the platform minted to fund trade-desk orders are not listed.
- [Get a wallet](https://docs.zuba.com/api-reference/wallets/get-a-wallet.md): One wallet of the request owner. A wallet that belongs to another owner, including a sub-account's when the header is omitted, is not found.
- [Create (or return) my standing virtual account](https://docs.zuba.com/api-reference/virtual-accounts/create-or-return-my-standing-virtual-account.md): Issues one durable collection account for the requested currency, owned by your master account — or by the sub-account named in `Zuba-Account-Id`, whose deposits then settle into that sub-account's balance. Idempotent per owner and currency: if a live account already exists it is returned with `201…
- [What this owner still needs before an account can be issued](https://docs.zuba.com/api-reference/virtual-accounts/what-this-owner-still-needs-before-an-account-can-be-issued.md): Answers, without issuing anything, whether a virtual account could be created right now for the request owner in the given currency — and when it could not, exactly what is outstanding and which call supplies it. Collect the answers from your customer before requesting the account, rather than disco…
- [List my virtual accounts](https://docs.zuba.com/api-reference/virtual-accounts/list-my-virtual-accounts.md): Returns every active, enabled virtual account of the request owner: your master account's own accounts, or the sub-account's named by `Zuba-Account-Id`.
- [List banks](https://docs.zuba.com/api-reference/banks/list-banks.md): Returns the supported banks for the given country as `{ name, bankCode }` pairs, sorted by name. Send a `bankCode` as `data.bankCode` on a `bank_account` beneficiary account whose `currency` is the country's. Every `bankCode` is a Zuba identifier (`ng_0001`, `gh_0003`, ...). For Nigeria, the default…
- [List banks (deprecated path)](https://docs.zuba.com/api-reference/banks/list-banks-deprecated-path.md): Deprecated alias of `GET /v1/banks`; call that path instead.
- [List all beneficiaries](https://docs.zuba.com/api-reference/payouts/list-all-beneficiaries.md): Deprecated: use GET /v2/beneficiaries for bounded opaque cursor pagination.
- [Create a new beneficiary](https://docs.zuba.com/api-reference/payouts/create-a-new-beneficiary.md): Create a new beneficiary with their account details for payouts. Idempotent: if a submitted account matches an active account already saved in the same scope (the sub-account named by Zuba-Account-Id, or the master account when none is named) on every identity it carries (its IBAN, and its bank code…
- [Get beneficiary by ID](https://docs.zuba.com/api-reference/payouts/get-beneficiary-by-id.md): Retrieve a specific beneficiary and their account details
- [Update beneficiary](https://docs.zuba.com/api-reference/payouts/update-beneficiary.md): Update an existing beneficiary's information
- [List payouts](https://docs.zuba.com/api-reference/payouts/list-payouts.md): Deprecated: use GET /v2/payouts for opaque cursor pagination.
- [Create one or multiple payouts](https://docs.zuba.com/api-reference/payouts/create-one-or-multiple-payouts.md): Create a single payout or batch of payouts. Send a single payout object or an array of payout objects. The source currency can be specified via inputCurrency field, or will be automatically selected from the currency with the largest available balance. When the beneficiary is supplied inline (no `be…
- [Get payout by ID](https://docs.zuba.com/api-reference/payouts/get-payout-by-id.md): Retrieve details of a specific payout transaction
- [Cancel a payout](https://docs.zuba.com/api-reference/payouts/cancel-a-payout.md): Cancels a payout while it is still `created` or `queued` and returns the balance its creation debited (principal, fee and any conversion legs) to the account it was taken from. A `payout.cancelled` webhook follows. Retrying a cancel is always safe: a cancelled payout is returned again, and a return…
- [Get the field requirements for a payout corridor](https://docs.zuba.com/api-reference/payouts/get-the-field-requirements-for-a-payout-corridor.md): Returns what a payout into a corridor requires of both parties: the beneficiary fields and the `senderInfo` keys that must and may be provided, reported for an individual and for a business of each party so a caller never has to declare one type to learn the other. Pass `route` (and, for mobile mone…
- [List available payout rails for an account](https://docs.zuba.com/api-reference/payouts/list-available-payout-rails-for-an-account.md): Returns rail options with static metadata (label, fee-from, ETA) for the given account. For non-USD accounts returns empty array (frontend skips picker).
- [Request a presigned upload URL for a SWIFT purpose-of-payment document](https://docs.zuba.com/api-reference/payouts/request-a-presigned-upload-url-for-a-swift-purpose-of-payment-document.md)
- [Create an order from an order-intent quote; idempotent](https://docs.zuba.com/api-reference/orders/create-an-order-from-an-order-intent-quote;-idempotent.md): Executes a held order quote: debits the source amount from your balance into a hold and queues the order for desk execution. The quote is single-use; retrying with the same `quotationId` returns the original order. Orders are executed manually by the trade desk within the execution window returned o…
- [List orders](https://docs.zuba.com/api-reference/orders/list-orders.md): Returns your orders newest-first with opaque cursor pagination. Filter by `status` and a `from`/`to` creation-time window.
- [Get an order by id](https://docs.zuba.com/api-reference/orders/get-an-order-by-id.md)
- [Cancel an order](https://docs.zuba.com/api-reference/orders/cancel-an-order.md): Cancels an order only before funding has been received. Once funded, the order is committed to the desk workflow and cannot be cancelled. Retrying a successful cancel returns the cancelled order.
- [Request an upload URL for a settlement proof of payment](https://docs.zuba.com/api-reference/orders/request-an-upload-url-for-a-settlement-proof-of-payment.md): Returns a short-lived URL to upload the payment confirmation for an order whose settlement has requirements.proofOfPayment=true, plus the key to pass back when submitting the proof. PUT the document (PDF, JPG or PNG) to the URL, then call the submit endpoint.
- [Submit an uploaded proof of payment for a settlement](https://docs.zuba.com/api-reference/orders/submit-an-uploaded-proof-of-payment-for-a-settlement.md): Attaches the uploaded payment confirmation to the order settlement when requirements.proofOfPayment=true and starts funding confirmation. Once the transfer is confirmed the order moves to funds_received and an order.funds_received webhook is sent. Re-submitting after confirmation has started is a no…
- [List all webhook endpoints](https://docs.zuba.com/api-reference/webhooks/list-all-webhook-endpoints.md): Deprecated: use GET /v2/webhooks for bounded opaque cursor pagination.
- [Create a webhook endpoint](https://docs.zuba.com/api-reference/webhooks/create-a-webhook-endpoint.md)
- [Get a webhook endpoint](https://docs.zuba.com/api-reference/webhooks/get-a-webhook-endpoint.md)
- [Update a webhook endpoint](https://docs.zuba.com/api-reference/webhooks/update-a-webhook-endpoint.md)
- [Delete a webhook endpoint](https://docs.zuba.com/api-reference/webhooks/delete-a-webhook-endpoint.md)
- [Rotate the signing secret for a webhook endpoint](https://docs.zuba.com/api-reference/webhooks/rotate-the-signing-secret-for-a-webhook-endpoint.md)
- [Send a test webhook event to this endpoint](https://docs.zuba.com/api-reference/webhooks/send-a-test-webhook-event-to-this-endpoint.md)
- [List delivery attempts for a webhook endpoint](https://docs.zuba.com/api-reference/webhooks/list-delivery-attempts-for-a-webhook-endpoint.md): Deprecated: use GET /v2/webhooks/:id/deliveries for opaque cursor pagination.
- [Get a single webhook delivery (includes payload)](https://docs.zuba.com/api-reference/webhooks/get-a-single-webhook-delivery-includes-payload.md)
- [Re-send a failed webhook delivery](https://docs.zuba.com/api-reference/webhooks/re-send-a-failed-webhook-delivery.md): Sends the stored payload of a failed delivery to the endpoint again: the same event id and, on payout events, the same sequence, under a fresh signature and timestamp. The delivery returns to pending and is retried on the normal schedule. Only a delivery whose status is failed can be re-sent.

## OpenAPI Specs

- [openapi](/openapi.json)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.