📘
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`

{
   "nsu":513,
   "correlationId":"217c34be-b374-4e33-9ae2-1b46f14b7116",
   "referenceId":"E3822485720230705211537850921369",
   "source":"SPI",
   "amount":12.12,
   "createdAt":"2023-07-05T17:52:33Z",
   "payer":{
      "name":"MARCONI DO NASCIMENTO OLIVEIRA",
      "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":"Marconi do Nascimento Oliveira",
            "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`

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

{
	"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": "Jedson Marlon",
	"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
}

Configuring webhooks

📘
Postman Collection

Webhooks configuration

Request

Headers

Body

Example

Configuration Maintenance

Event Types

Payload used by the Webhook

Paid Charge `CHARGE_PAID`

`PIX_RECEIVED`

Pix payment updated - `PIX_PAYMENT_UPDATED`

`PIX_REFUNDED`

WHITELABEL_CUSTOMER_DOCUMENTATION_REJECTED

WHITELABEL_CUSTOMER_APPROVED

📘Postman Collection

Webhooks configuration

Request

Headers

Body

Example

Configuration Maintenance

Event Types

Payload used by the Webhook

Paid Charge CHARGE_PAID

PIX_RECEIVED

Pix payment updated - PIX_PAYMENT_UPDATED

PIX_REFUNDED

WHITELABEL_CUSTOMER_DOCUMENTATION_REJECTED

WHITELABEL_CUSTOMER_APPROVED

📘
Postman Collection

Paid Charge `CHARGE_PAID`

`PIX_RECEIVED`

Pix payment updated - `PIX_PAYMENT_UPDATED`

`PIX_REFUNDED`