> ## Documentation Index > Fetch the complete documentation index at: https://docs.zuba.com/llms.txt > Use this file to discover all available pages before exploring further. > ## 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. # Create an order from an order-intent quote; idempotent > 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 on the order. When the `Zuba-Account-Id` header names one of your sub-accounts, the order is created for that sub-account and funds from its balance. ## OpenAPI ````yaml /openapi.json post /v1/orders openapi: 3.0.0 info: contact: {} description: >- Comprehensive payment platform API supporting fiat and crypto payments, currency conversion, and compliance management title: Zuba Payment Platform API version: '1.0' servers: [] security: [] tags: - description: Manage M2M API keys and credentials name: API Keys - description: Internal ledger accounts and transactions name: Ledger - description: Handle incoming payments and deposits name: Pay-ins - description: Manage payouts, beneficiaries, and SEPA transfers name: Payouts - description: Manage outbound webhook endpoints and deliveries name: Webhooks paths: /v1/orders: post: tags: - Orders summary: Create an order from an order-intent quote; idempotent description: >- 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 on the order. When the `Zuba-Account-Id` header names one of your sub-accounts, the order is created for that sub-account and funds from its balance. operationId: OrderController_createOrder parameters: - description: Client-generated idempotency key (UUID) in: header name: Idempotency-Key required: true schema: type: string - description: >- Optional. Names an owned sub-account (UUID) to create the order for: the order funds from that sub-account's balance and carries its accountId. Omit to act at the master (tenant) level. Naming an account this key does not own returns 403 not_account_owner. in: header name: Zuba-Account-Id required: false schema: format: uuid type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateOrderDto' required: true responses: '201': content: application/json: schema: $ref: '#/components/schemas/OrderResponseDto' description: '' '400': content: application/json: schema: $ref: '#/components/schemas/GenericErrorResponseDto' description: >- Missing Idempotency-Key, unknown/expired/mismatched quote, unknown beneficiary, unsupported corridor, or malformed Zuba-Account-Id '403': content: application/json: schema: oneOf: - $ref: '#/components/schemas/GenericErrorResponseDto' - $ref: '#/components/schemas/PaymentsNotEnabledErrorResponseDto' description: >- insufficient_scope (missing create:orders), Insufficient role (workspace viewers cannot act on orders), not_account_owner (Zuba-Account-Id does not name an account you own), or payments_not_enabled (the client is not payments-enabled) '409': content: application/json: schema: $ref: '#/components/schemas/GenericErrorResponseDto' description: CLIENT_REF_ALREADY_USED '422': content: application/json: schema: $ref: '#/components/schemas/GenericErrorResponseDto' description: >- INSUFFICIENT_BALANCE, transaction limit exceeded, or ACCOUNT_NOT_ACTIVE (the sub-account is not active) security: - bearer: [] components: schemas: CreateOrderDto: properties: beneficiaryId: description: >- Id of the saved beneficiary to deliver to. The beneficiary must hold an active account in the quote target currency. example: cc82fa1d-fc7a-478c-a734-d3bce40464e7 format: uuid type: string clientRef: description: >- Client-supplied reference, unique per client. Surfaces on the order and ledger history. example: ORD-2026-0001 maxLength: 100 type: string purpose: description: Free-text purpose of the order. example: Supplier settlement type: string quotationId: description: >- Id of the order-intent quote to execute (from POST /v1/quotes with intent 'order'). Single-use; the order must be created within the quote's TTL. example: 550e8400-e29b-41d4-a716-446655440000 format: uuid type: string required: - quotationId - beneficiaryId type: object OrderResponseDto: properties: accountId: description: >- Owning sub-account; present when the order was created in a sub-account context (`Zuba-Account-Id` header). Absent = the order belongs to your master account. format: uuid type: string beneficiaryId: description: Beneficiary id format: uuid type: string clientRef: description: Client-supplied reference type: string completedAt: description: When the order completed (ISO 8601) type: string createdAt: description: Creation time (ISO 8601) type: string executionDeadlineAt: description: Desk execution deadline, set when funds are received (ISO 8601) type: string failureReason: description: Fixed failure code; present only when status is failed enum: - execution_failed - review_expired type: string fromAmount: description: Total source debit, in fromCurrency (decimal string) example: '1006.5000' type: string fromCurrency: description: Funded (source) currency example: USDT type: string fundedAt: description: When funds were received (ISO 8601) type: string fundingDeadlineAt: description: >- Deadline for funds to be attributed to the order before it expires (ISO 8601) type: string id: description: Order id format: uuid type: string purpose: description: Free-text purpose type: string quoteId: description: Consumed quote id format: uuid type: string rate: description: 'All-in rate: fromCurrency per 1 toCurrency' example: '0.00067100' type: string settlement: allOf: - $ref: '#/components/schemas/OrderSettlementDto' description: >- Funding instructions; present when the order is (or was) settlement-funded rather than balance-funded status: description: Order lifecycle status enum: - created - awaiting_funds - funds_received - executing - completed - failed - expired - cancelled type: string toAmount: description: Amount delivered, in toCurrency (decimal string) example: '1500000.0000' type: string toCurrency: description: Delivered (target) currency example: NGN type: string uetr: description: >- Outbound wire reference (UETR); present once the order completes over a wire rail type: string updatedAt: description: Last update time (ISO 8601) type: string required: - id - quoteId - beneficiaryId - status - fromCurrency - toCurrency - fromAmount - toAmount - rate - fundingDeadlineAt - createdAt - updatedAt type: object GenericErrorResponseDto: properties: error: description: Error type identifier example: BAD_REQUEST type: string message: description: Error message example: Bad Request type: string path: description: Request path that generated the error example: /v1/beneficiaries type: string statusCode: description: HTTP status code example: 400 type: number timestamp: description: ISO timestamp when the error occurred example: '2024-01-15T10:30:00.000Z' type: string required: - statusCode - message - error - timestamp - path type: object PaymentsNotEnabledErrorResponseDto: properties: detail: description: Human-readable action required to enable payments example: >- Payments are not enabled. Complete merchant verification to activate payments. type: string error: description: Stable lowercase discriminator for new integrations example: payments_not_enabled type: string message: description: Stable legacy discriminator retained for v1 clients example: PAYMENTS_NOT_ENABLED type: string path: description: Request path that generated the error example: /v1/beneficiaries type: string statusCode: description: HTTP status code example: 400 type: number timestamp: description: ISO timestamp when the error occurred example: '2024-01-15T10:30:00.000Z' type: string required: - statusCode - message - error - timestamp - path - detail type: object OrderSettlementDto: properties: currency: description: Currency of the transfer example: XOF type: string expiresAt: description: When the funding window closes (ISO 8601) type: string instructions: additionalProperties: true description: >- Funding instructions: bank account fields (virtual_account) or deposit addresses per network (wallet_address) type: object method: description: >- Funding method: bank transfer to the account in the instructions, or a crypto transfer to your deposit address enum: - virtual_account - wallet_address type: string reference: description: >- Settlement reference. On fiat (virtual_account) settlements, include it in the transfer narration or wire memo wherever the rail supports one: narration-passing rails attribute the payment automatically, and it speeds up manual review everywhere else. When requirements.proofOfPayment is true, the proof submission is also required. Crypto (wallet_address) settlements attribute by receiving address alone: a reference cannot be attached to an on-chain transfer, so keep it purely as a support identifier. example: SETTLE-4F7A2C91B0 type: string requiredAmount: description: >- Exact amount to transfer, in currency (decimal string). When requirements.proofOfPayment is true, upload payment evidence after the transfer. On bank rails that pass the transfer narration through, a transfer carrying the settlement reference attributes at any amount (a short payment sits on your balance until topped up, an overpayment attributes with the excess left on your balance); without the reference, only a transfer of exactly this amount auto-matches and others are attributed manually. example: '1006.5000' type: string requirements: description: >- Actions required after making the transfer. proofOfPayment is true only when the resolved receiving rail requires payment evidence for that deposit. Do not infer this from currency or settlement method. example: proofOfPayment: true type: object settlementId: description: Settlement id format: uuid type: string status: description: Settlement state enum: - open - matched - expired type: string required: - settlementId - method - requiredAmount - currency - reference - status - requirements - instructions - expiresAt type: object securitySchemes: bearer: bearerFormat: JWT description: Enter Auth0 JWT token scheme: bearer type: http ````