Webhook

Introduction

Webhook is a feature that allows PicPay to send notifications to your system whenever the status of a charge changes. It is useful so that you can keep your system updated with the status of each charge, without having to consult the PicPay API all the time.

To receive notifications, you need to configure the URL on the Merchant Panel with the address of your system that will receive the notifications. After this configuration, PicPay will send an HTTP POST request to the configured URL every time a charge status changes.

Configuring the notification URL

To configure the notification URL, access the Merchant Panel and follow the steps below:

1. Access the Settings (Configurações) menu in the dropdown in the top right corner of the screen.
2. Click on the My Checkout (Meu checkout) tab.
3. Activate the Notification URL functionality by clicking the toggle button, and enter the URL of your system that will receive notifications.
   1. The URL must be HTTPS.
   2. The URL cannot contain any query parameters.
   3. Using an IPv4 as a notification URL is not allowed.
4. Finish by clicking Save changes button (Salvar alterações).

Ready! From that moment on, PicPay will start sending notifications to the configured URL.

Authentication

After setting up the notification URL, PicPay will generate an authentication token, which will be displayed on the screen. Make sure you save this token in a safe place, as it will not be possible to retrieve it later. PicPay will include this token in the Authorization header of each request.

Contract and Examples

In the request body sent by PicPay, you will receive a JSON object with information about the charge that had its status changed or about the result of the 3DS authentication. In the request, there will be a header event_type which can have the following values: TransactionUpdateMessage or Challenge3dsUpdateMessage.

Example of a Webhook for Charge Status Update

Below, you can see an example of the request body for a notification of a charge that was created and authorized.

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

Would you prefer to see an example of 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: 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"
        }
      }
    ]
  }
}'

Example of a Webhook for 3DS

If the transaction is carried out with 3DS authentication, you will receive a notification request informing you of the result of the 3DS authentication challenge. Below is an example of the request body in 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"
  }
}

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"
  }
}'