Webhook subscriptions

iBanFirst API (1.6.0)

Download OpenAPI description
ClientAPI.json
ClientAPI.yaml
Languages
Servers
https://api-demo.ibanfirst.com/api/

Accounts

Each of your accounts has its own specific currency and IBAN. The API allows you to get details and balances about each account in real time.

Note : accounts are also labelled as wallets in the iBanFirst API.

Operations

Financial movements

The API allows you to retrieve all financial movements from your accounts.

Operations

Beneficiaries

A beneficiary can be either your own account in another bank or a third party recipient account. Beneficiaries can be created or deleted through the API.

Note : beneficiaries are also labelled as externalBankAccounts in the iBanFirst API.

Operations

Payments

Sending funds from one of your iBanFirst accounts to your own external bank account or a third-party recipient involves two steps:

  1. Generate the payment object with the 'Create payment' method.
    A unique id is assigned to each payment.

  2. Use the 'Confirm Payment' method to send the payment for processing. When you confirm a payment, make sure you have sufficient funds in your account balance.

Caution: Payments are automatically rolled to the next closest working days if not confirmed in the scheduled date of operation. If the balance of your account is not sufficient to cover the payment amount, funds may be locked-in by iBanFirst.

Operations

Spot trades

The API provides a deliverable FX facility and deliverable FX liquidity. You will become counterparty to iBanFirst and can market and sell deliverable FX services to corporate and private clients as well as using such services on their behalf.

FX trades are always made between two accounts of a unique counterparty. iBanFirst will automatically debit the source account and credit the delivery account at the date specified in the FX trade instructions. If the delivery date has been scheduled, the delivery is automatically processed in the morning before 00:30 am Paris time. If the delivery date is today (TOD), the funds is available on your account by the next 20mn.

A FX trades also involves an amount, which includes both the numeric amount and the currency in order to define if this amount is the nominal to be bought or sold, for example: '100000.00+GBP'.

Operations

Fixed forward payment contract

Book a fixed forward payment contracts instantly on iBanFirst without manual intervention.

  • Available currency pairs:

    • EUR/USD
    • EUR/GBP
    • GBP/USD

  • Maturities: up to 6 months.

  • Transaction limit: 1M EUR equivalent per transaction.

Before using fixed forward, you must have:

  • Credit approval.
  • Collateral in place.
  • Accepted the Autonomous Forward disclaimer.

The deliveryDate must satisfy the following conditions:

  • Minimum date: current date + 3 business days.
  • Maximum date: earlier between [current date + 6 months] and maximum maturity date allowed.
Operations

Documents

The API allows you to access your documents stored on the iBanFirst platform through a one-time access link.

Documents must be generated on the platform before being available through the API.

Operations

Webhook subscriptions

1. WHAT IS A WEBHOOK ?

  • Webhooks are events based real-time notifications providing updates on transactions and removing the need for periodic polling.

  • Webhook notifications are sent as HTTPS POST requests to a URL of your choice.

2. WEBHOOK SUBSCRIPTIONS

  • Each webhook subscription allows you to receive notifications for one or more event types :

    • Outgoing payment :PAYMENT_PLANIFIED PAYMENT_FINALIZED PAYMENT_WAITING_SIGNATURE PAYMENT_AWAITING_CONFIRMATION PAYMENT_CANCELED PAYMENT_BLOCKED PAYMENT_WAITING_JUSTIFICATION PAYMENT_INCOMING

    • Spot trade : TRADE_PLANIFIED TRADE_FINALIZED TRADE_CANCELED TRADE_BLOCKED

    • Fixed forward payment contract : FIXED_FORWARD_PLANIFIED FIXED_FORWARD_FINALIZED FIXED_FORWARD_CANCELED

  • You may have up to 10 active subscriptions at the same time.

3. IMPLEMENTATION

  • Delivery and retries
    • Webhook notifications may not be delivered in order, your implementation should not assume sequential delivery.
    • If a notification delivery fails (HTTP status code 400 or 500), it will be retried twice, with a 60-second delay between attempts. This results in a maximum of three delivery attempts per event.
  • Acknowledgement
    • We recommend responding with a HTTP 204 code (No Content) to acknowledge receipt of a notification.
  • Whitelisting
    • To ensure webhook notifications reach your URL, you may need to whitelist the following IP (production and demo): 51.158.86.1.

4. SECURITY

  • Each webhook notification includes an HMAC-256 signature in the request header to let you validate its authenticity.
    • To verify the signature, recontruct the signed message by concatenating the exact timestamp and request raw body as received : x-ibanfirst-timestamp.{Body}.
    • Compute an HMAC-SHA256 hash of this string using the subscription secret key and compare the result with the x-ibanfirst-signature provided in the notification header.
    • You must reject the notification if the signatures do not match.
  • Recommended best practices :
    • Always validate the signature before processing any webhook notification.
    • Webhook notification payloads must be stored on a private server to protect sensitive data.

5. WEBHOOK NOTIFICATION CONTENT

Notifications contain the relevant object as described in each reconciliation service.

{
 "event": event_label,
 "payload": {
    see get payment details, get trade details or get fixed forward details
 },
"webhookId": "e35b6e8d-67ef-4973-945d-c3190a60d0aa"
}
Operations

Create webhook subscription

Request

You can subscribe to one or more events.

Note : Please save the issued secret as it cannot be retrieved again.

Bodyapplication/jsonrequired
eventsArray of strings(events)required
Items Enum"PAYMENT_CREATED""PAYMENT_PLANIFIED""PAYMENT_FINALIZED""PAYMENT_WAITING_SIGNATURE""PAYMENT_AWAITING_CONFIRMATION""PAYMENT_CANCELED""PAYMENT_BLOCKED""PAYMENT_WAITING_JUSTIFICATION""PAYMENT_INCOMING""TRADE_PLANIFIED"
urlstring(url)^(https?:\/\/)[^\s/$.?#].[^\s]*$required

Notifications are sent to this url.

Example: "https:\\www.notification.com"
curl -i -X POST \
  https://api-demo.ibanfirst.com/api/webhooks \
  -H 'Content-Type: application/json' \
  -d '{
    "events": [
      "PAYMENT_CREATED"
    ],
    "url": "https:\\www.notification.com"
  }'

Responses

OK

Bodyapplication/json
webhookIdstring(webhookId)^[0-9a-fA-F]{8}(-[0-9a-fA-F]{4}){3}-[0-9a-fA-...

ID of the webhook subscription.

Example: "cf16243d-7e0a-4a5b-b996-ba7018201e30"
eventsArray of strings(events)
Items Enum"PAYMENT_CREATED""PAYMENT_PLANIFIED""PAYMENT_FINALIZED""PAYMENT_WAITING_SIGNATURE""PAYMENT_AWAITING_CONFIRMATION""PAYMENT_CANCELED""PAYMENT_BLOCKED""PAYMENT_WAITING_JUSTIFICATION""PAYMENT_INCOMING""TRADE_PLANIFIED"
secretstring^[A-Za-z0-9]{32,64}$
urlstring(url)^(https?:\/\/)[^\s/$.?#].[^\s]*$

Notifications are sent to this url.

Example: "https:\\www.notification.com"
Response
application/json
{
  "webhookId": "cf16243d-7e0a-4a5b-b996-ba7018201e30",
  "events": [
    "PAYMENT_CREATED"
  ],
  "secret": "string",
  "url": "https:\\www.notification.com"
}

Get webhook subscriptions list

Request

Retrieve the list of your webhook subscriptions.

curl -i -X GET \
  https://api-demo.ibanfirst.com/api/webhooks

Responses

OK

Bodyapplication/jsonArray [
webhookIdstring(webhookId)^[0-9a-fA-F]{8}(-[0-9a-fA-F]{4}){3}-[0-9a-fA-...

ID of the webhook subscription.

Example: "cf16243d-7e0a-4a5b-b996-ba7018201e30"
eventsArray of strings(events)

List of subscribed events.

Items Enum"PAYMENT_CREATED""PAYMENT_PLANIFIED""PAYMENT_FINALIZED""PAYMENT_WAITING_SIGNATURE""PAYMENT_AWAITING_CONFIRMATION""PAYMENT_CANCELED""PAYMENT_BLOCKED""PAYMENT_WAITING_JUSTIFICATION""PAYMENT_INCOMING""TRADE_PLANIFIED"
urlstring(url)^(https?:\/\/)[^\s/$.?#].[^\s]*$

Notifications are sent to this url.

Example: "https:\\www.notification.com"
]
Response
application/json
[
  {
    "webhookId": "cf16243d-7e0a-4a5b-b996-ba7018201e30",
    "events": [ … ],
    "url": "https:\\www.notification.com"
  }
]

Get webhook subscription details

Request

Retrieve the details of a specific webhook subscription.

Path
webhookIdstringrequired

The ID of the webhook subscription.

curl -i -X GET \
  'https://api-demo.ibanfirst.com/api/webhooks/{webhookId}'

Responses

OK

Bodyapplication/json
webhookIdstring(webhookId)^[0-9a-fA-F]{8}(-[0-9a-fA-F]{4}){3}-[0-9a-fA-...

ID of the webhook subscription.

Example: "cf16243d-7e0a-4a5b-b996-ba7018201e30"
eventsArray of strings(events)

List of subscribed events.

Items Enum"PAYMENT_CREATED""PAYMENT_PLANIFIED""PAYMENT_FINALIZED""PAYMENT_WAITING_SIGNATURE""PAYMENT_AWAITING_CONFIRMATION""PAYMENT_CANCELED""PAYMENT_BLOCKED""PAYMENT_WAITING_JUSTIFICATION""PAYMENT_INCOMING""TRADE_PLANIFIED"
urlstring(url)^(https?:\/\/)[^\s/$.?#].[^\s]*$

Notifications are sent to this url.

Example: "https:\\www.notification.com"
Response
application/json
{
  "webhookId": "cf16243d-7e0a-4a5b-b996-ba7018201e30",
  "events": [
    [ … ]
  ],
  "url": "https:\\www.notification.com"
}

Update webhook subscription

Request

You can update the list of subscribed events and/or the url notifications are sent to.

Path
webhookIdstringrequired

The ID of the webhook subscription you want to update.

Bodyapplication/jsonrequired
eventsArray of strings(events)
Items Enum"PAYMENT_CREATED""PAYMENT_PLANIFIED""PAYMENT_FINALIZED""PAYMENT_WAITING_SIGNATURE""PAYMENT_AWAITING_CONFIRMATION""PAYMENT_CANCELED""PAYMENT_BLOCKED""PAYMENT_WAITING_JUSTIFICATION""PAYMENT_INCOMING""TRADE_PLANIFIED"
urlstring(url)^(https?:\/\/)[^\s/$.?#].[^\s]*$

Notifications are sent to this url.

Example: "https:\\www.notification.com"
curl -i -X PATCH \
  'https://api-demo.ibanfirst.com/api/webhooks/{webhookId}' \
  -H 'Content-Type: application/json' \
  -d '{
    "events": [
      "PAYMENT_CREATED"
    ],
    "url": "https:\\www.notification.com"
  }'

Responses

OK

Bodyapplication/json
webhookIdstring(webhookId)^[0-9a-fA-F]{8}(-[0-9a-fA-F]{4}){3}-[0-9a-fA-...

ID of the webhook subscription.

Example: "cf16243d-7e0a-4a5b-b996-ba7018201e30"
eventsArray of strings(events)
Items Enum"PAYMENT_CREATED""PAYMENT_PLANIFIED""PAYMENT_FINALIZED""PAYMENT_WAITING_SIGNATURE""PAYMENT_AWAITING_CONFIRMATION""PAYMENT_CANCELED""PAYMENT_BLOCKED""PAYMENT_WAITING_JUSTIFICATION""PAYMENT_INCOMING""TRADE_PLANIFIED"
urlstring(url)^(https?:\/\/)[^\s/$.?#].[^\s]*$

Notifications are sent to this url.

Example: "https:\\www.notification.com"
Response
application/json
{
  "webhookId": "cf16243d-7e0a-4a5b-b996-ba7018201e30",
  "events": [
    "PAYMENT_CREATED"
  ],
  "url": "https:\\www.notification.com"
}

Cancel webhook subscription

Request

Cancel a webhook subscription to stop receiving notifications.

Path
webhookIdstringrequired

The ID of the webhook subscription you want to cancel.

curl -i -X DELETE \
  'https://api-demo.ibanfirst.com/api/webhooks/{webhookId}'

Responses

OK

Response
application/json
{
  "errorCode": 0,
  "errorType": "string",
  "errorMessage": "string",
  "link": "string"
}

Rotate secret

Request

Ask for a new secret for a specific webhook subscription.

Path
webhookIdstringrequired

The ID of the webhook subscription.

curl -i -X POST \
  'https://api-demo.ibanfirst.com/api/webhooks/{webhookId}/rotate-secret'

Responses

OK

Bodyapplication/json
webhookIdstring(webhookId)^[0-9a-fA-F]{8}(-[0-9a-fA-F]{4}){3}-[0-9a-fA-...

ID of the webhook subscription.

Example: "cf16243d-7e0a-4a5b-b996-ba7018201e30"
eventsArray of strings(events)
Items Enum"PAYMENT_CREATED""PAYMENT_PLANIFIED""PAYMENT_FINALIZED""PAYMENT_WAITING_SIGNATURE""PAYMENT_AWAITING_CONFIRMATION""PAYMENT_CANCELED""PAYMENT_BLOCKED""PAYMENT_WAITING_JUSTIFICATION""PAYMENT_INCOMING""TRADE_PLANIFIED"
secretstring^[A-Za-z0-9]{32,64}$
urlstring(url)^(https?:\/\/)[^\s/$.?#].[^\s]*$

Notifications are sent to this url.

Example: "https:\\www.notification.com"
Response
application/json
{
  "webhookId": "cf16243d-7e0a-4a5b-b996-ba7018201e30",
  "events": [
    "PAYMENT_CREATED"
  ],
  "secret": "string",
  "url": "https:\\www.notification.com"
}

Get failed notifications

Request

Retrieve the list of failed notifications for a given subscription.

Path
webhookIdstringrequired

The ID of the webhook subscription.

Query
fromDatestring(YYYY-MM-DD)

The starting date to search for failed notifications.

toDatestring(YYYY-MM-DD)

The ending date to search for failed notifications.

pagestring

Index of the page.

Default "1"
per_pagestring

Number of items returned per page.

Default "50"
sortstring

Notifications are sorted by creation date.

Default "DESC"
Enum"ASC""DESC"
curl -i -X GET \
  'https://api-demo.ibanfirst.com/api/webhooks/{webhookId}/failed-notifications?fromDate=string&page=1&per_page=50&sort=ASC&toDate=string'

Responses

OK

Bodyapplication/json
failedNotificationsArray of objects(webhookFailedNotification)
totalCountstring

Total count of failed notifications

Example: "10"
pagestring

Index of the page.

Example: "1"
perPagestring

Number of items returned per page.

Example: "50"
totalPagesstring

Number of pages.

Example: "10"
Response
application/json
{
  "failedNotifications": [
    { … }
  ],
  "totalCount": "10",
  "page": "1",
  "perPage": "50",
  "totalPages": "10"
}

Logs

Operations
Company
© iBanFirst.com 2025
iBanFirst Platform
iBanFirst PSD2 API
Legal
Privacy Policy
Cookie Policy
Terms of use
Legal
Complaints
Whistleblowing
Fees
Security acknowledgments
iBanFirst S.A. is duly authorised and regulated by the National Bank of Belgium (under company number 0849.872.824) as a payment institution. Our registered address is at Avenue Louise 489, 1050 Brussels, Belgium. The products and services that iBanFirst S.A. offers are limited to unregulated spot FX transactions and deliverable forward payment contracts (forward payment, flexible forward payment and dynamic forward payment) excluded from MiFID and EMIR regulation, as they are intended to cover an underlying future payment for identifiable goods and services. iBanFirst S.A. does not offer options or any other financial instruments for investment or speculative purposes.