payout.failed

Payout execution failed and the funds it reserved were released.

Money and processing#

Read the payout for its current status and failure_reason. New events use destination_rejected when the destination was rejected, or internal_error for other execution failures, in error_message. Previously recorded events retain their original text when retried; handle unfamiliar values as an unspecified failure. There is no actual network-cost field in this payload.

A failure does not automatically reverse funding that already completed: read funding and balance_movements for the conversion debits and acquired target funds this payout kept. Do not repeat the original request with a new key while its outcome is uncertain. After a confirmed failure, a replacement payout is a new deliberate transfer with its own idempotency key.

Schema version 2#

Fields are taken from the public OpenAPI contract. Required nullable fields must be present and may contain null.

id · string · Required

Stable event UUID for merchant-side idempotency. · Format: uuid
event_seq · integer · Required

Global event sequence. Gaps are possible; it does not establish delivery or processing order. · Format: int64
type · "payout.failed" · Required

—
schema_version · 2 · Required

—
environment · "live" | "test" · Required

—
merchant_id · string · Required

Format: uuid
subject_type · "payout" · Required

—
subject_id · string · Required

Format: uuid
occurred_at · string · Required

Canonical business occurrence timestamp. · Format: date-time
data · object · Required

Frozen version-2 payout.failed facts. Amount is requested B; target_funding_amount is target obligation H, never a sum of source debits. Native movements and funding sources are recorded after this transition in the same transaction. Ordinary source-free payouts carry funding:null; historical unavailable economics remain null. Delivery retries preserve these exact saved bytes. · Unknown properties are rejected
data.payout_id · string · Required

Payout UUID. · Format: uuid
data.currency · string · Required

Currency code.
data.network · string · Required

Blockchain network code.
data.environment · "live" | "test" · Required

Environment.
data.amount · string · Required

Base/requested payout amount as a decimal string. · Format: decimal · Pattern: ^\d+(.\d+)?$
data.recipient_amount · string | null · Required

Amount intended for the recipient after customer-allocated commercial charges. · Format: decimal · Pattern: ^\d+(.\d+)?$
data.fee_amount · string | null · Required

Snapshotted platform payout fee in payout currency. · Format: decimal · Pattern: ^\d+(.\d+)?$
data.payout_fee_allocation · "customer" | "merchant" | "platform" | null · Required

Allocation of the snapshotted payout service fee.
data.configured_network_fee_amount · string | null · Required

Snapshotted commercial network charge. · Format: decimal · Pattern: ^\d+(.\d+)?$
data.network_fee_allocation · "customer" | "merchant" | "platform" | null · Required

Allocation of the snapshotted commercial network charge.
data.destination · string · Required

Destination blockchain address.
data.error_message · string · Required

Merchant-facing failure reason. funding_failed means funding closed before outbound execution without covering the target obligation; completed conversions and earned fees remain in the native facts. destination_rejected means the destination was rejected; internal_error covers other failures. Previously recorded events retain their original payloads.
data.status · "failed" · Required

Always "failed".
data.economics_status · "available" | "unavailable" · Required

—
data.target_funding_amount · string | null · Required

Target-denominated obligation H. It is not a source-gate debit. · Format: decimal · Pattern: ^\d+(.\d+)?$
data.funding · object | null · Required

Frozen multi-source funding and its durable progress. Null for ordinary source-free payouts and historical payouts without accepted economics. · Unknown properties are rejected
data.funding.mode · "same_asset_only" | "source_only" | "target_first" · Required

—
data.funding.service_class · "immediate" | "waiting" · Required

—
data.funding.direct_target_amount · string · Required

Format: decimal · Pattern: ^\d+(.\d+)?$
data.funding.target_ready_amount · string · Required

Format: decimal · Pattern: ^\d+(.\d+)?$
data.funding.target_surplus_released · string · Required

Format: decimal · Pattern: ^\d+(.\d+)?$
data.funding.funding_deadline · string | null · Required

Format: date-time
data.funding.sources · array<object> · Required

—
data.funding.sources.conversion_fee_payer · "merchant" | "platform" · Required

—
data.funding.sources.source_id · string · Required

Format: uuid
data.funding.sources.gate · object · Required

Unknown properties are rejected
data.funding.sources.gate.currency · string · Required

Minimum length: 1 · Maximum length: 20
data.funding.sources.gate.network · string · Required

Minimum length: 1 · Maximum length: 64
data.funding.sources.reserved_gross · string · Required

Format: decimal · Pattern: ^\d+(.\d+)?$
data.funding.sources.exchanged_principal · string · Required

Format: decimal · Pattern: ^\d+(.\d+)?$
data.funding.sources.earned_conversion_fee · string · Required

Format: decimal · Pattern: ^\d+(.\d+)?$
data.funding.sources.refunded_source · string · Required

Format: decimal · Pattern: ^\d+(.\d+)?$
data.funding.sources.outstanding_reserve · string · Required

Format: decimal · Pattern: ^\d+(.\d+)?$
data.funding.sources.target_delivered · string · Required

Format: decimal · Pattern: ^\d+(.\d+)?$
data.funding.status · "converting" | "needs_review" | "ready" | "closed" · Required

Funding lifecycle within the payout. The outer payout status remains processing during converting and needs_review.
data.balance_movements · array<object> · Required

—
data.balance_movements.gate · object · Required

Unknown properties are rejected
data.balance_movements.gate.currency · string · Required

Minimum length: 1 · Maximum length: 20
data.balance_movements.gate.network · string · Required

Minimum length: 1 · Maximum length: 64
data.balance_movements.direction · "credit" | "debit" | "none" · Required

—
data.balance_movements.amount · string · Required

Format: decimal · Pattern: ^\d+(.\d+)?$
data.balance_movements.credit_amount · string · Required

Format: decimal · Pattern: ^\d+(.\d+)?$
data.balance_movements.debit_amount · string · Required

Format: decimal · Pattern: ^\d+(.\d+)?$
data.balance_movements.reversed_credit_amount · string · Required

Format: decimal · Pattern: ^\d+(.\d+)?$
data.balance_movements.reversed_debit_amount · string · Required

Format: decimal · Pattern: ^\d+(.\d+)?$
data.balance_movements.amount_usd · string | null · Required

Format: decimal · Pattern: ^\d+(.\d+)?$

Example — version 2#

{
  "id": "00000000-0000-0000-0000-000000000001",
  "event_seq": 184203,
  "type": "payout.failed",
  "schema_version": 2,
  "environment": "live",
  "merchant_id": "00000000-0000-0000-0000-000000000002",
  "subject_type": "payout",
  "subject_id": "00000000-0000-0000-0000-000000000003",
  "occurred_at": "2026-09-14T10:00:00Z",
  "data": {
    "payout_id": "00000000-0000-0000-0000-000000000003",
    "currency": "USDC",
    "network": "ethereum",
    "environment": "live",
    "amount": "10.00",
    "recipient_amount": "10.00",
    "fee_amount": "0.10",
    "payout_fee_allocation": "merchant",
    "configured_network_fee_amount": "0.00",
    "network_fee_allocation": "platform",
    "destination": "0x0000000000000000000000000000000000000001",
    "error_message": "funding_failed",
    "status": "failed",
    "economics_status": "available",
    "target_funding_amount": "10.10",
    "funding": {
      "status": "closed",
      "mode": "target_first",
      "service_class": "immediate",
      "direct_target_amount": "0",
      "target_ready_amount": "0",
      "target_surplus_released": "0",
      "funding_deadline": null,
      "sources": [
        {
          "source_id": "00000000-0000-0000-0000-000000000104",
          "gate": {
            "currency": "USDT",
            "network": "ethereum"
          },
          "conversion_fee_payer": "merchant",
          "reserved_gross": "5.05",
          "exchanged_principal": "4.5",
          "earned_conversion_fee": "0.05",
          "refunded_source": "0.5",
          "outstanding_reserve": "0",
          "target_delivered": "4.5"
        },
        {
          "source_id": "00000000-0000-0000-0000-000000000105",
          "gate": {
            "currency": "ETH",
            "network": "ethereum"
          },
          "conversion_fee_payer": "merchant",
          "reserved_gross": "0.0025",
          "exchanged_principal": "0.001",
          "earned_conversion_fee": "0.00001",
          "refunded_source": "0.00149",
          "outstanding_reserve": "0",
          "target_delivered": "2.55"
        }
      ]
    },
    "balance_movements": [
      {
        "gate": {
          "currency": "USDT",
          "network": "ethereum"
        },
        "direction": "debit",
        "amount": "4.55",
        "credit_amount": "0",
        "debit_amount": "4.55",
        "reversed_credit_amount": "0",
        "reversed_debit_amount": "0",
        "amount_usd": null
      },
      {
        "gate": {
          "currency": "ETH",
          "network": "ethereum"
        },
        "direction": "debit",
        "amount": "0.00101",
        "credit_amount": "0",
        "debit_amount": "0.00101",
        "reversed_credit_amount": "0",
        "reversed_debit_amount": "0",
        "amount_usd": null
      },
      {
        "gate": {
          "currency": "USDC",
          "network": "ethereum"
        },
        "direction": "credit",
        "amount": "7.05",
        "credit_amount": "7.05",
        "debit_amount": "0",
        "reversed_credit_amount": "0",
        "reversed_debit_amount": "0",
        "amount_usd": null
      }
    ]
  }
}

See delivery and envelope, signature verification, and business processes.

Money and processing# #

Schema version 2# #

Example — version 2# #

Money and processing#

Schema version 2#

Example — version 2#