Use-cases

How it works

Fonbnk Pay Widget is a secure and efficient way to accept payments in stable coins from customers in an integrated and non-integrated way.

It's a P2P platform that connects people who want to sell mobile money(Airtime, M-PESA, Bank, etc.) with people who would like to buy it.

How it works for end users:

1. A customer selects his funds source (Airtime, M-PESA, Bank, etc.) and the amount of crypto he would like to receive

2. Customer provides his wallet details

3. Customer transfers funds to an agent we found for him and confirms the order

4. An agent confirms the order and the system sends USDC to a customer's wallet

Example of a flow:

On-ramp flow in Kenya

Pay Widget supports configuration via URL parameters. Merchants can force the widget to use specific wallet address, memo, crypto amount, etc. This allows integrating the widget as a payment system.

Integration types

Basic

The simplest way to start accepting payments is to use the widget as a standalone page with a link to it from your website. You can configure the widget to use your wallet address via URL parameters. In this case, you will receive payments but won't be able to track them.

Possible use cases:

• crowdfunding campaigns

• donations

• purchases when a user manually provides transaction hash to the merchant

Iframe/Webview integration

You can embed the widget into your website or mobile app using iframe or Webview and use URL parameters to configure it. Using this approach, you will be able to track order progress via window events. An integrator can react to order success/failure and show appropriate messages to the user. An integrator can extract order details and send them to its back-end.

Registered merchant integration with webhooks

This is the most advanced integration type. A merchant needs to register in the merchant dashboard.

In the dashboard, a merchant can:

• set up a webhook

• track webhook requests

• track orders

• configure USDC wallets associated with his account

We associate orders with a merchant in two ways:

1. By wallets configured in the dashboard. If an order wallet matches one of the merchant wallets, we associate the order with the merchant and send him webhook requests.

2. By a special "source" query parameter provided to a pay widget URL. It can be found in the dashboard settings.

How to choose between these two approaches:

• if a merchant operates with a huge amount of different wallets he must use the "source" parameter

• if a merchant just wants to receive payments to a couple of wallets, he can configure them in the dashboard

A merchant can associate orders in our system with his users in his system by providing orderParams query parameter to a pay widget URL. This parameter will be included in webhook requests and can be used to match a merchant system user to an order user.

Application examples

Donations​

Let's say, you have a USDC on a Polygon network wallet and want to receive donations. All you need is to add the following link to your website:

<a href="https://pay.fonbnk.com/?freezeWallet=1&network=POLYGON&address=0xa6dBAE6239E2B18A8c60E8F0EC2eE84ca623e5c2">Donate</a>

freezeWallet parameter will freeze the wallet address and type, so a user can't change it and network and address parameters will force the widget to use your wallet address.

Crypto wallets website

Let's say you have a crypto wallet website and want to allow your users to buy USDC with their mobile money. You need to embed an iframe with the following URL:

https://pay.fonbnk.com/?freezeWallet=1&network={USER_WALLET_NETWORK}&address={USER_WALLET_ADDRESS}

Then you can start to listen for success or failure and react on it:

function handleFonbnkEvent(event) {
  try {
    const data = JSON.parse(event.data);
    if (data.source === 'fonbnk') {
      switch (data.type) {
        case 'order-success':
          // show success message and close the widget
          const transactionHash = data.data.transactionHash;
          const address = data.data.order.walletAddress;
          const network = data.data.order.walletType;
          const usdcAmount = data.data.cashout.usdcWithdrawAmount;
          // send transactionHash, address, network, usdcAmount to your back-end for history tracking
          break;
        case 'order-failed':
          // show fail message and close the widget
          break;
      }
    }
  } catch (e) {}
}
window.addEventListener('message', handleFonbnkEvent, false);

Mobile game currency purchase

Let's say you have a mobile game and want to allow your users to buy in-game currency with their mobile money.

You need to register in our system as a merchant and configure a wallet you want to receive funds and a webhook URL. Let's say you've configured the following webhook URL: https://your-game.com/fonbnk/webhook and the following USDC wallet: AVALANCHE 0xa6dBAE6239E2B18A8c60E8F0EC2eE84ca623e5c2.

You have a user in your system with ID 33789 who would like to buy in-game currency for 5 USDC.

You have to display a WebView with the following URL:

https://pay.fonbnk.com/?orderParams=33789&freezeWallet=1&network=AVALANCHE&address=0xa6dBAE6239E2B18A8c60E8F0EC2eE84ca623e5c2&amount=5&currency=usdc&freezeAmount=1

It will:

• freeze the wallet address and USDC amount, so a user can't change it

• link the order to your user with ID 33789

When a user completes the order and funds are sent to your wallet, we will send a webhook request to your webhook URL https://your-game.com/fonbnk/webhook with a content like following:

{
  "data": {
    "status": "complete",
    "orderId": "...our system order id...",
    "phoneNumber": "...customer phone number...",
    "amount": 5,
    "network": "AVALANCHE",
    "address": "0xa6dBAE6239E2B18A8c60E8F0EC2eE84ca623e5c2",
    "memo": "",
    "hash": "...transaction hash...",
    "orderParams": "33789"
  },
  "hash": "...signature hash..."
}

You can extract orderParams from the webhook request and use it to match your user with ID 33789 to the order and add in-game currency to his account.