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.
`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", // 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/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/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).