Guides
API StatusAPI ReferenceError DocsInstitutionsSupportSign inCreate a Sandbox account

🇧🇷 OFPI Webhooks

Suggest Edits

Charges

STATUS_UPDATE

You'll receive a webhook event whenever the status of a charge is updated to:

EventSent when
SCHEDULEDThe charge is 'paused' until the scheduled payment date.
SUCCEEDEDThe charge has been confirmed and processed by the open finance network.
FAILEDThe user hasn't provided consent for the payment, or there has been a general error in the open finance network.
CANCELEDThe 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_codes and failure_messages that you can receive in a Charges webhook when a charge fails:

CodeMessage
AMOUNT_OVER_LIMITThe payment amount or the number of payments exceeds the limits set by the institution.
INVALID_PAYMENT_DETAILPayment is invalid because it does not comply with the Open Finance business rules.
INVALID_CHARGEExpiration validation, due date validation, or Valid Status.
INSUFFICIENT_FUNDSThe account has insufficient funds to make the payment
ISSUER_REJECTED_PAYMENTThe issuer rejected the payment.
PAYMENT_CONSENT_MISMATCHThe payment details does not match the consent
SPI_REJECTED_PAYMENTThe SPI network rejected the payment.
UNKNOWN_ERRORNo 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:

EventSent when
REQUIRES_PAYMENT_METHODAdditional details are required to complete the payment intent flow.
REQUIRES_ACTIONYou have sent through confirm=true in the payment intent flow and Belvo now initiates the payment flow in the open finance network.
PROCESSINGThe payment is being processed in the open finance network.
SCHEDULEDThe payment is 'paused' until the scheduled payment date.
CANCELEDThe scheduled payment intent was canceled.
SUCCEEDEDThe payment has been confirmed and processed by the open finance network.
FAILEDThe 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 links

You 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 the object_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 the object_id of the transaction (which you receive in the webhook event).

Updated 28 days ago