Webhooks

O PagBank poderá enviar notificações via webhook para seu ambiente sempre que um evento (uma mudança de status de transação ou de checkout) acontecer, possibilitando a automação de seus processos de gestão de vendas.

Configurando o recebimento de notificação

Para receber notificações via webhook utilizando a API de Checkout é necessário enviar no payload o campo opcional notification_urls. Assim, sempre que um evento associado ao checkout ocorrer, o PagBank enviará uma notificação para a URL definida por você utilizando o método POST.

Eventos de webhook

A API de Checkout do PagBank gera webhooks a partir de dois tipos de eventos, transacionais e de Checkout. Os eventos transacionais ocorrem quando uma alteração do status do pagamento ocorre. Já webhooks de checkout ocorrem quando o status do webhook muda.

Transacional

Os webhooks transacionais podem ser vinculados a mudança para um dos status apresentados abaixo.

Status transacionalDescrição
PAIDIndica que o pagamento foi capturado.
IN_ANALYSISO comprador optou por pagar com um cartão de crédito e o PagBank está analisando o risco da transação.
DECLINEDA cobrança foi rejeitada pelo PagBank ou pelo emissor do cartão.
CANCELEDA cobrança foi cancelada sem ter sido finalizada.
WAITINGAguardando o pagamento da transação.

Checkout

Os webhooks de checkout podem ser vinculados a mudança para um dos status apresentados abaixo.

Status do checkoutDescrição
EXPIREDIndica que a validade do checkout criado expirou. Por padrão, todo checkout criado tem 2 horas de validade. Você pode alterar isso ao definir a data de expiração através do parâmetro expiration_date ao criar o checkout.

Exemplo de payload enviado na notificação:

No bloco de código a seguir são apresentados exemplos de payload enviados na notificação.

{ "id": "CHEC_120301FA-8B8B-4C25-B07D-A4541EB78EB5", "reference_id": "6a45813f-2d11-4a4b-a91c-8cfe49862858", "expiration_date": "2023-06-14T21:45:00-03:00", "created_at": "2023-06-14T15:45:00-03:00", "status": "INACTIVE", "customer": { "name": "joao", "email": "joao@joao.com", "tax_id": "00000000000", "phone": { "country": "+55", "area": "27", "number": "999999999" } }, "customer_modifiable": true, "items": [ { "reference_id": "123", "name": "Compra Checkout Pagbank", "quantity": 1, "unit_amount": 500, "dimensions": { "length": 1234, "width": 10, "height": 12345 }, "weight": 10, "image_url": "https://www.google.com" } ], "additional_amount": 0, "discount_amount": 0, "shipping": { "type": "FREE", "service_type": "PAC", "amount": 0, "address": { "country": "BRA", "region_code": "SP", "city": "São Paulo", "postal_code": "01452002", "street": "Faria Lima", "number": "1384", "locality": "Pinheiros", "complement": "5 andar" }, "address_modifiable": true }, "redirect_url": "https://pagseguro.uol.com.br", "return_url": "https://pagseguro.uol.com.br", "notification_urls": [ "https://pagseguro.uol.com.br" ], "links": [ { "rel": "PAY", "href": "https://pagamento.pagseguro.uol.com.br/pagamento?code=xxxx", "method": "GET" }, { "rel": "SELF", "href": "https://api.pagseguro.com/checkouts/CHEC_xxxx", "method": "GET" }, { "rel": "INACTIVATE", "href": "https://api.pagseguro.com/checkouts/CHEC_xxxx/activate", "method": "POST" } ] }
{ "id": "ORDE_F87334AC-BB8B-42E2-AA85-8579F70AA328", "reference_id": "ex-00001", "created_at": "2020-11-21T23:23:22.69-03:00", "shipping": { "address": { "street": "Avenida Brigadeiro Faria Lima", "number": "1384", "complement": "apto 12", "locality": "Pinheiros", "city": "São Paulo", "region_code": "SP", "country": "BRA", "postal_code": "01452002" } }, "items": [ { "reference_id": "referencia do item", "name": "nome do item", "quantity": 1, "unit_amount": 500 } ], "customer": { "name": "Jose da Silva", "email": "email@test.com", "tax_id": "12345678909", "phones": [ { "country": "55", "area": "11", "number": "999999999", "type": "MOBILE" } ] }, "charges": [ { "id": "CHAR_F1F10115-09F4-4560-85F5-A828D9F96300", "reference_id": "referencia da cobranca", "status": "PAID", "created_at": "2020-11-21T23:30:22.695-03:00", "paid_at": "2020-11-21T23:30:24.352-03:00", "description": "descricao da cobranca", "amount": { "value": 500, "currency": "BRL", "summary": { "total": 500, "paid": 500, "refunded": 0 } }, "payment_response": { "code": "20000", "message": "SUCESSO", "reference": "1606012224352" }, "payment_method": { "type": "PIX", "holder": { "name": "Francisco da Silva", "tax_id": "***534218**" } }, "links": [ { "rel": "SELF", "href": "https://sandbox.api.pagseguro.com/charges/CHAR_F1F10115-09F4-4560-85F5-A828D9F96300", "media": "application/json", "type": "GET" }, { "rel": "CHARGE.CANCEL", "href": "https://sandbox.api.pagseguro.com/charges/CHAR_F1F10115-09F4-4560-85F5-A828D9F96300/cancel", "media": "application/json", "type": "POST" } ] } ], "qr_code": [ { "id": "QRCO_86FE511B-E945-4FE1-BB5D-297974C0DB74", "amount": { "value": 500 }, "text": "00020101021226600016BR.COM.PAGSEGURO013686FE511B-E945-4FE1-BB5D-297974C0DB7452048999530398654045.005802BR5922Rafael Gouveia Firmino6009SAO PAULO63049879", "links": [ { "rel": "QRCODE.PNG", "href": "https://sandbox.api.pagseguro.com/qrcode/QRCO_86FE511B-E945-4FE1-BB5D-297974C0DB74/png", "media": "image/png", "type": "GET" }, { "rel": "QRCODE.BASE64", "href": "https://sandbox.api.pagseguro.com/qrcode/QRCO_86FE511B-E945-4FE1-BB5D-297974C0DB74/base64", "media": "text/plain", "type": "GET" } ] } ], "links": [ { "rel": "SELF", "href": "https://sandbox.api.pagseguro.com/orders/ORDE_F87334AC-BB8B-42E2-AA85-8579F70AA328", "media": "application/json", "type": "GET" }, { "rel": "PAY", "href": "https://sandbox.api.pagseguro.com/orders/ORDE_F87334AC-BB8B-42E2-AA85-8579F70AA328/pay", "media": "application/json", "type": "POST" } ] }
{ "id": "ORDE_F87334AC-BB8B-42E2-AA85-8579F70AA328", "reference_id": "ex-00001", "created_at": "2020-11-21T23:23:22.69-03:00", "shipping": { "address": { "street": "Avenida Brigadeiro Faria Lima", "number": "1384", "complement": "apto 12", "locality": "Pinheiros", "city": "São Paulo", "region_code": "SP", "country": "BRA", "postal_code": "01452002" } }, "items": [ { "reference_id": "referencia do item", "name": "nome do item", "quantity": 1, "unit_amount": 500 } ], "customer": { "name": "Jose da Silva", "email": "email@test.com", "tax_id": "12345678909", "phones": [ { "country": "55", "area": "11", "number": "999999999", "type": "MOBILE" } ] }, "charges": [ { "id": "CHAR_F1F10115-09F4-4560-85F5-A828D9F96300", "reference_id": "referencia da cobranca", "status": "PAID", "created_at": "2020-11-21T23:30:22.695-03:00", "paid_at": "2020-11-21T23:30:24.352-03:00", "description": "descricao da cobranca", "amount": { "value": 500, "currency": "BRL", "summary": { "total": 500, "paid": 500, "refunded": 0 } }, "payment_response": { "code": "20000", "message": "SUCESSO", "reference": "1606012224352" }, "payment_method": { "type": "CREDIT_CARD", "installments": 1, "capture": true, "card": { "brand": "visa", "first_digits": "411111", "last_digits": "1111", "exp_month": "12", "exp_year": "2026", "holder": { "name": "Jose da Silva" } } }, "links": [ { "rel": "SELF", "href": "https://sandbox.api.pagseguro.com/charges/CHAR_F1F10115-09F4-4560-85F5-A828D9F96300", "media": "application/json", "type": "GET" }, { "rel": "CHARGE.CANCEL", "href": "https://sandbox.api.pagseguro.com/charges/CHAR_F1F10115-09F4-4560-85F5-A828D9F96300/cancel", "media": "application/json", "type": "POST" } ] } ], "qr_code": [ { "id": "QRCO_86FE511B-E945-4FE1-BB5D-297974C0DB74", "amount": { "value": 500 }, "text": "00020101021226600016BR.COM.PAGSEGURO013686FE511B-E945-4FE1-BB5D-297974C0DB7452048999530398654045.005802BR5922Rafael Gouveia Firmino6009SAO PAULO63049879", "links": [ { "rel": "QRCODE.PNG", "href": "https://sandbox.api.pagseguro.com/qrcode/QRCO_86FE511B-E945-4FE1-BB5D-297974C0DB74/png", "media": "image/png", "type": "GET" }, { "rel": "QRCODE.BASE64", "href": "https://sandbox.api.pagseguro.com/qrcode/QRCO_86FE511B-E945-4FE1-BB5D-297974C0DB74/base64", "media": "text/plain", "type": "GET" } ] } ], "links": [ { "rel": "SELF", "href": "https://sandbox.api.pagseguro.com/orders/ORDE_F87334AC-BB8B-42E2-AA85-8579F70AA328", "media": "application/json", "type": "GET" }, { "rel": "PAY", "href": "https://sandbox.api.pagseguro.com/orders/ORDE_F87334AC-BB8B-42E2-AA85-8579F70AA328/pay", "media": "application/json", "type": "POST" } ] }

👍

Confirmando autenticidade da notificação

É importante se certificar de que as notificações enviadas ao seu sistema são de propriedade e origem do Pagbank e que o conteúdo não foi manipulado ou sofreu nenhuma intervenção externa. Dessa forma, você pode fazer uma confirmação de autenticidade e garantir a integridade das notificações recebidas pelo seu sistema.

Acesse a página Confirmar autenticidade da notificação para aprender como como confirmar a autenticidade da notificação usando SHA256.

© 1996-2025 Todos os direitos reservados.

PAGSEGURO INTERNET INSTITUIÇÃO DE PAGAMENTO S/A - CNPJ/MF 08.561.701/0001-01

Av. Brigadeiro Faria Lima, 1.384, São Paulo - SP - CEP 01451-001

English
Powered by Localize
Português (Brasil)