iBanFirst API (1.4.0)

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.

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

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.

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.

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.

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. SUBSCRIPTIONS

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

• You may have multiple active subscriptions at the same time.

• Available payment events : PAYMENT_CREATED PAYMENT_PLANIFIED PAYMENT_FINALIZED PAYMENT_WAITING_SIGNATURE PAYMENT_AWAITING_CONFIRMATION PAYMENT_CANCELED PAYMENT_BLOCKED PAYMENT_WAITING_JUSTIFICATION

• Trade events : coming soon

3. IMPLEMENTATION

• Delivery and retries
  • Webhooks may not be delivered in order, so your implementation should not assume sequential delivery.
  • If a notification fails (error code HTTP 400 or 500), it will be retried twice, with a 60-second delay between attempts. This means a maximum of 3 delivery attempts per event.
• Acknowledgement
  • We recommend responding with a HTTP 204 code (No Content) to acknowledge receipt of a notification.
• Whitelisting
  • To ensure webhooks 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 request header.
  • You must reject the notification if the signatures does not match.
• Recommended best practices :
  • Always validate the signature before processing any webhook.
  • Webhook payloads must be stored on a private server to protect sensitive data.

5. WEBHOOK NOTIFICATION CONTENT

For a payment (see get payment details) :

{
 "event": "PAYMENT_PLANIFIED",
 "payload": {
    "id": "Mck0OMkzOQ",
    "status": "planified",
    "createdDate": "2025-12-03 10:45:25",
    "desiredExecutionDate": "2025-12-03",
    "executionDate": null,
    "amount": {
      "value": "11.00",
      "currency": "EUR"
    },
    "tag": "Automation",
    "externalBankAccountId": "NmgdNDU5",
    "sourceWalletId": "NjgtNjgz",
    "sourceWalletNumber": null,
    "communication": "documentation ",
    "priorityPaymentOption": "normal",
    "feePaymentOption": "SEPA",
    "feePaymentAmount": {
      "value": "1.00",
      "currency": "EUR"
    }
  },
"webhookId": "e35b6e8d-67ef-4973-945d-c3190a60d0aa"
}