Webhook

Introduction

A webhook is a feature that allows PicPay to send notifications to your system every time a payment charge status changes. It is useful for keeping your system updated with the status of each payment charge without constantly querying the PicPay API.

To receive notifications, you need to configure the URL in the Seller 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 payment charge status changes.

Configuring the Notification URL

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

1. Access the Settings menu in the dropdown at the top right of the screen.

2. Click on the My Checkout tab.

3. Enable the Notification URL feature by clicking the button, and enter the URL of your system that will receive the notifications.
   1. The URL must be HTTPS.
   2. The URL cannot contain any query parameters.
   3. Using an IPv4 as the notification URL is not allowed.

4. When you click on Save changes, an API Key will be generated, as shown in the image below.

5. Copy the API Key, as it will be sent in the authorization header of all requests.

Done! From this moment on, PicPay will send notifications to the configured URL.

Contract and Examples

In the body of the request sent by PicPay, you will receive a JSON object with information about the payment charge whose status has been changed. The request will have an event_type header that can have the following values: TransactionPaymentMessage.

Fields

Field	Description	Type	Values
data.transaction.originalTransactionId	Original transaction ID	String UUID or null
data.transaction.status	Transaction status	PAYED, REFUNDED or PARTREFUNDED	PAYED, REFUNDED or PARTREFUNDED
data.transaction.id	Transaction ID	String UUID
data.transaction.amount	Transaction amount*	Integer in cents
data.transaction.paymentType	Transaction payment type	String	WALLET, PIX or CREDIT_CARD
data.transaction.createdAt	When the transaction was created	Date in string
data.transaction.updatedAt	When the transaction was updated	Date in string
data.charge.qrCode	Payment link QR code	String
data.charge.expiresAt	When the payment link expires	Date in string or null
data.charge.amount	Payment link amount	Integer in cents
data.charge.paymentLinkId	Payment link ID	String
data.charge.checkoutLink	Payment link	String
eventDate	When the event occurred	String
type	Type of transaction	String	REFUND or PAYMENT

*The amount for partial cancellation will be shown in this field.

Webhook examples for payment charge status update

PAYMENT

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

{
  "data": {
    "transaction": {
      "originalTransactionId": null,
      "status": "PAYED",
      "id": "a105da56-a372-4e6e-976e-xxxxxxxxxxxx",
      "amount": 300,
      "paymentType": "CREDIT_CARD",
      "createdAt": "2025-05-12T20:50:46.000000Z",
      "updatedAt": "2025-05-12T20:50:46.000000Z"
    },
    "charge": {
      "qrCode": "00020126810014BR.GOV.BCB.PIX2559qr-code.picpay.com/xxxxxxxxxxxxxxxxxxxxx...",
      "expiresAt": "2025-06-30 00:00:00",
      "amount": 300,
      "paymentLinkId": "174708287368xxxxxxxxxxx",
      "checkoutLink": "https://link.picpay.com/p/174708287368xxxxxxxxxxx"
    }
  },
  "eventDate": "2025-05-12T20:50:46.000000Z",
  "type": "PAYMENT"
}

Need an example as cURL? Here it is:

curl -X 'POST' 'https://yourdomain.com/webhook' \
-H 'connection: close' \
-H 'host: yourdomain.com' \
-H 'accept-encoding: gzip, compress, deflate, br' \
-H 'authorization: a45c2dee-6435-xxxx-yyyy-zzzzzzzzzzzz' \
-H 'event-type: TransactionPaymentMessage' \
-H 'content-type: application/json' \
-H 'accept: application/json, text/plain, */*' \
-d $'{
  "data": {
    "transaction": {
      "originalTransactionId": null,
      "status": "PAYED",
      "id": "a105da56-a372-4e6e-976e-xxxxxxxxxxxx",
      "amount": 300,
      "paymentType": "CREDIT_CARD",
      "createdAt": "2025-05-12T20:50:46.000000Z",
      "updatedAt": "2025-05-12T20:50:46.000000Z"
    },
    "charge": {
      "qrCode": "00020126810014BR.GOV.BCB.PIX2559qr-code.picpay.com/xxxxxxxxxxxxxxxxxxxxx...",
      "expiresAt": "2025-06-30 00:00:00",
      "amount": 300,
      "paymentLinkId": "174708287368xxxxxxxxxxx",
      "checkoutLink": "https://link.picpay.com/p/174708287368xxxxxxxxxxx"
    }
  },
  "eventDate": "2025-05-12T20:50:46.000000Z",
  "type": "PAYMENT"
}'

REFUND

Below is an example of the request body for a notification of a payment charge that was refunded.

{
  "data": {
    "transaction": {
      "originalTransactionId": "48581c5f-f077-4727-9d44-xxxxxxxxxxxx",
      "status": "REFUNDED",
      "id": "2ac7260e-15ab-497f-a31c-xxxxxxxxxxxx",
      "amount": 2,
      "paymentType": "WALLET",
      "createdAt": "2025-05-12T21:08:15.000000Z",
      "updatedAt": "2025-05-12T21:08:15.000000Z"
    },
    "charge": {
        "qrCode": "00020126810014BR.GOV.BCB.PIX2559qr-code.picpay.com/xxxxxxxxxxxxxxxxxxxxx...",
        "expiresAt": "2025-06-30 00:00:00",
        "amount": 2,
        "paymentLinkId": "174708287368xxxxxxxxxxx",
        "checkoutLink": "https://link.picpay.com/p/174708287368xxxxxxxxxxx"
    }
  },
  "eventDate": "2025-05-12T21:08:15.000000Z",
  "type": "REFUND"
}

Example as cURL:

curl -X 'POST' 'https://yourdomain.com/webhook' \
-H 'connection: close' \
-H 'host: yourdomain.com' \
-H 'accept-encoding: gzip, compress, deflate, br' \
-H 'authorization: a45c2dee-6435-xxxx-yyyy-zzzzzzzzzzzz' \
-H 'event-type: TransactionPaymentMessage' \
-H 'content-type: application/json' \
-H 'accept: application/json, text/plain, */*' \
-d $'{
  "data": {
    "transaction": {
      "originalTransactionId": "48581c5f-f077-4727-9d44-xxxxxxxxxxxx",
      "status": "REFUNDED",
      "id": "2ac7260e-15ab-497f-a31c-xxxxxxxxxxxx",
      "amount": 2,
      "paymentType": "WALLET",
      "createdAt": "2025-05-12T21:08:15.000000Z",
      "updatedAt": "2025-05-12T21:08:15.000000Z"
    },
    "charge": {
        "qrCode": "00020126810014BR.GOV.BCB.PIX2559qr-code.picpay.com/xxxxxxxxxxxxxxxxxxxxx...",
        "expiresAt": "2025-06-30 00:00:00",
        "amount": 2,
        "paymentLinkId": "174708287368xxxxxxxxxxx",
        "checkoutLink": "https://link.picpay.com/p/174708287368xxxxxxxxxxx"
    }
  },
  "eventDate": "2025-05-12T21:08:15.000000Z",
  "type": "REFUND"
}'