Security

We use API Keys to ensure the security of your sensitive data, which is transmitted via Secure Sockets Layer (SSL) over the HTTPS protocol.

API Key Authentication

For REST authentication the following HTTP headers in each HTTP request targeted are required.

Mandatory API Key authentication basic:

1. Template: “Authorization: Basic {Base64(API_KEY:)}”
2. Example
   • With the following given APIKey = bb09c2b6a9478720765c757a8bcadf1aa1fb31554566a21118c9c75e26c29686
   • We encode this in base 64: bb09c2b6a9478720765c757a8bcadf1aa1fb31554566a21118c9c75e26c29686: (note that the colon (:) is required)
   • the HTTPS header will then be: Authorization: Basic YmIwOWMyYjZhOTQ3ODcyMDc2NWM3NTdhOGJjYWRmMWFhMWZiMzE1NTQ1NjZhMjExMThjOWM3NWUyNmMyOTY4Njo=

PKI Management

PKI (Public Key Infrastructure) Management is used to generate a private key and signed certificate to be used in generating JSON Web Signatures (JWS) for non-repudiation in our REST endpoints.

To generate your private key and certificate:

• Log on to the Developer Dashboard.
• Navigate to the ‘PKI Management’ screen.
• If this is the first time using this screen the only button available to you will be Generate PKI Key.
• Click this button to generate your Private key and signed certificate.

Once you click the button you will be prompted to download your private key in .key format.

We recommend you store your private key in a secure location such as on a local or cloud based HSM.

After closing the download dialog box you will see your active certificate and there are two actions you can carry out on it:

JSON Web Signature

The ‘JSON Web Signature’ (JWS) is used as part of a REST header to validate requests made to create an instant payment. Having this header indicates that you have signed the request with your private key. Any requests to this specific endpoint that does not include the Javascript Object Signing and Encryption (JOSE) header will fail.

Steps Required to Generate a Valid Header

To create a JOSE header you will need to:

• Generate a Private Key and a Certificate (as outlined above).
• Retrieve the certificate serial number and decode it.
• Extract the issuer details from your certificate.
• Use the JWS Signature Generator to generate the JOSE header.

You will then use this header value in any APIs where it is required.

Retrieving Details from the Certificate

In order to generate the JOSE Header you’ll need to extract certain details from your certificate:

1. Browse to where you downloaded your certificate (.CRT file) and double-click to view its details.
2. Locate the certificate serial number section of the certificate. This is stored as a hexadecimal number and will need to be decoded.



3. There are various tools available online to allow you to decode the haxadecimal value, see https://www.rapidtables.com/convert/number/hex-to-decimal.html for example. (The decoded number is the kid value that you will need to generate your Header later).
4. Next, locate the subject parameters from the certificate:

At this point you have gathered everything you need from the Certificate. These are the details you need to generate the JOSE Header:

Use the JWS Signature Generator to generate the JOSE Header.