---
title: "Withdrawal failed"
method: POST
path: "WITHDRAWAL_FAILED"
tags: ["Webhooks"]
---

# Withdrawal failed

`POST WITHDRAWAL_FAILED` (webhook)

The network rejected the transfer and the funds were returned to your balance. This also carries provider-driven reversals.

The HTTP body is this object exactly — there is no envelope and no `type` field. The event name is delivered in the `X-Webhook-Event` header. Most optional fields arrive as an explicit `null`; a few keys are dropped from the JSON entirely when unset, and those are marked as such below. Read values with a null-safe accessor rather than testing key presence.

## Payload

- object
  - `withdrawalId` string, uuid — Withdrawal id.
  - `txId` string — Withdrawal transaction id.
  - `netAmount` number — Amount that was attempted, in BRL.
  - `status` 'FAILED' — Always `FAILED`.
  - `endToEndId` string, nullable — PIX end-to-end identifier. `null` when the network did not assign one.
  - `recipient` WebhookRecipientBlock — Recipient block. `null` when every field would be null. There is no `documentType` here, unlike `payer`.
    - `name` string, nullable — Recipient name as reported by the settling institution.
    - `document` string, nullable — Recipient CPF or CNPJ. Populated when the withdrawal was created with `destination.recipientDocument`, or with a CPF or CNPJ `destination.pixKey`, or when the settling provider reported the receiving account. `null` otherwise.
    - `institutionName` string, nullable — Recipient institution name.
    - `institutionIspb` string, nullable — Recipient institution ISPB code.
    - `branch` string, nullable — Recipient branch, when the provider reports it.
    - `account` string, nullable — Recipient account, when the provider reports it.
  - `failureReason` string — Merchant-safe failure description. Never `null` — the key is absent when the network supplied no usable reason text.

## Acknowledgement `200`

Return a 2xx status to acknowledge receipt.

---

[API](https://skmtc.dev/yuvexpay/apis/yuvexpay-api.md) · [All operations](https://skmtc.dev/yuvexpay/apis/yuvexpay-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/yuvexpay/yuvexpay-api/revisions/9d4ba1cc037c/schema)