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. Assim, sempre que um evento associado ao checkout ocorrer, o PagBank enviará uma notificação para a URL definida por você utilizando o método POST.
Eventos de webhook
A API de Checkout do PagBank gera webhooks a partir de dois tipos de eventos, transacionais e de Checkout. Os eventos transacionais ocorrem quando uma alteração do status do pagamento ocorre. Já webhooks de checkout ocorrem quando o status do webhook muda.
Transacional
Os webhooks transacionais podem ser vinculados a mudança para um dos status apresentados abaixo.
| Status transacional | Descrição |
|---|---|
PAID | Indica que o pagamento foi capturado. |
IN_ANALYSIS | O comprador optou por pagar com um cartão de crédito e o PagBank está analisando o risco da transação. |
DECLINED | A cobrança foi rejeitada pelo PagBank ou pelo emissor do cartão. |
CANCELED | A cobrança foi cancelada sem ter sido finalizada. |
WAITING | Aguardando o pagamento da transação. |
Checkout
Os webhooks de checkout podem ser vinculados a mudança para um dos status apresentados abaixo.
| Status do checkout | Descrição |
|---|---|
EXPIRED | Indica que a validade do checkout criado expirou. Por padrão, todo checkout criado tem 2 horas de validade. Você pode alterar isso ao definir a data de expiração através do parâmetro expiration_date ao criar o checkout. |
Exemplo de payload enviado na notificação:
No bloco de código a seguir são apresentados exemplos de payload enviados 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": "joao@joao.com",
"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@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",
"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.
Acesse a página Confirmar autenticidade da notificação para aprender como como confirmar a autenticidade da notificação usando SHA256.