Skip to main content

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"
| "STELLAR"
| "AVALANCHE"
| "SOLANA"
| "ALGORAND"
| "TRON"
| "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
}
}