---
title: "Create a fiat payout"
method: POST
path: "/v2/payouts"
tags: ["Payouts"]
---

# Create a fiat payout

`POST /v2/payouts`

Creates and immediately starts a payout using a valid quote. Requires `payout.write` permission. The payout does not enter the dashboard approval workflow.

`quote_id` binds the provider, destination snapshot, source and destination currencies, payout rail, amount mode, fee responsibility, exchange rate, amounts, and fee breakdown. Do not repeat those fields in this request.

This operation performs the authoritative pre-execution checks, including API-key ownership and permissions, quote ownership and expiry, request-to-quote consistency, account and destination validation, compliance controls, limits, available balance, execution-provider availability, and idempotency.

`client_reference_id` must uniquely identify one logical payout within the authenticated organization. Retrying the same business request returns the existing payout with `is_duplicate=true`. Reusing the value with different request data returns a conflict.

A successful response means the payout was accepted and bank execution started. It does not mean the receiving bank has credited the account. Use `GET /v2/payouts/{payout_id}` to obtain the latest state.

Only one payout submission per organization can enter execution at a time. A concurrent submission is rejected with `108015 payout_submission_in_progress` before the quote is consumed, a payout is created, or the balance is debited. Retry after a short randomized delay and keep the same `client_reference_id` for the same logical payout.

## Headers

- `Date` string
- `Authorization` string
- `Digest` string

## Request body

- CreatePayoutRequest
  - `client_reference_id` string, required — Merchant-scoped idempotency and reconciliation reference for one logical payout.
  - `quote_id` string, required — Unexpired quote owned by the authenticated organization. It binds the destination, amounts, fee responsibility, provider, rail, and pricing.
  - `purpose_code` string, required — Business purpose code accepted for the payout corridor.
  - `statement_reference` string — Reference displayed to the recipient when supported by the bank rail.

## Response `200`

Payout created or an idempotent existing payout returned

- PayoutEnvelope
  - `code` 0, required — Business code. `0` means success.
  - `message` string, required — Response message.
  - `data` Payout, required
    - `payout_id` string, required — Infini fiat payout ID.
    - `client_reference_id` string, required — Merchant-provided payout reconciliation reference.
    - `quote_id` string, required — Quote used to create the payout.
    - `provider` 'sgb', required — Execution provider selected by Infini.
    - `status` 'processing' | 'completed' | 'failed', required — Current payout lifecycle state. A receiving-bank return does not change a completed payout's status; inspect the `return` object for the compensating refund. API payouts have no approval-pending state.
    - `payout_type` 'swift', required — Payout rail bound by the quote.
    - `source_currency` 'USD', required — Organization balance currency.
    - `destination_currency` 'USD', required — Currency delivered to the recipient.
    - `destination_country` string, required — Destination country as an ISO 3166-1 alpha-2 code.
    - `amount_mode` 'send' | 'receive', required — Side fixed by the accepted quote.
    - `fee_paid_by` 'PAYER' | 'BENEFICIARY', required — Party responsible for payout fees. `PAYER` means external deduction; `BENEFICIARY` means internal deduction. Persisted for statement reconciliation.
    - `sending_amount` string, required — Actual total source-balance debit. This is also the authoritative outgoing statement amount.
    - `receiving_amount` string, required — Amount delivered to the recipient.
    - `transfer_fee_amount` string, required — Infini service fee frozen by the quote. It excludes any bank or rail fee.
    - `bank_fee_amount` string, required — Banking fee for the selected bank and payout rail frozen by the quote. Rail examples include SWIFT, ACH, and wire.
    - `fee_rate_decimal` string, required — Decimal transfer-fee rate frozen by the quote.
    - `rate` string, required — Exchange rate frozen by the quote.
    - `billing` BillingBreakdown, required
      - `currency` 'USD', required — Currency used by all billing amounts.
      - `transfer_fee` string, required — Infini service fee for processing the payout. It does not include any bank or rail fee.
      - `fx_fee` string, required — Foreign-exchange fee. It is `0.00` for the current USD-to-USD route.
      - `rail_fee` string, required — Banking fee associated with the selected bank and payout rail.
      - `total_fee` string, required — Sum of all fee components in the billing breakdown.
      - `fee_lines` FeeLine[], required — Itemized fee components used for reconciliation.
        - `type` 'transfer_fee' | 'fx_fee' | 'rail_fee', required — Fee component type.
        - `amount` string, required — Fee component amount in `currency`.
        - `currency` 'USD', required — Fee component currency.
        - `rate` string, required — Decimal rate used for this fee line, or `1` for a fixed rail fee.
    - `destination` BankDestinationView, required
      - `type` 'bank_account', required — Destination type.
      - `account_holder_type` 'individual' | 'business', required — Legal type of the bank-account holder.
      - `account_holder_name` string, required — Full legal name registered on the bank account.
      - `bank_country` string, required — Bank country as an ISO 3166-1 alpha-2 code.
      - `bank_name` string, required — Receiving bank's legal name.
      - `account_number_masked` string, required — Masked account number. Raw account details are never returned.
      - `swift_code` string, required — Receiving bank SWIFT/BIC code.
    - `purpose_code` string, required — Business purpose supplied at creation.
    - `statement_reference` string, nullable, required — Recipient-facing reference when supported.
    - `bank_reference` string, nullable, required — Bank transfer reference when available.
    - `failure` Failure, nullable, required — Failure details when the payout could not be completed; otherwise null.
      - `code` string, required — Stable machine-readable payout failure code.
      - `message` string, required — Human-readable payout failure details.
    - `return` PayoutReturn, nullable, required — Compensating refund created after a receiving bank returns a completed payout; otherwise null. The original payout remains `completed`.
      - `status` 'refunded', required — Settlement state of the compensating refund.
      - `reason_code` 'recipient_bank_rejected', required — Stable machine-readable reason for the bank return.
      - `reason` string, required — Human-readable bank-return reason when supplied by the banking partner.
      - `returned_amount` string, required — Amount the banking partner reported as returned.
      - `refund_amount` string, required — Amount actually credited back to the organization's balance after retained fees.
      - `retained_fee` string, required — Original payout fee retained and not included in `refund_amount`.
      - `currency` 'USD', required — Currency of the return, refund, and retained-fee amounts.
      - `returned_at` integer, required — Time the compensating refund was recorded, as Unix seconds.
    - `is_duplicate` boolean, required — Whether this response was produced by an idempotent create retry.
    - `created_at` integer, required — Payout creation time as Unix seconds.
    - `updated_at` integer, required — Payout last-update time as Unix seconds.
    - `completed_at` integer, nullable, required — Time the banking partner reported payout completion, as Unix seconds.

## Other responses

- `400` — Request syntax or field validation failed
- `401` — HMAC gateway validation or application authentication failed
- `403` — API key permission, IP whitelist, or organization eligibility rejected the request
- `404` — Resource was not found for the authenticated organization
- `409` — The request conflicts with idempotency, quote state, or another payout submission
- `422` — Request is syntactically valid but cannot pass payout eligibility or execution checks
- `500` — An unexpected internal error occurred
- `503` — Payout execution service or provider liquidity is temporarily unavailable

---

[API](https://skmtc.net/infini/apis/infini-fiat-payout-api.md) · [All operations](https://skmtc.net/infini/apis/infini-fiat-payout-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/infini/infini-fiat-payout-api/revisions/44f2f91e720d/schema)