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.

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. Note: You will need to use the information you receive in the `data.fido_options` object in your frontend as the arguments for the requestEnrollmentConfirmation Payments Web SDK.
`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" },
    "fido_options": {
      "rp": { "id": "belvo.com", "name": "Belvo" },
      "user": {
        "id": "cba3fb04-5b0f-44c0-83d8-fed7db98d8d9",
        "name": "Mock User",
        "displayName": "Mock User"
      },
      "challenge": "R3JlZXRpbmdzIGZyb20gQmVsdm8h",
      "pubKeyCredParams": [{ "alg": -7, "type": "public-key" }],
      "timeout": 0,
      "excludeCredentials": [{ "id": "AAABBB-ID", "type": "public-key" }],
      "authenticatorSelection": {
        "authenticatorAttachment": "platform, cross-platform",
        "userVerification": "discouraged, preferred, required",
        "requireResidentKey": true,
        "residentKey": "111-ID"
      },
      "attestation": "none, indirect, direct, enterprise",
      "attestationFormats": [
        "packed, tpm, android-key, android-safetynet, fido-u2f, apple, none"
      ],
      "extensions": { "someAdditionalProp1": {} }
    }
  }
}

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

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

🇧🇷 OFPI Webhooks

Charges

STATUS_UPDATE

Failure codes and messages

Enrollments

STATUS_UPDATE

Payment intents

STATUS_UPDATE

📘
`STATUS_UPDATE` webhook when using payment links

Transactions

OBJECT_CREATED

Charges

STATUS_UPDATE

Failure codes and messages

Enrollments

STATUS_UPDATE

Payment intents

STATUS_UPDATE

📘STATUS_UPDATE webhook when using payment links

Transactions

OBJECT_CREATED

📘
`STATUS_UPDATE` webhook when using payment links