Webhook

Introdução

Webhook é um recurso que permite que o PicPay envie notificações para o seu sistema a cada mudança de status de uma charge e a resposta da autenticação 3DS. Ele é útil para que você possa manter o seu sistema atualizado com o status de cada charge, sem precisar consultar a API do PicPay a todo momento.

Para receber as notificações, você precisa configurar a URL no Painel Lojista com o endereço do seu sistema que irá receber as notificações. Após essa configuração, o PicPay irá enviar uma requisição HTTP POST para a URL configurada a cada mudança de status de uma charge.

Configurando a URL de notificação

Para configurar a URL de notificação, acesse o Painel Lojista e siga os passos abaixo:

1. Acesse o menu Configurações que fica no dropdown do canto superior direito da tela.
2. Clique na aba Meu checkout.
3. Ative a funcionalidade URL de notificação clicando no botão toggle, e informe a URL do seu sistema que irá receber as notificações.
   1. A URL deve ser HTTPS.
   2. A URL não pode conter nenhum query parameter.
   3. Não é permitido usar um IPv4 como URL de notificação.
4. Finalize clicando em Salvar alterações.

Pronto! A partir desse momento, o PicPay passará a enviar notificações para a URL configurada.

Autenticação

Após a configuração da URL de notificação, o PicPay irá gerar um token de autenticação, que será exibido na tela. Certifique-se de salvar esse token em um local seguro, pois não será possível recuperá-lo posteriormente. O PicPay incluirá esse token no cabeçalho Authorization de cada requisição.

Contrato e Exemplos

No corpo da requisição enviada pelo PicPay, você receberá um objeto JSON com as informações sobre a charge que teve o pagamento realizado. Na requisição haverá uma header event_type que pode possuir o seguinte valor: TransactionUpdateMessage

Exemplo de webhook para atualização de status da Charge

Abaixo, você pode ver um exemplo do corpo de uma requisição de notificação de uma charge que foi criada e paga.

{
   "type": "PAYMENT",
   "eventDate": "2025-04-16T11:30:04.157929932",
   "merchantDocument": "47723455000100", 
   "merchantCode": "000000001179422", 
   "id": "d65712a5-6222-4156-883a-d89e5fa9c87b", 
   "data": {
      "status": "PAID", 
      "amount": 10000, 
      "originalAmount": 10000, 
      "refundedAmount": 0, 
      "customer": {
          "document": "01414553064", 
          "documentType": "CPF", 
          "email": "pessoa.dev@picpay.com", 
          "name": "Pessoa desenvolvedora"
       }, 
      "merchantChargeId": "6751cac1-9e13-437d-bbf9-8f00708b9b20", 
      "smartCheckoutId": null, 
      "paymentSource": "GATEWAY", 
      "lateCapture": false, 
      "transactions": [
           {
               "createdAt": "2025-04-16T14:29:31.393779",
               "transactionId": "160784f8-e433-4c3a-b587-d78abe1725da",
               "status": "PAID",
               "numberOfInstallments": 2,
               "softDescriptor": "PicPay",
               "paymentType": "PIX",
               "amount": 10000,
               "originalAmount": 10000,
               "refundedAmount": 0,
               "updatedAt": "2025-04-16T14:30:04.109002406",
               "pix": {
                  "qrCode": "00033526810014br.gov.bcb.pix2559qr-code.picpay.com/pix/d4700523-263b-4103-8a4c-ccfe2a80d03d5204000053039865802BR5917EMPRESA6009Itu62070503***0102F1F2", 
                  "qrCodeBase64": null, 
                  "endToEndId": "E00416911112501234429olrr6BQh8vW", 
                  "payer": {
                     "id": "26204109",
                     "name": "Amanda Barbosa", 
                     "documentNumber": "29708061000", 
                     "type": "REGULAR", 
                     "bankIspb": "22896431", 
                     "branchNumber": "1", 
                     "bankName": "PICPAY"
                  }
               }
           }
       ]
   }
}

Prefere ver um exemplo como um curl? Segue abaixo:

curl -X 'POST' 'https://yourdomain.com/webhook' \
-H 'connection: close' \
-H 'host: yourdomain.com' \
-H 'accept-encoding: gzip, compress, deflate, br' \
-H 'content-length: 1830' \
-H 'user-agent: axios/1.4.0' \
-H 'authorization: a45c2dee-6435-1234-5678-b2a5f0ae7a8a' \
-H 'event-type: TransactionUpdateMessage' \
-H 'content-type: application/json' \
-H 'accept: application/json, text/plain, */*' \
-d $'{
   "type": "PAYMENT",
   "eventDate": "2025-04-16T11:30:04.157929932",
   "merchantDocument": "47723455000100",
   "merchantCode": "000000001179422",
   "id": "d65712a5-6222-4156-883a-d89e5fa9c87b",
   "data": {
       "status": "PAID",
       "amount": 10000,
       "originalAmount": 10000,
       "refundedAmount": 0,
       "customer": {
           "document": "01414553064",
           "documentType": "CPF",
           "email": "pessoa.dev@picpay.com",
           "name": "Pessoa desenvolvedora"
       },
       "merchantChargeId": "6751cac1-9e13-437d-bbf9-8f00708b9b20",
       "smartCheckoutId": null,
       "paymentSource": "GATEWAY",
       "lateCapture": false,
       "transactions": [
           {
               "createdAt": "2025-04-16T14:29:31.393779",
               "transactionId": "160784f8-e433-4c3a-b587-d78abe1725da",
               "status": "PAID",
               "numberOfInstallments": 2,
               "softDescriptor": "PicPay",
               "paymentType": "PIX",
               "amount": 10000,
               "originalAmount": 10000,
               "refundedAmount": 0,
               "updatedAt": "2025-04-16T14:30:04.109002406",
               "pix": {
                   "qrCode": "00033526810014br.gov.bcb.pix2559qr-code.picpay.com/pix/d4700523-263b-4103-8a4c-ccfe2a80d03d5204000053039865802BR5917EMPRESA6009Itu62070503***0102F1F2",
                   "qrCodeBase64": null,
                   "endToEndId": "E00416911112501234429olrr6BQh8vW",
                   "payer": {
                     "id": "26204109", 
                     "name": "Amanda Barbosa", 
                     "documentNumber": "29708061000", 
                     "type": "REGULAR", 
                     "bankIspb": "22896431", 
                     "branchNumber": "1", 
                     "bankName": "PICPAY"
                  }
               }
           }
       ]
   }
}'