API StatusAPI ReferenceError DocsInstitutionsSupportSign inCreate a Sandbox account

🇧🇷 OFPI Webhooks

Suggest Edits

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.
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", // The status of the payment intent.
    "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", // The status of the payment intent.
    "metadata": {"internal_reference_id": "GGq12345w2"},
    "failure_code": "beneficiary_not_registered", // A unique code for the error.
    "failure_message": "There was an unexpected error. Please contact support." // Human-readable description of the error.
  }
}

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"}
  },
}

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 2 days ago