Partner Widget Overview
The Pagamio Partner Widget is an embeddable purchase journey for your customers. It lets a customer of your app buy airtime, data, electricity, vouchers and other Pagamio VAS products without leaving your app, and pay from the wallet you already hold for them.
You do not build the purchase screens. Pagamio hosts the widget, you open it for a signed-in customer, and Pagamio calls your wallet API to hold, capture or release the customer's funds.
What The Customer Sees
Categories, products by brand, amount and details, confirmation, processing, receipt and the customer's purchase history. The widget takes your brand colours and logo, and it works without a login of its own: your app has already identified the customer.
How It Is Embedded
| Mode | How it works | Typical use |
|---|---|---|
| Web-view | Your mobile app opens the widget URL in a system web-view (Android WebView, iOS WKWebView). | Native apps. |
| iframe | Your website frames the widget URL. Your origin must be on the allow-list. | Partner websites and web wallets. |
| Full redirect | You send the customer's browser to the widget. On Close the widget sends the customer back to your return_url. | Web apps that prefer a page hand-off (partner-initiated launch only). |
The widget also works when opened directly in a browser. In every mode, the widget tells your app about key events through the host bridge.
Roles
| Role | Responsibility |
|---|---|
| Partner app | Identifies the customer, opens the widget (web-view, iframe or redirect), listens for bridge events. |
| Partner backend | Holds the Pagamio API key and launch secret. Creates sessions, or signs launch tokens. Never exposes either to the app. |
| Partner wallet | The wallet API Pagamio calls to hold, capture or release the customer's funds. See Partner Wallet Contract. |
| Pagamio | Hosts the widget and its API, runs the purchase with the product aggregator, drives the hold/capture/release lifecycle, and gives you statements. |
How A Purchase Flows
- Your backend opens a session for the customer (or signs a launch token). The customer's identity and wallet are fixed at this point; the widget cannot change them.
- The customer picks a product and confirms.
- Pagamio asks your wallet to hold the amount.
- Pagamio buys the product from the aggregator.
- On success, Pagamio asks your wallet to capture the hold. On failure, it asks your wallet to release it.
- The customer sees the receipt or the failure reason. Your app receives a bridge event.
If Pagamio cannot tell whether the purchase succeeded (for example the aggregator does not answer), the purchase stays pending while Pagamio reads the outcome back, and your hold must stay valid the whole time. See Timing Requirements.
Two Ways To Start A Session
| Path | Who calls what | Read |
|---|---|---|
| Server-to-server (default) | Your backend calls POST /partner/v1/sessions with the API key and loads the returned widgetUrl. | Creating A Session |
| Partner-initiated launch | Your app redirects the customer to /w/{partnerCode}/launch with a short-lived signed token. | Partner-Initiated Launch |
Your onboarding agreement says which path applies to you.
Where To Go Next
- Onboarding: what you and Pagamio exchange.
- Start a session using one of the two paths above.
- Implement the Partner Wallet Contract and meet the Timing Requirements.
- Test in the Sandbox.
- Read the Security Notes before go-live.
Last updated: September 2026