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_codes and failure_messages 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.

Customers

OBJECT_CREATED

Whenever there is a new customer created by the Belvo application (that is, when the customer is created asynchronously and not as a result of a direct POST call), you will receive the following webhook:

{
  "webhook_id": "3b9a69f7-0f0a-455b-832d-49ad6fd4905c",
  "webhook_type": "CUSTOMERS",
  "webhook_code": "OBJECT_CREATED",
  "object_id": "7d01c4cf-57ed-4ed9-b109-a5bfb2d8c42b",
  "data": null
}

Once you receive the notification, you can get details on the customer by making the following request:

curl --request GET 'https://api.belvo.com/payments/br/customers/{id}/' \
  -u [Secret Key ID]:[Secret Key PASSWORD]

Where:

id is the object_id of the customer (which you receive in the webhook event).

Enrollments

STATUS_UPDATE

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

Event	Sent when
`PENDING`	The enrollment is awaiting biometric details to be sent through.
`SUCCEEDED`	The enrollment was accepted by the institution.
`FAILED`	The enrollment was rejected by the institution.

{
  "webhook_id": "9f91116b-bfe1-45f2-8ae3-aa604161c4aa",
  "webhook_type": "ENROLLMENTS",
  "webhook_code": "STATUS_UPDATE",
  "object_id": "06a51b80-708d-49c9-8620-7b0fd2fbc548",
  "data": {
    "status": "PENDING",
    "metadata": null,
    "details": { "status": "AWAITING_ENROLLMENT" }
  }
}

{
  "webhook_id": "9f91116b-bfe1-45f2-8ae3-aa604161c4aa",
  "webhook_type": "ENROLLMENTS",
  "webhook_code": "STATUS_UPDATE",
  "object_id": "e64de9d0-0045-49ad-b1ee-779a9c269ab3",
  "data": {
    "status": "SUCCEEDED",
    "metadata": null,
    "details": { "status": "AUTHORIZED" }
  }
}

{
  "webhook_id": "9f91116b-bfe1-45f2-8ae3-aa604161c4aa",
  "webhook_type": "ENROLLMENTS",
  "webhook_code": "STATUS_UPDATE",
  "object_id": "e64de9d0-0045-49ad-b1ee-779a9c269ab3",
  "data": {
    "status": "FAILED",
    "metadata": null,
    "details": { "status": "REJECTED" }
  }
}

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 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).

Failure codes and messages

Below is a list of failure_codes and failure_messages that you can receive in a Payment Intents webhook when a charge fails:

Code	Message
`ACCOUNT_NOT_ALLOWED`	The account does not allow payments.
`SAME_ORIGIN_DESTINATION_ACCOUNTS`	The origin and destination accounts are the same.
`INVALID_QRCODE`	The QR Code used to initiate payment is not valid.
`USER_REJECTED`	The user rejected the authorization of the consent.
`AUTHORIZATION_EXPIRED`	The authorization time has expired.
`CONSUMPTION_EXPIRED`	The consent consumption time has expired.
`INVALID_CHARGE`	Expiration validation, due date validation, or Valid Status.
`INVALID_PAYMENT_DETAIL`	Payment is invalid because does not comply with the Open Finance business rules.
`PAYMENT_CONSENT_MISMATCH`	The payment does not match the consent.
`ISSUER_REJECTED_PAYMENT`	The issuer rejected the payment.
`SPI_REJECTED_PAYMENT`	The SPI network rejected the payment.
`NOT_INFORMED`	No error reason was provided by the institution.
`INSUFFICIENT_FUNDS`	The account has insufficient funds to make the payment.
`AMOUNT_OVER_LIMIT`	The payment amount or the number of payments exceeds the limits set by the institution.
`INVALID_AMOUNT`	The value sent is not valid for the QR Code entered.
`UNKNOWN_ERROR`	No error reason was provided by the institution.

Transactions

OBJECT_CREATED

Whenever there is a new transaction created, you will receive the following webhook:

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

Once you receive the notification, you can get details on the transaction by making the following request:

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).

🇧🇷 OFPI Webhooks

Charges

STATUS_UPDATE

Failure codes and messages

Customers

OBJECT_CREATED

Enrollments

STATUS_UPDATE

Payment intents

STATUS_UPDATE

📘
`STATUS_UPDATE` webhook when using payment links

Failure codes and messages

Transactions

OBJECT_CREATED

Charges

STATUS_UPDATE

Failure codes and messages

Customers

OBJECT_CREATED

Enrollments

STATUS_UPDATE

Payment intents

STATUS_UPDATE

📘STATUS_UPDATE webhook when using payment links

Failure codes and messages

Transactions

OBJECT_CREATED

📘
`STATUS_UPDATE` webhook when using payment links