PIX Charge Webhook

Overview

The PIX Charge webhook provides real-time notifications for PIX charge events, including payment confirmations and refund processing. This webhook is essential for maintaining up-to-date information about your PIX transactions.

Webhook Configuration

Webhook Type

Type: PIX_QR_INBOUND
Events: Payment confirmations and refund notifications
Endpoint: Your registered webhook URL

Registration

To receive PIX charge webhooks, you must register a webhook endpoint using the Webhook API :

Webhook Events

Payment Confirmation Event

Triggered when a PIX charge is successfully paid.

Refund Confirmation Event

Triggered when a refund is processed for a PIX charge.

Webhook Payload Structure

The webhook payload includes the following fields:

{
  "txid": "astra202412dfsdrtsdgdgdst00005Z",
  "amount": 100.00,
  "payer": {
    "documentNumber": "12345678901",
    "name": "João Silva"
  },
  "endToEndId": "E12345678202401151030123456789",
  "devolutionEndToEndId": "E98765432202401151030987654321",
  "type": "PAYMENT",
  "status": "PAID",
  "paymentDate": "2024-01-15T10:30:00.000Z",
  "userReference": "order-12345"
}

Payload Fields

Field	Type	Description
`txid`	string	Unique transaction identifier of the PIX charge
`amount`	number	Payment amount
`payer`	object	Information about the payer
`payer.documentNumber`	string	Payer's document number (CPF/CNPJ)
`payer.name`	string	Payer's name
`endToEndId`	string	End-to-end transaction identifier from the payment
`devolutionEndToEndId`	string	End-to-end identifier for refunds (only present in refund events)
`type`	string	Event type: `PAYMENT` or `REFUND`
`status`	string	Transaction status
`paymentDate`	string	ISO 8601 timestamp of the payment/refund
`userReference`	string	Client's reference identifier (if provided during charge creation)

Event Types

Payment Events

Payment Confirmation

{
  "txid": "astra202412dfsdrtsdgdgdst00005Z",
  "amount": 100.00,
  "payer": {
    "documentNumber": "12345678901",
    "name": "João Silva"
  },
  "endToEndId": "E12345678202401151030123456789",
  "devolutionEndToEndId": null,
  "type": "PAYMENT",
  "status": "PAID",
  "paymentDate": "2024-01-15T10:30:00.000Z",
  "userReference": "order-12345"
}

Refund Events

Refund Confirmation

{
  "txid": "astra202412dfsdrtsdgdgdst00005Z",
  "amount": 50.00,
  "payer": {
    "documentNumber": "12345678901",
    "name": "João Silva"
  },
  "endToEndId": "E12345678202401151030123456789",
  "devolutionEndToEndId": "E98765432202401151030987654321",
  "type": "REFUND",
  "status": "REFUNDED",
  "paymentDate": "2024-01-15T11:00:00.000Z",
  "userReference": "order-12345"
}

Status Values

Payment Status

Status	Description
`PAID`	Payment has been successfully processed
`FAILED`	Payment processing failed
`CANCELLED`	Payment was cancelled

Refund Status

Status	Description
`REFUNDED`	Refund has been successfully processed
`REFUND_FAILED`	Refund processing failed
`REFUND_CANCELLED`	Refund was cancelled