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 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 ou Challenge3dsUpdateMessage

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 autorizada.

{
  "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",
        "amount": 10000,
        "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 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",
        "amount": 10000,
        "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 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",
  "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"
  }
}

Example as a curl? See below:

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",
  "merchantDocument": "123456789012",
  "id": "21b91897-a897-49bc-b16e-6256f0bf2368",
  "merchantCode": "1234",
  "data": {
    "status": "Approved",
    "paresStatus": "Y",
    "eciRaw": "05",
    "merchantChargeId": "string",
    "chargeId": "string"
  }
}'