O PagBank poderá enviar notificações via webhook para seu ambiente sempre que um evento (uma mudança de status de transação ou de checkout) 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 Checkout é necessário enviar no payload o campo opcional 'notification_urls' para receber atualização de status do Checkout e 'payment_notification_url' para receber atualizações de Status de Pagamento.
Assim, sempre que ocorrer um evento nessa transação o PagSeguro enviará as notificações para a URL de destino (método POST).
Eventos de webhook
Transacionais:
PAID
: Indica que o pagamento foi capturado.IN_ANALYSIS
: Indica que o comprador optou por pagar com um cartão de crédito e o PagBank está analisando o risco da transação.DECLINED
: Indica que a cobrança foi negada pelo PagBank ou Emissor.CANCELED
: Indica que a cobrança foi canceladaWAITING
: Significa que a cobrança está aguardando pagamento
De Checkout:
EXPIRED
: Indica que o Checkout expirou. A expiração ocorre por um tempo default de 2 horas, caso deseje personalizar esse tempo é possível via envio do pamâmetroexpiration_date
Exemplo de payload enviado na notificação:
{
"id": "CHEC_120301FA-8B8B-4C25-B07D-A4541EB78EB5",
"reference_id": "6a45813f-2d11-4a4b-a91c-8cfe49862858",
"expiration_date": "2023-06-14T21:45:00-03:00",
"created_at": "2023-06-14T15:45:00-03:00",
"status": "INACTIVE",
"customer": {
"name": "joao",
"email": "[email protected]",
"tax_id": "00000000000",
"phone": {
"country": "+55",
"area": "27",
"number": "999999999"
}
},
"customer_modifiable": true,
"items": [
{
"reference_id": "123",
"name": "Compra Checkout Pagbank",
"quantity": 1,
"unit_amount": 500,
"dimensions": {
"length": 1234,
"width": 10,
"height": 12345
},
"weight": 10,
"image_url": "https://www.google.com"
}
],
"additional_amount": 0,
"discount_amount": 0,
"shipping": {
"type": "FREE",
"service_type": "PAC",
"amount": 0,
"address": {
"country": "BRA",
"region_code": "SP",
"city": "São Paulo",
"postal_code": "01452002",
"street": "Faria Lima",
"number": "1384",
"locality": "Pinheiros",
"complement": "5 andar"
},
"address_modifiable": true
},
"redirect_url": "https://pagseguro.uol.com.br",
"return_url": "https://pagseguro.uol.com.br",
"notification_urls": [
"https://pagseguro.uol.com.br"
],
"links": [
{
"rel": "PAY",
"href": "https://pagamento.pagseguro.uol.com.br/pagamento?code=xxxx",
"method": "GET"
},
{
"rel": "SELF",
"href": "https://api.pagseguro.com/checkouts/CHEC_xxxx",
"method": "GET"
},
{
"rel": "INACTIVATE",
"href": "https://api.pagseguro.com/checkouts/CHEC_xxxx/activate",
"method": "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": "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"
}
]
}
Confirmando autenticidade da notificação
Para 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, 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 HSA256 aqui)