Posted by Marco Dal Monte, Last modified by Marco Dal Monte on 14 January 2020 10:18 AM
HSM and Token Creation
When you have to set up the integration for ClearBank for a client, one step is to create the connection with the portal given by ClearBank
The step are the following:
The generation for the pair private/public keys can be done in the local machine using the tool openssl
The command to type are:
The first command will generate the private key, the second one will use the private key to generate the public key
The next step is to access the HSM panel: it is recommended to use Microsoft Azure Key Vault, as there is a set of API calls available, in case of future needs; for testing I recommend to subscribe for a trial version
When logged in, in the panel access to the link "Security" from the side menu, and click on "Key vaults"
You have to generate a new Key vault, having a unique name all over the world: for this reason, I recommend to choose a name formed of company name, department name, client name, mixing them to form a probably unique name, and follow the wizard steps.
If the name is unique, at the end of the procedure you will see a Success message, otherwise an error will be shown on screen.
After this step, access in the Key vault details, and go to "Keys" to upload your private key.
Choose the "Import" procedure, choose your file from the disk and give a unique name.
The last step is to access "Certificates", choose to generate a new certificate, give a unique name, choose Self-Signed from the drop-down box, give a subject (for example, CN=<domain>), give a number of month of validity and click on "Create".
The creation process will be shown as pending, after few minutes it will be possible to reload the page and download the CSR clicking on the record for the created certificate.
Download the CSR certificate
To generate the token, please access to the ClearBank portal for the client; the portal should have an address like:
for testing, or
in live version.
When logged in, access to Institution->Certificates and Tokens and procede uploading your CSR certificate.
Click on the symbol + close to API Tokens, select the CSR file from your disk, give a unique name and a large expiration date and click on "Generate New Certificate".
The system will show the new generate token, which can be accessible later clicking on the information icon relative to each generated token.
Warning: Even if a token with a name has been deleted, it is not possible to re-use that name for a newly-generated token.
When connecting to ClearBank API,
Currently R1 integration does not involve any non-GET call, but the HSM procedure is needed to pass the self-certification with ClearBank, as standard procedure.
Configuration in ARM
To configure ClearBank API in ARM, please access Configuration Settings and search for the configuration variable called
As standard, the values for this variable will be the following
When configuring, the possible values are the following:
The system will be set up
The integration involve a cron job downloading the transaction for the MTOs at regular time intervals (normally every hour), and a page to show these transactions, filtering by agent, start and end date
The standard values for the filters are All Agents, and the last 3 days as time window
In master mode the admin can filter by agents, or see the transactions for all of them, while the agent can see only the transactions related to him
In agent mode the admin can see only the transaction related to his default_client->account_id, while the agent cannot see any record
When logged to ARM as admin, the page will be included in the menu Accounting as agent there will be a separate menu MTO Account.
In both cases the menu item is called ClearBank Account Activity
Note that before going live, the client (or RemitOne) has to submit a self-certification form that has to be approved by ClearBank.
This form is in Excel format and it is sent by ClearBank: in this form you have to reply to few questions about which calls you have tested, which HSM you will use and sign it.