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:

  1. 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.
  2. Your web page loads the widget in an iframe and passes it the token with postMessage.
  3. 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:

WhatFormatWhere it comes from
API keySecret stringYour 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 tokenusr_ + 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 walletNon-zero balance, not PNTSThe 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:

EnvironmentMassPay API (Step 1)Widget host (Steps 2 and 3)
Staginghttps://staging-api.masspay.io/v1.0.0https://dev.clients.masspay.io
Productionhttps://api.masspay.io/v1.0.0https://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)

PartValue
Authorization headerBearer <your API key>, as on every MassPay API call
Accept headerapplication/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).
Bodynone
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
}
  • token is signed by MassPay. Treat it as an opaque string: pass it to the widget, never parse or modify it.
  • expires_in is in seconds (30 minutes). expires_at is a Unix timestamp in seconds.
  • dry_run is true for 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"]}}.

StatusdetailsCause
400Invalid user tokenThe user_token is malformed, or the payee does not belong to your account
400User is not activeThe payee exists but is not ACTIVE
401noneThe API key is missing or not valid
403noneThe key may not call this endpoint, e.g. a scoped key without the payout scope
500Unable to look up the userRetry shortly
503Widget sessions are temporarily unavailableRetry 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.

DirectionMessageFields
Widget → your pagetransfer-widget:readynone
Your page → widgettransfer-widget:inittoken (required); mode: 'light' or 'dark' (optional, default follows the user's OS setting)
Your page → widgettransfer-widget:set-modemode: 'light' or 'dark', to follow your page's theme switch
Widget → your pagetransfer-widget:successpickupCode
Widget → your pagetransfer-widget:errorreason (a message you can show)
Widget → your pagetransfer-widget:closenone

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.

EventWhen it is sentWhat your page should do
transfer-widget:successThe 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:errorA 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:closeThe 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:success arrives with dryRun: true and an empty pickupCode; 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.

OptionHowNotes
Mode at load?mode=light or ?mode=dark on the iframe srcApplies from the first paint, so a dark page shows no white flash. Useful when you cannot send messages.
Mode at startmode in transfer-widget:initOverrides the URL value.
Follow your theme switchtransfer-widget:set-mode with modeSend it whenever your page changes theme.
DefaultSend nothingThe widget follows the user's OS setting (prefers-color-scheme), including live changes, until you send a mode.
SizeYour iframe's width and heightThe 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" }
}
FieldUsed forRules
primary1Accent: buttons, focus rings, selected rowsHex, #rgb or #rrggbb. Invalid values are ignored.
primary2TextSame
secondary1BordersSame
secondary2Secondary buttonsSame
dark_colorsThe same four colours in dark modeWithout it, only primary1 carries over to dark mode.
logo.light, logo.darkThe logo in the widget headerAn 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 returns 401. The user sees an error in the widget and your page gets transfer-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>

StatusBodyMeaning
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.

#MethodPathReturns
1GET/walletsWallets the payee can send from, and destination countries
2GET/services/{wallet}/{country}/{amount}Delivery options with fee, rate and amount received
3GET/attrs/{destination_token}/{destination_currency}Recipient fields that destination requires
4POST/attrs/{amount}/{wallet}/{destination_token}/{destination_currency}Saves recipient fields and returns a quote
5POST/{payout_token}/confirmCommits the quoted payout
6GET/{payout_token}/statusCurrent status of a payout
7GET/sessionWhether the token is still valid
8GET/themeYour 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_ or clnt_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_kind is one of radio, checkbox, select, date, tel, text; options lists 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.
  • label may contain an HTML <a> link. Render it as text or sanitise it.
  • type IDSelfieCollection is 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 HTTP 200. See Errors for the statuses.
  • If the call times out, do not retry it blindly: check /status first.

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.

StatusreasonReturned byWhat to do
400invalid_wallet_tokenservices, POST attrsPick a wallet from the latest /wallets
400invalid_amountPOST attrsSend an amount greater than 0
401invalid_or_expired_tokenevery endpointGet a new token from your server
429none (errors list)confirmWait 60 seconds
502store_attrs_failedPOST attrsThe recipient details were rejected or could not be saved; let the user check them and retry
502quote_failedPOST attrsNo quote; retry, or try another delivery option
502commit_failedconfirmOutcome unknown: call /status before retrying
503unavailableevery endpointMassPay 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.

statusMeaningWhat to do
nsfNot enough funds for amount plus feeGo back and choose a smaller amount
ex_rate_expiredThe quote's rate guarantee ran outSubmit the recipient details again for a new quote
addtl_attr_reqThe destination needs more recipient detailsReload the recipient fields and submit again
failureRejectedShow 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:

  1. 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.
  2. 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.
  3. 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 through postMessage.
  4. Check event.origin and event.source on every message, and always post to the MassPay origin, never '*'.
  5. Verify every reported transfer on your server before you credit, notify or release anything.
  6. 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 build
  • REACT_APP_API_BASE_URL makes the widget call the MassPay API across origins. The widget API's open CORS allows this.
  • PUBLIC_URL overrides the build's default asset path, /v2/widget-transfer, to wherever you serve the files.
  • npm run dev:mock runs 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.origin and post init against that origin instead of clients.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 400 Invalid user token.
  • The widget lists the payee's funded wallets and your client's account balance.
  • A full transfer completes, success arrives, 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.

Did this page help you?