Back to Blog Archive

Digital banking services with Modulr using MuleSoft

Posted on: January 16, 2020
Author:
Sam Elleray

I would like to share some insight into using Mulesoft to achieve digital banking services using Modulr as a platform. In this article, we will be looking at Payments with Modulr. I will outline the steps to creating everything needed to make a payment to and from an account.

1. Introduction

Modulr is a business payments platform being used by more and more companies to move billions of pounds for businesses across alternative lending, payments fintech, payroll services, travel, marketplaces and more. The platform comes with API usage out of the box so is perfect for Mulesoft to integrate with.

2. Scenario

Setting up a service API within Mulesoft to create customers, accounts and beneficiaries within Modulr. Once a beneficiary has been set up, pay them a loan from an account. To achieve this we need to consider authentication and security, and sending requests to Modulr API.

3. Gaining access to the Sandbox

Please note, all of the below HMAC Functions should be created in a subflow, so that it can be referenced later by all flows, and reduces code duplication.

Modulr comes with a free sandbox environment, available to anyone. To gain access, head over to https://www.modulrfinance.com/developers and sign up to the free sandbox account. Once you have the access, you will receive an email containing all of the sandbox information to connect.

Modulr uses an HMAC Authentication type, which you can find more information on here.

4. Starting your development

The HMAC String in the case of Modulr is created using a number of different components:

  • Date (as of now, must be in GMT), must be in the format “Mon, 20 Jan 2020 16:36:07 GMT”
  • Nonce (a single unique ID per request)
  • Sandbox Secret (supplied to you via email when creating sandbox account)
  • Sandbox Key (supplied to you via email when creating sandbox account)

To generate all of the above and assign them to variables, please see code snippet below.

 

Once all of the variables have been created, it’s time to build the String that will be used in the HMAC Signature Generation. The String used in the HMAC Signature must be in this date format:

Mon, 25 Jul 2016 16:36:07 GMT\nx-mod-nonce: 28154b2-9c62b93cc22a-24c9e2-5536d7d

 

 

Mulesoft has a built-in HMAC Signature Generation function within Dataweave, so this is what will be used to generate the Signature. The HMAC Function is split into 2 parts: the Key used to encrypt the data, and the String that you want encrypting.

The Key goes on the left and, in this case, is the API Secret supplied to us from Modulr, and the String we want encrypting is the String we created earlier. The Signature must also be base64 URI encoded. To achieve this we will be using the Crypto functions that are handily available in Mule 4, as long as we import the Function.

Let’s break it down and take a look at the screenshots below:

 

Modulr with MuleSoft

 

  • The data that needs to be used in the function to create the Signature.
  • The crpyto::HMACBinary() function is creating the HMAC String, based on the data provided.
  • toBase64() is base64 encoding the Signature.
  • The encodeURIcomponent() is encoding the entire thing as URI, so that it can be passed via HTTP connectors.

 

Once the HMAC Signature String has been created using the Date, Nonce and API Key, we need to build the entire Authorization Header using Dataweave, to put it into the correct format to match what is listed on the Modulr documentation. The String must match 100% as the exact same process is going to be done by Modulr’s HMAC Function when the request is sent.

The signature also includes the API Key. This is the identifier for the account we are using to log in. The secret is stored on the client side as well as yours, and will be used to generate the HMAC value on their side.

Below, you can see the example String that they give for the Authorization Header:

Authorization: Signature keyId=”57502612d1bb2c0001000025fd53850cd9a94861507a5f7cca236882″,algorithm=”hmac-sha1″,headers=”date x-mod-nonce”,signature=”WBMr%2FYdhysbmiIEkdTrf2hP7SfA%3D”

To generate your own version using Dataweave, use the example below:

5. Sending requests to Modulr

For HMAC Authentication to work, you need to send all of the information that was used to create the Signature over to the target system, so that they may re-create the Signature and make sure that it checks out.

All of these will be included in the headers of the HTTPs requests to Modulr:

  • x-mod-nonce – this is the Nonce ID that we created at the start, and used to generate the HMAC Token.
  • Date – this is the Date we generated at the start, and used to generate the HMAC Token.
  • Authentication – this is the final Signature String that we created in the previous step. It includes the Header names needed to regenerate the Token Date and x-mod-nonce, along with the API Key of our account.

5. 1. Using Modulr API – GET/POST requests

Using the list of API resources available at https://modulr.readme.io/reference, we can now start sending requests to verify that our HMAC Signature is correct. For example, we’re going to use the GET accounts, as we know that at least one exists and it’s a simple GET resource so we don’t need a request body.

Modulr offers 2 base URI’s when using their API’s:

  • https://api-sandbox.modulrfinance.com/api-sandbox/ – this is the base URI to use when you have HMAC Authentication set up, and is the one we will be using.
  • https://api-sandbox.modulrfinance.com/api-sandbox-token/ – this is the base URI to use when you have not got HMAC Authentication setup.

The flow needs to be created which calls the HMAC Signature Generation subflow, so that we have a valid Signature for the request, and an outbound HTTPs GET request needs to be made to the URL with all of the above Headers included
https://api-sandbox.modulrfinance.com/api-sandbox/customers/{CustomerID}/accounts.

Replace {CustomerID} with the customer ID you received when signing up for the sandbox environment. If the request was incorrect, please verify that your Authorization Header String is correct. Please find the “Common problems” section at the bottom of the page with some suggestions as to where it could be failing.

5. 2. Creating a new beneficiary

Once this method works, it confirms that the HMAC Signature is correct, and more complicated requests can be made to the Modulr API. Below is a flow which creates a new beneficiary within Modulr. The POST request is sent to
https://api-sandbox.modulrfinance.com/api-sandbox/customers/{CustomerID}/beneficiaries.

 

 

Modulr with MuleSoft

 

 

5. 3. Paying a beneficiary

Using a similar method that was used to create the beneficiary, create a new POST request to the URL:
https://api-sandbox.modulrfinance.com/api-sandbox/payment.

Modulr with MuleSoft

 

Example body for paying an account below:

 

The “Destination” object is used for the details of the person/account being paid. In this case, it’s another account, but can be a beneficiary too.

Example response below:


6. Common problems with HMAC Signature

If you are having Authorisation issues, please be sure to check for common issues mentioned below:

  • A mismatch between date used to calculate the Signature and actual date sent on the request.
  • Date format. Commonly we see that this date isn’t in the correct format or it’s in UTC instead of GMT (for example, an incorrect date format “Mon, 5 February 2019 08:54:13 GMT” should be > “Mon, 05 Feb 2019 08:54:13 GMT”).
  • Common misspellings:
    • Items in the header
    • “algorithm”
    • “Authorisation” header should be”Authorization”
    • Check headers are correctly named e.g. ‘nonce’ should be ‘x-mod-nonce’
    • Check for empty spaces
  • The Signature String should be made of two lines, i.e. it needs to have \n after “date: …” and not as one line.
  • Trying to base64 encode the hex representation of the signature instead of the raw bytes. Symptom: the generated signature is longer than expected.
  • Base URL that the call is being pointed to is not correct.
  • URL encode character uses lower cases instead of upper case. Symptom: the signature may end in %3d instead of %3D.
Author:
Sam Elleray

Comments

Contact Us

Ricston Ltd.
Triq G.F. Agius De Soldanis,
Birkirkara, BKR 4850,
Malta
MT: +356 2133 4457
UK: +44 (0)2071935107

Send our experts a message

Need Help?
Ask our Experts!