INinfini
Payouts

Create a fiat payout

Changed on

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.

post/v2/payouts

Request

Headers

X-API-Key-IDstring required

32-character Base58 credential ID returned after public-key registration.

X-API-Timestampstring required

Unix timestamp in seconds; tolerance is ±300 seconds.

X-API-Noncestring required

16 cryptographically random bytes encoded as unpadded Base64URL; fresh on every attempt.

Digeststring required

SHA-256= followed by standard padded Base64 of SHA-256 of exact request body bytes. Required even for an empty body; included in the signing string.

Authorizationstring required

Use Ed25519 signature="BASE64_SIGNATURE", where BASE64_SIGNATURE is the standard padded Base64 signature. See /docs/en/4-authorization for the exact signing string.

Request body

client_reference_idstring required

Merchant-scoped idempotency and reconciliation reference for one logical payout.

quote_idstring required

Unexpired quote owned by the authenticated organization. It binds the destination, amounts, fee responsibility, provider, rail, and pricing.

purpose_codestring required

Business purpose code accepted for the payout corridor.

statement_referencestring

Reference displayed to the recipient when supported by the bank rail.

Example request

{
  "client_reference_id": "payout_20260730_0001",
  "quote_id": "poq_01JQ90B8S5VJ6R3T7F1M2C4N9X",
  "purpose_code": "goods_and_services",
  "statement_reference": "INV-2026-0730"
}

Response

Payout created or an idempotent existing payout returned

code0 required

Business code. 0 means success.

messagestring required

Response message.

Example response

{
  "data": {
    "payout_id": "fpo_01JQ90GQJTC5P7B2D8N6R4K1MX",
    "client_reference_id": "payout_20260730_0001",
    "quote_id": "poq_01JQ90B8S5VJ6R3T7F1M2C4N9X",
    "provider": "sgb",
    "status": "processing",
    "payout_type": "swift",
    "source_currency": "USD",
    "destination_currency": "USD",
    "destination_country": "US",
    "amount_mode": "receive",
    "fee_paid_by": "PAYER",
    "sending_amount": "1051.05",
    "receiving_amount": "1000.00",
    "transfer_fee_amount": "1.05",
    "bank_fee_amount": "50.00",
    "fee_rate_decimal": "0.001",
    "rate": "1",
    "billing": {
      "currency": "USD",
      "transfer_fee": "1.05",
      "fx_fee": "0.00",
      "rail_fee": "50.00",
      "total_fee": "51.05",
      "fee_lines": [
        {
          "type": "transfer_fee",
          "amount": "1.05",
          "currency": "USD",
          "rate": "0.001"
        }
      ]
    },
    "destination": {
      "type": "bank_account",
      "account_holder_type": "business",
      "account_holder_name": "Acme Supplies LLC",
      "bank_country": "US",
      "bank_name": "Example Bank",
      "account_number_masked": "******3210",
      "swift_code": "BOFAUS3NXXX"
    },
    "purpose_code": "goods_and_services",
    "statement_reference": "INV-2026-0730",
    "bank_reference": "RMTO2084957259539812352",
    "failure": {
      "code": "payout_failed",
      "message": "The payout could not be completed"
    },
    "return": {
      "status": "refunded",
      "reason_code": "recipient_bank_rejected",
      "reason": "Beneficiary bank rejected the transfer",
      "returned_amount": "1000.00",
      "refund_amount": "1000.00",
      "retained_fee": "51.05",
      "currency": "USD",
      "returned_at": 1786674271
    },
    "created_at": 1786587000,
    "updated_at": 1786587001,
    "completed_at": 1786587871
  }
}

Changes

  • 25c3ff16936dRevision changes
    • breaking

      added the new required header request parameter X-API-Key-ID

    • breaking

      added the new required header request parameter X-API-Nonce

    • breaking

      added the new required header request parameter X-API-Timestamp

    • breaking

      the header request parameter Authorization became required

    • breaking

      the header request parameter Digest became required

    • breaking

      removed the media type application/json for the response with the status

    • breaking

      removed the media type application/json for the response with the status

    • warning

      deleted the header request parameter Date

  • 44f2f91e720dRevision changes
    • info

      added the non-success response with the status

    • info

      added the non-success response with the status