Iframe events

When the pay widget is integrated as an iframe into a website, a website can listen to its events.

How to listen for events from the iframe pay widget

window.addEventListener(
 "message",
 function (event) {
   try {
     const data = JSON.parse(event.data);
     if (data.source === "fonbnk") {
       console.info("fonbnk pay widget iframe event", data);
     }
   } catch (e) {}
 },
 false
);

Order status events

• order-created - user created an order, now he should transfer funds to a market maker and confirm the order

• order-buyer-confirmed - user confirmed his order

• order-buyer-rejected - user rejected his order

• order-pending-seller-confirmation - user waits for an agent to confirm an order

• order-seller-confirmed - user confirmed an order

• order-seller-rejected - user rejected an order

• order-pending-payment - user waits for a USDC/cUSD transfer to his wallet

• order-success - USDC/cUSD transferred successfully to a user

• order-failed - filed to transfer USDC/cUSD to a user

• close-iframe - if there is a closeBtn queey param and user clicked on the button

Order status event structure:

type FonbnkEvent = {
 type: string; // events described above
 source: "fonbnk";
 data: {
   order: {
     _id: string;
     userId: string;
     walletType:
       | "POLYGON"
       | "ETHEREUM"
       | "CELO"
       | "STELLAR"
       | "AVALANCHE"
       | "SOLANA"
       | "BASE"
       | "LISK";

     walletAddress: string;
     memo: string;
     minAmount: number; // order amount in cents
     buySwapId: {
       _id: string;
       sellerUser: {
         _id: string;
         id: string;
         username: string;
         confirmedSellSwapsAmount: number;
         isVerifiedMarketMaker: boolean;
         averageSwapApprovalTime: number;
       };
       amount: number;
       airtimeAmount: number;
       exchangeRate: number;
       status:
         | "initiated"
         | "buyer_confirmed"
         | "buyer_rejected"
         | "seller_confirmed"
         | "seller_rejected"
         | "expired"
         | "seller_confirmation_pending"
         | "seller_confirmation_failed";
       carrierName: string;
       provider: string;
       expiresAt: string;
       buyerConfirmedAt: string;
       sellerConfirmedAt: string;
       id: string;
     };
     createdAt: string;
     updatedAt: string;
     withdrawalId?: {
       _id: string;
       status: "complete" | "pending" | "failed";
       amount: number;
       withdrawAmount: number;
       feeAmount: number;
       feePercent: number;
       gasAmount: number;
       destinationAddress: string;
       destinationChain: string;
       transactionHash: string;
     };
   };
   cashout: {
     feePercent: number; // fonbnk fee percent
     usdcFeeAmount: number; // fonbnk fee amount
     usdcGasAmount: number;
     usdcTotalAmount: number; // amount before fee
     usdcWithdrawAmount: number; // amount user will receive
   };
 };
};

Offer search events

• order-search - user performed an order search, this event can have next statuses: "success", "no-liquidity", "cant-fill", "out-of-limits"

Order search event structure:

type FonbnkEvent = {
  type: "order-search";
  source: "fonbnk";
  data: {
    status:
      | "success" // user found an offer
      | "no-liquidity" // no offers found because there is no liquidity at all for selected parameters
      | "cant-fill"  // no offers found because there is no enough liquidity for selected parameters
      | "out-of-limits", // no offers found because the amount is out of limits
    params: {
      country: string; // country iso code
      carrierId?: string;
      amount: number;
      provider:
        | "carrier"
        | "mpesa"
        | "mobile_money"
        | "bank_transfer";
      walletType:
        | "POLYGON"
        | "ETHEREUM"
        | "STELLAR"
        | "AVALANCHE"
        | "SOLANA"
        | "ALGORAND"
        | "TRON"
        | "CELO"
        | "LISK";
      currency: "airtime" | "usdc";
      trafficSource?: string; // query "source" param
      address?: string;
    },
    message?: string; // error message displayed to a user
  }
}