MassPay Transfer Widget: Partner Integration Guide
Overview
The transfer widget lets your own website send a cash payout from one of your MassPay payees' wallets, without building the payout flow yourself. You embed a MassPay page in an <iframe>, hand it a short-lived token, and the widget handles wallet choice, delivery method, recipient details, quote and confirmation.
An integration has three parts, and your API key only ever touches the first:
- Your server calls the MassPay API with your API key and gets a widget token for one payee. The token is valid for 30 minutes.
- Your web page loads the widget in an iframe and passes it the token with
postMessage. - The widget calls the MassPay widget API with that token and reports back to your page when the transfer succeeds, fails or is closed.
Everything the widget does is limited to the client and payee the token was created for. Your end user never sees your API key, and the token cannot be used for any other payee or client.
[embedded content: integration sequence · 4 parties, 11 calls]
Read top to bottom: your server creates the session and later verifies the result; the widget does everything in between with the token alone.
Before you start
You need three things from your MassPay account before the first call:
| What | Format | Where it comes from |
|---|---|---|
| API key | Secret string | Your active MassPay API key, the same one you use for the MassPay API. Keys are per environment. A key limited to scopes needs the payout scope. |
| Payee user token | usr_ + UUID, e.g. usr_1b2c… | Returned when the payee was created under your account. The payee must belong to your account and be ACTIVE. |
| A funded wallet | Non-zero balance, not PNTS | The payee's wallet, or your account's own balance. Empty, inactive and PNTS wallets are not offered. |
The token comes from the MassPay API; the widget page and its calls live on the MassPay clients host. Use staging with your staging API key while you build:
| Environment | MassPay API (Step 1) | Widget host (Steps 2 and 3) |
|---|---|---|
| Staging | https://staging-api.masspay.io/v1.0.0 | https://dev.clients.masspay.io |
| Production | https://api.masspay.io/v1.0.0 | https://clients.masspay.io |
The widget page is /v2/widget/transfer on the widget host, and the widget's own calls go under /v2/widget/transfer/api/ on that host.
Step 1: Get a widget token from the MassPay API (server-to-server)
Call the MassPay API from your backend each time a payee opens the widget. It returns a token for that one payee. This call carries your API key, so make it only from your server and send only the token to your page.
POST https://api.masspay.io/v1.0.0/payout/USER_TOKEN/widget-session (staging: https://staging-api.masspay.io/v1.0.0)
| Part | Value |
|---|---|
Authorization header | Bearer <your API key>, as on every MassPay API call |
Accept header | application/json |
user_token (path) | The payee, usr_ + UUID. It must belong to your account and be ACTIVE. |
dry_run (query, optional) | true creates a test token: every transfer made with it is a test that sends nothing (see Test mode). |
| Body | none |
curl -X POST https://staging-api.masspay.io/v1.0.0/payout/usr_1b2c3d4e-5f60-7182-93a4-b5c6d7e8f901/widget-session \
-H 'Accept: application/json' \
-H "Authorization: Bearer $MASSPAY_API_KEY"Successful response, 201:
{
"token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzI1NiJ9…",
"expires_in": 1800,
"expires_at": 1794482400,
"dry_run": false
}tokenis signed by MassPay. Treat it as an opaque string: pass it to the widget, never parse or modify it.expires_inis in seconds (30 minutes).expires_atis a Unix timestamp in seconds.dry_runistruefor a test token.- Create a new token for every widget open. A live token ends after one completed transfer.
When no token can be issued, the response says why in error.details, for example {"code": 400, "error": {"reason": "Error creating widget session", "details": ["Invalid user token"]}}.
| Status | details | Cause |
|---|---|---|
400 | Invalid user token | The user_token is malformed, or the payee does not belong to your account |
400 | User is not active | The payee exists but is not ACTIVE |
401 | none | The API key is missing or not valid |
403 | none | The key may not call this endpoint, e.g. a scoped key without the payout scope |
500 | Unable to look up the user | Retry shortly |
503 | Widget sessions are temporarily unavailable | Retry shortly |
Step 2: Embed the widget and pass the token
Load the widget page in an iframe, wait for its ready message, then send the token with init. The token never goes in the iframe URL.
<iframe id="masspay-widget"
src="https://clients.masspay.io/v2/widget/transfer"
title="MassPay transfer"
style="width:100%;height:640px;border:none"></iframe>const WIDGET_ORIGIN = 'https://clients.masspay.io';
const iframe = document.getElementById('masspay-widget');
window.addEventListener('message', (event) => {
if (event.origin !== WIDGET_ORIGIN || event.source !== iframe.contentWindow) return;
if (event.data?.type === 'transfer-widget:ready') {
iframe.contentWindow.postMessage(
{ type: 'transfer-widget:init', token: tokenFromYourServer, mode: 'light' },
WIDGET_ORIGIN,
);
}
});The widget sends ready once it has loaded. Answer it every time: if the iframe reloads, it sends ready again and needs the token again.
| Direction | Message | Fields |
|---|---|---|
| Widget → your page | transfer-widget:ready | none |
| Your page → widget | transfer-widget:init | token (required); mode: 'light' or 'dark' (optional, default follows the user's OS setting) |
| Your page → widget | transfer-widget:set-mode | mode: 'light' or 'dark', to follow your page's theme switch |
| Widget → your page | transfer-widget:success | pickupCode |
| Widget → your page | transfer-widget:error | reason (a message you can show) |
| Widget → your page | transfer-widget:close | none |
The widget learns your page's origin from the Referer of the iframe load and only talks to that origin. Keep the browser default referrer policy, or set referrerpolicy="origin" on the iframe. With no-referrer, the widget cannot send you any messages.
The reference integration uses the full container width and 640 px of height.
Step 3: Handle the widget's events
The widget tells your page about three outcomes. Only success means money moved, and even that is a browser message: confirm it on your server before you act on it.
| Event | When it is sent | What your page should do |
|---|---|---|
transfer-widget:success | The transfer was committed. The widget then shows a receipt with a Done button. | Record the pickupCode and refresh your own view of the payee. Verify the payout server-side (see below). Request a new session if the user wants another transfer. |
transfer-widget:error | A step failed: wallets could not load, no quote, delivery methods or recipient form failed to load. The widget shows the same message and a Start over button. | Log the reason. Usually do nothing else: the user can retry inside the widget with the same token. |
transfer-widget:close | The user clicked Done on the receipt. | Remove or hide the iframe. |
pickupCode can be an empty string: a test transfer has none, and neither does a transfer whose confirm call timed out but which a follow-up status check showed had gone through.
The reason in an error is a sentence written for the end user, not a stable code. Do not branch on its text.
To verify a transfer, look the payout up on your server with the MassPay API under your API key rather than trusting the message. Any script on your page could post a fake success to your own listener.
Test mode (dry run)
Create the token with ?dry_run=true in Step 1 to try the whole flow without moving money. The payee, their wallets, the delivery methods and the quote are real; nothing is sent and no payout is created.
- The widget shows "Test mode: no money will be sent." on every step, and the last button reads Run test transfer.
transfer-widget:successarrives withdryRun: trueand an emptypickupCode; the receipt says nothing was sent.- A test token is not used up by its test transfers, so it can run the flow again until it expires.
- The flag is signed into the token: the page that embeds the widget cannot turn a test token into a live one, or the reverse. To go live, create a token without
dry_run. - Recipient details the payee enters (such as a new bank account) are saved, exactly as in a live transfer.
In test mode, confirm returns {"success": true, "pickup_code": null, "dry_run": true}, /status returns {"dry_run": true}, and confirming a payout_token that did not come from this token's own quote returns 404 unknown_payout.
Styling the widget
You set the widget's light or dark mode from the iframe URL or by message. Brand colours and your own logo are set once in the MassPay dashboard under Settings > Transfer Widget, and the widget loads them by itself.
| Option | How | Notes |
|---|---|---|
| Mode at load | ?mode=light or ?mode=dark on the iframe src | Applies from the first paint, so a dark page shows no white flash. Useful when you cannot send messages. |
| Mode at start | mode in transfer-widget:init | Overrides the URL value. |
| Follow your theme switch | transfer-widget:set-mode with mode | Send it whenever your page changes theme. |
| Default | Send nothing | The widget follows the user's OS setting (prefers-color-scheme), including live changes, until you send a mode. |
| Size | Your iframe's width and height | The widget fills the frame. The reference integration uses full width and 640 px. |
<iframe src="https://clients.masspay.io/v2/widget/transfer?mode=dark" …></iframe>Brand colours and logo
On start the widget requests GET /v2/widget/transfer/api/theme and applies what you saved under Settings > Transfer Widget, in this shape (logos must be https links):
{
"colors": { "primary1": "#0b6bcb", "primary2": "#1f2430", "secondary1": "#d7dae0", "secondary2": "#5b6472" },
"dark_colors": { "primary1": "#4c9df0" },
"logo": { "light": "https://example.com/logo.png", "dark": "https://example.com/logo-dark.png" }
}| Field | Used for | Rules |
|---|---|---|
primary1 | Accent: buttons, focus rings, selected rows | Hex, #rgb or #rrggbb. Invalid values are ignored. |
primary2 | Text | Same |
secondary1 | Borders | Same |
secondary2 | Secondary buttons | Same |
dark_colors | The same four colours in dark mode | Without it, only primary1 carries over to dark mode. |
logo.light, logo.dark | The logo in the widget header | An https/http URL or a data:image/… URI. Dark falls back to light, then to the MassPay logo. |
You give one shade per colour. The widget derives the hover, pressed, tint and disabled shades from it, so they fit both light and dark backgrounds.
Session lifetime
A widget session lasts exactly 30 minutes from creation and ends early after one completed transfer. Activity in the widget does not extend it.
- Expiry. After
expires_at, every widget API call returns401. The user sees an error in the widget and your page getstransfer-widget:error. - Completed transfer. A successful confirm revokes the session at once, so the token cannot be replayed. Failed or abandoned attempts do not revoke it.
- Quote expiry is separate. A quote carries its own short rate guarantee. The widget shows the countdown and fetches a new quote by itself.
Create the session right before you show the widget, not when your page loads. If the widget may stay hidden for a while, check the token first; this endpoint allows browser calls:
GET /v2/widget/transfer/api/session with Authorization: Bearer <token>
| Status | Body | Meaning |
|---|---|---|
200 | {"valid":true,"expires_at":1794482400} | Token is good until expires_at (Unix seconds) |
401 | {"success":false,"reason":"invalid_or_expired_token"} | Expired, revoked or unknown: get a new token from your server and send a fresh init |
If a session expires while the iframe is open, get a new token and reload the iframe. The reloaded widget sends ready again, and your listener answers it with the new token.
Widget API reference
The hosted widget makes these calls for you; you need them only to build your own interface or to self-host the widget. Every call sends Authorization: Bearer <token>, and paths are relative to /v2/widget/transfer/api. The token decides the payee and client, so no endpoint takes a user or client ID.
| # | Method | Path | Returns |
|---|---|---|---|
| 1 | GET | /wallets | Wallets the payee can send from, and destination countries |
| 2 | GET | /services/{wallet}/{country}/{amount} | Delivery options with fee, rate and amount received |
| 3 | GET | /attrs/{destination_token}/{destination_currency} | Recipient fields that destination requires |
| 4 | POST | /attrs/{amount}/{wallet}/{destination_token}/{destination_currency} | Saves recipient fields and returns a quote |
| 5 | POST | /{payout_token}/confirm | Commits the quoted payout |
| 6 | GET | /{payout_token}/status | Current status of a payout |
| 7 | GET | /session | Whether the token is still valid |
| 8 | GET | /theme | Your colours and logo from Settings; see Styling the widget |
1. GET /wallets
{
"user_token": "usr_…",
"wallets": [{ "token": "usr_wlt_…", "balance": 250.0, "currency_code": "USD", "active": true, "type": "…", "client_paying_fees": false }],
"countries": [{ "code": "MX", "name": "Mexico", "three_letter_code": "MEX" }]
}Only active wallets with a non-zero balance appear, never PNTS. Your client's own account balances are included, with type USER_FUNDS.
2. GET /services/{wallet}/{country}/{amount}
wallet: a token from/wallets(usr_wlt_,mp_card_orclnt_wlt_+ UUID).country: the three-letter code, upper case, e.g.MEX.amount: digits and a dot, in the wallet's currency, e.g.100.00.
{
"services": [{
"delivery_type": "CASH_PICKUP", "payer_name": "…", "payer_logo": null,
"destination_token": "dest_…", "destination_currency": "MXN",
"number_of_locations": 1200, "additional_description": null,
"fee": 2.99, "source_amount": 100.0, "exchange_rate": 17.1, "destination_amount": 1710.0
}],
"wallet": { "token": "usr_wlt_…", "…": "…" },
"user_token": "usr_…",
"amount": "100.00"
}One row per payer and currency. When wallet.client_paying_fees is true, your client pays the fee and the payee sees it as free. An empty services list means nothing is available for that amount. A wallet not in /wallets returns 400 invalid_wallet_token.
3. GET /attrs/{destination_token}/{destination_currency}
{ "attrs": [{
"token": "attr_…", "type": "BankAccountNumber", "label": "Account number",
"is_optional": false, "expected_value": "…", "validation": "…",
"value": "*****3523", "dirty_check_hash": "5f4dcc3b…", "attr_set_token": null,
"widget_kind": "text", "options": null, "default_value": "*****3523"
}] }widget_kindis one ofradio,checkbox,select,date,tel,text;optionslists the choices for the first three.- Saved sensitive values come back masked except the last 4 characters. Dates, option lists and account types are not masked.
labelmay contain an HTML<a>link. Render it as text or sanitise it.typeIDSelfieCollectionis an identity check: the widget shows its own flow and re-reads this endpoint until it completes.
4. POST /attrs/{amount}/{wallet}/{destination_token}/{destination_currency}
Send every field, each with the dirty_check_hash it came with. A value whose MD5 still matches its hash counts as unchanged and is not re-saved, so a masked value can be sent back as is.
{ "values": [{ "token": "attr_…", "value": "*****3523", "hash": "5f4dcc3b…" }] }{ "success": true,
"payout": { "payout_token": "payout_…", "source_amount": 100.0, "destination_amount": 1710.0, "exchange_rate": 17.1, "fee": 2.99, "expiration": "2026-11-12T18:04:00Z" },
"wallet": { "token": "usr_wlt_…", "…": "…" } }payout_token equal to "NSF" means the wallet cannot cover the amount plus fee: ask for a smaller amount. expiration is when the quoted rate stops being guaranteed.
5. POST /{payout_token}/confirm
No body. Limited to 10 calls per 60 seconds per IP and User-Agent.
- Committed:
{"success":true,"pickup_code":"…"}. The session is revoked. - Refused:
{"success":false,"status":"ex_rate_expired","reason":…}with HTTP200. See Errors for the statuses. - If the call times out, do not retry it blindly: check
/statusfirst.
6. GET /{payout_token}/status
Returns the payout as the MassPay API reports it, including status and, once available, pickup_code. Returns {} when the lookup fails. Treat any status other than PENDING, ERROR or CANCELLED as sent.
7. GET /session
See Session lifetime.
8. GET /theme
The widget asks for branding (colors, dark_colors, logo.light, logo.dark) and falls back to the MassPay theme when the call fails.
Errors
Widget API errors share one body shape, {"success":false,"reason":"<code>"}, and the reason code is stable. A rate-limited call is the only exception: it returns an errors list instead.
| Status | reason | Returned by | What to do |
|---|---|---|---|
400 | invalid_wallet_token | services, POST attrs | Pick a wallet from the latest /wallets |
400 | invalid_amount | POST attrs | Send an amount greater than 0 |
401 | invalid_or_expired_token | every endpoint | Get a new token from your server |
429 | none (errors list) | confirm | Wait 60 seconds |
502 | store_attrs_failed | POST attrs | The recipient details were rejected or could not be saved; let the user check them and retry |
502 | quote_failed | POST attrs | No quote; retry, or try another delivery option |
502 | commit_failed | confirm | Outcome unknown: call /status before retrying |
503 | unavailable | every endpoint | MassPay could not load your client's API key, or storage is down; retry later and contact MassPay if it persists |
A confirm that MassPay refuses returns HTTP 200 with success: false and one of these status values. reason then carries the API's own message.
status | Meaning | What to do |
|---|---|---|
nsf | Not enough funds for amount plus fee | Go back and choose a smaller amount |
ex_rate_expired | The quote's rate guarantee ran out | Submit the recipient details again for a new quote |
addtl_attr_req | The destination needs more recipient details | Reload the recipient fields and submit again |
failure | Rejected | Show reason; do not retry unchanged |
Security requirements
MassPay checks that the payee belongs to your client. It cannot check who is sitting at your page, so deciding that the signed-in user may move this payee's money is your job.
You must:
- Keep the API key on your server. Create sessions only from your backend, and never send the key to a browser or a mobile app.
- Create a session only for the payee your signed-in user is, or is entitled to act for, and only after your own login and authorisation checks.
- Treat the token as a password for 30 minutes. Do not put it in URLs, logs, analytics or
localStorage; keep it in memory and pass it only throughpostMessage. - Check
event.originandevent.sourceon every message, and always post to the MassPay origin, never'*'. - Verify every reported transfer on your server before you credit, notify or release anything.
- Allow the MassPay host in your page's Content Security Policy (
frame-src https://clients.masspay.io) and keep the iframe's referrer as described in Step 2.
What MassPay enforces:
- A token works for one payee under one client. It never carries staff rights and never switches to another client.
- Every widget call runs under your client's own API key, whatever cookies the browser holds.
- Sessions expire after 30 minutes, end after one completed transfer, and confirm is rate limited.
- The widget API uses bearer tokens only, with no cookies. Its CORS is open to any origin for that reason, and the widget page allows framing from any site.
Self-hosting the widget (optional)
Most integrations should frame the hosted page. If you need the widget served from your own domain, you can build it yourself and point it at the MassPay API. The source is a React app in a private MassPay repository, so ask MassPay for access.
REACT_APP_API_BASE_URL=https://clients.masspay.io/v2/widget/transfer/api PUBLIC_URL=/your/path npm run buildREACT_APP_API_BASE_URLmakes the widget call the MassPay API across origins. The widget API's open CORS allows this.PUBLIC_URLoverrides the build's default asset path,/v2/widget-transfer, to wherever you serve the files.npm run dev:mockruns the widget locally on fake data, with no token or backend, for styling work.
What changes when you self-host:
- The widget's origin becomes your hosting origin, so check
event.originand postinitagainst that origin instead ofclients.masspay.io. - Tokens still come from the MassPay API,
POST /payout/USER_TOKEN/widget-session, called from your server exactly as in Step 1. - You take on updates: fixes to the hosted widget reach you only when you rebuild.
Testing and a complete example
Build against staging (https://staging-api.masspay.io/v1.0.0 for tokens, https://dev.clients.masspay.io for the widget) with your staging API key and a staging payee that has a funded wallet. Use test tokens (dry_run=true) until you are ready for a real transfer, and switch hosts and key to production only when the checklist below passes.
Quick check from a terminal:
curl -s -X POST "https://staging-api.masspay.io/v1.0.0/payout/usr_1b2c3d4e-5f60-7182-93a4-b5c6d7e8f901/widget-session?dry_run=true" \
-H 'Accept: application/json' \
-H "Authorization: Bearer $MASSPAY_API_KEY"Server (Node.js, Express). Your own route, called by your page once the user is signed in:
const MASSPAY_API = process.env.MASSPAY_API; // https://staging-api.masspay.io/v1.0.0 on staging
app.post('/masspay/widget-token', requireLogin, async (req, res) => {
const userToken = await payeeTokenFor(req.user); // your own lookup and authorisation
if (!userToken) return res.status(403).end();
const testMode = process.env.MASSPAY_WIDGET_TEST_MODE === 'true';
const r = await fetch(
`${MASSPAY_API}/payout/$USERTOKEN/widget-session${testMode ? '?dry_run=true' : ''}`,
{
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.MASSPAY_API_KEY}`,
Accept: 'application/json',
},
},
);
if (r.status !== 201) return res.status(502).json({ error: 'widget_unavailable' });
const body = await r.json();
res.json({ token: body.token, expiresAt: body.expires_at, testMode: body.dry_run });
});Browser. Fetch a token, mount the iframe, answer ready, react to the outcome:
<div id="masspay"></div>
<script>
const WIDGET_ORIGIN = 'https://dev.clients.masspay.io';
async function openTransferWidget() {
const { token } = await fetch('/masspay/widget-session', { method: 'POST' }).then((r) => r.json());
const iframe = document.createElement('iframe');
iframe.src = `${WIDGET_ORIGIN}/v2/widget/transfer`;
iframe.title = 'MassPay transfer';
iframe.style.cssText = 'width:100%;height:640px;border:none';
function onMessage(event) {
if (event.origin !== WIDGET_ORIGIN || event.source !== iframe.contentWindow) return;
const msg = event.data || {};
if (msg.type === 'transfer-widget:ready') {
iframe.contentWindow.postMessage({ type: 'transfer-widget:init', token }, WIDGET_ORIGIN);
} else if (msg.type === 'transfer-widget:success') {
fetch('/masspay/transfer-reported', { method: 'POST' }); // verify on your server
} else if (msg.type === 'transfer-widget:error') {
console.warn('Transfer widget:', msg.reason);
} else if (msg.type === 'transfer-widget:close') {
window.removeEventListener('message', onMessage);
iframe.remove();
}
}
window.addEventListener('message', onMessage);
document.getElementById('masspay').appendChild(iframe);
}
</script>Before going live, confirm each of these on staging:
- A token is created for a payee of your account, and a payee of another account gets
400Invalid user token. - The widget lists the payee's funded wallets and your client's account balance.
- A full transfer completes,
successarrives, and your server finds the payout. - After success, reusing the same token returns
401. - A token older than 30 minutes is replaced before the widget opens.
- Messages from any other origin are ignored by your listener.
- No API key or token appears in browser storage, URLs or logs.
Updated about 6 hours ago