fi-api-postman

This repository contains Postman collections for integrating with the FI API.

A more detailed blog post about Self-Signing requests in Postman can be found here.

Getting Started

To communicate with the FI API you need to register your Authentication Profile with the Clear Bank platform. This guide contains a quick how-to for setting up a basic Authentication Profile for a test environment. More information about Authentication Profiles and the configuration required for production can be found on our Developer Guide.

Create a Certificate

A basic certificate can be created using OpenSSL. In test environments CSRs can be generated using Open Source solutions (such as OpenSSL) but production has stricter requirements.

From the commandline navigate to a directory where you have read/write permissions. Running the following script will generate a <name>.csr and <name>.Key file that you wil need to access later.

openssl req -out .\<name>.csr -new -sha256 -newkey rsa:2048 -nodes -subj "/ST=localhost/L=localhost/CN=localhost/" -keyout .\<name>.key

Create an API Token

Log in to the Clear Bank portal and navigate to Institution > Certificates and Tokens. From here you can generate a new API Token. To do this you'll need to upload to <name>.csr file you generated in the previous step. Again, once generated, make sure you store your API Token somewhere safe.

Getting Started with GET requests

1. Import the collections and environments
2. Set the 'fi-api-authToken' variable to the one you generated in the ClearBank portal for that environment
3. Make the request

Getting Started with POST requests

POST requests require the body to be signed and included in the request headers as 'DigitalSignature'.

1. Import the collections and environments
2. Set the 'fi-api-authToken' variable to the one that you've generated in the ClearBank portal for that environment
3. Set 'APIPrivateKey' to the contents of the <name>.key file you generated earlier
4. Make the request

Notes

In order to sign the request body we're utalising a third-party utility which can be found here. The javascript bundle needs to be stored in an environment variable so that it can be accessed in the Pre-Request scripts. More information about importing this bundle can be found here.

Gotcha's

Content-Type Header

The Pre-Request script used to generate the DigitalSignature hardcodes the Content-Type request header to application/json. You can override this by supplying your own Content-Type header (I.e. override the one auto-generated by postman)