--- updatedAt: 2026-08-26T16:49:12.000Z agentTools: projectIndex: https://developer.pagbank.com.br/llms.txt --- # Webhooks Os webhooks permitem que os aplicativos forneçam informações em tempo real sempre que um evento ocorre sem a necessidade de solicitações constantes. Assim, requisições sucessivas para verificar se o status da operação foi alterada tornam-se desnecessárias. Após configurar os webhooks, o Pagbank enviará notificações via webhook para seu ambiente sempre que um evento (uma mudança de status de transação) acontecer, possibilitando a automação de seus processos de gestão de vendas. > 📘 Formato e conteúdo dos webhooks > > Por padrão nossos webhooks possuem o mesmo payload (formato e conteúdo) do response síncrono das requisições das APIs na nova plataforma. ## Configurando o recebimento de notificação Para receber notificações via webhook utilizando a API de Pedidos, é necessário enviar no payload o campo opcional `notification_urls`. Assim, sempre que ocorrer um evento nessa transação, o PagSeguro enviará as notificações para a URL de destino (método POST). No bloco de código a seguir são apresentados exemplos de payload enviados na notificação para transações utilizando PIX e cartão de crédito: ```json Pedido pago com PIX { "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", "pix":{ "notification_id": "NTF_13EE7E12-E1E0-4A32-8E1B-B7C06EA49B7F", "end_to_end_id": "E18236120202306271832s05145d8d3d", "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" } ] } ``` ```json Pedido pago com Cartão de Crédito { "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. > > Veja como confirmar a autenticidade da notificação usando SHA256 [aqui](https://developer.pagbank.com.br/devpagbank/reference/confirmar-autenticidade-da-notificacao). ## Headers de identificação O header serve para identificar o produto Pagbank, que originou o pedido. A tabela a seguir apresenta os possíveis tipos de produtos e seus respectivos ids. [block:html] { "html": "\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
HeaderValorTipo
x-product-originORDERString (128 caracteres)
CHECKOUT
x-product-idORDE_XXXXXXXXXXXX
CHEC_XXXXXXXXXXXX
" } [/block] ## Status de eventos transacionais Os status de transação pode variar de um método de pagamento para outro. A tabela a seguir apresenta os possíveis status para transações realizadas com Cartão de Crédito e Boleto Bancário. [block:html] { "html": "\n\n \n \n \n \n \n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n
Método de pagamentoStatus transacionalDescrição
Cartão de CréditoAUTHORIZEDEsse status indica que a transação foi autorizada.
PAIDA transação foi concluída com sucesso.
IN_ANALYSISA transação está em análise pela operadora do Cartão de Crédito.
DECLINEDEsse status indica que a transação foi rejeitada.
CANCELEDA transação foi cancelada sem ter sido finalizada.
Boleto BancárioWAITINGAguardando pagamento ou aprovação do Boleto Bancário.
PAIDA transação foi concluída com sucesso.
CANCELEDA transação foi cancelada sem ter sido finalizada. Quando o comprador opta por pagar com Boleto Bancário e não finaliza o pagamento, a transação assume este status.
" } [/block] ## Eventos pós-transacionais > ❗️ ATENÇÃO > > No momento, eventos de pós-transação (disponibilização de saldo, chargebacks e cancelamentos) serão enviados para a mesma URL, mas em outro formato, conforme exemplo abaixo. ```text EVENTO: CHARGE Disponível notificationCode=093C100E7FA87FA8C0B664B79F8359773B96 notificationType=transaction ``` A tabela a seguir apresenta os possíveis status de eventos pós transacionais para pedidos com Cartão de Crédito e Boleto Bancário. [block:html] { "html": "\n\n\n \n \n \n \n \n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n
Método de pagamentoStatus pós-transacionalDescrição
Cartão de Crédito e
Boleto Bancário		DisponívelEste status indica que o valor da transação está disponível para saque.
DevolvidaO valor da transação foi devolvido ao comprador.
CanceladaA transação foi cancelada sem ter sido finalizada. Por exemplo, quando o comprador opta por pagar com
Boleto Bancário e não finaliza o pagamento, a transação assume este status.
Retenção temporáriaO comprador abriu uma solicitação de chargeback junto à operadora de cartão de crédito.
" } [/block] Os passos seguintes descrevem como você deve proceder com a identificação de eventos pós-transacionais. ### 1. Tratar a notificação O primeiro passo para proceder com notificações derivadas de eventos pós-transacionais é tratar a notificação. A tabela a seguir apresenta a descrição dos parâmetros que você receberá na resposta: | Campo | Tipo | Descrição | | :----------------- | :--------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `notificationCode` | String (36 caracteres) | Este campo identifica a notificação. Ele é usado para consultar a notificação e obter os dados da transação. Note que o código que identifica a notificação não é o mesmo código que identifica a transação. | | `notificationType` | String (41 caracteres) | Tipo de notificação enviada. | | `token_api` | String | Esse parâmetro corresponde a chave de autenticação utilizada nas requisições da API de Cobrança (Charge). | ### 2. Consultar as informações no Pagbank Para saber o status que foi notificado nesse formato, é necessário realizar um GET na API de notificação, cujo endpoint é apresentado como segue: ```Text Endpoint de Notificação ``` O bloco de código a seguir apresenta esse procedimento para as liguagens Java e Python. ```java import java.io.IOException; import org.apache.http.client.methods.CloseableHttpResponse; import org.apache.http.client.methods.HttpGet; import org.apache.http.impl.client.CloseableHttpClient; import org.apache.http.impl.client.HttpClients; import org.apache.http.util.EntityUtils; private static final String URL = "https://ws.pagseguro.uol.com.br/v3/transactions/notifications/{{notificationCode}}?email={{email}}&token={{token}}"; try { CloseableHttpClient client = HttpClients.createDefault(); HttpGet getRequest = new HttpGet(URL); getRequest.setHeader("Content-Type", "application/xml"); CloseableHttpResponse response = client.execute(getRequest); String result = EntityUtils.toString(response.getEntity()); System.out.println(result); client.close(); return response; } catch (IOException e) { e.printStackTrace(); } ``` ```python import requests from xml.etree import ElementTree url = 'https://ws.pagseguro.uol.com.br/v3/transactions/notifications/{{notificationCode}}?email={{email}}&token={{token}}' headers = { 'Content-Type': 'application/xml' } string_xml = response.content xml_tree = ElementTree.fromstring(string_xml) print(ElementTree.tostring(xml_tree, encoding='utf8').decode('utf8')) ``` Um exemplo de resposta no formato XML é apresentado a seguir: ```xml EVENTO: CHARGE Disponível 2019-08-19T18:10:02.000-03:00 992582AF-FEBF-44FB-994B-81CD00B743B0 1 4 2019-09-18T03:31:52.000-03:00 1 102 5.00 0.00 0.00 0.40 0.20 4.40 0.00 2019-09-18T01:00:00.000-03:00 1 1 1 Web 1 5.00 PUB******************************** ```