Notifications

Notifications, or webhooks, are HTTP callbacks. These allow you to track your transactions and their status changes in a more efficient manner, and enable you to automate communications internally or with your customers.

Below are the event types that can trigger notifications on the Banking Circle Platform. When one of these events is triggered, we send an HTTP POST request to the webhook URL (the web URL that you define). The data about the event is then sent to your webhook URL in JSON format, which we refer to as payload. In terms of implementation, you can write an API endpoint with https that can receive an HTTP POST in an application stack of your choice.

Notification TypeDescription
IncomingPaymentProcessedWhen one of your physical or virtual accounts is successfully funded (this includes also internal credit transfers)
OutgoingPaymentRejectedWhen one of your outgoing payments is rejected
OutgoingPaymentProcessedWhen one of your outgoing payments is successfully processed (this includes also internal credit transfers)

Subscriptions are performed on company level for all accounts. This means that you'll be receiving notifications when events are triggered for all the accounts belonging to your company.

When you are ready to start testing Notifications in our Sandbox environment, to go live or make changes to existing subscriptions, contact our Sales team here.

You can find more information on our Sandbox capabilities here.

Setup prerequisites

You'll need to provide the following details through LiquidFiles:

  • Endpoint: The web address we should push the notifications to. You will need to set up your system and have a URL with https ready to listen for our notifications.
  • Subscription type: What events you want to subscribe to. It can be some or all of the following:
    • Incoming payments
    • Outgoing Rejected payments
    • Outgoing Processed payments
  • Encryption key: The secret key used for encryption and decryption of the payload. For more details on the encryption mechanism continue reading Webhook security section.

Webhook security

There are 3 security mechanisms we are using for communicating data to your endpoint:

1. HTTPS with TLS 1.2

You have to ensure that the communication channel is secured with TLS 1.2.

2. Encryption

Payload encryption

We support UTF-8 for the password. You should provide a password of exactly 32 characters, compatible with the 256-bit key required by the AES-256-GCM encryption algorithm.

Payload decryption

The encrypted payload is stored in the body of the message as a stream of bytes. To decrypt, you will need the same encryption key that was used during the encryption process. As a result, we recommend that you store this key so that it can be used later for decryption.

Along with the encryption key, you will also need the Nonce and the Authentication Tag. These will be sent as Base64-strings as part of our HTTP Request header.

The decrypted payload is encoded as unicode/UTF-16LE.

3. Data Integrity check

To ensure the data received at your endpoint is the same as the data sent from our API, an SHA256-checksum will be sent as a Base64-string as one of the HttpRequest headers called Checksum. Through it, you can be sure the data you received from us hasn't been tampered with.

Notification payload

You can expect to receive notifications that will include a header and a body.

The payload's body includes properties that could be sent as part of the notification. Some properties might be omitted or be null. Depending on the notificationType, Classification and Status body parameters will change as for the web service. For the "notificationType": "OutgoingPaymentRejected", the "transfer" object won't be present in the payload.

We advise on building a flexible parser as properties might change their location. You can read more about Reports API here.

For reconciliation purposes, we recommend the Reports endpoints.

HeaderDescription
Subscription VersionThe subscription and the related payload we are sending
NonceIt's short for Number used Once and it's an AES-GCM encryption parameter
AuthTagThe Authentication Tag is an AES-GCM encryption verification parameter
ChecksumHash of the message body (SHA-256 hash)
Body (JSON array)Description
eventIdA unique id given to the individual event notification
subscriptionIdA unique id given to the parent subscription
subscriptionEventIdA unique id given to one the child subscriptions - Incoming Payment Processed subscription, Outgoing Payment Rejected subscription, and Outgoing Payment Processed
notificationTypeCan have one of these values: IncomingPaymentProcessed, OutgoingPaymentRejected, OutgoingPaymentProcessed
timestampThe time when the event was triggered
paymentThis object includes properties with information on the specific instruction/transaction. You will get creditor and debtor account details, amount and currency among others. See more in the example below.

Here you have an example of a outgoing processed notification what we will send to your endpoint:

Checksum: omCWli/jqujrbchOIEw18Zkb9hcoJvPtGxMeCd4DvfA=,
Nonce: A/zhOsBsRB/zIf6y, AuthTag: Oe0P37s3DqHROlsvQ8UpDA==
SubscriptionVersion: 1

{ "notifications": [ { "subscriptionId": "0944149a-5bd3-48b0-a6e2-ebff3108685f", "subscriptionEventId": "bcfb5826-cc74-4ecd-9a7b-13b3b9498d94", "eventId": "0252c415-b40e-42a9-ac9c-734e7d0a44b3", "notificationType": "OutgoingPaymentProcessed", "timestamp": "2021-05-05T20:34:33.0350148Z", "payment": { "paymentId": "1c982897-d96f-f8bf-664f-9ab64dac5e71", "transactionReference": "1c982897-d96f-f8bf-664f-9ab64dac5e71", "classification": "Outgoing", "status": "Processed", "errors": null, "lastChangedTimestamp": "2021-05-05T20:33:11.861789+00:00", "debtorInformation": { "paymentBulkId": null, "accountId": "40ebe223-7bbd-40d7-fe3e-e583028b3e76", "account": { "account": "DK5289000049910071", "financialInstitution": "SXPYDKKKXXX", "country": null }, "vibanId": null, "viban": null, "instructedDate": "2021-05-05T00:00:00+00:00", "debitAmount": { "currency": "EUR", "amount": 15 }, "debitValueDate": "2021-05-05T00:00:00+00:00", "fxRate": null, "instruction": { "debtorAccount": { "account": "DK5289000049914571", "financialInstitution": null, "country": null }, "debtorViban": null, "debtorReference": "FMC pmt", "debtorNarrativeToSelf": null, "currencyOfTransfer": "EUR", "amount": { "currency": "EUR", "amount": 15 }, "requestedExecutionDate": "2021-05-05T00:00:00+00:00", "chargeBearer": "Sha", "remittanceInformation": { "line1": "FMC pmt rem1", "line2": null, "line3": null, "line4": null }, "creditorId": null, "creditorAccount": { "account": "DK3789000049910050", "financialInstitution": null, "country": "DK" }, "creditorName": "Payments 1", "creditorAddress": { "line1": "25 Oxford Str.", "line2": "GB - London, SW 5T", "line3": null } } }, "transfer": { "debtorAccount": { "account": "DK52890000499104571", "financialInstitution": "SXPYDKKKXXX", "country": null }, "debtorName": "Payments 2", "debtorAddress": { "line1": "26 Oxford Str.", "line2": "GB - London, SW 5T", "line3": "United Kingdom" }, "amount": { "currency": "EUR", "amount": 15 }, "valueDate": "2021-05-05T00:00:00+00:00", "chargeBearer": "Sha", "remittanceInformation": { "line1": "FMC pmt rem1", "line2": null, "line3": null, "line4": null }, "creditorAccount": { "account": "DK3789000049910050", "financialInstitution": null, "country": "DK" }, "creditorName": "Payments 1", "creditorAddress": { "line1": "25 Oxford Str.", "line2": "GB - London, SW 5T", "line3": null } }, "creditorInformation": null } } ] }

Retry strategy

In the case that a notification cannot be successfully delivered to an endpoint, we will retry delivery with an increasing backoff with every failed delivery. Your endpoint must respond with an HTTP success status (2xx) to indicate successful receipt of the notification. After the tenth unsuccessful retry, we will stop sending notifications and deactivate the subscription.

The notification that caused the retries and other notifications that happened before the subscription deactivation are stored and they will be sent once the subscription is re-activated.

Any payments which are made while the subscription is deactivated will not trigger any notifications.

You can request payments status by sending a request to GET payments/singles. You can read more about the Payments API here.

RetryTime after first failure
1st Retry00:00:02
2nd Retry00:00:05
3rd Retry00:00:10
4th Retry00:10:00
5th Retry00:30:00
6th Retry01:00:0
7th Retry03:00:00
8th Retry06:00:00
9th Retry12:00:00
10th Retry24:00:00