JSON Web Signature UI Setup | Nuapay Developer Hub

JSON Web Signature User Interface Configuration

It is possible to set up and manage the JWS via the User Interface (as described in this section) or alternatively, this may be done via REST.

Tip: Partner users cannot configure their JWS via the User Interface instead they must use the REST API approach.

Generating the PKI Key and Certificate via the UI

Note: You will require access to the Developer Dashboard via the Nuapay front end. Once you have logged on to Nuapay, the Developer Dashboard link is available on the top right of the screen. Click this to launch the dashboard.

To generate your private key and certificate:

Navigate to the ‘PKI Management’ screen on the Developer Dashboard. (If you cannot see this as a menu option please contact your Account Manager - specific permissions must be enabled to allow you to access this section of the dashboard).
If this is the first time using this screen you will see a notification to say that no PKI key has been generated.
Click Generate PKI Key. This will generate:
- Your Private Key
- A Signed certificate
You will be prompted to download your private key (in .key format):

Important: This will be the only time you will be able to download this key and we will not retain it on our servers. If you need to regenerate the key for any reason you will need to revoke the certificate (see below).

Important: Ideally you should generate your public private key pair in a HSM and present the CSR to be signed over the REST endpoints. The certificate creation UI in the developer dashboard is offered as a convience tool to you

Managing Certificates via the UI

Once you have generated your PKI Key you have two available actions, you can:

Download the certificate in .crt format. .
Revoke your active certificate. This will invalidate the active certificate and private key, and you will no longer be able to generate JSON Web Signatures with this key and certificate. You will need to generate a new private key and certificate.

Retrieving Details from the Certificate

You need to extract certain details from your certificate:

Browse to where you downloaded your certificate (.CRT file) and double-click 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 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). In the example above, 0094cf4671 is decoded as 2496611953.

Next, locate the subject parameters from the certificate:

The following details are provided:

Attribute	Value	Description
OU	Nuapay API	Organization unit, this will always be 'Nuapay API' for certificates signed by Nuapay.
CN	a2av3py82w (for example)	Common name, the merchant 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.

You have now gathered everything you need from the Certificate.

JOSE Header

To generate the JOSE Header you will need the following:

Attribute	Example Value	Description
alg	RS256	Algorithm, always 'RS256'
kid	2496611953 (for example)	Key ID, use the decoded certificate serial number (see Step 3 above).
iat	0	Issued at, the current Unix Epoch timestamp (in milliseconds). Note: this cannot be a future-date timestamp.
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	"crit": [ "iat", "iss", "b64" ]	Critical, always ["iat","iss","b64"]

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.

Detached Payload JWS

The JWS signature generated will need to have a detached payload (the payload is sent as normal in the POST request body but it is not included in the 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.