Using Integration via API

Open

Open

1. Introduction

The Masspay payout instruction functionality is implemented to allow a user to perform multiple payout requests with a single click. Efficiency and productivity are the main drivers of this feature as it allows a user to perform up to 1000 payouts in a single operation.

The focus of this guide is Masspay payout instruction functionality via API.

2. Encryption

2.1. Cryptography

In cryptography, an encryption key is a variable value that is applied using an algorithm to a string or block of unencrypted text to produce encrypted text or to decrypt encrypted text. The length of the key is a factor in considering how difficult it will be to decrypt the text in a given message. A strong encryption key is typically a randomly generated sequence of bits that is not easily guessed. Encryption algorithms are implemented in software, and they encrypt data by applying a key to unencrypted data. Ciphertext results from that process. It is protected from unauthorized access and is accessible only to users or software that have the proper decryption key. Encrypted data is decrypted when the encryption algorithm applies the correct key to the ciphertext. The above-mentioned cryptographic operation may be conveniently summarised by means of the following diagram:

This system implements asymmetric encryption. Public key cryptography, also referred to as asymmetric cryptography, uses public key pairs. One of the paired keys is public, and the other is private. Each of these keys can transform plaintext into encrypted ciphertext – but ciphertext encrypted with one of the keys can only be decrypted with the other key. When the public key is used to encrypt ciphertext, that text can only be decrypted using the private key. This enables anyone with access to the public key to encrypt a plaintext message, which only the private key holder will be able to decrypt. This is how private messages can be sent without exchanging a shared secret key. Text encrypted with the private key can only be decrypted using the public key. A ciphertext encrypted with a private key is decrypted using the public key to authenticate the signature. Public keys are published in publicly accessible repositories, where anyone who needs to communicate with public key pair holders can access them. The key pair owner is the only one who can hold the private key. It must remain secret, or else the key pair can't be trusted to authenticate the owner. Asymmetric encryption may be visualised as per the following diagram:

This guide outlines the generation of keys using a suitable IDE, where the private keys are kept, and the public keys are shared.

2.2. X-Content-Signature header

ISX has its own secure cloud service, which can be used for sharing keys.

Upon request, sample software for signature creation can be provided via our cloud service.

Currently we have Java, .NET, and Node.js implementations.

The signature is calculated over the bytes of the body only:

• Signature = RSA 4096 (Base64(HMACSHA512(key, nonce, datetime, bytes of request body))).

• Key is direction specific – a different key is used for requests and responses.

• Data for HMAC is bytes of the 4 fields concatenated in the provided order.

• The X-Content-Signature value is "v=1; k=<key name>; n=<Base64(8 byte nonce)>; d=<datetime in UTC milliseconds>; s=<signature>".

• The <key name> is a short key name (2-3 characters) so that we can pre-exchange and rotate keys easily without downtime or signature failures.

Also, the public key of the RSA 4096 and the generated HMAC secret key must be provided.

Merchants will need to generate the RSA private/public key pair with 4096 bits and also choose an HMAC SHA 512 secret key, following common best practices:
private keys must be kept private, whereas the public key and the HMAC secret key must be shared via a secure platform with the ISX relationship management team.

The above is summarised in the figure below:

3. Setting up keys

3.1. IntelliJ IDEA

In order to perform this task, a Java compiler is required. For the purposes of this manual, IntelliJ IDEA will be used. IntelliJ IDEA is an integrated development environment (IDE) written in Java for developing computer software written in Java, Kotlin, Groovy, and other languages. It is developed by JetBrains (formerly known as IntelliJ) and is available as an Apache 2 Licensed community edition and as a proprietary commercial edition. Both editions can be used for commercial development.
Download the IntelliJ IDEA IDE (opt for the Community edition) that is compatible with your operating system:

Once downloaded and installed, you will need the ‘SignatureCreatorStandalone.zip’ provided by ISX after being granted access to ISX Cloud.

Path: Files > Payouts Integrations > COMMON > JAVA > SignatureCreatorStandalone_.zip

Unzip the ‘SignatureCreatorStandalone_.zip’ file and launch the IntelliJ IDEA program.

Then, select the ‘Open’ option to open the ‘SignatureCreatorStandalone’ directory. It will prompt you to trust it - click on ‘Trust Project’. Once it is open, note the following files:

• ‘SubmitBatchRequest.json’

• ‘private.pem’

• ‘private_dec.pem’

• ‘public.pem’

3.2. Key generation

Delete the following 3 PEM files because new ones will be generated:

• ‘private.pem’

• ‘private_dec.pem’

• ‘public.pem’

Open the IntelliJ IDEA terminal.

Ensure that you are in the same path as the one in the figure: '..\SignatureCreatorStandalone'

You must have Openssl installed. For Windows, download it from here, selecting the latest version. If necessary, refer to this tutorial.

Firstly, generate the encrypted private key PEM file - copy the following command & paste it into the terminal:

Enter a PEM password of your choice twice.

A new file named ‘private.pem’ should now have been created.

Secondly, generate the decrypted private key PEM file - copy the following command & paste it into the terminal:

Enter the same PEM password that was created before.

A new file named ‘private_dec.pem’ should now have been created.

Finally, generate the public key PEM file - copy the following command & paste it into the terminal:

Enter the same PEM password that was created before.

A new file named ‘public.pem’ should now have been created.

This last file, ‘public.pem’, must be sent to ISX via encrypted open banking message to proceed.

But, this file needs to be changed to .txt format, before being sent. This can be accomplished in Windows by running the following command in the same terminal used to generate the keys:

This command will generate a copy of the public key in .txt format that can be easily opened and sent.

Create a random and secure password that will be needed later, which is called ‘hmacSecret’. This should be at least 30 characters long, composed of uppercase and lowercase characters with numbers.

This ‘hmacSecret’ must also be sent to ISX via encrypted open banking message to proceed.

Once you have received a successful response from ISX you may continue with the following steps.

3.3. Modify the 'SubmitBatchRequest.json' file as required

The ‘SubmitBatchRequest.json’ file includes all the data of a given transaction that ISX needs to create a payout.

Enter as many records as necessary enclosing each record within curly braces (i.e., {}) and separating each record with a comma.

Each record in the JSON dataset is composed of the following data:

• payment_details (mandatory): a free text description to be used in the account statement. Maximum field length: 75 characters. Alphanumeric characters are allowed. The following special characters are allowed: [ ] ? : - + . ' / \ ( ) . These details are passed into the description fields of the outgoing transactions of ISX Money.

• beneficiary_name (mandatory): the name of the account holder. Maximum field length: 75 characters. Only alphabetic characters are allowed. The following special characters are allowed: [ ] ? : - + . ' / \ ( ) .

• beneficiary_reference (mandatory): a beneficiary reference field that is only visible on the iSXMoney dashboard. This is a description to the merchant that explains the nature of a transaction. Maximum field length: 75 characters. Alphanumeric characters are allowed. The following special characters are allowed: [ ] ? : - + . ' / \ ( ) .

• beneficiary_iban (mandatory): the IBAN to which the funds will be paid out.

• payment_amount (mandatory): the amount of money to be paid out. Decimals must be separated with a period, not a comma.

• currency (mandatory): the value of this field must always be EUR. This is a case-sensitive field.

• reference_ID (mandatory): an arbitrary unique (for the batch) ID that is only visible on the iSXMoney dashboard. Maximum field length: 75 characters. Alphanumeric characters are allowed. The following special characters are allowed: [ ] ? : - + . ' / \ ( ) _.

• beneficiary_address (conditional): the address of the beneficiary. Maximum field length: 75 characters. Alphanumeric characters are allowed.

• beneficiary_city (conditional): the city of the beneficiary. Maximum field length: 75 characters. Alphanumeric characters are allowed.

• beneficiary_country (conditional): the country code representing the country of the beneficiary. Only alphabetic characters are allowed. This field must be expressed as an ISO 3166-1 Alpha-2 code.

The ‘SubmitBatchRequest.json’ file, in the ‘SignatureCreatorStandalone’ directory, is an example and must be edited:

The following fields need to be edited with data provided by the ISX relationship management team:

• merchant_id

• sender_iban

The other fields of the JSON file can be edited by the merchant as required.

3.4. Run the ‘SignatureCreator’ file

The SignatureCreator is implemented in 3 frameworks, as per the following.

3.4.1. The SignatureCreator in Java:

Open the ‘SignatureCreator.java’ file from the ‘src’ directory of the ‘SignatureCreatorStandalone’ folder in IntelliJ IDEA, as per the following:

Modify the following line in the file:

This should be the hmacSecret password that was previously provided to ISX.

Before continuing ensure the following:

Click the ‘Settings’ in IntelliJ IDEA (top right corner as per the figure below):

Click on the ‘Project Structure’ option in the 'Settings' drop-down menu:

Ensure that the ‘SDK’ field is selected, as per the figure below:

If the ‘SDK’ field was already selected, then leave it as is.

Furthermore, there is a small possibility that you will need to clear the field below from ‘Edit Configurations…’, as per the figure below:

Ensure that the ‘Program arguments’ field is empty, as per the figure below:

Now run the ‘SignatureCreator’ file using the 'Run' button, as per the figure below:

The output should resemble the figure below:

From this output, you will need the following:

X-Content-Signature:

SubmitBatchRequest.json:

3.4.2. The SignatureCreator in .NET:

For more information regarding the SignatureCreator in the .NET platform, please contact us.

3.4.3. The SignatureCreator in Node.js:

For more information regarding the SignatureCreator in the Node.js platform, please contact us.

3.5. Postman: create the API request

Request Method: POST.

The API is accessed from the Request URL. This is a combination of our URL and the addition of the following text to the end of the URL: “/v1/batch/”.

• Production Environment URL: https://api.payout.isx.money/api/v1/batch

• Staging Environment URL: https://api.stage.payout.isx.money/api/v1/batch

Required Headers:

Complete the appropriate header information.

The Domain and Subdomain keys are provided by the ISX relationship management team.

Example:

Postman example:

Required body:

The body must be the same as the content of the ‘SubmitBatchRequest.json’ that was used before to generate the X-Content-Signature signature.

SubmitBatchRequest.json:

Postman example:

3.6. CURL: example of an API request

Creating a CURL request requires the parameters and structure as per the code below: 

3.7. API request response

Once the POST has been successfully sent, you will receive the following response:

Postman example:

4. Callbacks

Callbacks refers the channel that is used for notification purposes.

4.1. Receiving callbacks

Firstly, in order to receive callbacks with updates regarding the transactions, the ‘SubmitBatchRequest.json’ must be amended to include a callback URL.

The callback URL must have appended to the end as ‘version=XXXXMMDD’ (i.e., XXXXMMDD  = year + month + day).

SubmitBatchRequest.json:

However, these notifications do not include the status, only the batch ID as per the below example:

Furthermore, in the header of this callback, an ‘X-Content-Signature’ is received that can only be used to verify that this callback was indeed sent by ISX and signed with a public.key that ISX holds.

Use a tool like webhook.site to understand how ISX sends a callback to a webhook.

The following refers to an example of a callback using webhook.site:

The callback URL used: 'https://webhook.site/#!/d89ad899-7888-46fb-91e1-ddb63645a484?version=20231222'.

5. API batch request

Now that a callback with a batch ID was received, the status of the transactions in that batch can be requested with an API Get request.

5.1. Get batch state

5.1.1. Postman: Create an API request

Request Method: GET.

The API is accessed from the Request URL. This is a combination of our URL and the addition of the following text to the end of the URL: “/v1/batch/{+ batch_id}”.

• Production Environment URL: https://api.payout.isx.money/api/v1/batch/{+ batch_id}

• Staging Environment URL: https://api.stage.payout.isx.money/api/v1/batch/{+ batch_id}

Required Headers:

Complete the appropriate header information.

The Domain and Subdomain keys are provided by the ISX relationship management team.

Example:

Postman example:

The body must be empty.

5.1.2. CURL: Example of an API request

Creating a CURL request requires the below parameters and structure:

5.1.3. CURL: Example of an API request

Once the GET is successfully sent, the following response will be received:

Postman example:

5.1.4. Batch statuses

5.2. Get batch details

5.2.1. Postman: Create an API request

Request Method: GET.

The API is accessed from the Request URL. This is a combination of our URL and the addition of the following text to the end of the URL: “/v1/batchdetails/{+ batch_id}”.

• Production Environment URL: https://api.payout.isx.money/api/v1/batchdetails/{+ batch_id}

• Staging Environment URL: https://api.stage.payout.isx.money/api/v1/batchdetails/{+ batch_id}

Required Headers:

Complete the appropriate header information.

The Domain and Subdomain keys are provided by the ISX relationship management team.

Example:

Postman example:

The body must be empty.

5.2.2. CURL: Example of an API request

Creating a CURL request requires the below parameters and structure:

5.2.3. CURL: Example of an API request

Once the GET is successfully sent, the following response will be received:

Postman example:

5.2.4. Transaction statuses

6. When to perform GET API batch requests

This refers to the retrieval of the overall batch status or of the status per transaction.
It is recommended performing an API batch or batch details request only after receiving a callback from ISX.