# Integration Guide

### Video tutorial <a href="#setting-up-your-sandbox-environment" id="setting-up-your-sandbox-environment"></a>

{% embed url="<https://vimeo.com/1082484387>" %}

### Setting Up Your Sandbox Environment <a href="#setting-up-your-sandbox-environment" id="setting-up-your-sandbox-environment"></a>

To begin integrating with our system, the first step is to register a merchant account in the sandbox environment. Follow this link to initiate the registration process: <https://sandbox-dashboard.fonbnk.com/register-initiate>.<br>

Configuring Webhook Integration

Once you have a sandbox account, navigate to the **Settings** page on the dashboard. Here, you can configure a webhook URL to receive notifications regarding order status changes.

<figure><img src="/files/WLp7NY8uq3jqDU4aPxoT" alt=""><figcaption><p>Webhook setup in the merchant dashboard</p></figcaption></figure>

{% hint style="info" %}
Learn more about the webhook structure and signature [here](/v1.5/on-ramp/webhook.md).
{% endhint %}

You can also test your webhook integration using the **Simulate the webhook request** feature. Provide a URL and click the **Send Request** button to have the dashboard send a test notification to the specified URL.

<figure><img src="/files/59XUJmIHX8yrnA6ZJRY5" alt=""><figcaption><p>Webhook simulation in the merchant dashboard</p></figcaption></figure>

{% hint style="info" %}
If you want to preview webhook notifications without setting up a server, you can use the [webhooks service](https://webhook.site/).
{% endhint %}

### Generating Payment URLs and Creating Orders <a href="#generating-payment-urls-and-creating-orders" id="generating-payment-urls-and-creating-orders"></a>

To create sandbox orders, utilize the sandbox pay widget, which can be accessed at [Sandbox Pay Widget](https://sandbox-pay.fonbnk.com/). To associate an order with your merchant account, you must include the **source** parameter in the pay widget URL. You can find the **source** parameter value in the **Additional Details** section of the **Settings** page on the dashboard.

<figure><img src="/files/8baGHxHiA0Rh05lpzVD3" alt=""><figcaption><p>Source param in the merchant dashboard</p></figcaption></figure>

Additionally, you must provide a unique **signature** parameter, which is a JWT token (HS256 encryption algorithm) generated using "URL signature secret" value as a secret. You must add some unique value to the token payload to make each token unique because we don't allow to create more than 1 order using the same signature. During testing, you can generate a JWT signature using this website, <https://jwt.io/>. You can also provide [URL configuration parameters](/v1.5/on-ramp/url-parameters.md) in the JWT token payload.\
&#x20;

An example of a token generation in typescript:

```typescript
import * as jsonwebtoken from 'jsonwebtoken';
import { v4 as uuid } from 'uuid';

const token = jsonwebtoken.sign(
    {
      uid: uuid(),
    },
    YOUR_SIGNATURE_SECRET,
    {
      algorithm: 'HS256',
    },
 );
```

With the provided **source** parameter, the pay widget URL will look like this: <https://sandbox-pay.fonbnk.com/?source=bd3X9Cgq&signature=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1aWQiOiJlcmcyMmYyZkBAIn0.Z1BB4eiClKH_k18w5I3tMiutuWpPgPb5gI33FrkpJcY>.

To create an order in the sandbox environment, you must use one of the following accounts if you want an order to be automatically confirmed.

<table><thead><tr><th>Country</th><th>Email</th><th width="170">Password</th></tr></thead><tbody><tr><td>Nigeria</td><td>sandbox-ng@fonbnk.com</td><td>ZoA8dA9CXF</td></tr><tr><td>Kenya</td><td>sandbox-ke@fonbnk.com</td><td>ZoA8dA9CXF</td></tr><tr><td>Ghana</td><td>sandbox-gh@fonbnk.com</td><td>ZoA8dA9CXF</td></tr><tr><td>Any supported country</td><td>sandbox-{countryCode}@fonbnk.com</td><td>ZoA8dA9CXF</td></tr></tbody></table>

You can register your email, but orders will be automatically rejected.

Make sure to use the **Login with Password** flow:

<figure><img src="/files/Vet3e1FwiIBMRoDjq6wU" alt=""><figcaption></figcaption></figure>

{% hint style="warning" %}
Warning

During sandbox testing, do not use real money. Simply confirm the order, and it will be marked as paid.
{% endhint %}

If the correct **source** parameter is present in the URL, the order will be displayed in the **Orders** tab of the dashboard:

<figure><img src="/files/SCkoYgsxnt7YU1ifrlAW" alt=""><figcaption><p>Merchant dashboard on-ramp orders list</p></figcaption></figure>

Webhook requests will also be visible in the **Webhooks** tab of the dashboard:

<figure><img src="/files/nJwAESQwcfJpVw5jIwtN" alt=""><figcaption><p>Merchant dashboard on-ramp webhooks</p></figcaption></figure>

### Merchant API <a href="#merchant-api" id="merchant-api"></a>

For those who wish to access pay widget-related data from their back-end, our merchant API is available. You can find the API documentation here.

### Transitioning to Production <a href="#transitioning-to-production" id="transitioning-to-production"></a>

To create a live merchant account, proceed to register it here: <https://dashboard.fonbnk.com/register-initiate>. The live pay widget can be accessed at <https://pay.fonbnk.com/>.&#x20;

{% hint style="warning" %}
After registering, you'll need to contact our support team and complete a KYB process. Thereafter, you'll be able to receive webhooks and preconfigure user wallet addresses.
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.fonbnk.com/v1.5/integration-guide.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.