Todos os eventos são enviados através de uma requisição HTTP/HTTPS POST com o formato JSON no payload.
Seu endpoint precisa retornar um status code de sucesso na resposta, sendo (2xx) um formato válido, assim consideraremos como entregue. Caso contrário, vamos retentar entregar a notificação mais 2 vezes, depois disso, não vamos mais tentar entregar a notificação deste evento.
O exemplo abaixo é um exemplo de um payload de evento que enviamos.
CashIn
Webhook contendo atualização de informações sobre um recebimento.
{
"id": "7d3aae40-6655-4d9a-801b-d0ab7ae906d7", // Event ID
"version": "v1", // Event payload schema version
"account_id": "d95e7630-1b3c-4ac5-991d-d599d75efdd0", // Event digital account id
"object": "CashIn", // Event object type
"date": "2019-10-01T17:54:39.000Z", // Event date and time
"data": { // Event Payload
"id": "7d3aae40-6655-4d9a-801b-d0ab7ae906d7", // CashIn ID
"value": 50.54, // CashIn value
"end2end_id": "E12345asdf123", // Cashin end2end ID
"receipt_file_url": "https://app.com/r/1234", // Cashin receipt URL
"txid": "abc123", // CashIn QRCode txid
"integration_id": "abc123", // CashIn QRCode integration id
"pix_key": "[email protected]", // CashIn receiver pix key
"pix_description": "Some description", // Open text informed by the CashIn payer
"payer": {
"document": "***.123.456-**", // CashIn payer document (CPF / CNPJ)
}
}
}
CashInRefund
Webhook contendo atualização de informações sobre uma devolução recebimento.
{
"id": "7d3aae40-6655-4d9a-801b-d0ab7ae906d7", // Event ID
"version": "v1", // Event payload schema version
"account_id": "d95e7630-1b3c-4ac5-991d-d599d75efdd0", // Event digital account id
"object": "CashInRefund", // Event object type
"date": "2019-10-01T17:54:39.000Z", // Event date and time
"data": { // Event Payload
"id": "7d3aae40-6655-4d9a-801b-d0ab7ae906d7", // CashInRefund ID
"status": "DEVOLVIDO", // CashInRefund status ("DEVOLVIDO" or "NAO_REALIZADO")
"error_code": null, // CashInRefund error code (only present if status="NAO_REALIZADO")
"error_message": null, // CashInRefund error message (only present if status="NAO_REALIZADO")
"value": 50.54, // CashInRefund value
"original_end2end_id": "E12345asdf123", // CashIn original end2end ID
"return_id": "R12345asdf123", // CashInRefund end2end ID
"integration_id": "abc123", // CashInRefund integration id
"receiver": {
"document": "***.123.456-**", // CashInRefund receiver document (CPF / CNPJ)
}
}
}
PixKey
Webhook contendo atualizações de status de chaves Pix.
{
"id": "7d3aae40-6655-4d9a-801b-d0ab7ae906d7", // Event ID
"version": "v1", // Event payload schema version
"account_id": "d95e7630-1b3c-4ac5-991d-d599d75efdd0", // Event digital account id
"object": "PixKey", // Event object type
"date": "2019-10-01T17:54:39.000Z", // Event date and time
"data": { // Event Payload
"id": "61afc88b-4412-4f66-a091-8f8bbda407e1", // Pix key ID
"key_type": "EMAIL", // Pix key type
"key": "[email protected]", // Pix key
"status": "REGISTRADA", // Pix key status
"ownership_date": "2020-10-13T14:30:24.000Z", // Date and time the key became available for use
"error": null // Error that happened during key registration, if any
}
}
A propriedade
errortem a estrutura abaixo e só estará preenchida caso o status da chave seja ERRO:{ "message": "string", "field": "string", "code": "string" }
ChargeReceivable
Webhook contendo atualizações de status da cobrança.
{
"id": "1ee57bc6-cd3a-6a26-a255-94b7d37eb9ff", // Event ID
"version": "v1", // Event payload schema version
"account_id": "fc1587f5-3950-4305-9a27-55d45122a5d5", // Event digital account ID
"object": "ChargeReceivable", // Event object type
"date": "2023-09-20T13:48:48.634320962Z", // Event date and time
"data": { // Event payload
"id": "1ee57bc3-8af6-65de-a67a-c8ef1188c70b", // Receivable ID
"charge_id": "1ee57bc3-8a5a-63c3-a67a-53f970a80545", // Charge ID
"status": "paid", // Receivable status (created, processing, paid, refunded, canceled)
"amount": 100, // Receivable amount in cents
"due_date": "2023-10-13T00:00:00Z", // Receivable due date
"expiration_date": "2023-10-15T00:00:00Z", // Receivable expiration date
"description": "txt", // Receivable description (qrcode and boleto description)
"fine_amount": null, // Receivable fine amount in cents
"fine_percent": null, // Receivable fine percentage
"fine_type": null, // Receivable fine type (fixed, percentage)
"interest_amount": null, // Receivable interest amount in cents
"interest_percent": null, // Receivable interest percentage
"interest_type": null, // Receivable interest type(fixed_per_day, fixed_per_working_day, percentage_per_month, percentage_per_month_working_days)
"discount_amount": null, // Receivable discount amount
"discount_percent": null, // Receivable discount percentage
"discount_dates": null, // Receivable discount dates
"discount_type": null, // Receivable discount type (fixed_until_informed_dates, percentage_until_informed_dates, fixed_per_anticipated_day, fixed_per_anticipated_working_day, percentage_per_anticipated_day, percentage_per_anticipated_working_day)
"qrcode": { // Receivable qrcode data
"id": "911a3c3b-a269-4328-a9ab-266fd72eb7b5", // Receivable qrcode id
"txid": "d0701e0cb6378a3ca4bf7cb6adebcd9c", // Receivable qrcode txid
"emv_payload": "00020101021226960014br.gov.bcbSC62070503***6304D44C" // Receivable qrcode emv (pix copie e cola)
},
"boleto": { // Receivable boleto data
"id": "1ee57bc3-9f1b-6f63-92b7-bd517a433f7b", // Receivable boleto ID
"barcode": "20891950200000001000030010000000000504614110", // Receivable boleto barcode
"linha_digitavel": "20890030041000000000905046141106195020000000100", // Receivable boleto "linha digitavel" for online payments
"identification_number": "55" // Receivable identification number (field "nosso número" present on boletos)
},
"payments": [ // Payments received for this receivable, may have more than one payment per receivable if the payment was done multiple times or the user paid the boleto and the qrcode at same time
{
"amount": 100, // Payment amount in cents
"paid_with": "pix", // Payment method (pix, boleto)
"receipt_url": "http://my-receipt.com/xxxxx", // Payment receipt
"created_at": "2023-09-20T10:48:48.62822-03:00", // Payment creation date
"updated_at": "2023-09-20T10:48:48.62822-03:00" // Payment last updated date
}
],
"created_at": "2023-09-20T10:47:21.155121-03:00", // Receivable creation date
"updated_at": "2023-09-20T10:47:21.155121-03:00" // Receivable last updated date
}
}
- O webhook se refere ao recebível de uma cobrança e você será notificado a cada mudança de status.
- É possível que o recebível contenha mais de um pagamento (mais de um item no array
payments, caso isso aconteça, significa que o pagamento foi efetuado mais de uma vez pelo usuário final. É uma situação rara, mas caso ocorra, nós iremos enviar um webhook para cada vez que um pagamento for recebido, então em casos de pagamento duplicado, você receberá mais de um webhook com o statuspaid, o primeiro contendo um pagamento e o segundo contendos dois pagamentos e assim por diante.- O valor do pagamento recebido pode ser diferente do valor especificado na criação da cobrança pois podem existir descontos, juros e multas associados à cobrança. Recomendamos sempre checar se o valor recebido está correto ao receber um webhook.