API Quickstart Guide

Welcome to API iBanFirst! This quickstart guide will help you get started, allowing you to make your first API call and begin exploring the possibilities of iBanFirst possibilities.

Step 1: Sign Up and Get Your API Key

1. Visit the iBanFirst Sign-Up Page.
2. Create your account and log in.
3. Uppon request, our Support team will generate API tokens linked to your account

API tokens can be granted per method, so you may have one for account statement fetching and one for payment execution if you want.

Step 2: Authentication

Every call to the iBanFirst API must be authenticated, which must be done by adding a custom HTTP header (X-WSSE) with your username and secret. This section contains detailed instructions on how to create valid header.

All API request must be made over HTTPS. Calls made over plain HTTP will fail. You must authenticate for all requests.

X-WSSE Format

The header has the following format, usually a single HTTP header line which we broke down into multiple lines for easier readability:

        X-WSSE: UsernameToken
        Username="customer001",
        PasswordDigest="+QpstwYoZeToelOvVaObTdRdEZs=",
        Nonce="d36e3162829ed4c89851497a717f",
        Created="2025-01-01T12:51:45Z"

The following sections describe each component in detail:

• X-WSSE: Name of the HTTPS header we use for authenticating the request.

• UsernameToken: Authentication method. The X-WSSE header must contain a UsernameToken as we only support token-based authentication.

• Username: Field containing the username you were provided during onboarding.

• PasswordDigest: Field containing the hashed token which will prove the authenticity of your request. It is essential that you recompute this hash for every request as a hash is only valid for a certain period of time, and then it expires.

• Nonce: A random value used to make your request unique so it cannot be replicated by any other unknown party.

• Created: Field containing the current UTC, GMT, ZULU timestamp (YYYY-MM-DDTHH:MM:SSZ) according to the ISO8601 format, e.g. 2025-01-01T12:51:45Z.

Computing the Password Digest

Computing the password digest involves 5 simple steps:

• Get a randomly generated 16 byte Nonce formatted as 32 hexadecimal characters.

• Get the current Created timestamp in ISO-8601 format.

• Concatenate the following three values in this order: nonce, timestamp, secret.

• Calculate the SHA-1 hash value of the concatenated string, and make sure this value is in binary format! Some languages, like PHP, output hexadecimal hash by default. You may need to use special methods to obtain hexadecimal hashes in different languages or even convert byte to hex values by hand (see the sample codes below for more information).

• Apply a Base64 encoding to the resulted hash to get the final PasswordDigest value.

Example of creating the X-WSSE header

Here is a sample code that you can use to make your X-WSSE header, or just in a way of understanding the process.

const crypto = require('crypto');

class ibanfirst {
   userId;
   password;
   constructor(userId, password) {
       this.userId = userId;
       this.password = password;
   }

   generateHeader() {
       /**
       * Generate iBanFirst header with WSSE and optional custom fields.
       *
       * @return {Object} A dictionary representing the header with WSSE.
       */

       // Generate a random 16-byte nonce
       const nonce = crypto.randomBytes(16);

       // Get the current UTC timestamp in ISO 8601 format
       const created = new Date().toISOString();

       // Hash nonce + created + password
       const hash = crypto.createHash('sha1');
       hash.update(nonce);
       hash.update(Buffer.from(created, 'utf-8'));
       hash.update(Buffer.from(this.password, 'utf-8'));

       // Encode nonce and hashed password in Base64
       const nonceBase64 = nonce.toString('base64');
       const passwordDigestBase64 = hash.digest('base64');

       // Construct the WSSE header string
       const wsseString = `UsernameToken Username="${this.userId}", PasswordDigest="${passwordDigestBase64}", Nonce="${nonceBase64}", Created="${created}"`;

       // Initialize header with WSSE string
       const header = {
           'X-WSSE': wsseString,
           "Content-Type": "application/json; charset=utf-8"
       };
       return header
                        }
                    }
                    
                    const USER_ID = process.env.USER_ID;
                    const PASSWORD = process.env.PASSWORD;

                    const ibanfirst = new IbanFirst(USER_ID, PASSWORD);
                    console.log(ibanfirst.generateHeader());

Browse API doc and use API

The api doc is here, you may use the "try it out" feature within doc

Sandbox environement vs live environement

Sandbox is your testing environement, it is not related to actual account, it contains only test accounts and balances for you to test your integration before going live.

• sandbox host is sandbox.ibanfirs.com
• live host is api.ibanfirst.com

Special characters

When sending data to our API, you may notice that certain characters are forbidden for security purpose. Those characters are forbidden in route parameters, optional (query) parameters and JSON bodies.

The following characters are not allowed in input fields: