Knowledgebase:
ClearBank Integration
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:

  1. Create the pair private/public key
  2. Upload the private key to a HSM
  3. Generate the CSR certificate in the HSM and download it
  4. Use the CSR in the portal of ClearBank to generate the token

Keys generation

The generation for the pair private/public keys can be done in the local machine using the tool openssl

The command to type are:

openssl genpkey -out rsakey_private.pem -algorithm RSA -pkeyopt rsa_keygen_bits:2048
openssl rsa -in rsakey_private.pem -pubout -out rsakey_public.pem

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

Token generation

To generate the token, please access to the ClearBank portal for the client; the portal should have an address like:

http://institution-sim.clearbank.co.uk

for testing, or

http://institution.clearbank.co.uk

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,

  • the token will be used for every kind of operation (GET, PUT, POST, PATCH)
  • the private key will be used to sign the body of every non-GET call

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 CONFIG_MTO_BANK_ACCOUNT_INTEGRATION

As standard, the values for this variable will be the following


CONFIG_MTO_BANK_ACCOUNT_INTEGRATION {
   "enabled": false, 
   "mode": "master",
   "implementation_class": "externalBank",
   "api_url": "",
   "api_credentials": { "token": "" },
   "master_account_id": "",
   "mto_account_ids": { },
   "default_client": {
      "account_id": "",
      "agent_name": ""
   },
   "private_key_path": "classes/integration/ClearBank/certificate"
}

When configuring, the possible values are the following:

  • enabled: True or False
  • mode: master is for the main organisation,
         agent
     is for the MTOs connected to the main organisation
  • implementation_class: "ClearBank"
  • api_url
    https://institution-api-sim.clearbank.co.uk
    when testing in simulation environment,
      
           https://institution-api.clearbank.co.uk
    when going live
  • token: the token generated in the ClearBank panel for the main organisation (see previous section about HSM and token)
  • master_account_id: it has to be set when configuring in master mode; it is given by the client
  • mto_account_ids: this is a list of pairs
         "agent_name": "virtual_account_id"

    to be configured in master mode; these pairs are given by the client
  • default_client: it has to be set when configuring in agent mode; it iincludes the account_id corresponding to the agent (MTO) for which the system is set up, when in agent mode, and the agent_name to be displayed.

The system will be set up

  • in master mode for the main organisation, which has to have the master_account_id and the pairs of mto_accounts_ids
  • in agent mode for the MTOs, which has to have only the default_client

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

Self-Certification

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.

(0 vote(s))
Helpful
Not helpful

Comments (0)