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 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).
Eventos transacionais
Cartão de crédito
AUTHORIZEDPAIDIN_ANALYSISDECLINEDCANCELED
Boleto bancário
WAITINGPAIDCANCELED
Exemplo de payload enviado na notificação:
{
"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",
"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"
}
]
}
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