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:

Acesse o menu Ajustes que fica no dropdown do canto superior direito da tela.
Clique na aba Meu checkout.
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.
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 status alterado ou sobre o resultado da autenticação 3DS. Na requisição haverá uma header event_type que pode possuir os seguintes valores: TransactionUpdateMessage para eventos de Wallet, Credit e PIX ou Challenge3dsUpdateMessage para eventos de 3DS.

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

Abaixo, você pode ver exemplos dos corpos das requisições de notificações de charges que foram enviadas.

Exemplo de webhook para Wallet

{
  "type": "PAYMENT",
  "eventDate": "2024-07-01T16:00:00-03:00",
  "merchantDocument": "123456789012",
  "id": "21b91897-a897-49bc-b16e-6256f0bf2368",
  "merchantCode": "1234",
  "data": {
    "status": "AUTHORIZED",
    "amount": 10000,
    "originalAmount": 10000,
    "refundedAmount": 0,
    "customer": {
      "document": "123456789",
      "documentType": "CPF",
      "email": "pessoa.silva@email.com",
      "name": "Pessoa Da Silva"
    },
    "merchantChargeId": "61e35ec2-caa8-4598-bed5-d43e25e14151",
    "smartCheckoutId": null,
    "paymentSource": "GATEWAY",
    "lateCapture": false,
    "transactions": [
      {
        "paymentType": "WALLET",
        "transactionId": "07bef486-8d86-41b8-804b-f68e343a1791",
        "status": "CAPTURED",
        "numberOfInstallments": 0,
        "softDescriptor": "PicPay",
        "amount": 10000,
        "originalAmount": 10000,
        "refundedAmount": 0,
        "createdAt": "2024-07-01T16:00:00-03:00",
        "updatedAt": "2024-07-01T16:01:00-03:00",
        "wallet": {
          "expiresAt": "2024-07-01T16:04:00-03:00",
          "qrCode": "xpto",
          "qrCodeBase64": "xpto in base64"
        }
      }
    ]
  }
}

Prefere ver um exemplo de WALLET 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": "2024-07-01T16:00:00-03:00",
  "merchantDocument": "123456789012",
  "id": "21b91897-a897-49bc-b16e-6256f0bf2368",
  "merchantCode": "1234",
  "data": {
    "status": "AUTHORIZED",
    "amount": 10000,
    "originalAmount": 10000,
    "refundedAmount": 0,
    "customer": {
      "document": "123456789",
      "documentType": "CPF",
      "email": "pessoa.silva@email.com",
      "name": "Pessoa Da Silva"
    },
    "merchantChargeId": "61e35ec2-caa8-4598-bed5-d43e25e14151",
    "smartCheckoutId": null,
    "paymentSource": "GATEWAY",
    "lateCapture": false,
    "transactions": [
      {
        "paymentType": "WALLET",
        "transactionId": "07bef486-8d86-41b8-804b-f68e343a1791",
        "status": "CAPTURED",
        "numberOfInstallments": 0,
        "softDescriptor": "PicPay",
        "amount": 10000,
        "originalAmount": 10000,
        "refundedAmount": 0,
        "createdAt": "2024-07-01T16:00:00-03:00",
        "updatedAt": "2024-07-01T16:01:00-03:00",
        "wallet": {
          "expiresAt": "2024-07-01T16:04:00-03:00",
          "qrCode": "xpto",
          "qrCodeBase64": "xpto in base64"
        }
      }
    ]
  }
}'

Exemplo de webhook para Credit

{
  "type": "PAYMENT",
  "eventDate": "2024-07-01T16:00:00-03:00",
  "merchantDocument": "123456789012",
  "id": "21b91897-a897-49bc-b16e-6256f0bf2368",
  "merchantCode": "1234",
  "data": {
    "status": "PAID",
    "amount": 10000,
    "originalAmount": 10000,
    "refundedAmount": 0,
    "customer": {
      "document": "123456789",
      "documentType": "CPF",
      "email": "pessoa.silva@email.com",
      "name": "Pessoa Da Silva"
    },
    "merchantChargeId": "61e35ec2-caa8-4598-bed5-d43e25e14151",
    "smartCheckoutId": null,
    "paymentSource": "GATEWAY",
    "lateCapture": false,
    "transactions": [
      {
        "paymentType": "CREDIT",
        "transactionId": "07bef486-8d86-41b8-804b-f68e343a1791",
        "status": "PAID",
        "numberOfInstallments": 2,
        "softDescriptor": "PicPay",
        "amount": 10000,
        "originalAmount": 10000,
        "refundedAmount": 0,
        "createdAt": "2024-07-01T16:00:00-03:00",
        "updatedAt": "2024-07-01T16:01:00-03:00",
        "credit": {
          "cardholderName": "Ester****************",
          "cardholderDocument": "111********",
          "expirationMonth": 11,
          "brand": "MASTERCARD",
          "nsu": 118786,
          "expirationYear": 2024,
          "authorizationCode": 331000,
          "authorizationResponseCode": 331000,
          "reasonCode": 00,
          "reasonMessage": "",
          "acquirerName": "PICPAY",
          "installmentType": "MERCHANT",
          "subMerchant": {
            "id": "13874098123674",
            "mcc": "5299",
            "document": "12344567890",            
            "address": {
              "city": "Vitória",
              "country": "Brasil",
              "number": "320",
              "street": "R. Gil Martins de Oliveira",
              "state": "ES",
              "zipCode": "29056300"
            }
          }
        }
      }
    ]
  }
}

Prefere ver um exemplo de CREDIT 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": "2024-07-01T16:00:00-03:00",
  "merchantDocument": "123456789012",
  "id": "21b91897-a897-49bc-b16e-6256f0bf2368",
  "merchantCode": "1234",
  "data": {
    "status": "PAID",
    "amount": 10000,
    "originalAmount": 10000,
    "refundedAmount": 0,
    "customer": {
      "document": "123456789",
      "documentType": "CPF",
      "email": "pessoa.silva@email.com",
      "name": "Pessoa Da Silva"
    },
    "merchantChargeId": "61e35ec2-caa8-4598-bed5-d43e25e14151",
    "smartCheckoutId": null,
    "paymentSource": "GATEWAY",
    "lateCapture": false,
    "transactions": [
      {
        "paymentType": "CREDIT",
        "transactionId": "07bef486-8d86-41b8-804b-f68e343a1791",
        "status": "PAID",
        "numberOfInstallments": 2,
        "softDescriptor": "PicPay",
        "amount": 10000,
        "originalAmount": 10000,
        "refundedAmount": 0,
        "createdAt": "2024-07-01T16:00:00-03:00",
        "updatedAt": "2024-07-01T16:01:00-03:00",
        "credit": {
          "cardholderName": "Ester****************",
          "cardholderDocument": "111********",
          "expirationMonth": 11,
          "brand": "MASTERCARD",
          "nsu": 118786,
          "expirationYear": 2024,
          "authorizationCode": 331000,
          "authorizationResponseCode": 331000,
          "reasonCode": 00,
          "reasonMessage": "",
          "acquirerName": "PICPAY",
          "installmentType": "MERCHANT",
          "subMerchant": {
            "id": "13874098123674",
            "mcc": "5299",
            "document": "12344567890",            
            "address": {
              "city": "Vitória",
              "country": "Brasil",
              "number": "320",
              "street": "R. Gil Martins de Oliveira",
              "state": "ES",
              "zipCode": "29056300"
            }
          }
        }
      }
    ]
  }
}'

Exemplo de webhook para Pix

{
   "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 de PIX 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"
                  }
               }
           }
       ]
   }
}'

Exemplo de webhook para 3DS

Caso a transação seja realizada com a autenticação 3DS, você receberá requisição de notificação que informa o resultado do desafio da autenticação 3DS. Abaixo está um exemplo do corpo da requisição em Json:

{
  "type": "THREE_DS_CHALLENGE",
  "eventDate": "2025-04-16T11:30:04.157929932",
  "merchantDocument": "123456789012",
  "id": "21b91897-a897-49bc-b16e-6256f0bf2368",
  "merchantCode": "72425145000145",
  "data": {
    "status": "Approved",
    "paresStatus": "Y",
    "eciRaw": "05",
    "merchantChargeId": "61e35ec2-caa8-4598-bed5-d43e25e14151",
    "chargeId": "bac0ffd7-e4cb-48c7-9f3e-a05ff7eb40a1"
  }
}

Prefere ver um exemplo de 3DS 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: Challenge3dsUpdateMessage' \
-H 'content-type: application/json' \
-H 'accept: application/json, text/plain, */*' \
-d $'{
  "type": "THREE_DS_CHALLENGE",
  "eventDate": "2025-04-16T11:30:04.157929932",
  "merchantDocument": "123456789012",
  "id": "21b91897-a897-49bc-b16e-6256f0bf2368",
  "merchantCode": "72425145000145",
  "data": {
    "status": "Approved",
    "paresStatus": "Y",
    "eciRaw": "05",
    "merchantChargeId": "61e35ec2-caa8-4598-bed5-d43e25e14151",
    "chargeId": "bac0ffd7-e4cb-48c7-9f3e-a05ff7eb40a1"
  }
}'

Webhook

Introdução​

Configurando a URL de notificação​

Autenticação​

Contrato e Exemplos​

Exemplos de webhook para atualização de status da Charge​

Exemplo de webhook para Wallet​

Exemplo de webhook para Credit​

Exemplo de webhook para Pix​

Exemplo de webhook para 3DS​