Search
Entrar no Portal do DesenvolvedorCriar Conta
Entrar no Portal do DesenvolvedorCriar Conta
Start typing to search…

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@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"
        }
    ]
}

{
    "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.

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)
CHECKOUT
x-product-id ORDE_XXXXXXXXXXXX
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:

CampoTipoDescrição
notificationCodeString (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.
notificationTypeString (41 caracteres)Tipo de notificação enviada.
token_apiStringEsse 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>

Updated over 1 year ago

Did this page help you?

Updated over 1 year ago

Did this page help you?

© 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)