> ## Documentation Index
> Fetch the complete documentation index at: https://developer.tazapay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Payout Failure Code in Fetch Payout

# 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**](/API-Reference/appendix/payout-failure-reasons-updated) |

<Info>
  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`.
</Info>

## Example Response (Failed Payout)

```json theme={null}
{
  "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)

```json theme={null}
{
  "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)

```json theme={null}
{
  "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"
  }
}
```

## Relevant Links

* [**GET Payout**](/API-Reference/tazapay-api/payout/fetch-payout)
* [**Payout Webhooks**](/API-Reference/tazapay-api/payout/payout-webhooks)
* [**Payout Failure Reason Codes**](/API-Reference/appendix/payout-failure-reasons-updated)