Webhooks

O PagSeguro poderá 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.

Configurando o recebimento de notificação

Para receber notificações via webhook utilizando a API de Cobrança é necessário enviar no payload da cobrança 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).

Eventos transacionais

Cartão de crédito

  • AUTHORIZED
  • PAID
  • DECLINED
  • CANCELED

Boleto bancário

  • WAITING
  • PAID
  • CANCELED

Exemplo de payload enviado na notificação:

{
  "id": "CHAR_992582af-febf-44fb-994b-81cd00b743b0",
  "reference_id": "ref0001",
  "status": "PAID",
  "created_at": "2019-08-19T18:09:45.294-03:00",
  "paid_at": "2019-08-19T18:09:45.294-03:00",
  "description": "Pagamento de teste",
  "amount": {
    "value": 500,
    "currency": "BRL",
    "summary": {
      "total": 500,
      "paid": 500,
      "refunded": 0
    }
  },
  "payment_response": {
    "code": "20000",
    "message": "SUCESSO"
  },
  "payment_method": {
    "type": "CREDIT_CARD",
    "installments": 1,
    "capture": true,
    "card": {
      "brand": "MASTERCARD",
      "first_digits": "411111",
      "last_digits": "1111",
      "exp_month": "02",
      "exp_year": "2026",
      "holder": {
        "name": "Nome Sobrenome"
      }
    }
  },
  "links": [
    {
      "rel": "SELF",
      "href": "https://api.pagseguro.com/charges/992582af-febf-44fb-994b-81cd00b743b0",
      "media": "application/json",
      "type": "GET"
    },
    {
      "rel": "CHARGE.CAPTURE",
      "href": "https://api.pagseguro.com/charges/992582af-febf-44fb-994b-81cd00b743b0/capture",
      "media": "application/json",
      "type": "POST"
    },
    {
      "rel": "CHARGE.CANCEL",
      "href": "https://api.pagseguro.com/charges/992582af-febf-44fb-994b-81cd00b743b0/cancel",
      "media": "application/json",
      "type": "POST"
    }
  ],
  "metadata": {}
}

📘

WEBHOOK = RESPONSE

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.

👍

Confirmando autenticidade da notificação

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

Veja como fazer essa confirmação de autenticidade usando SHA256 aqui.

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:

1. Primeiro Passo: Tratar a notificação

Veja exemplo abaixo:

notificationCode=093C100E7FA87FA8C0B664B79F8359773B96
notificationType=transaction

Campo

Tipo

Descrição

notificationCode

String (36 caracteres)

Identifica a notificação.
É 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

É a mesma chave de autenticação utilizada
nas requisições da Charge.

2. Segundo Passo: Consultar as informações no PagSeguro

Para saber o status que foi notificado nesse formato, é necessário realizar um GET na API de notificação, cujo endpoint segue abaixo:

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

Veja exemplo:

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'))
<?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>

📘

Documentação

Através desse link aqui você encontra os detalhes do payload da notificação em formato XML