Skip to main content

​
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.
    FieldTypeDescription
    codestringError code indicating the reason for the payout failure
    descriptionstringHuman-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"
  }
}