Esta página cobre os quatro eventos de webhook relacionados a transações Pix.
PIX_RECEIVED Disparado quando um Pix é creditado na sua conta. É o principal evento para confirmar o recebimento de pagamentos Pix.
Como registrar: { "eventType" : "PIX_RECEIVED" , "url" : "https://seuservidor.com.br/webhooks/pix-recebido" , "authorizationScheme" : "BEARER" , "authorization" : "seu-token" }
Payload recebido na sua URL: { "eventType" : "PIX_RECEIVED" , "correlationId" : "S110211111111111111111111" , "referenceId" : "E182361202024041911111111111111" , "endToEndId" : "E182361202024041911111111111111" , "amount" : 100.0 , "createdAt" : "2024-04-19T16:20:22.274Z" , "proof" : { "eventType" : "PIX_PAYMENT_EFFECTIVE" , "endToEndId" : "E182361202024041911111111111111" , "idempotencyKey" : "E182361202024041911111111111111" , "correlationId" : "S110211111111111111111111" , "status" : "PIX_EFFECTIVE" , "amount" : 100.0 , "payer" : { "number" : "49041111116" , "branch" : "0001" , "type" : "PAYMENT" , "participant" : { "name" : "NU PAGAMENTOS - IP" , "ispb" : "18236120" }, "holder" : { "name" : "GUSTAVO EXEMPLO" , "document" : "94881558099" , "type" : "NATURAL" } }, "beneficiary" : { "number" : "11111" , "branch" : "0001" , "type" : "CURRENT" , "participant" : { "name" : "DELCRED SCD S.A." , "ispb" : "38224857" }, "holder" : { "document" : "48689840000130" , "type" : "LEGAL" } } } }
Campos do payload PIX_RECEIVED
Campo Descrição eventType"PIX_RECEIVED"correlationIdIdentificador de conciliação do QR Code ou cobrança referenceIdIdentificador de rastreamento do pagamento endToEndIdIdentificador único da transação Pix no SPI amountValor recebido em reais createdAtTimestamp de criação da transação proof.eventTypeTipo de evento interno (PIX_PAYMENT_EFFECTIVE) proof.statusStatus da transação (PIX_EFFECTIVE) proof.payerDados da conta pagadora (número, agência, tipo, banco, titular) proof.beneficiaryDados da conta beneficiária (sua conta)
PIX_PAYMENT_UPDATED Disparado quando o status de um Pix enviado é atualizado. Cobre tanto liquidações bem-sucedidas quanto erros. Também é acionado para devoluções Pix enviadas bem-sucedidas.
Para erros em devoluções enviadas , use PIX_REFUND_PAYMENT_UPDATED — não este evento.
Como registrar: { "eventType" : "PIX_PAYMENT_UPDATED" , "url" : "https://seuservidor.com.br/webhooks/pix-enviado" , "authorizationScheme" : "BEARER" , "authorization" : "seu-token" }
Payload — Pix enviado com sucesso: { "eventType" : "PIX_PAYMENT_EFFECTIVE" , "endToEndId" : "E3822485720231013020122659082578" , "idempotencyKey" : "idempotencyKey999999" , "status" : "PIX_EFFECTIVE" , "amount" : 20.0 , "createdAt" : "2023-10-13T05:01:22.953Z" , "description" : "Pagamento de fatura" , "payer" : { "number" : "999999" , "branch" : "0001" , "type" : "CURRENT" , "participant" : { "ispb" : "38224857" }, "holder" : { "name" : "EMPRESA EXEMPLO" , "document" : "111111111111111" , "type" : "LEGAL" } }, "beneficiary" : { "number" : "1234556" , "branch" : "0001" , "type" : "PAYMENT" , "participant" : { "ispb" : "08561701" }, "holder" : { "name" : "FULANO DA SILVA" , "document" : "11111111111" , "type" : "NATURAL" } } }
Payload — Pix enviado com erro: { "eventType" : "PIX_PAYMENT_ERROR" , "endToEndId" : "E3822485720231013015126180935816" , "idempotencyKey" : "idempotencyKey12345" , "status" : "PIX_ERROR" , "error" : { "code" : "AC06" , "description" : "Conta transacional do usuário recebedor encontra-se bloqueada." }, "amount" : 100.0 , "createdAt" : "2023-10-13T04:51:26.84Z" , "payer" : { "..." : "..." }, "beneficiary" : { "..." : "..." } }
Campos do payload PIX_PAYMENT_UPDATED
Campo Descrição eventType"PIX_PAYMENT_EFFECTIVE" (sucesso) ou "PIX_PAYMENT_ERROR" (erro)endToEndIdIdentificador único da transação idempotencyKeyChave de idempotência usada no envio status"PIX_EFFECTIVE" ou "PIX_ERROR"error.codeCódigo de erro do SPI (quando PIX_ERROR) error.descriptionDescrição do motivo do erro amountValor da transação createdAtTimestamp de criação descriptionDescrição informada pelo pagador payerDados da conta debitada (sua conta) beneficiaryDados da conta creditada (destinatário)
PIX_REFUNDED Disparado quando uma devolução Pix é creditada na sua conta — ou seja, quando alguém devolveu um Pix para você.
Como registrar: { "eventType" : "PIX_REFUNDED" , "url" : "https://seuservidor.com.br/webhooks/pix-devolucao-recebida" , "authorizationScheme" : "BEARER" , "authorization" : "seu-token" }
Payload: { "eventType" : "PIX_REFUNDED" , "endToEndId" : "D38224857202502281818Xo3VqKXafNW" , "originalEndToEndId" : "E38224857202502281816OTCGIA6RVKG" , "amount" : 10 , "bankAccount" : "43028" , "refundCode" : "MD06" , "reasonRefund" : "Pedido reembolso" , "idempotencyKey" : "9ee5dfcb-8733-4271-bceb-64130171b616" , "externalId" : "13c5edd4-616e-43a1-aa80-c25b6ee15967" , "createdAt" : "2025-02-28T18:18:35.861Z" , "proof" : { "endToEndId" : "D38224857202502281818Xo3VqKXafNW" , "originalEndToEndId" : "E38224857202502281816OTCGIA6RVKG" , "status" : "PIX_EFFECTIVE" , "operationType" : "CREDIT_REFUND" , "amount" : 10 , "createdAt" : "2025-02-28T18:18:35.776Z" , "finishedAt" : "2025-02-28T18:18:35.776Z" , "description" : "Pedido reembolso" , "payer" : { "number" : "10138" , "branch" : "0001" , "type" : "CURRENT" , "participant" : { "name" : "DELCRED SCD S.A." , "ispb" : "38224857" }, "holder" : { "name" : "FIDC DELCRED" , "document" : "11468192000181" , "type" : "LEGAL" } }, "beneficiary" : { "number" : "43028" , "branch" : "0001" , "type" : "CURRENT" , "participant" : { "name" : "DELCRED SCD S.A." , "ispb" : "38224857" }, "holder" : { "name" : "JOSE WILSON DOS SANTOS JUNIOR" , "document" : "498925*" , "type" : "NATURAL" } } } }
Campos do payload PIX_REFUNDED
Campo Descrição eventType"PIX_REFUNDED"endToEndIdIdentificador único da devolução originalEndToEndIdIdentificador da transação Pix original que gerou esta devolução amountValor devolvido bankAccountNúmero da conta que recebeu a devolução refundCodeCódigo de motivo da devolução (ex: "MD06") reasonRefundDescrição textual do motivo idempotencyKeyChave de idempotência externalIdIdentificador externo para conciliação proof.operationType"CREDIT_REFUND"proof.statusStatus da devolução (PIX_EFFECTIVE) proof.payerQuem originou a devolução proof.beneficiarySua conta (que recebeu de volta)
PIX_REFUND_PAYMENT_UPDATED Disparado quando ocorre um erro ao processar uma devolução Pix que você enviou. Não é acionado para devoluções bem-sucedidas — para essas, use PIX_PAYMENT_UPDATED.
Como registrar: { "eventType" : "PIX_REFUND_PAYMENT_UPDATED" , "url" : "https://seuservidor.com.br/webhooks/pix-devolucao-erro" , "authorizationScheme" : "BEARER" , "authorization" : "seu-token" }
Payload: { "status" : "PIX_ERROR" , "error" : { "code" : "DEL20" , "description" : "Pix original ainda não foi processado." }, "eventType" : "PIX_REFUND_PAYMENT_ERROR" , "endToEndId" : "D38224857202505151236QaPfJMQyyRj" , "idempotencyKey" : "E38224857202505151235EU6L6UCKIAM" , "correlationId" : null , "amount" : 0.01 , "createdAt" : "2025-05-15T12:36:48" , "finishedAt" : "2025-05-15T12:36:48" , "description" : null , "payer" : null , "beneficiary" : null }
Campos do payload PIX_REFUND_PAYMENT_UPDATED
Campo Descrição eventType"PIX_REFUND_PAYMENT_ERROR"status"PIX_ERROR"error.codeCódigo interno do erro error.descriptionDescrição do erro endToEndIdIdentificador da devolução com erro idempotencyKeyChave de idempotência da devolução original correlationIdCorrelation ID da transação (pode ser nulo) amountValor que seria devolvido createdAt / finishedAtTimestamps do processamento
