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
IN_ANALYSIS
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