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.

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.

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.

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 accounts if you want an order to be automatically confirmed.

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

Make sure to use the Login with Password flow:

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

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

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