Webhooks are the primary method for receiving updates from our API. They are given the highest priority, ensuring updates are delivered to them first. Therefore, it is crucial to properly configure your webhooks to ensure you receive updates promptly and reliably.
Postman Collection
Click here to open the collection
Webhooks configuration
Request
POST 'https://apisandbox.delbank.com.br/baas/api/v1/webhooks'
curl --location 'https://apisandbox.delbank.com.br/baas/api/v1/charges/webhooks' \
--header 'Content-Type: application/json' \
--header 'x-delbank-api-key: ${apiKey}' \
--data '{
{
"eventType": "CHARGE_PAID",
"url": "https://sample.delbank.com.br/webhook"
}
}'
Headers
| Name | Description |
|---|---|
| x-delbank-api-key | Required. API key |
Body
| Name | Type | Description |
|---|---|---|
| eventType | enum | Required. Type of event to be monitored/listened |
| url | string | Required. API URL of the client system that will receive the webhook information |
| authorizationScheme | enum | Type of authorization that must be used when executing the endpoint call (according to the url field). Domains:- BASIC- BEARER- HEADER |
| authorization | string | Information that will be sent in the request header to the endpoint |
Example
Configuring the webhook with Authentication Basic
{
"eventType": "PIX_RECEIVED",
"url": "https://example.com.br/webhooks/v1/bankslips",
"authorization": "bG9naW46cGFzc3dvcmQ=",
"authorizationScheme": "BASIC"
}
Configuring the webhook with Authentication Bearer
{
"eventType": "PIX_RECEIVED",
"url": "https://example.com.br/webhooks/v1/bankslips",
"authorization": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"authorizationScheme": "BEARER"
}
Configuration Maintenance
| Endpoint | HTTP Method | Description |
|---|---|---|
| https://apisandbox.delbank.com.br/baas/api/v1/webhooks | GET | Query all the registered webhooks registered by the API Key used in the requisition. |
| https://apisandbox.delbank.com.br/baas/api/v1/webhooks/{ID} | GET | Query webhook by ID |
| https://apisandbox.delbank.com.br/baas/api/v1/webhooks/{ID} | PATCH | Update webhook by ID (Uses the same payload as the register webhook) |
| https://apisandbox.delbank.com.br/baas/api/v1/webhooks/{ID} | DELETE | Remove registered Webhook by ID |
Event Types
Below is a list of event types and their meaning
| Name | Description |
|---|---|
| CHARGE_PAID | Change paid. |
| PIX_RECEIVED | Pix received. (New webhook flow for Pix receiving only) |
| PIX_PAYMENT_UPDATED | Update payment status for Pix. |
| PIX_REFUNDED | Event for refunds received |
| WHITELABEL_CUSTOMER_DOCUMENTATION_REJECTED | Rejected documents for a new created account |
| WHITELABEL_CUSTOMER_APPROVED | Customer approved and bank account created |
Payload used by the Webhook
Paid Charge CHARGE_PAID
CHARGE_PAID{
"nsu":513,
"correlationId":"217c34be-b374-4e33-9ae2-1b46f14b7116",
"referenceId":"E3822485720230705211537850921369",
"source":"SPI",
"amount":12.12,
"createdAt":"2023-07-05T17:52:33Z",
"payer":{
"name":"FULANO DA SILVA",
"document":"12399999999"
},
"proof":{
"endToEndId":"E3822485720230705211537850921369",
"transactionId":"chargeCqkFlaENmal5NrPK58J",
"key":"5b0ac9a4-fad6-43f9-be70-6d7c9a2fad26",
"amount":12.12,
"payer":{
"number":"10065",
"branch":"0001",
"type":"CURRENT",
"holder":{
"name":"FULANO DA SILVA",
"document":"02599999908"
},
"participant":{
"ispb":"38224857",
"name":"DELCRED SCD S.A."
}
},
"payee":{
"number":"29823",
"branch":"0001",
"type":"CURRENT",
"holder":{
"name":"HOMOLOGACAO INTEGRACAO API",
"document":"30287697789"
},
"participant":{
"ispb":"38224857",
"name":"DELCRED SCD S.A."
}
}
}
}
PIX_RECEIVED
PIX_RECEIVED{
"eventType": "PIX_RECEIVED",
"correlationId": "S110211111111111111111111",
"referenceId": "E182361202024041911111111111111",
"endToEndId": "E182361202024041911111111111111",
"amount": 100.0,
"createdAt": "2024-04-19T16:20:22.274Z",
"proof": {
"eventType": "PIX_PAYMENT_EFFECTIVE",
"endToEndId": "E182361202024041911111111111111",
"idempotencyKey": "E182361202024041911111111111111",
"correlationId": "S110211111111111111111111",
"status": "PIX_EFFECTIVE",
"amount": 100.0,
"payer": {
"number": "49041111116",
"branch": "0001",
"type": "PAYMENT",
"participant": {
"name": "NU PAGAMENTOS - IP",
"ispb": "18236120"
},
"holder": {
"name": "GUSTAVO EXEMPLO",
"document": "94881558099",
"type": "NATURAL"
}
},
"beneficiary": {
"number": "11111",
"branch": "0001",
"type": "CURRENT",
"participant": {
"name": "DELCRED SCD S.A.",
"ispb": "38224857"
},
"holder": {
"document": "48689840000130",
"type": "LEGAL"
}
},
"payee": {
"number": "11111",
"branch": "0001",
"type": "CURRENT",
"participant": {
"name": "DELCRED SCD S.A.",
"ispb": "38224857"
},
"holder": {
"document": "48689840000130",
"type": "LEGAL"
}
}
}
}
Pix payment updated - PIX_PAYMENT_UPDATED
PIX_PAYMENT_UPDATEDPix life cycle. Once finished, the Pix can have these two states:
- PIX_EFFECTIVE: The Pix took effect on the other side of the receiver PSP;
- PIX_ERROR: The Pix were sent to the receiver SPI/PSP, something that lead to an error.
{
"eventType":"PIX_PAYMENT_EFFECTIVE",
"endToEndId":"E3822485720231013020122659082578",
"idempotencyKey":"idempotencyKey999999",
"status":"PIX_EFFECTIVE",
"amount":20.0,
"createdAt":"2023-10-13T05:01:22.953Z",
"description":"description",
"payer":{
"number":"999999",
"branch":"0001",
"type":"CURRENT",
"participant":{
"ispb":"38224857"
},
"holder":{
"name":"EXAMPLE EXAMPLE",
"document":"111111111111111",
"type":"LEGAL"
}
},
"beneficiary":{
"number":"1234556",
"branch":"0001",
"type":"PAYMENT",
"participant":{
"ispb":"08561701"
},
"holder":{
"name":"HOLDER NAME",
"document":"11111111111",
"type":"NATURAL"
}
}
}
{
"eventType":"PIX_PAYMENT_ERROR",
"endToEndId":"E3822485720231013015126180935816",
"idempotencyKey":"idempotencyKey12345",
"status":"PIX_ERROR",
"error":{
"code":"AC06",
"description":"Conta transacional do usuário recebedor encontra-se bloqueada."
},
"amount":100.0,
"createdAt":"2023-10-13T04:51:26.84Z",
"description":"description",
"payer":{
"number":"12345",
"branch":"0001",
"type":"CURRENT",
"participant":{
"ispb":"38224857"
},
"holder":{
"name":"EXAMPLE EXAMPLE",
"document":"11111111111111",
"type":"LEGAL"
}
},
"beneficiary":{
"number":"12345",
"branch":"3231",
"type":"CURRENT",
"participant":{
"ispb":"90400888"
},
"holder":{
"name":"HOLDER NAME",
"document":"11111111111",
"type":"NATURAL"
}
}
}
PIX_REFUNDED
PIX_REFUNDED{
"eventType": "PIX_REFUNDED",
"endToEndId": "D0041696820240426011111111111",
"originalEndToEndId": "E38224857202404260111111111111",
"amount": 500.0,
"bankAccount": "11111",
"refundCode": "MD06",
"reasonRefund": "Devolução solicitada pelo cliente",
"createdAt": "2024-04-26T01:53:04.329Z",
"proof": {
"idempotencyKey": "D0041696820240426011111111111",
"endToEndId": "D0041696820240426011111111111",
"originalEndToEndId": "E38224857202404260111111111111",
"status": "PIX_EFFECTIVE",
"operationType": "CREDIT_REFUND",
"amount": 500.0,
"createdAt": "2024-04-26T01:53:02.901Z",
"finishedAt": "2024-04-26T01:53:02.901Z",
"payer": {
"number": "11111111111",
"branch": "0001",
"type": "CURRENT",
"participant": {
"name": "BANCO XXXXX",
"ispb": "1111111111"
},
"holder": {
"document": "***1111111**",
"type": "NATURAL"
}
},
"beneficiary": {
"number": "38709",
"branch": "0001",
"type": "CURRENT",
"participant": {
"name": "DELCRED SCD S.A.",
"ispb": "38224857"
},
"holder": {
"name": "EMPRESA LTDA",
"document": "94478450000138",
"type": "LEGAL"
}
}
}
}
WHITELABEL_CUSTOMER_DOCUMENTATION_REJECTED
{
"name": "Fulano da silva",
"document": "49126271869",
"bankAccountNumber": null
}
WHITELABEL_CUSTOMER_APPROVED
In case of approval, the newly created account number will be returned.
{
"name": "JOSEVALDO",
"document": "61263079091",
"bankAccountNumber": 13102
}