Sign in

v1

latestOpenAPI 3.0.02026-08-0631647.5 KB
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, SGB 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 SGB execution started. It does not mean the receiving bank has credited the account. Use GET /v2/payouts/{payout_id} to obtain the latest state.

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 this SGB 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": "SGB-20260730-849201",
    "failure": {
      "code": "recipient_bank_rejected",
      "message": "The receiving bank returned the transfer"
    },
    "created_at": 1786587000,
    "updated_at": 1786587001,
    "completed_at": 1786587871,
    "returned_at": 1786674271
  }
}