> ## Documentation Index
> Fetch the complete documentation index at: https://docs.niobi.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Creating and Verifying Signatures

> To maintain the Niobi payment system security and integrity, users are required to sign their request messages using their private key. By following these steps, you'll learn how to make a signature for your message and how Niobi checks that signature to make sure it's really from you. If the signature doesn't check out, Niobi won't accept the message.

## 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)

```json theme={null}
{
  "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 client ID (public identifier) to the JSON object with the field name `"client_id"`. Also **temporarily** add your secret key in the JSON object with the field name `"senderKey"`

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. (K-sort refers to sorting keys alphabetically, recursively for nested objects.)

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:

```json theme={null}
{
  "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):

```Copy code theme={null}
client_id=your_client_key_here&params.amount=10&params.city=Nairobi&params.client_callback_url=https://your-domain.com/niobi/result&params.country=KEN&params.currency=KES&salt=random_salt_value&sender=Integration_title&senderKey=your_secret_key_here&timestamp=UNIX_timestamp
```

After hashing (Step 8, 9 and 10):

```json theme={null}
{
  "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 client ID (public identifier) to the JSON object with the field name `"client_id"`. Also **temporarily** add your secret key in the JSON object with the field name `"senderKey"`.

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.

<Note>
  Please make sure to save this `signature` somewhere as you will need this signature to compare it with your own.
</Note>

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.