JSON Web Signature Configuration via REST

JSON Web Signature

Tip: It is possible to set up and manage the JWS via REST (as described in this section) or alternatively, this may be done via the Nuapay User Interface through the Developer Dashboard. Partner users MUST use the REST approach.

Creating a Certificate Signing Request (CSR)

Before you can create a certificate you must first generate a CSR. When generating your CSR you must provide the following details:

Attribute	Value	Description
OU	Nuapay API	Organization unit, this will always be 'Nuapay API' for certificates signed by Nuapay.
CN	example: a2av3py82w	Common name; the merchant/partner identifier. If you don't have this identifier, please contact Nuapay Support.
O	Nuapay	Organization, will always be 'Nuapay' for certificates signed by Nuapay.
L	London	Locality, will always be 'London' for certificates signed by Nuapay.
C	GB	Country Name, two letter country code will always be 'GB' for certificates signed by Nuapay.

Important: The State attribute is not required. If you want to provide it, or if it is required in the CSR-generation software that you are using, ensure that you reference its value as ST in the iss section of your JWS Header.

The process for creating a CSR varies depending on the Web Server being used and it is not possible to cover all the variations in this documentation. Details are available online for all popular Web Servers.

The Common Name CN may be either:

A single merchant identifier
Or it may be the partner identifier.

Where a partner identifier is used, the Certificate that is generated will be used to generate the JOSE header that will be used by that partner when calling API services (where non-repudiation is required) on behalf of its merchants.

Please contact Nuapay Support if you do not know your Nuapay merchant/partner identifier.

Detached Payload JWS

A signed JWS encodes information in three parts separated by periods:

a header
a payload
a signature

‘header.payload.signature’
A JWS also supports a detached format that omits the payload from the JWS:
‘header..signature’

When using a detached JWS, the payload is sent as normal in the body but it is not included in the JWS.

Generating Your Certificate via REST

To generate your certificate via REST:

Call the POST/certificates endpoint.
Provide your CSR in the request.
A successful 201 reponse will return your certificate details.

Swagger Reference: Gatekeeper

Retrieving Details from the Certificate

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

Copy the cert returned in the response (as described above) and paste it into a text file.
Replace the \n characters in the certificate with a new line character:
Save the file as a .crt.
Double-click this file to view its details.
Locate the certificate serial number section of the certificate. This is stored as a hexadecimal number and will need to be decoded.
There are various tools available online to allow you to decode the hexadecimal 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 signature later). In the example above, 0094cf4671 is decoded as 2496611953.
Next, locate the subject parameters from the certificate:

The following details are required:

Attribute	Value	Description
OU	Nuapay API	Organization unit: this will always be ‘Nuapay API’ for certificates signed by Nuapay.
CN	a2av3py82w (Example)	Common name: the merchant/partner identifier.
O	Nuapay	Organization: will always be ‘Nuapay’ for certificates signed by Nuapay.
L	London	Locality: will always be ‘London’ for certificates signed by Nuapay.
C	GB	Country Name: two letter country code will always be ‘GB’ for certificates signed by Nuapay.

Only the CN will vary per merchant/partner; all other attributes are static.

The following are the details you need to generate the JOSE Header:

Attribute	Value	Description
alg	RS256	Algorithm: always ‘RS256’
kid	2496611953 (Example)	Key ID: use the decoded certificate serial number
iat	0	Issued at: always ‘0’
iss	“C=GB, L=London, OU=Nuapay API, O=Nuapay, CN=a2av3py82w”	Issuer: use the certificate subject parameters
b64	false	Base64 encoded payload: always ‘false’
crit	[“b64”,”iat”,”iss”]	Critical: always [“b64”,”iat”,”iss”]

At this point you have the following unique details:

Your Private Key.
The Key ID (kid): the serial number from your .crt file.
The Common Name (CN): the Nuapay identifier for your merchant or partner entity. (Other certificate elements are always the same i.e. the C, OU, L, etc. )

Use these details to generate your signature.

Unit Testing

We recommend that you create a unit test that takes your inputs (as described above) and generates an appropriate JWS Signature. To better understand how best to do this please refer to the:

Java sample project: https://github.com/sentenial/jws-sample-java OR
JWS Signature Sample values to see how a specific Private Key, Certificate and payload, can be used to generate a specific JWS signature (using the JWS Generator tool). You can then use the tool to pass in YOUR private key and certificate details to generate a signature for testing purposes.

Note: Once enabled on Production, the Signature needs to be dynamically generated each time you create a request that require the JWS signature as a header e.g. for Create Beneficiary, or Create Credit Transfer. The payload used in the JWS signature generation must match exactly the payload in your request.

Managing Certificates

It is possible to List and Delete Certificates: