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
Configurações
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.- A URL deve ser HTTPS.
- A URL não pode conter nenhum query parameter.
- 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 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"
}
}'