# 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, and deposit status tracking.
> Use the sandbox (api.sandbox.zuba.com) with its deterministic magic values before touching production.

## Docs

- [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.
- [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.
- [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`.
- [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 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.
- [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.
- [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)
- [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.
- [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.
- [Add a person to an application](https://docs.zuba.com/api-reference/applications-v2/add-a-person-to-an-application.md)
- [Confirm a document upload completed](https://docs.zuba.com/api-reference/applications-v2/confirm-a-document-upload-completed.md)
- [Create a KYB/KYC application](https://docs.zuba.com/api-reference/applications-v2/create-a-kybkyc-application.md)
- [Get an application by id](https://docs.zuba.com/api-reference/applications-v2/get-an-application-by-id.md)
- [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).
- [List persons on an application](https://docs.zuba.com/api-reference/applications-v2/list-persons-on-an-application.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)
- [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)
- [Soft-delete a document](https://docs.zuba.com/api-reference/applications-v2/soft-delete-a-document.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.
- [Update a person](https://docs.zuba.com/api-reference/applications-v2/update-a-person.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)
- [Convert corridors enabled for this client](https://docs.zuba.com/api-reference/conversions/convert-corridors-enabled-for-this-client.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)
- [API Reference](https://docs.zuba.com/api-reference/introduction.md): Complete API reference for the Zuba Payment Platform
- [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.
- [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 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…
- [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 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 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.
- [Cancel an order](https://docs.zuba.com/api-reference/orders/cancel-an-order.md): Cancels an order that has not yet been approved for execution and returns any held funds to your balance. Once the desk has approved execution the order can no longer be cancelled. Retrying a successful cancel returns the cancelled order.
- [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…
- [Get an order by id](https://docs.zuba.com/api-reference/orders/get-an-order-by-id.md)
- [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.
- [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 awaiting funds, 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 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-op.
- [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.
- [List deposits](https://docs.zuba.com/api-reference/pay-ins/list-deposits.md): Deprecated: use GET /v2/deposits for opaque cursor pagination.
- [Resolve a crypto deposit address](https://docs.zuba.com/api-reference/pay-ins/resolve-a-crypto-deposit-address.md): Provision (or return the existing) on-chain deposit address for the requested network. A wallet is created only for the requested network. Send USDT/USDC to the returned address; the deposit is credited once it confirms on-chain. EVM addresses are valid across all EVM chains.
- [Cancel a payout](https://docs.zuba.com/api-reference/payouts/cancel-a-payout.md): Cancel a pending payout transaction
- [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 any submitted account (IBAN or NGN crAccount+bankCode) matches an existing active beneficiary for this client, the existing beneficiary is returned unchanged instead of creating a duplicate.
- [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 beneficiary by ID](https://docs.zuba.com/api-reference/payouts/get-beneficiary-by-id.md): Retrieve a specific beneficiary and their account details
- [Get beneficiary field requirements for a currency](https://docs.zuba.com/api-reference/payouts/get-beneficiary-field-requirements-for-a-currency.md): Returns required and optional beneficiary fields based on destination currency. Aggregates requirements across all providers that support the currency.
- [Get payout by ID](https://docs.zuba.com/api-reference/payouts/get-payout-by-id.md): Retrieve details of a specific payout transaction
- [List all beneficiaries](https://docs.zuba.com/api-reference/payouts/list-all-beneficiaries.md): Deprecated: use GET /v2/beneficiaries for bounded opaque cursor pagination.
- [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).
- [List payouts](https://docs.zuba.com/api-reference/payouts/list-payouts.md): Deprecated: use GET /v2/payouts for opaque cursor pagination.
- [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)
- [Update beneficiary](https://docs.zuba.com/api-reference/payouts/update-beneficiary.md): Update an existing beneficiary's information
- [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 / USD-source / same-currency quote (the corridor picks the engine), and 'convert' prices an in-wallet conversion between the caller's own balances (specifying the source `amo…
- [Get a quote by ID](https://docs.zuba.com/api-reference/quotes/get-a-quote-by-id.md)
- [Create a webhook endpoint](https://docs.zuba.com/api-reference/webhooks/create-a-webhook-endpoint.md)
- [Delete a webhook endpoint](https://docs.zuba.com/api-reference/webhooks/delete-a-webhook-endpoint.md)
- [Get a single webhook delivery (includes payload)](https://docs.zuba.com/api-reference/webhooks/get-a-single-webhook-delivery-includes-payload.md)
- [Get a webhook endpoint](https://docs.zuba.com/api-reference/webhooks/get-a-webhook-endpoint.md)
- [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.
- [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.
- [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)
- [Update a webhook endpoint](https://docs.zuba.com/api-reference/webhooks/update-a-webhook-endpoint.md)
- [Authentication](https://docs.zuba.com/authentication.md): Learn how to authenticate with the Zuba API using OAuth 2.0
- [Ledger System](https://docs.zuba.com/concepts/ledger.md): Double-entry bookkeeping and transaction management
- [Platform Overview](https://docs.zuba.com/concepts/overview.md): Understanding the Zuba Payment Platform architecture
- [Payins](https://docs.zuba.com/concepts/payins.md): Fund your Zuba balance with bank transfers and crypto deposits
- [Payouts](https://docs.zuba.com/concepts/payouts.md): Send money globally with Zuba payouts
- [Batch Payouts](https://docs.zuba.com/guides/batch-payouts.md): Process multiple payouts efficiently with batch operations
- [Error Handling](https://docs.zuba.com/guides/error-handling.md): Handle errors and edge cases gracefully in your payment integration
- [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
- [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
- [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
- [Webhook Notifications](https://docs.zuba.com/guides/webhooks.md): Set up real-time notifications for payment events using webhooks
- [Introduction](https://docs.zuba.com/introduction.md): Zuba Payment Platform API — global payouts, payment acceptance, and multi-currency operations
- [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
- [Quickstart](https://docs.zuba.com/quickstart.md): Start building with Zuba in under 5 minutes
- [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

## OpenAPI Specs

- [openapi](https://docs.zuba.com/openapi.json)