Integration Guide

Video tutorial

Setting Up Your Sandbox Environment

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.

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.

Webhook setup in the merchant dashboard

Learn more about the webhook structure and signature here.

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.

Webhook simulation in the merchant dashboard

If you want to preview webhook notifications without setting up a server, you can use the webhooks service.

Generating Payment URLs and Creating Orders

To create sandbox orders, utilize the sandbox pay widget, which can be accessed at Sandbox Pay Widget. 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.

Source param in the merchant dashboard

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 in the JWT token payload.

An example of a token generation in 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 phone numbers:

Country	Carrier	Phone Number	Password
Nigeria	MTN	2347000000007	ZoA8dA9CXF
Kenya	Safaricom	254740719977	ZoA8dA9CXF

Make sure to use the Login with Password flow:

Pay widget login with password

Warning

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

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

Merchant dashboard on-ramp orders list

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

Merchant dashboard on-ramp webhooks

Merchant API

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

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/.

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.