Payout Object Changes

The Payout object has been enhanced to include a new failure object in the response. This provides more structured and cleaner failure information when a payout has failed, making it easier to programmatically identify and handle failure scenarios. We will be deprecating the old failure codes that were populated in the status_description field soon. It is recommended to consume these new failure codes instead.

New Field Added

failure An object that contains details about why a payout failed. This field is null for payouts that have not failed.
Field Type Description
code string Error code indicating the reason for the payout failure
description string Human-readable description of the failure reason

Field	Type	Description
`code`	string	Error code indicating the reason for the payout failure
`description`	string	Human-readable description of the failure reason

The failure object is only populated when the payout status is failed. For all other statuses (e.g., succeeded, processing, reversed), this field will be null.

Example Response (Failed Payout)

{
  "status": "success",
  "message": "",
  "data": {
    "amount": 100000,
    "balance_transaction": "btr_d35pv4qcl8imrv60",
    "beneficiary": "bnf_d3inm6ami8u10oqfg",
    "beneficiary_details": {
      "address": {
        "country": "CN",
        "line1": "Zhen Rui Yun Lu 66",
        "postal_code": "311011"
      },
      "destination_details": {
        "bank": {
          "account_number": "33050167624000001030",
          "account_type": "",
          "bank_codes": {
            "swift_code": "PCBCCNBJZJX"
          },
          "bank_name": "CHINA CONSTRUCTION BANK, ZHEJIANG BRANCH",
          "country": "CN",
          "currency": "USD",
          "transfer_type": "swift"
        },
        "type": "bank"
      },
      "email": "",
      "name": "IMPORT AND EXPORT CO., LTD",
      "type": "business"
    },
    "charge_type": "ours",
    "created_at": "2025-09-18T10:07:35.101708Z",
    "currency": "USD",
    "holding_currency": "USD",
    "holding_fx_transaction": {
      "exchange_rate": 1,
      "final": { "amount": 100000, "currency": "USD" },
      "id": "fx_d35tjpnfigp2dt2hgg",
      "initial": { "amount": 100000, "currency": "USD" },
      "object": "fx_transaction"
    },
    "id": "pot_d35tjpn4qcl8iv30",
    "local": {
      "fund_transfer_network": "swift"
    },
    "logistics_tracking_details": [],
    "metadata": null,
    "mt103": "",
    "object": "payout",
    "on_behalf_of": "",
    "payout_fx_transaction": {
      "exchange_rate": 1,
      "final": { "amount": 100000, "currency": "USD" },
      "id": "fx_d35tfigo4p2dt2hh0",
      "initial": { "amount": 100000, "currency": "USD" },
      "object": "fx_transaction"
    },
    "purpose": "PYR003",
    "reference_id": "INV-CN-2025-0042",
    "statement_descriptor": "Payment for goods",
    "status": "failed",
    "status_description": "PO1012",
    "failure": {
      "code": "PF020101",
      "description": "Bank identification code is missing/invalid"
    },
    "tracking_details": null,
    "transaction_description": "Payment for goods acc 125",
    "type": "swift"
  }
}

Example Response (Successful Payout)

{
  "status": "success",
  "message": "",
  "data": {
    "amount": 3000000,
    "balance_transaction": "btr_dhuvflvi5frlneafr0",
    "beneficiary": "bnf_d0dla9u8dpp4edio0",
    "beneficiary_details": {
      "address": null,
      "destination_details": {
        "bank": {
          "account_type": "",
          "bank_codes": {
            "swift_code": "FBDEFF"
          },
          "bank_name": "ER VOLKSBANK EG",
          "country": "DE",
          "currency": "EUR",
          "iban": "DE535019045650474185",
          "transfer_type": "any"
        },
        "type": "bank"
      },
      "email": "",
      "name": "GMBH",
      "type": "business"
    },
    "charge_type": "",
    "created_at": "2025-09-16T08:27:41.832790Z",
    "currency": "EUR",
    "holding_currency": "USD",
    "holding_fx_transaction": {
      "exchange_rate": 0.846438,
      "final": { "amount": 3000000, "currency": "EUR" },
      "id": "fx_d34flc7loipp34fmg",
      "initial": { "amount": 3544266, "currency": "USD" },
      "object": "fx_transaction"
    },
    "id": "pot_d34hlvi5frlneafo0",
    "local": {
      "fund_transfer_network": "sepa"
    },
    "logistics_tracking_details": [],
    "metadata": null,
    "mt103": "",
    "object": "payout",
    "on_behalf_of": "",
    "payout_fx_transaction": {
      "exchange_rate": 1,
      "final": { "amount": 3000000, "currency": "EUR" },
      "id": "fx_d34huvflc7pp34fm0",
      "initial": { "amount": 3000000, "currency": "EUR" },
      "object": "fx_transaction"
    },
    "purpose": "PYR001",
    "reference_id": "DE-LOG-2024-0909",
    "statement_descriptor": "Logistics Payment",
    "status": "succeeded",
    "status_description": "",
    "failure": null,
    "tracking_details": {
      "tracking_number": "098771252590P9A",
      "tracking_type": "UTR"
    },
    "transaction_description": "Payment for logistic services 9-09",
    "type": "local"
  }
}

Payout Webhook Changes

The payout.failed webhook event now includes the same failure object in its payload. When a payout fails, the webhook response will contain the failure object with code and description fields, providing structured failure details alongside the existing status_description.

Example Webhook Payload (payout.failed)

{
  "id": "evt_d35tjpn4qcl8iv31",
  "type": "payout.failed",
  "created_at": "2025-09-18T10:15:22.304512Z",
  "data": {
    "amount": 100000,
    "balance_transaction": "btr_d35pv4qcl8imrv60",
    "beneficiary": "bnf_d3inm6ami8u10oqfg",
    "beneficiary_details": {
      "address": {
        "country": "CN",
        "line1": "Zhen Rui Yun Lu 66",
        "postal_code": "311011"
      },
      "destination_details": {
        "bank": {
          "account_number": "33050167624000001030",
          "bank_codes": {
            "swift_code": "PCBCCNBJZJX"
          },
          "bank_name": "CHINA CONSTRUCTION BANK, ZHEJIANG BRANCH",
          "country": "CN",
          "currency": "USD",
          "transfer_type": "swift"
        },
        "type": "bank"
      },
      "email": "",
      "name": "IMPORT AND EXPORT CO., LTD",
      "type": "business"
    },
    "created_at": "2025-09-18T10:07:35.101708Z",
    "currency": "USD",
    "id": "pot_d35tjpn4qcl8iv30",
    "local": {
      "fund_transfer_network": "swift"
    },
    "object": "payout",
    "purpose": "PYR003",
    "reference_id": "INV-CN-2025-0042",
    "statement_descriptor": "Payment for goods",
    "status": "failed",
    "status_description": "PO1012",
    "failure": {
      "code": "PF020101",
      "description": "Bank identification code is missing/invalid"
    },
    "tracking_details": null,
    "transaction_description": "Payment for goods acc 125",
    "type": "swift"
  }
}

2026

2025

Payout Failure Code in Fetch Payout

Payout Object Changes

New Field Added

Example Response (Failed Payout)

Example Response (Successful Payout)

Payout Webhook Changes

Example Webhook Payload (payout.failed)

Relevant Links

​Payout Object Changes

​New Field Added

​Example Response (Failed Payout)

​Example Response (Successful Payout)

​Payout Webhook Changes

​Example Webhook Payload (payout.failed)

​Relevant Links

Payout Object Changes

New Field Added

Example Response (Failed Payout)

Example Response (Successful Payout)

Payout Webhook Changes

Example Webhook Payload (payout.failed)

Relevant Links