Some banks require sensitive end-user data (sometimes called Payment Service User information or PSU ID), such as national identity number, to allow certain operations in their API. End-user consent is one example. This type of data needs strong protection.

If a bank requires sensitive end-user data, the bank object returned from the GET Bank endpoint API will have the field personalIdentificationRequired set to true.

Encryption and decryption

The Neonomics API requires encryption of sensitive end-user data before it is sent in the request header. The header parameter used for encrypted end-user data is x-psu-id. The value of this parameter passes through Neonomics platform in encrypted form before it gets decrypted, as it is being sent from the Neonomics platform to the bank’s PSD2 API.

Encryption key

The Neonomics Developer Portal is where you generate an encryption key. It is possible to create one key per Application. This key cannot be re-generated.

To generate an encryption key, Edit the Application in the Developer Portal. Then click on the Generate Key button to create an encryption key for your Application in the Neonomics platform.

Once the key is created, a Download Key button will appear. Click this button and download the <client_id>.json encryption key file. Please store this file in a secure location.

After you have downloaded the encryption key, the next step is to encrypt the value of the x-psu-id parameter, which will be sent to the Neonomics API. The same encryption key will be used by the Neonomics platform for decryption.

Encoding

You should encode the encrypted value to Base64 before sending it as the x-psu-id header parameter.

Algorithms

Tink

The Neonomics platform uses the cross-platform, multi-language cryptographic library Tink (created and maintained by Google) to decrypt data sent to the API. The sensitive end-user data sent in the x-psu-id header parameter needs to be encrypted using the generated encryption key and the cryptographic library Tink.

📘

Info

In case your language is not supported by the Tink encryption library, you can use the rawValue attribute from the encryption key file along with another library that supports AES GCM to perform the encryption. Please contact us if you need specific AES GCM parameters.

Crypto

Crypto is one example of an alternative library for customers who use JavaScript.

Crypto is a module in Node.js which provides cryptographic functionality that includes a set of wrappers for open SSL's hash HMAC, cipher, decipher, sign and verify functions.

Example:

Below are examples of how to encrypt the data in Java, JavaScript with Node.js using the crypto library, and PHP:

// 1. Register Aead key types supported in a particular release of Tink.  
AeadConfig.register();

// Path of the encryption file downloaded from the Neonomics Portal.  
String keySetFileName = "/path/to/my/encrypted/key/key.json";

// 2. Generate the key material.  
KeysetHandle handle = CleartextKeysetHandle.read(JsonKeysetReader.withFile(new File(keySetFileName)));

// 3. Get the primitive.  
Aead aead = AeadFactory.getPrimitive(handle);

// Value to encrypt for the x-psu-id Neonomics API header  
String valueToEncrypt = "31125451740";

// 4. Use the primitive.  
byte\[] plaintext = valueToEncrypt.getBytes();  
byte\[] ciphertext = aead.encrypt(plaintext, new byte[0]);

// 5. Create a Base64 value of the encrypted data.  
String dataToSendToNeonomics = new String(Base64.getEncoder().encode(ciphertext));

const crypto = require('crypto');  
const rawValue = "\<raw_value>";  
const ssn = "\<value_to_encrypt>";  
const iv = crypto.randomBytes(12);  
const key= Buffer.from(rawValue, 'base64');  
const cipher = crypto.createCipheriv('aes-128-gcm', key, iv, {  
    authTagLength:16  
});

        <?php
        $data_to_encrypt = "31125451740"; // the social security number to encrypt
        echo "Data to encrypt: " . $data_to_encrypt . "<br>";
        $cipher = "aes-128-gcm";
        $raw_data = "pxedhkec6hmWrS/oV4Xlwg=="; // value of the rawValue field from the encryption key
        $key = base64_decode($raw_data);            
        if (in_array($cipher, openssl_get_cipher_methods())) {
            $iv_len = openssl_cipher_iv_length($cipher);
            $iv = openssl_random_pseudo_bytes($iv_len);
            $tag = "";
            $ciphertext = openssl_encrypt($data_to_encrypt, $cipher, $key, OPENSSL_RAW_DATA, $iv,$tag);
            echo "Encrypted String: " . base64_encode($ciphertext) . "<br>";
            $with_iv = base64_encode($iv.$ciphertext.$tag);
            echo "Encrypted String with IV to be sent to Neonomics: " . $with_iv;
        }
        ?>

Example of the Base64 value generated above, required in the x-psu-id header parameter: ARxbvsVFZnYiYrkVCDOn1AE0EY955HQVMZwSOdV0eSg7QQ2kzfVIlY7Hr/D3

Supported sandbox banks

To test sensitive end-user data functionality in the sandbox environment, you can use the Norwegian bank DNB. It requires the end-user's National Identification Number, which is an 11-digit number assigned to every resident of Norway.

Please see the testing in sandbox page for test login credentials that you can use to test DNB in our sandbox.