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": {
"bank": { // CashIn payer bank
"code": "341",
"ispb": "60701190",
"name": "Itaú"
},
"name": "Pagador 123", // CashIn payer name
"agency": "0001", // CashIn payer agency number
"account": "12345", // CashIn payer account number
"document": "74667077000", // CashIn payer document (CPF / CNPJ)
"account_type": "CONTA_CORRENTE", // CashIn payer account type
"account_digit": "6" // CashIn payer account digit
}
}
}
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)
"external_id": "external-id", // Charge external_id (value provided when creating the charge)
"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.
PaymentLink
Webhook contendo atualizações de status de um link de pagamento.
{
"id": "1ef803c1-ddfa-667d-be55-3a8a8bf91278", // Event ID
"version": "v1", // Event payload schema version
"account_id": "8ded3cfe-2eb9-4377-b0ba-5b2a336365a2", // Event digital account ID
"object": "PaymentLink", // Event object type
"date": "2024-10-01T21:28:35.936422508Z", // Event date and time
"data": { // Event payload
"id": "1ef803c1-ddf5-6f4c-be55-ff2d6b7655a5", // Payment link ID
"status": "waiting_payment", // Payment link status (pending, waiting_payment, paid)
"payment_methods":["pix","credit_card","boleto"], // Payment link payment methods (pix, boleto, credit_card)
"amount": 4300, // Payment link amount in cents
"name": "Payment link name", // Payment link name
"description": "Payment link description", // Payment link description
"link": "https://your-checkout.com/SaOJZqjfQqAxsqazx", // Payment link url
"created_at": "2024-10-01T21:28:23.494065013Z", // Payment link creation time
"updated_at": "2024-10-01T21:28:35.847270593Z", // Payment link update time
"expires_at": "2024-10-01T21:28:23.494065013Z", // Payment link expiration time
"payment_method_details": { // Payment link description
"credit_card": { // Credit card details
"max_installments": 1, // Maximum number of card's installments allowed for receipt of this link
},
"boleto": { // Boleto details
"due_days": 1 // Boleto due days after boleto creation
},
}
}
}
}
Payin
Webhook contendo atualizações de status de um payin.
{
"id": "1ef803c1-ddfa-667d-be55-3a8a8bf91278", // Event ID
"version": "v1", // Event payload schema version
"account_id": "8ded3cfe-2eb9-4377-b0ba-5b2a336365a2", // Event digital account ID
"object": "Payin", // Event object type
"date": "2024-10-01T21:28:35.936422508Z", // Event date and time
"data": { // Event payload
"id": "1ef803c1-ddf5-6f4c-be55-ff2d6b7655a5", // Payin ID
"amount": 4300, // Payin amount in cents
"status": "pending", // Payin status
"payment_method": "credit_card", // Payin payment method (credit_card)
"payment_method_details": { // Payin payment method details
"credit_card": { // Credit card details
"installments": 1, // Number of installments
"token": null,
"antifraud_fingerprint_id": "1ef803be-fa22-6b97-be55-4475e13bbe8d", // Antifraud fingerprint ID
"rejection_reason": null, // Payin rejection reason (returned when payin is unauthorized)
"payer": { // Payer details
"tax_id": "74667077000", // Payer tax ID
"email": "[email protected]", // Payer email
"phone": "41998340000", // Payer phone
"name": "Pagador 123", // Payer name
"address": { // Payer address
"street": "Rua São Bento", // Payer street
"number": "123", // Payer number
"complement": "", // Payer complement
"district": "Centro", // Payer district
"city": "São Paulo", // Payer city
"state": "SP", // Payer state
"postal_code": "01010000", // Payer postal code
"country": "BR" // Payer country
}
},
}
},
"created_at": "2024-10-01T21:28:23.494065013Z", // Payin creation time
"updated_at": "2024-10-01T21:28:35.847270593Z" // Payin update time
}
}