Sign in
latestOpenAPI 3.0.02026-08-1831755.3 KB

44f2f91e720d

Payouts

Create a fiat payout

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

Headers

Datestring
Example:Tue, 30 Jul 2026 08:50:00 GMT

GMT server time, e.g. Tue, 21 Jan 2025 12:00:00 GMT. Required on the wire; the Try it signer injects it automatically.

Authorizationstring
Example:Signature keyId="key_example",algorithm="hmac-sha256",headers="@request-target date",signature="<signature>"

HMAC-SHA256 Signature header. Required on the wire; the Try it signer injects it automatically. See the Authentication guide.

Digeststring
Example:SHA-256=<base64(sha256(request body))>

SHA-256 digest required on the wire when a body is present; the Try it signer injects it automatically.

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.00",
    "receiving_amount": "1000.00",
    "transfer_fee_amount": "1.00",
    "bank_fee_amount": "50.00",
    "fee_rate_decimal": "0.001",
    "rate": "1",
    "billing": {
      "currency": "USD",
      "transfer_fee": "1.00",
      "fx_fee": "0.00",
      "rail_fee": "50.00",
      "total_fee": "51.00",
      "fee_lines": [
        {
          "type": "transfer_fee",
          "amount": "1.00",
          "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.00",
      "currency": "USD",
      "returned_at": 1786674271
    },
    "created_at": 1786587000,
    "updated_at": 1786587001,
    "completed_at": 1786587871
  }
}