# 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="https://3854995783-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F18qPmpVTf1krG1JEgbI2%2Fuploads%2FecKXr3rzJhVxQzff7Dg9%2FScreenshot%202025-07-07%20at%2014.36.00.png?alt=media&#x26;token=d0f1fc19-210f-479d-9b13-497e27233a1f" alt=""><figcaption><p>Webhook setup in the merchant dashboard</p></figcaption></figure>

{% hint style="info" %}
Learn more about the webhook structure and signature [here](https://docs.fonbnk.com/v1.5/on-ramp/webhook).
{% 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="https://3854995783-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F18qPmpVTf1krG1JEgbI2%2Fuploads%2F8gj4DwzQOdI5DiCA5fhY%2FScreenshot%202025-07-03%20at%2015.20.01.png?alt=media&#x26;token=9bcdd9ca-8570-4ceb-8093-a7d281b4ff7f" 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="https://3854995783-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F18qPmpVTf1krG1JEgbI2%2Fuploads%2F2fXVB6C7SkrxAcGtTY1k%2FScreenshot%202025-07-07%20at%2014.38.03.png?alt=media&#x26;token=5a964028-1ea7-4676-8ce0-fb291f5048f8" 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](https://docs.fonbnk.com/v1.5/on-ramp/url-parameters) 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="https://3854995783-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F18qPmpVTf1krG1JEgbI2%2Fuploads%2FgfD8NCUsS36uNo0BJxIZ%2FScreenshot%202025-06-05%20at%2016.25.52.png?alt=media&#x26;token=b038ee70-bcd2-4011-ac38-5afaa1a4c317" 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="https://3854995783-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F18qPmpVTf1krG1JEgbI2%2Fuploads%2FdA2GD765rbpMdcghC14L%2Fimage.png?alt=media&#x26;token=23bc4950-c047-46f4-89cc-cd1583874fa3" 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="https://3854995783-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F18qPmpVTf1krG1JEgbI2%2Fuploads%2FMbPsmLWo9PxRxzSE51rL%2Fimage.png?alt=media&#x26;token=df546fb8-3abe-4244-bbad-d022b99b50b5" 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 %}