Sign in
webhook-event
transfer

Transfer payout failure

Triggered every time a payout fails. Use this event to get further information about a failed payment. See the Webhooks guide for setup instructions, signature verification, and best practices.

Events may not be delivered in the order they occurred. Use data.occurred_at to reconcile the order. See the Event Ordering guide for details.

  • Event type: transfers#payout-failure
  • Profile level subscriptions: Supported
  • Application level subscriptions: Supported

The transfers#state-change event provides high level information about the state of transfers. But it doesn't provide details about payout failures.

While the transfers#state-change event is in outgoing_payment_sent state, the payout could fail for certain reasons.

Please note that not every payout failure will trigger a transfers#state-change. For example a payout might fail with MANDATE_NOT_FILLED_IN code but the corresponding transfer might stay in the same state.

We recommend to process both event types(transfers#payout-failure and transfers#state-change) separate from each other.

{% admonition type="info" %} To simulate payout failure in Sandbox, use the payout failure simulation endpoint. {% /admonition %}

For available failure reason codes and descriptions, see the Payout failures guide.

Wise could add new failure codes and your system should be able to handle the events even if the failure reason code is not recognised.

postWebhooktransfers#payout-failure

Headers

X-Signature-SHA256string

RSA-SHA256 signature of the request body, Base64 encoded. Verify this against the Wise public key to ensure the request is authentic and has not been tampered with.

X-Delivery-Idstring uuid

Unique identifier for this webhook delivery attempt.

X-Test-Notificationboolean

Present with the value true if this is a test notification sent to verify your callback URL during subscription setup.

Payload

OR

Example payload

{
  "schema_version": "4.0.0",
  "subscription_id": "01234567-89ab-cdef-0123-456789abcdef",
  "event_type": "transfers#payout-failure",
  "sent_at": "2023-08-10T10:17:28.123Z",
  "data": {
    "transfer_id": 111,
    "profile_id": 222,
    "failure_reason_code": "WRONG_ID_NUMBER",
    "failure_description": "Invalid recipient's ID document number",
    "occurred_at": "2023-08-10T10:17:23.123Z"
  }
}

Response

Return any 2xx status to acknowledge receipt of the event.

statusstring

Example response

{
  "status": "ok"
}

Changes