> ## 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, application, and virtual-account status tracking. > Use the sandbox (api.sandbox.zuba.com) with its deterministic magic values before touching production. # Execute a conversion (consume a quote) ## OpenAPI ````yaml /openapi.json post /v1/conversions 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: Per-country bank directories and bank-account enquiries name: Banks - 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/conversions: post: tags: - Conversions summary: Execute a conversion (consume a quote) operationId: ConversionsController_execute parameters: - description: A repeat returns the original conversion result. in: header name: Idempotency-Key required: false schema: type: string - description: >- Optional. Names an owned sub-account (UUID) to convert as: the conversion debits and credits that sub-account's own balance, never the master's, and only a quote minted with the same Zuba-Account-Id can be spent (any other quote returns 400 QUOTE_NOT_FOUND). A sub-account that is not active returns 422 ACCOUNT_NOT_ACTIVE. Omit to convert on the master (tenant) balance, spending any quote of the master and its sub-accounts. 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/ExecuteConversionDto' required: true responses: '201': content: application/json: schema: $ref: '#/components/schemas/ConversionResponseDto' description: >- The executed conversion: completed, or pending while the institution holding both sides of the pair executes it, after which it reads completed, or failed with the source debit returned to the source balance. '400': description: >- QUOTE_NOT_FOUND | QUOTE_EXPIRED | INSUFFICIENT_BALANCE | QUOTE_INTENT_MISMATCH | AMOUNT_OUT_OF_BOUNDS | CONVERSIONS_DISABLED (your policy switched conversions off after the quote was minted) (QUOTE_EXPIRED also means where the cash on the two sides of the pair is held changed after the quote was minted; re-quote) (ceiling breaches carry details: { maxCad, maxUsd }; INSUFFICIENT_BALANCE also carries code INSUFFICIENT_BALANCE and a display detail). A malformed Zuba-Account-Id also returns 400. '403': content: application/json: schema: anyOf: - $ref: '#/components/schemas/GenericErrorResponseDto' - $ref: '#/components/schemas/PaymentsNotEnabledErrorResponseDto' description: >- Insufficient role, API key missing the create:conversions scope, not_account_owner (Zuba-Account-Id does not name an account you own), or payments_not_enabled (Zuba-Account-Id names a sub-account and the client is not payments-enabled). '409': description: QUOTE_ALREADY_USED '422': description: >- POSITION_LIMIT_EXCEEDED | transaction_limit_exceeded | IDEMPOTENCY_KEY_REUSED | ACCOUNT_NOT_ACTIVE (the sub-account Zuba-Account-Id names is not active, or the account holding your cash for one side of the pair was frozen after the quote was minted; nothing is booked) | FUNDING_ACCOUNT_AMBIGUOUS (your cash in one side of the pair is held at more than one institution; nothing is booked) security: - bearer: [] components: schemas: ExecuteConversionDto: properties: quoteId: description: Id of the firm convert quote to execute example: 550e8400-e29b-41d4-a716-446655440000 type: string required: - quoteId type: object ConversionResponseDto: properties: accountId: description: >- Owning sub-account; present when the conversion was made in a sub-account context (`Zuba-Account-Id` header) and booked on that sub-account's balance. Absent = the conversion booked on your master account. format: uuid type: string createdAt: description: Created at (ISO 8601) type: string fee: description: >- Per-conversion fee charged on the source leg, in feeCurrency, as locked on the quote: the greater of the basis-point charge and the fixed floor from your pricing, "0.0000" when your pricing carries none. Part of the source amount, not added to it. example: '0.0000' type: string feeCurrency: description: Fee currency example: USD type: string id: description: Conversion id example: uuid type: string rate: description: 'All-in rate applied: source units per 1 target unit' example: '1.09860000' type: string sourceAmount: description: Debited from the source balance example: '500.0000' type: string sourceCurrency: description: Source currency example: USD type: string status: description: >- pending while the conversion is in flight, with the source amount already debited; completed once the target amount is credited; failed when nothing was converted and the source amount is back on the source balance enum: - completed - failed - pending example: completed type: string targetAmount: description: Credited to the target balance example: '455.1200' type: string targetCurrency: description: Target currency example: EUR type: string required: - id - sourceCurrency - targetCurrency - sourceAmount - targetAmount - rate - fee - feeCurrency - status - createdAt 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/resource 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/resource 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 securitySchemes: bearer: bearerFormat: JWT description: Enter Auth0 JWT token scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.