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:

{
    "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 protected]",
        "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"
        }
    ]
}

{
    "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 protected]",
        "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.

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.

Header	Valor	Tipo
x-product-origin	`ORDER`	String (128 caracteres)
x-product-origin	`CHECKOUT`
x-product-id	`ORDE_XXXXXXXXXXXX`
x-product-id	`CHEC_XXXXXXXXXXXX`

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.

Método de pagamento	Status transacional	Descrição
Cartão de Crédito	`AUTHORIZED`	Esse status indica que a transação foi autorizada.
	`PAID`	A transação foi concluída com sucesso.
	`IN_ANALYSIS`	A transação está em análise pela operadora do Cartão de Crédito.
	`DECLINED`	Esse status indica que a transação foi rejeitada.
	`CANCELED`	A transação foi cancelada sem ter sido finalizada.
Boleto Bancário	`WAITING`	Aguardando pagamento ou aprovação do Boleto Bancário.
	`PAID`	A transação foi concluída com sucesso.
	`CANCELED`	A 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.

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.

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.

Método de pagamento	Status pós-transacional	Descrição
Cartão de Crédito e Boleto Bancário	`Disponível`	Este status indica que o valor da transação está disponível para saque.
	`Devolvida`	O valor da transação foi devolvido ao comprador.
	`Cancelada`	A 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ária`	O comprador abriu uma solicitação de chargeback junto à operadora de cartão de crédito.

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:

<https://ws.pagseguro.uol.com.br/v3/transactions/notifications/{notificationCode}?email={email_conta_pagseguro}&token={token_api}>

O bloco de código a seguir apresenta esse procedimento para as liguagens Java e Python.

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();
}

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 version="1.0" encoding="ISO-8859-1" standalone="yes"?>
<transaction>
    <date>2019-08-19T18:10:02.000-03:00</date>
    <code>992582AF-FEBF-44FB-994B-81CD00B743B0</code>
    <type>1</type>
    <status>4</status>
    <lastEventDate>2019-09-18T03:31:52.000-03:00</lastEventDate>
    <paymentMethod>
        <type>1</type>
        <code>102</code>
    </paymentMethod>
    <grossAmount>5.00</grossAmount>
    <discountAmount>0.00</discountAmount>
    <creditorFees>
        <installmentFeeAmount>0.00</installmentFeeAmount>
        <intermediationRateAmount>0.40</intermediationRateAmount>
        <intermediationFeeAmount>0.20</intermediationFeeAmount>
    </creditorFees>
    <netAmount>4.40</netAmount>
    <extraAmount>0.00</extraAmount>
    <escrowEndDate>2019-09-18T01:00:00.000-03:00</escrowEndDate>
    <installmentCount>1</installmentCount>
    <itemCount>1</itemCount>
    <items>
        <item>
            <id>1</id>
            <description>Web</description>
            <quantity>1</quantity>
            <amount>5.00</amount>
        </item>
    </items>
    <primaryReceiver>
        <publicKey>PUB********************************</publicKey>
    </primaryReceiver>
</transaction>

Webhooks

📘
Formato e conteúdo dos webhooks

Configurando o recebimento de notificação

👍
Confirmando autenticidade da notificação

Headers de identificação

Status de eventos transacionais

Eventos pós-transacionais

❗️
ATENÇÃO

1. Tratar a notificação

2. Consultar as informações no Pagbank

📘Formato e conteúdo dos webhooks

Configurando o recebimento de notificação

👍Confirmando autenticidade da notificação

Headers de identificação

Status de eventos transacionais

Eventos pós-transacionais

❗️ATENÇÃO

1. Tratar a notificação

2. Consultar as informações no Pagbank

📘
Formato e conteúdo dos webhooks

👍
Confirmando autenticidade da notificação

❗️
ATENÇÃO