--- title: "Payout Failed Webhook" source_url: https://docs.rapyd.net/en/payout-failed-webhook.html lang: en --- # Payout Failed Webhook The **PAYOUT_FAILED** webhook is sent when Rapyd attempts to disburse funds with the sender’s designated payout method, and the disbursement attempt fails. > **Note:** > > The endpoint for webhooks is unique for each client. To set up a webhook endpoint, see [Defining a Webhook Endpoint](https://docs.rapyd.net/en/defining-a-webhook-endpoint.md "Defining a Webhook Endpoint"). ### Parameters ### Webhook Header Parameters - - Content-Type - Indicates that the data appears in JSON format. Set to **application/json**. - - salt - Random string. - - signature - Signature calculated for each webhook individually. See [Webhook Authentication](https://docs.rapyd.net/en/webhook-authentication.md "Webhook Authentication"). - - timestamp - Timestamp for the webhook, in [Unix time](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_unix_time "Unix time") (seconds). ### Webhook Root Parameters - - created_at - Time that the webhook was created, in [Unix time](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_unix_time "Unix time"). > **Note:** > > Inside the `data` object, some webhooks have another `created_at` field that refers to a different event. - - data - Contains the actual data of the webhook. For details, see below. - - extended_timestamp - Time in milliseconds that the webhook was created, in [Unix time](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_unix_time "Unix time"). - - id - ID of the webhook. String starting with **wh_**. - - status - Status of the webhook. One of the following: - **NEW** - **CLO** - Closed. - **ERR** - Error. - **RET** - Re-sent. > **Note:** > > Inside the `data` object, some webhooks have another `status` field that refers to a different event. - - trigger_operation_id - ID of the operation that triggered the webhook. UUID. - - type - Name of the webhook type. > **Note:** > > The name in the Client Portal is different. ### Webhook Data Parameters - - amount - Amount of the payout, in units defined by `payout_currency`. Decimal, including the correct number of decimal places for the currency exponent, as defined in ISO 2417:2015. Same as `payout_amount`. - - batch_file - Batch file ID. Relevant to batch payouts that were created via the Client Portal. - - beneficiary - Object describing the beneficiary. - - beneficiary_country - Beneficiary bank country. The country to which funds are sent. Two-letter ISO 3166-1 ALPHA-2 code. - - bin_details - Bank identification details. Relevant to cards. - - bin_number - [Bank identification number](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_bin "Bank Identification Number") of the issuing bank. - - brand - The brand of the card. - - country - The country where the card was issued. - - issuer - Name of the bank that issued the card. - - level - The level of the card. - - type - The type of card. - - created_at - Time of creation of the `payout` object, in [Unix time](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_unix_time "Unix time"). - - crypto_payout_hash - A unique identifier that is proof that a payout was validated and added to the blockchain. Relevant to stablecoin cryptocurrency payouts via the `xx_stablecoin_ewallet` payout method. Value is **null** when payout has not been completed or when not relevant. - - error - Indicates the error code of the last unsuccessful operation on the `payout` object. - - estimated_time_of_arrival - The estimated time period in which the beneficiary will receive the funds. > **Note:** > > Rapyd will try to complete the payout within the estimated time. However, completion of a payout can be delayed for legal or other reasons. - - ewallets - An array of one object, which contains the following fields: - - ewallet_id - The ID of the wallet that the money is transferred from, a string starting with **ewallet_**. - - amount - Amount of the transaction in currency units defined in `currency`. - - percent - A decimal number representing a percentage of the total payout. - - expiration - Determines the day the payout expires, in [Unix time](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_unix_time "Unix time"). The payout must be completed before the start of this day. Relevant to cash payout methods where the `is_expirable` field is **true** in the response to [List Payout Method Types](https://docs.rapyd.net/en/list-payout-method-types.md "List Payout Method Types"). - - fx_rate - Currency conversion rate for the payout. Decimal. - - gc_error_code - Reserved. - - id - ID of the payout. String starting with **payout_**. - - identifier_type - Reserved. - - identifier_value - Reserved. - - instructions - Describes how the customer collects the payout. Contains the following fields: - - name - Description of the payment method. - - steps - An array containing a list of steps for the customer to take. Each step is named **step*N***, where ***N*** is an integer. - - merchant_ewallet - ID of the client wallet of the sub-merchant. - - merchant_reference_id - Identifier defined by the client for reference purposes. Limit: 45 characters. - - metadata - A JSON object defined by the client. See [Metadata](https://docs.rapyd.net/en/metadata.md "Metadata"). - - paid_amount - Cumulative amount received by the beneficiary, in units defined by `payout_currency`. - - paid_at - Time of the payout, in [Unix time](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_unix_time "Unix time"). - - payout_currency - Currency received by the beneficiary. Three-letter ISO 4217 code. > **Note:** > > Four-letter codes are supported for stablecoin payouts. - - payout_fees - Object that defines transaction fees and foreign exchange fees that the client can define for payout transactions. - - transaction_fee - Describes the fee for processing the transaction. - - calc_type - Specifies how the fee is calculated. One of the following: - **net** - The fee is deducted from the amount paid. For example, in a payment of $100 with a fee of 5%, the recipient receives $95.00 and the $5.00 fee goes to the client wallet. - **gross** - The fee is added to the amount paid. For example, for a transaction of $100 with a fee of 5%, the sender pays $105.00. - - fee_type - One of the following: - **percentage** - A percentage of the transaction amount. For example, 5 percent is represented by **value=5**. - **absolute** - A fixed amount. - - value - The amount of the fee. - - fx_fee - Describes the fees for processing the currency exchange. Relevant to payments with FX. - - calc_type - Specifies how the fee is calculated. One of the following: - **net** - The fee is deducted from the amount paid. For example, in a payment of $100 with a fee of 5%, the recipient receives $95.00 and the $5.00 fee goes to the client wallet. - **gross** - The fee is added to the amount paid. For example, for a transaction of $100 with a fee of 5%, the sender pays $105.00. - - value - The amount of the fee. Percentage. - - fee_currency - The currency in which fees are deducted. Required when  `payout_currency` is stablecoin and `calc_type` is not **gross**. After the fees are calculated, they are converted to the `fee_currency`. One of the following: - **USD** - **EUR** - **GBP** - **SGD** - **HKD** - **AUD** - - gross_fees - The total gross fees for the transaction, in units defined by `currency_code`. - - net_fees - The total net fees for the transaction, in units defined by `merchant_requested_currency`. - - total_merchant_fees - The amount of the fee. - - payout_method_type - The type of payout method. The two-letter prefix must match the country code of the beneficiary. - - payout_type - The type of the payout method. One of the following values: - **bank** - Payout to bank account. - **card** - Payout to card. - **cash** - Payout to cash. - **ewallet** - Payout to local eWallet. - - sender - Object describing the sender. - - company_name - Name of the sender company. Relevant when `entity_type` is **company**. - - country - Country of the sender. Two-letter ISO 3166-1 ALPHA-2 code. - - currency - Currency that the sender is paying with. Three-letter ISO 4217 code. - - entity_type - Type of entity. One of the following values: - **company** - **individual** - - first_name - First name of the sender. Relevant when `entity_type` is **individual**. - - identification_type - Type of identification document for the sender. When `entity_type` is **company**, this field must be **company_registered_number**. When `entity_type` is **individual**, one of the following values: - **drivers_license** - **identification_id** - **international_passport** - **residence_permit** - **social_security** - **work_permit** - - identification_value - Identification number on the document mentioned in `identification_type`. - - last_name - Last name of the sender. Relevant when `entity_type` is **individual**. - - sender_amount - Amount that the sender is paying in units of the currency defined in `sender_currency`. This amount remains the same regardless of FX fees. Decimal. - - sender_country - Country of the sender. Two-letter ISO 3166-1 ALPHA-2 code. - - sender_currency - Currency that the sender is paying with. Three-letter ISO 4217 code. - - statement_descriptor - A statement that includes the reason for the payout. Limited to 35 characters. - - status - Indicates the status of the payout. One of the following: - **Canceled** - The payout was canceled. - **Completed** - The beneficiary received some or all payout funds. - **Confirmation** - The payout is waiting for the beneficiary to confirm the FX rate. - **Created** - The payout was created successfully. - **Declined** - The payout failed to pass inspection. - **Error** - The payout was not created or failed after creation. - **Expired** - The payout has expired. - **Hold** - A bank payout is being reviewed manually by Rapyd Protect. A [Quarantine Under Review Webhook](https://docs.rapyd.net/en/quarantine-under-review-webhook.md "Quarantine Under Review Webhook") is also triggered. - **Pending** - The payout is waiting for the beneficiary to confirm acceptance of the funds. - **Returned** - Funds were returned to after the payout was completed. - - uetr - Unique End-to-End Transaction Reference. A 36-character alphanumeric code that uniquely identifies a specific international payout. When not relevant, the parameter does not appear in the response. - PAYOUT_FAILED Webhook - ```json { "id": "wh_2a8954384f46933f92ffe568b04b10b5", "type": "PAYOUT_FAILED", "data": { "id": "payout_221c0c369aa760fb720521e95f733ac7", "error": null, "amount": 185, "sender": { "id": "sender_06a63fd14ad661c045f4a4c0ec72a9d9", "city": "Anytown", "name": "John Doe", "state": "NY", "address": "123 First Street", "country": "US", "currency": "USD", "postcode": "12345", "entity_type": "individual", "purpose_code": "ABCDEFGHI", "date_of_birth": "22/02/1980", "account_number": "123456789", "source_of_income": "salary", "identification_type": "License No", "identification_value": "123456789", "beneficiary_relationship": "client" }, "status": "Declined", "fx_rate": 1, "paid_at": null, "ewallets": [ { "amount": 185, "percent": 100, "ewallet_id": "ewallet_6ff6a059a31d298a7bf31e8e193f9718" } ], "metadata": { "merchant_defined": true }, "created_at": 0, "expiration": null, "beneficiary": { "id": "beneficiary_d37f5aae807b78489cb4224a6ea63225", "city": "Anytown", "name": "Jane Doe", "email": "janedoe@rapyd.net", "state": "NY", "address": "456 Second Street", "country": "US", "ach_code": "123456789", "currency": "USD", "postcode": "10101", "bank_name": "US General Bank", "bic_swift": "BUINBGSF", "entity_type": "individual", "account_number": "BG96611020345678", "identification_type": "SSC", "identification_value": "123456789" }, "description": "Payout - Bank Transfer: Beneficiary/Sender objects", "paid_amount": 0, "payout_fees": null, "payout_type": "bank", "instructions": {}, "gc_error_code": "MISSING_PAYOUT_METHOD_REQUIRED_FIELD - [PHONE_NUMBER]", "sender_amount": 185, "sender_country": "US", "identifier_type": null, "payout_currency": "USD", "sender_currency": "USD", "identifier_value": null, "payout_method_type": "us_general_bank", "beneficiary_country": "US", "statement_descriptor": null, "merchant_reference_id": "GHY-0YU-HUJ-POIuetr": null "uetr": null, "crypto_payout_hash": null }, "trigger_operation_id": "d6ede5ee-e87c-41bd-8fe7-fef71e708bf8", "status": "NEW", "created_at": 1672045360,   "extended_timestamp": 1672045360394 } ```