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.

Copy

Copied

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

The second one will be generated in case of error:

Copy

Copied

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

Types of errorClass are:

Copy

Copied

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.

Copy

Copied

{
  "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:00+00:00",
  "noticeLevel": 0
}

noticeLevel can assume these values:

0 => consent will expire in 20 days
1 => consent will expire in 10 days
2 => consent will expire in 0 days

payment

A-Cube will send notifications to webhooks about the progress of 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.

Copy

Copied

{
  "fiscalId": "ABCD",
  "success": true,
  "payment": {
    "uuid": "11ce6377-ff28-4c7c-842f-ba500fb94759",
    "direction": "inbound",
    "status": "accepted",
    "system": "sepa",
    "amount": "345.67",
    "currencyCode": "EUR",
    "description": "Order nr. 12345",
    "endToEndId": "A+C000001",
    "createdAt": "2023-03-30T07:51:34Z",
    "debtorProviderName": "Mario Rossi",
    "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.

Copy

Copied

{
  "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": "Mario Rossi",
    "account": {
      "uuid": "c83ea9a5-78aa-4bd8-9e9a-fe46827603f9",
      "name": "ABCD123",
      "nature": "account",
      "providerName": "Commercial Bank Institute"
    }
  }
}

Types of errorClass are:

Copy

Copied

Timeout
InvalidCredentials
AccessDenied
ProviderError
PaymentFailed
GenericError