🇧🇷 OFPI Webhooks
Charges
STATUS_UPDATE
You'll receive a webhook event whenever the status of a charge is updated to:
Event | Sent when |
---|---|
SCHEDULED | The charge is 'paused' until the scheduled payment date. |
SUCCEEDED | The charge has been confirmed and processed by the open finance network. |
FAILED | The user hasn't provided consent for the payment, or there has been a general error in the open finance network. |
CANCELED | The scheduled charge was canceled. |
{
"webhook_id": "3b9a69f7-0f0a-455b-832d-49ad6fd4905c",
"webhook_type": "CHARGES",
"webhook_code": "STATUS_UPDATE",
"object_id": "d2e40773-19f6-48d1-93c3-3590ec0c74df",
"data": {
"status": "SUCCEEDED", // The status of the charge.
"metadata": {"internal_reference_id": "GGq12345w2"},
"failure_code": null,
"failure_message": null,
"end_to_end_id": "E432158152024081610416f2b595b056",
},
}
{
"webhook_id": "3b9a69f7-0f0a-455b-832d-49ad6fd4905c",
"webhook_type": "CHARGES",
"webhook_code": "STATUS_UPDATE",
"object_id": "d2e40773-19f6-48d1-93c3-3590ec0c74df",
"data": {
"status": "FAILED",
"metadata": {"internal_reference_id": "GGq12345w2"},
"failure_code": "consent_expired",
"failure_message": "The payment consent was not accepted in time.",
"end_to_end_id": "E432158152024081610416f2b595b056"
}
}
Failure codes and messages
Below is a list of failure_code
s and failure_message
s that you can receive in a Charges webhook when a charge fails:
Code | Message |
---|---|
AMOUNT_OVER_LIMIT | The payment amount or the number of payments exceeds the limits set by the institution. |
INVALID_PAYMENT_DETAIL | Payment is invalid because it does not comply with the Open Finance business rules. |
INVALID_CHARGE | Expiration validation, due date validation, or Valid Status. |
INSUFFICIENT_FUNDS | The account has insufficient funds to make the payment |
ISSUER_REJECTED_PAYMENT | The issuer rejected the payment. |
PAYMENT_CONSENT_MISMATCH | The payment details does not match the consent |
SPI_REJECTED_PAYMENT | The SPI network rejected the payment. |
UNKNOWN_ERROR | No error reason was provided by the institution. |
Payment intents
STATUS_UPDATE
You'll receive a webhook event whenever the status of a payment intent is updated to:
Event | Sent when |
---|---|
REQUIRES_PAYMENT_METHOD | Additional details are required to complete the payment intent flow. |
REQUIRES_ACTION | You have sent through confirm=true in the payment intent flow and Belvo now initiates the payment flow in the open finance network. |
PROCESSING | The payment is being processed in the open finance network. |
SCHEDULED | The payment is 'paused' until the scheduled payment date. |
CANCELED | The scheduled payment intent was canceled. |
SUCCEEDED | The payment has been confirmed and processed by the open finance network. |
FAILED | The payment has been rejected by the user, the user hasn't provided consent for the payment, or there has been a general error in the open finance network. |
STATUS_UPDATE
webhook when using payment linksYou will also receive
STATUS_UPDATE
webhooks when using payment links. Please see the Widget payment process of our OFPI inflow payments article for in-depth information regarding when each webhook event is sent.
{
"webhook_id": "3b9a69f7-0f0a-455b-832d-49ad6fd4905c",
"webhook_type": "PAYMENT_INTENTS",
"webhook_code": "STATUS_UPDATE",
"object_id": "d2e40773-19f6-48d1-93c3-3590ec0c74df",
"data": {
"status": "SUCCEEDED",
"end_to_end_id": "E432158152024081610416f2b595b056",
"metadata": {"internal_reference_id": "GGq12345w2"}
},
}
{
"webhook_id": "3b9a69f7-0f0a-455b-832d-49ad6fd4905c",
"webhook_type": "PAYMENT_INTENTS",
"webhook_code": "STATUS_UPDATE",
"object_id": "d2e40773-19f6-48d1-93c3-3590ec0c74df",
"data": {
"status": "FAILED",
"metadata": {"internal_reference_id": "GGq12345w2"},
"failure_code": "consent_expired",
"failure_message": "The payment consent was not accepted in time.",
"end_to_end_id": "E432158152024081610416f2b595b056",
}
}
Once you receive the notification, you can get details on the payment intent by making the following request:
curl --request GET 'https://api.belvo.com/payments/br/payment-intents/{id}' \
-u [Secret Key ID]:[Secret Key PASSWORD]
Where:
id
is theobject_id
of the payment intent (which you receive in the webhook event).
Transactions
OBJECT_CREATED
Whenever there is a new transaction created, you will receive the following webhook:
Once you receive the notification, you can get details on the transaction by making the following request:
{
"webhook_id": "3b9a69f7-0f0a-455b-832d-49ad6fd4905c",
"webhook_type": "TRANSACTIONS",
"webhook_code": "OBJECT_CREATED",
"object_id": "d2e40773-19f6-48d1-93c3-3590ec0c74df",
"data": {
"metadata": {"internal_reference_id": "GGq12345w2"},
"end_to_end_id": "E432158152024081610416f2b595b056",
},
}
curl --request GET 'https://api.belvo.com/payments/br/transactions/{id}/' \
-u [Secret Key ID]:[Secret Key PASSWORD]
Where:
id
is theobject_id
of the transaction (which you receive in the webhook event).
Updated 28 days ago