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 cobrança. Ele é útil para que você possa manter o seu sistema atualizado com o status de cada cobrança, 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 cobrança.

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, 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. Ao clicar em Salvar alterações, será gerada uma API Key, conforme imagem abaixo.

5. Copie a API Key, pois será enviada no header authorization de todas as requisições.

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

Contrato e Exemplos

No corpo da requisição enviada pelo PicPay, você receberá um objeto JSON com as informações sobre a cobrança que teve o status alterado. Na requisição haverá uma header event_type que pode possuir os seguintes valores: TransactionPaymentMessage.

Campos

Campo	Descrição	Tipo	Valores
data.transaction.originalTransactionId	Id original da transação	String UUID ou nulo
data.transaction.status	Status da transação	PAYED, REFUNDED ou PARTREFUNDED	PAYED, REFUNDED ou PARTREFUNDED
data.transaction.id	Id da transação	String UUID
data.transaction.amount	Valor da transação*	Inteiro em centavos
data.transaction.paymentType	Tipo de pagamento da transação	String	WALLET, PIX ou CREDIT_CARD
data.transaction.createdAt	Data que a transação foi criada	Data em string
data.transaction.updatedAt	Data que a transação foi alterada	Data em string
data.charge.qrCode	qrCode do link de pagamento	String
data.charge.expiresAt	Data em que o link expira	Data em string ou nulo
data.charge.amount	Valor do link	Inteiro em centavos
data.charge.paymentLinkId	Id do link de pagamento	String
data.charge.checkoutLink	Link de pagamento	String
eventDate	Data em que o evento aconteceu	String
type	Tipo da transação	String	REFUND ou PAYMENT

*O valor do cancelamento parcial será apresentado nesse campo.

Exemplos de webhook para atualização de status da cobrança

PAGAMENTO

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

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

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

CANCELAMENTO

A seguir, temos um exemplo do corpo de uma requisição de notificação de uma cobrança que foi cancelada.

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

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