​

Overview

To maintain the Niobi payment system security and integrity, users are required to generate a unique signature for each request. This signature is generated by using the unique secret key generated by a user in their Niobi App. Once sent, the signature is verified by Niobi upon receipt and then subsequently the payment request is approved.

​

Signing Requests

To ensure the security and integrity of your communication with the Niobi API, it’s essential to sign each request. The complete step by step process for doing this is as follows:

​

Request Signing Algorithm

Follow these steps to sign your requests:

1. Once your onboarding with Niobi has been completed, navigate to the Integration section under Workspace and generate new credentials by creating a new entity Integration. Make sure to name your integration, as this will be used in the signature process.

2. Now, create a request JSON object with the following additional parameters in the payload. (in addition to the payment request)

{
  "sender": "Integration_title",
  "timestamp": "UNIX_timestamp",
  "salt": "random_salt_value",
  "client_id": "your_client_key_here",
  "senderKey": "your_secret_key_here",
}

3. Add a Salt: Insert a salt value into your request’s JSON object. Use the field name "salt" for this value. This is a random string and can be unique value for each request or always the same.

4. Include Your Client and Secret Key: Add your public key in to the JSON object with the field name "client_id". Also temporarily add your secret key in the JSON object with the field name "secret_id"

5. Add the Integration Title Take the integration title you have set when creating credentials on the app and add it to the request with the field name "sender".

6. Sort: Sort the key-value pairs alphabetically before conversion. A recursive K-sort would work well here.

7. Convert to a String: Convert the entire JSON object into a string representation. Format each pair as "key=value" and concatenate them using the "&" character.

8. Hash the String: Use the SHA-256 hashing algorithm, along with your secret key, to hash the string obtained in the previous step. This produces a hash string.

9. Add the Signature: Insert the hash string back into the JSON object as the value of a new "signature" field.

10. Remove the Secret Key: Finally, remove the "senderKey" field from the JSON object to prevent exposing your secret key.

​

Example

Here’s an example to illustrate the process (This does not include the payment payload, which MUST be part of the same request)

Before signing:

{
  "sender": "Integration_title",
  "timestamp": "UNIX_timestamp",
  "salt": "random_salt_value",
  "client_id": "your_client_key_here",
  "senderKey": "your_secret_key_here",
  "params": {
    "amount": 10,
    "city": "Nairobi",
    "client_callback_url": "https://your-domain.com/niobi/result",
    "country": "KEN",
    "currency": "KES"
  }
}

After steps 6 and 7 (Stringify, Sort, and Hash):

client_id=your_client_key_here&params.amount=10&params.city=Nairobi&params.client_callback_url=https%3A%2F%2Fyour-domain.com%2Fniobi%2Fresult&params.country=KEN&params.currency=KES&salt=random_salt_value&senderKey=your_secret_key_here&sender=Integration_title&timestamp=UNIX_timestamp

After hashing (Step 8, 9 and 10):

{
  "sender": "Integration_title",
  "timestamp": "UNIX_timestamp",
  "salt": "random_salt_value",
  "client_id": "your_client_key_here",
  "params": {
    "amount": 10,
    "city": "Nairobi",
    "client_callback_url": "https://your-domain.com/niobi/result",
    "country": "KEN",
    "currency": "KES"
  }
  "signature": kfjhsfk**********39450knf
}

Ensure you follow these steps carefully to secure your requests. A correctly signed request assures both parties of the authenticity and integrity of the messages being exchanged.

​

Verifying Response Signatures

After receiving a response from the Niobi API, it’s critical to verify the signature to ensure the response’s integrity and authenticity. Follow the steps below to verify the signature of the response:

​

Steps for Verification

1. Include Your Client and Secret Key: Add your public key in to the JSON object with the field name "client_id". Also temporarily add your secret key in the JSON object with the field name "secret_id".

2. Preserve the Signature: Before making any modifications, ensure you save the value of the "signature" field elsewhere for later comparison. After saving, remove the "signature" field from the JSON object.

3. Stringify and Sort: Convert the modified JSON object into a string. Ensure the key-value pairs are alphabetically sorted before conversion.

4. Hash the String: Apply a hash function (e.g., SHA-256) to the string obtained in the previous step.

5. Compare Signatures: Finally, compare the hash result from Step 4 with the signature sent with the original response.