Skip to main content
Download OpenAPI

API orchestration - Webhooks

You can configure your own webhooks that A-CUBE Open Banking API will call when an event happens. To manage your endpoints you can use the API or the dashboard.

Please note that a signature is included in each call to webhooks.

Here are the events that can occur in the platform.

connect​

A-CUBE triggers this event when the consent for a connection has been correctly established or when this process has experienced any problem. The message can have two shapes. The first one is in case of success.

{
  "fiscalId": "some_fiscal_id",
  "success": true,
  "updatedAccounts": [
    "aSampleAccountID-001",
    "aSampleAccountID-002",
    "aSampleAccountID-003"
  ]
}

The second one will be generated in case of error:

{
  "fiscalId": "some_fiscal_id",
  "success": false,
  "errorClass": "Timeout",
  "errorMessage": "Some error message"
}

Types of errorClass are:

Timeout
InvalidCredentials
AccessDenied
ProviderError
GenericError

reconnect​

A-CUBE periodically will send this event when a Business Registry needs to renew the consent that is about to expire for one of its connections. Here is a sample message body.

{
  "fiscalId": "some_fiscal_id",
  "connectUrl": "The URL to invoke to start the reconnection process",
  "providerName": "The name of the financial institution to renew consent for",
  "consentExpiresAt": "2031-01-01T00:00:00Z",
  "noticeLevel": 1,
  "email": "The email of the bank manager that connected the accounts"
}

noticeLevel can assume these values:

  • 1 => consent will expire within 20 days
  • 2 => consent will expire within 10 days
  • 3 => consent has expired

connection​

A-CUBE triggers this event when the financial institution fails to provide data for a connection that has already been established, for example during the automatic refreshes that happen in the background. A failure does not always mean that the consent has expired: a connection can still be active while it has stopped updating transactions.

Each affected Business Registry receives a separate message, identified by its fiscalId and listing only its own enabled accounts belonging to the connection. No message is sent for connections that are still being created: in that case the connect event is sent.

{
  "fiscalId": "some_fiscal_id",
  "success": false,
  "providerName": "The name of the financial institution",
  "status": "active",
  "errorClass": "FetchingStopped",
  "accounts": [
    "c83ea9a5-78aa-4bd8-9e9a-fe46827603f9"
  ],
  "reconnectUrl": "The URL to invoke to start the reconnection process"
}

status is the status of the connection after the failure:

  • active => the connection can still be refreshed, but the last update failed
  • inactive => the connection cannot be refreshed anymore and must be reconnected
  • disabled => the connection has been closed and its accounts have been removed; reconnectUrl is null and a new connection is needed

Types of errorClass are:

FetchingStopped
ConsentExpired
InvalidCredentials
AccessDenied
NoAccounts
Timeout
ProviderError
GenericError

Timeout and ProviderError are usually temporary and the next automatic refresh may succeed. If you receive FetchingStopped, ConsentExpired, InvalidCredentials or AccessDenied, or if the same error keeps coming, transactions will not be updated until the user reconnects the accounts through reconnectUrl.

payment​

A-Cube will send notifications to webhooks about the progress of the payment process. Here are samples of the messages you can receive.

In case of success you will receive a JSON payload containing the fiscal ID of Business Registry that initiated the process, plus a payment object describing the payment.

{
  "fiscalId": "ABCD",
  "success": true,
  "payment": {
    "uuid": "11ce6377-ff28-4c7c-842f-ba500fb94759",
    "direction": "inbound",
    "status": "confirmed",
    "system": "sepa",
    "amount": "345.67",
    "currencyCode": "EUR",
    "description": "Order nr. 12345",
    "endToEndId": "A+C000001",
    "createdAt": "2023-03-30T07:51:34Z",
    "debtorProviderName": "Retail Bank Institute",
    "account": {
      "uuid": "c83ea9a5-78aa-4bd8-9e9a-fe46827603f9",
      "name": "ABCD123",
      "nature": "account",
      "providerName": "Commercial Bank Institute"
    }
  }
}

In case of failure, in addition to data we have already seen for the success event, you will also receive a description of the error.

{
  "fiscalId": "ABCD",
  "success": false,
  "errorClass": "PaymentFailed",
  "errorMessage": "Payment cancelled",
  "payment": {
    "uuid": "11ce6377-ff28-4c7c-842f-ba500fb94759",
    "direction": "inbound",
    "status": "failed",
    "system": "sepa",
    "amount": "345.67",
    "currencyCode": "EUR",
    "description": "Order nr. 12345",
    "endToEndId": "A+C000001",
    "createdAt": "2023-03-30T07:51:34Z",
    "debtorProviderName": "Retail Bank Institute",
    "account": {
      "uuid": "c83ea9a5-78aa-4bd8-9e9a-fe46827603f9",
      "name": "ABCD123",
      "nature": "account",
      "providerName": "Commercial Bank Institute"
    }
  }
}

When the payment belongs to a bulk payment, a webhook is sent for each payment of the batch, and the payment object also contains the bulkUuid field with the identifier of the batch.

Types of errorClass are:

Timeout
InvalidCredentials
AccessDenied
ProviderError
PaymentFailed
GenericError
Last updated on