> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ledig.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Confirm a quote

> Start the conversion or payment described by a quote.

**Required scope:** `transfers:write`

For a new transfer, use a pending, unexpired quote belonging to your business and keep enough available funds to cover it. This endpoint does not use Idempotency-Key. Save the quoteId and any reference you sent. After a timeout, retry with those same values and a fresh signature and timestamp. Once your credentials and business access are checked, a retry matching an existing quoteId or reference returns the original transfer. A reused reference with a new quoteId returns the original transfer and leaves the new quote unused. A reused quoteId with a new reference returns the original transfer without saving the new reference. If quoteId and reference identify different existing transfers, the response is 409 IDEMPOTENCY\_CONFLICT. Concurrent retries do not create another transfer. A new quoteId with an unused reference, or without a reference, starts a new request. HTTP 201 means the request was accepted, not that funds were delivered. replayed=false identifies a new transfer; replayed=true identifies the original transfer returned without another payment. Follow GET /v1/transfers/{id} for the current outcome.


## OpenAPI

````yaml /openapi/public.yaml post /v1/transfers
openapi: 3.1.0
info:
  title: Ledig payments API
  version: 0.1.0
  description: >-
    Use the Ledig payments engine to receive funds, view balances, convert
    currencies and send payments.


    Choose Sandbox to test your integration or Live for production payments.
    Each endpoint explains the fields, permissions and errors you need to
    handle.


    Sign API requests with your business API key and HMAC-SHA256. Endpoints
    listing BearerAuth also accept a user access token. Follow
    https://docs.ledig.io/auth/authentication to sign your requests.
  contact:
    name: Ledig
    email: support@ledig.io
    url: https://docs.ledig.io
servers:
  - url: https://api-sandbox.ledig.io
    description: Sandbox
  - url: https://api.ledig.io
    description: Live
security:
  - LedigApiKey: []
    LedigTimestamp: []
    LedigSignature: []
tags:
  - name: Managed businesses
    description: Onboarding for businesses you manage.
  - name: System
    description: Health and availability.
  - name: Balances
    description: Your available and reserved funds by currency.
  - name: Currencies and rates
    description: Supported currencies, networks and indicative rates.
  - name: Funding accounts
    description: Fiat accounts that receive customer deposits.
  - name: Deposit wallets
    description: Crypto addresses that receive customer deposits.
  - name: Recipients
    description: Saved payout destinations.
  - name: Ledig businesses
    description: Find a business before paying through the Ledig network.
  - name: Payment options
    description: Available payout methods, fees and limits.
  - name: Quotes
    description: Confirm rates, fees and amounts before sending.
  - name: Transfers
    description: Start and track conversions and payments.
  - name: Transactions
    description: Customer transaction history.
paths:
  /v1/transfers:
    post:
      tags:
        - Transfers
      summary: Confirm a quote
      description: Start the conversion or payment described by a quote.
      operationId: createTransfer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required:
                - quoteId
              properties:
                quoteId:
                  type: string
                reference:
                  type: string
                  maxLength: 64
            example:
              quoteId: quote_example_001
              reference: invoice-example-001
      responses:
        '201':
          description: >-
            Transfer created or the original transfer recovered. Acceptance does
            not mean payment completion.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Success'
                  - type: object
                    required:
                      - data
                      - replayed
                    properties:
                      replayed:
                        type: boolean
                        description: >-
                          True when the original resource is returned without
                          creating another operation.
                      data:
                        $ref: '#/components/schemas/ClientTransfer'
              example:
                status: success
                data:
                  id: transfer_example_001
                  profileId: profile_example_001
                  reference: invoice-example-001
                  sourceCurrency: USDT
                  destinationCurrency: USD
                  sourceAmount: '100.00'
                  destinationAmount: '100.00'
                  rate: '1.00'
                  createdAt: '2026-01-15T10:00:00.000Z'
                  updatedAt: '2026-01-15T10:00:00.000Z'
                  feeAmount: '0.50'
                  feeCurrency: USDT
                  sourceDebitAmount: '100.50'
                  payoutFeeAmount: '0'
                  payoutFeeCurrency: USD
                  payoutFeeSourceAmount: '0'
                  totalFeeAmount: '0.50'
                  totalFeeCurrency: USDT
                  totalSourceDebitAmount: '100.50'
                  meta:
                    rate:
                      product: USDTUSD
                      sourceCurrency: USDT
                      destinationCurrency: USD
                      rate: '1.00'
                      side: sell
                      type: fixed
                  quoteId: quote_example_001
                  status: processing
                  failureReason: null
                  events:
                    - eventType: created
                      sourceId: null
                      status: pending
                      createdAt: '2026-01-15T10:00:00.000Z'
                      updatedAt: '2026-01-15T10:00:00.000Z'
                      meta: {}
                  customerPresentation:
                    status: processing
                    label: Processing
                    message: Your conversion is processing.
                    actionRequired: false
                  balanceImpact:
                    state: on_hold
                    lines:
                      - code: principal
                        currency: USDT
                        amount: '100.00'
                        state: reserved
                      - code: conversion_fee
                        currency: USDT
                        amount: '0.50'
                        state: reserved
                replayed: false
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          description: >-
            IDEMPOTENCY_CONFLICT means quoteId and reference identify different
            transfers; the new quote remains unused.
            INSTANT_CONVERSION_LIMIT_EXCEEDED includes your daily or monthly
            allowance details. Resolve the original request's outcome before
            creating a replacement quote.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                status: error
                code: CONFLICT
                message: The request conflicts with the current state of this resource.
        '422':
          description: >-
            The payout exceeds your business's per-payment or monthly allowance,
            measured in USD equivalent. The payment is not sent and the quote is
            not used. Read GET /v1/balances/summary and the error details for
            the limit, remaining allowance and reset time where applicable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PayoutUsdLimitExceededError'
              examples:
                transactionLimit:
                  value:
                    status: error
                    code: PAYOUT_TRANSACTION_LIMIT_EXCEEDED
                    message: >-
                      This payment exceeds your account limit per payment,
                      measured in USD equivalent.
                monthlyLimit:
                  value:
                    status: error
                    code: PAYOUT_MONTHLY_LIMIT_EXCEEDED
                    message: >-
                      This payment exceeds your account remaining monthly
                      allowance, measured in USD equivalent.
        '423':
          description: >-
            COMPLIANCE_REVIEW_REQUIRED: this payment needs review before it can
            proceed. Check its status or contact support@ledig.io.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                status: error
                code: COMPLIANCE_REVIEW_REQUIRED
                message: This action requires a review before it can continue.
        '429':
          $ref: '#/components/responses/RateLimited'
        '503':
          description: >-
            A service required to start the payment is temporarily unavailable.
            RATE_AUTHORITATIVE_STORE_UNAVAILABLE means the USD equivalent needed
            to check your payment allowance could not be calculated; the
            transfer is not created and the quote remains unused.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                required:
                  - status
                  - code
                  - message
                properties:
                  status:
                    type: string
                    const: error
                  code:
                    type: string
                  message:
                    type: string
              example:
                status: error
                code: RATE_AUTHORITATIVE_STORE_UNAVAILABLE
                message: A current indicative USD valuation is unavailable.
      x-codeSamples:
        - lang: javascript
          label: Node.js
          source: >-
            import { createHmac } from "node:crypto";


            // Node.js 18+. Set credentials and resource values on your server.

            function required(name) {
              const value = process.env[name];
              if (!value) throw new Error(`Set ${name} before running this example.`);
              return value;
            }


            const baseUrl = process.env.LEDIG_API_BASE_URL ??
            "https://api-sandbox.ledig.io";

            const method = "POST";

            const path = `/v1/transfers`;

            const pathWithQuery = path;

            const body = {
              "quoteId": required("LEDIG_QUOTE_ID"),
              "reference": required("LEDIG_REFERENCE")
            };

            const rawBody = JSON.stringify(body);

            const headers = { "Accept": "application/json" };

            headers["Content-Type"] = "application/json";

            const timestamp = Math.floor(Date.now() / 1000).toString();

            const payload =
            `${timestamp}.${method}.${pathWithQuery}.${rawBody}`;

            headers["x-ledig-key"] = required("LEDIG_API_KEY");

            headers["x-ledig-timestamp"] = timestamp;

            headers["x-ledig-signature"] = "v1=" + createHmac("sha256",
            required("LEDIG_API_SECRET"))
              .update(payload).digest("base64");

            const response = await fetch(`${baseUrl}${pathWithQuery}`, {
              method,
              headers,
              body: rawBody,
            });

            const result = await response.json();

            // Use result in your application; do not log credentials or upload
            links.

            console.log(response.status);
components:
  schemas:
    Success:
      type: object
      required:
        - status
      properties:
        status:
          type: string
          const: success
        message:
          type: string
    ClientTransfer:
      type: object
      additionalProperties: false
      description: >-
        A transfer's progress and accepted fees. Use balanceImpact, when
        present, to check how funds were debited, reserved or refunded;
        processing status alone does not confirm those balance changes.
      required:
        - id
        - profileId
        - reference
        - sourceCurrency
        - destinationCurrency
        - sourceAmount
        - destinationAmount
        - rate
        - createdAt
        - updatedAt
        - feeAmount
        - feeCurrency
        - sourceDebitAmount
        - payoutFeeAmount
        - payoutFeeCurrency
        - payoutFeeSourceAmount
        - totalFeeAmount
        - totalFeeCurrency
        - totalSourceDebitAmount
        - meta
        - quoteId
        - status
        - failureReason
        - events
        - customerPresentation
      properties:
        id:
          type: string
        profileId:
          type: string
        reference:
          type: string
        sourceCurrency:
          type: string
        destinationCurrency:
          type: string
        sourceAmount:
          type: string
        destinationAmount:
          type: string
        rate:
          type: string
        createdAt:
          type: string
        updatedAt:
          type: string
        feeAmount:
          type: string
        feeCurrency:
          type: string
        sourceDebitAmount:
          type: string
        payoutFeeAmount:
          type: string
        payoutFeeCurrency:
          type: string
        payoutFeeSourceAmount:
          type: string
        totalFeeAmount:
          type: string
        totalFeeCurrency:
          type: string
        totalSourceDebitAmount:
          type: string
        meta:
          $ref: '#/components/schemas/ClientMoneyMeta'
        quoteId:
          type: string
        status:
          type: string
          enum:
            - pending
            - processing
            - completed
            - failed
            - reversed
        failureReason:
          type:
            - string
            - 'null'
          description: >-
            An explanation of why the transfer failed and what you may need to
            do next.
        approval:
          type:
            - object
            - 'null'
          additionalProperties: false
          required:
            - status
            - reason
            - version
          properties:
            status:
              type: string
              enum:
                - pending
                - approved
                - rejected
                - expired
                - executing
            reason:
              type: 'null'
            version:
              type: integer
        events:
          type: array
          items:
            $ref: '#/components/schemas/ClientTransferEvent'
        customerPresentation:
          $ref: '#/components/schemas/TransferCustomerPresentation'
        balanceImpact:
          $ref: '#/components/schemas/ClientBalanceImpact'
    Error:
      type: object
      required:
        - status
        - message
        - code
      properties:
        status:
          type: string
          const: error
        message:
          type: string
        code:
          type: string
        details:
          description: >-
            Additional information to help resolve an error, such as a file
            problem, allowed amount range or remaining payment allowance. The
            fields depend on the error code.
          oneOf:
            - type: object
              additionalProperties: false
              description: >-
                File-validation details returned with HTTP 400, 413 or 422
                BAD_REQUEST.
              required:
                - validationCode
                - reasonCode
                - retryable
              properties:
                validationCode:
                  type: string
                  enum:
                    - document_unreadable
                    - document_type_mismatch
                    - document_password_protected
                    - document_limits_exceeded
                reasonCode:
                  type: string
                  enum:
                    - document_unreadable
                    - document_type_mismatch
                    - document_password_protected
                    - document_limits_exceeded
                retryable:
                  type: boolean
                  const: false
                documentId:
                  type: string
                  maxLength: 128
                requirementType:
                  type: string
                maxSizeBytes:
                  type: integer
                  minimum: 1
                  maximum: 1073741824
                  description: >-
                    Maximum accepted file size in bytes, when supplied with HTTP
                    413.
            - type: object
              additionalProperties: false
              required:
                - reason
              properties:
                reason:
                  type: string
                  enum:
                    - current_password_incorrect
                    - unsupported_asset_network
                    - recipient_unavailable
                    - recipient_incompatible
                    - payout_method_unavailable
                    - payout_method_incompatible
                    - network_unavailable
                    - quote_expired
                    - quote_already_used
                    - quote_changed
                    - invoice_required
                    - invoice_invalid
                    - amount_invalid
                    - amount_precision_invalid
                    - onboarding_revision_required
                    - onboarding_revision_changed
                    - onboarding_document_kind_mismatch
                precision:
                  type: integer
                  minimum: 0
                  maximum: 18
                  description: >-
                    Allowed number of decimal places when reason is
                    amount_precision_invalid.
            - type: object
              additionalProperties: false
              required:
                - period
                - sourceCurrency
                - requested
                - remaining
                - limit
                - resetsAt
                - timezone
              properties:
                period:
                  type: string
                  enum:
                    - daily
                    - monthly
                sourceCurrency:
                  type: string
                  pattern: ^[A-Z][A-Z0-9]{1,19}$
                requested:
                  type: string
                  pattern: ^(0|[1-9][0-9]*)(\.[0-9]+)?$
                remaining:
                  type: string
                  pattern: ^(0|[1-9][0-9]*)(\.[0-9]+)?$
                limit:
                  type: string
                  pattern: ^(0|[1-9][0-9]*)(\.[0-9]+)?$
                resetsAt:
                  type: string
                  format: date-time
                timezone:
                  type: string
                  const: UTC
            - type: object
              additionalProperties: false
              required:
                - sourceCurrency
                - minimumAmount
                - maximumAmount
              properties:
                sourceCurrency:
                  type: string
                minimumAmount:
                  type: string
                maximumAmount:
                  type: string
              description: >-
                Returned with HTTP 422 RATE_ROUTE_AMOUNT_OUT_OF_RANGE. These
                limits apply to the amount being converted, in the source
                currency.
            - type: object
              additionalProperties: false
              required:
                - currency
                - requestedUsd
                - limitUsd
              properties:
                currency:
                  type: string
                  const: USD
                requestedUsd:
                  type: string
                limitUsd:
                  type: string
              description: >-
                Returned with HTTP 422 PAYOUT_TRANSACTION_LIMIT_EXCEEDED. This
                per-payment limit uses USD equivalent and is separate from the
                payout method's currency limits.
            - type: object
              additionalProperties: false
              required:
                - currency
                - requestedUsd
                - remainingUsd
                - resetsAt
                - timezone
              properties:
                currency:
                  type: string
                  const: USD
                requestedUsd:
                  type: string
                remainingUsd:
                  type: string
                resetsAt:
                  type: string
                  format: date-time
                timezone:
                  type: string
                  const: UTC
              description: >-
                Returned with HTTP 422 PAYOUT_MONTHLY_LIMIT_EXCEEDED. Shows your
                business's remaining monthly allowance and when it resets.
    PayoutUsdLimitExceededError:
      type: object
      additionalProperties: false
      required:
        - status
        - code
        - message
      properties:
        status:
          type: string
          const: error
        code:
          type: string
          enum:
            - PAYOUT_TRANSACTION_LIMIT_EXCEEDED
            - PAYOUT_MONTHLY_LIMIT_EXCEEDED
        message:
          type: string
    ClientMoneyMeta:
      type: object
      additionalProperties: false
      description: The pricing and payment instructions accepted for this transaction.
      properties:
        rate:
          type: object
          additionalProperties: false
          required:
            - product
            - sourceCurrency
            - destinationCurrency
            - rate
            - side
            - type
          properties:
            product:
              type: string
            sourceCurrency:
              type: string
            destinationCurrency:
              type: string
            rate:
              type: string
            side:
              type: string
              enum:
                - buy
                - sell
            type:
              type: string
              const: fixed
        payIn:
          type: object
          additionalProperties: false
          description: >-
            Receiving instructions accepted for this transaction. New
            temporary_bank_account requests are not supported.
          required:
            - type
          properties:
            type:
              type: string
              const: temporary_bank_account
        payOut:
          type: object
          additionalProperties: false
          description: The accepted destination and instructions for the payout.
          required:
            - type
            - paymentMethodId
          properties:
            paymentMethodId:
              type: string
            chain:
              type: string
            narration:
              type: string
            transferPurpose:
              type: string
            invoiceDocumentId:
              type: string
            recipientId:
              type: string
            businessId:
              type: string
            businessName:
              type: string
            type:
              type: string
              enum:
                - fiat
                - crypto
                - ledig
    ClientTransferEvent:
      type: object
      additionalProperties: false
      description: A transfer progress update and any related payment receipt.
      required:
        - eventType
        - sourceId
        - status
        - createdAt
        - updatedAt
        - meta
      properties:
        eventType:
          type: string
          enum:
            - created
            - conversion
            - withdrawal
        sourceId:
          type:
            - string
            - 'null'
          description: >-
            The payout receipt reference for a withdrawal event. Null for
            created and conversion events.
        status:
          type: string
        createdAt:
          type: string
        updatedAt:
          type: string
        meta:
          type: object
          additionalProperties: false
          properties:
            rate:
              type: object
              additionalProperties: false
              required:
                - product
                - sourceCurrency
                - destinationCurrency
                - rate
                - side
                - type
              properties:
                product:
                  type: string
                sourceCurrency:
                  type: string
                destinationCurrency:
                  type: string
                rate:
                  type: string
                side:
                  type: string
                  enum:
                    - buy
                    - sell
                type:
                  type: string
                  const: fixed
            payIn:
              type: object
              additionalProperties: false
              description: >-
                Receiving instructions accepted for this transaction. New
                temporary_bank_account requests are not supported.
              required:
                - type
              properties:
                type:
                  type: string
                  const: temporary_bank_account
            payOut:
              type: object
              additionalProperties: false
              description: The accepted destination and instructions for the payout.
              required:
                - type
                - paymentMethodId
              properties:
                paymentMethodId:
                  type: string
                chain:
                  type: string
                narration:
                  type: string
                transferPurpose:
                  type: string
                invoiceDocumentId:
                  type: string
                recipientId:
                  type: string
                businessId:
                  type: string
                businessName:
                  type: string
                type:
                  type: string
                  enum:
                    - fiat
                    - crypto
                    - ledig
            payoutDetails:
              type: object
              additionalProperties: false
              properties:
                feeAmount:
                  type: string
                feeCurrency:
                  type: string
                payoutFeeSourceAmount:
                  type: string
                payoutFeeSourceCurrency:
                  type: string
                transactionHash:
                  type: string
                processingState:
                  type: string
                  enum:
                    - awaiting_processing
                    - processing
    TransferCustomerPresentation:
      type: object
      additionalProperties: false
      required:
        - status
        - label
        - message
        - actionRequired
      properties:
        status:
          type: string
          enum:
            - awaiting_processing
            - processing
            - completed
            - failed
            - returned
            - action_required
        label:
          type: string
        message:
          type: string
        actionRequired:
          type: boolean
    ClientBalanceImpact:
      type: object
      additionalProperties: false
      description: >-
        How the transfer affected your balance, shown separately from its
        processing status.
      required:
        - state
        - lines
      properties:
        state:
          type: string
          enum:
            - not_started
            - on_hold
            - deducted
            - hold_released
            - returned
            - still_checking
            - return_pending
            - finishing_completion
        lines:
          type: array
          items:
            type: object
            additionalProperties: false
            required:
              - code
              - currency
              - amount
              - state
            properties:
              code:
                type: string
                enum:
                  - principal
                  - transfer_fee
                  - conversion_fee
                  - converted_principal
              currency:
                type: string
              amount:
                type: string
              state:
                type: string
                enum:
                  - no_effect
                  - reserved
                  - settled
                  - released
                  - returned
                  - late_settled
                  - pending_finalization
                  - pending_return
                  - unknown
  responses:
    BadRequest:
      description: The request is invalid. Check the error message and submitted fields.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            status: error
            code: BAD_REQUEST
            message: Check the request fields and try again.
    Unauthorized:
      description: >-
        Authentication is missing, invalid or expired. Check your credentials
        and request signature.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            status: error
            code: UNAUTHORIZED
            message: Authentication is required.
    Forbidden:
      description: >-
        Your account is inactive, the business selection is missing, or your
        credentials do not have the required permission.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            status: error
            code: FORBIDDEN
            message: You do not have permission to perform this action.
    RateLimited:
      description: >-
        A request or operation allowance has been reached. Wait before retrying.
        If the endpoint uses an idempotency key, keep the same key for the
        retry.
      headers:
        Retry-After:
          description: The number of seconds to wait before retrying.
          schema:
            type: integer
            minimum: 1
        Cache-Control:
          description: >-
            Responses use private, no-store or no-store. Do not cache this
            response.
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            status: error
            code: RATE_LIMITED
            message: Too many requests. Wait before trying again.
  securitySchemes:
    LedigApiKey:
      type: apiKey
      in: header
      name: x-ledig-key
      description: >-
        Your business API key ID. Keep its secret on your server and use that
        secret to sign each request.
    LedigTimestamp:
      type: apiKey
      in: header
      name: x-ledig-timestamp
      description: The current Unix timestamp in seconds, used in the signed request.
    LedigSignature:
      type: apiKey
      in: header
      name: x-ledig-signature
      description: >-
        The request's HMAC-SHA256 signature. Use the v1= prefix for supported
        own-business requests, or v2= when acting for a managed business with
        signed business-selection headers. Follow the authentication guide to
        construct and sign the exact request.

````

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