Devoluções

Eventos de Devolução

Ao solicitar uma devolução (parcial ou total) de um pagamento PIX, o processo passa por duas etapas. A cada etapa, um evento webhook é disparado para a URL configurada, permitindo que você acompanhe o status da devolução em tempo real.

Fluxo de Eventos

Solicitação

refund.requested

PROCESSING

Confirmação

refund.confirmed

CONFIRMED

Falha

refund.failed

ERROR

Detalhes dos Eventos

refund.requested

Disparado quando uma devolução é solicitada. A devolução entra em processamento e aguarda confirmação do banco.

Campos do payload

Campo	Tipo	Descrição
`event`	string	Nome do evento: refund.requested
`timestamp`	string	Data/hora do evento (ISO 8601)
`accountId`	string	ID da conta que solicitou a devolução
`refundId`	string	Identificador único da devolução
`chargeId`	string	ID da cobrança original associada
`endToEndId`	string	EndToEndId da transação PIX original
`amount`	number	Valor da devolução (parcial ou total)
`reason`	string	Motivo da devolução: BANK_ERROR, FRAUD, CUSTOMER_REQUEST ou PIX_CHANGE_ERROR
`status`	string	Status da devolução: PROCESSING
`customer`	object	Cliente resolvido a partir do chargeId. Pode vir com todos os campos null quando a cobrança não tem cliente vinculado
`paymentType`	string	Somente no estorno de cartão: CREDIT_CARD
`providerChargeId`	string	Somente no estorno de cartão: ID da transação no adquirente. Neste caso não há endToEndId

Exemplo de payload

{
  "event": "refund.requested",
  "timestamp": "2026-03-26T15:27:40.152Z",
  "accountId": "429131212",
  "refundId": "ref_1774538859355_e45i9a29a",
  "chargeId": "cha_1774538005499_oz92qbnw2",
  "endToEndId": "E00360305202603261524fbd278ed679",
  "amount": 1,
  "reason": "CUSTOMER_REQUEST",
  "status": "PROCESSING",
  "customer": {
    "customerId": "cus_1770483634516_pwj5e9k4f",
    "name": "João Silva",
    "email": "customer@example.com",
    "taxId": "40162317018",
    "phone": "11987654321"
  }
}

refund.confirmed

Disparado quando a devolução é confirmada pelo banco. O valor foi devolvido com sucesso ao pagador original.

Campos do payload

Campo	Tipo	Descrição
`event`	string	Nome do evento: refund.confirmed
`timestamp`	string	Data/hora da confirmação (ISO 8601)
`accountId`	string	ID da conta que solicitou a devolução
`refundId`	string	Identificador único da devolução
`chargeId`	string	ID da cobrança original associada
`endToEndId`	string	EndToEndId da transação PIX original
`returnIdentification`	string	Identificador da devolução gerado pelo banco (EndToEndId da devolução)
`amount`	number	Valor devolvido
`status`	string	Status da devolução: CONFIRMED
`customer`	object	Cliente da cobrança original; pode vir com todos os campos null
`splitReversals`	array	Presente quando a cobrança tinha split. Estorno por participante; status PENDING com debtId significa que o valor virou débito a quitar no próximo crédito

Exemplo de payload

{
  "event": "refund.confirmed",
  "timestamp": "2026-03-26T15:30:08.854Z",
  "accountId": "429131212",
  "refundId": "ref_1774538859355_e45i9a29a",
  "chargeId": "cha_1774538005499_oz92qbnw2",
  "endToEndId": "E00360305202603261524fbd278ed679",
  "returnIdentification": "D13935893202603261527pphMftAjFaA",
  "amount": 1,
  "status": "CONFIRMED",
  "customer": {
    "customerId": "cus_1770483634516_pwj5e9k4f",
    "name": "João Silva",
    "email": "customer@example.com",
    "taxId": "40162317018",
    "phone": "11987654321"
  },
  "splitReversals": [
    {
      "accountNumber": "429131213",
      "amount": 0.2,
      "status": "REVERSED"
    },
    {
      "accountNumber": "429131214",
      "amount": 0.1,
      "status": "PENDING",
      "debtId": "sdb_1774538859_x9k2"
    }
  ]
}

refund.failed

Disparado quando a devolução falha. O campo error contém o código de erro retornado pelo banco (ex: MD06 — solicitação de devolução rejeitada pelo PSP do recebedor).

Campos do payload

Campo	Tipo	Descrição
`event`	string	Nome do evento: refund.failed
`timestamp`	string	Data/hora da falha (ISO 8601)
`accountId`	string	ID da conta que solicitou a devolução
`refundId`	string	Identificador único da devolução
`chargeId`	string	ID da cobrança original associada
`endToEndId`	string	EndToEndId da transação PIX original
`returnIdentification`	string	Identificador da devolução gerado pelo banco
`amount`	number	Valor da devolução que falhou
`status`	string	Status da devolução: ERROR
`error`	string	Código de erro retornado pelo banco (ex: MD06). Repete o próprio status quando não há detalhe do motivo
`customer`	object	Cliente da cobrança original; pode vir com todos os campos null

Exemplo de payload

{
  "event": "refund.failed",
  "timestamp": "2026-03-26T14:19:29.150Z",
  "accountId": "429131212",
  "refundId": "ref_1774534713674_wrlnq1txh",
  "chargeId": "cha_1774534422864_dyegbocbf",
  "endToEndId": "E00360305202603261416c60fc3916be",
  "returnIdentification": "D13935893202603261418H4YznmZoCCX",
  "amount": 1,
  "status": "ERROR",
  "error": "MD06",
  "customer": {
    "customerId": null,
    "name": null,
    "email": null,
    "taxId": null,
    "phone": null
  }
}

Observações importantes

Os eventos são enviados via webhook para a URL configurada no painel em app.validapay.com.br/integracao/webhooks
O campo refundId é o identificador único da devolução em ambos os eventos
O campo returnIdentification só está presente no evento refund.confirmed e representa o EndToEndId da devolução gerado pelo banco
O amount indica o valor efetivamente devolvido, que pode ser parcial
Os motivos possíveis em reason são: BANK_ERROR, FRAUD, CUSTOMER_REQUEST e PIX_CHANGE_ERROR