Before You Code: Account Setup

Required

Complete KYB (Know Your Business): MassPay verifies your legal name, registered address, tax ID, and corporate structure before granting API access. KYB is a regulatory requirement - it's what ensures only legitimate businesses operate on the platform and reduces fraud risk for everyone.

Get your API credentials: After KYB approval, your Account Manager delivers your API key and Dashboard login. Treat your API key like a password - store it securely server-side and never expose it in client-facing code.

Base URLs

Sandbox: https://staging-api.masspay.io/v1.0.0/payout/

Production: https://api.masspay.io/v1.0.0/payout/

Headers

Required on every request: include your apiKey

Strongly recommended: add an Idempotency-Key - use your internal client_transfer_id as the value

The Idempotency-Key is what makes retries safe. If a network request times out mid-flight, resending with the same key guarantees MassPay won't process the payout twice. Build this in from day one.

Payout Methods: What's Available

MassPay supports a wide range of delivery methods. Availability varies by country, but the platform covers most of the world across these categories:

Local Bank Transfer - funds deposited directly to the recipient's bank account. Typically processes in 1–3 business days.

Wire Transfer - fast, direct bank-to-bank transfers. Typically 1–2 business days. Note: the receiving bank may charge an incoming wire fee; MassPay covers all other fees.

Push to Card / Debit Card - funds sent directly to a recipient's debit or prepaid card. Typically instant or within a few hours.

Digital Wallet - transfers to digital wallet addresses. Typically instant or within a few hours.

Mobile Money - transfers to mobile money accounts via the recipient's mobile phone. Typically instant or within a few hours.

Cash Pickup - recipient collects funds in cash at a designated physical location. Typically available within a few hours, using a pickup code.

Cryptocurrency - MassPay supports Bitcoin, Ethereum, and a range of other cryptocurrencies. Transfers typically process within a few hours.

On fees: MassPay does not charge network or hidden fees. The payout fee can be structured two ways - deducted from the payee's wallet balance, or deducted from your (the client's) wallet. Wallet loads are always free. Contact your Account Manager for current fee schedules by payout method and corridor.

The Integration Flow

Step 0 - Check Your Wallet Balance

GET /account/balance

Before initiating any payout, confirm you have sufficient funds. This call returns a token (your source_token) and your current balance. Save the source_token - you'll pass it in every payout and wallet load call.

Step 1 - Look Up or Create a User

Every payout recipient is a "user" in MassPay. The User API lets you create, update, retrieve, and search user accounts, as well as pull full transaction history per user or across all users.

First, check whether the user already exists:

GET /user/lookup?internal_user_id={id}&email={email}

This returns a user_token, which is required for all subsequent calls - wallet loads, direct payouts, attribute storage, and transaction history. Cache it in your database to avoid repeated lookups.

If the user doesn't exist, create them:

POST /user

Required: internal_user_id, country, first_name, last_name, email, Add optional fields - address, mobile number, date of birth, timezone, language - now. These fields are used for KYC verification and delivery notifications, and collecting them upfront saves friction later.

Other User API calls available:

GET /user/{user_token} - retrieve a user by token.
PUT /user/{user_token} - update user profile information.
GET /user/{user_token}/transactions - full transaction history for a user (payouts, loads, spendbacks).
GET /user/transactions - transaction history across all users.
‍

Step 2 - Choose Your Payout Method

You have two approaches. Wallet Load is recommended for most platforms.

Option A: Wallet Load (Recommended)

POST /load/{user_token}

Required: source_token - you'll pass it in every payout and wallet load call. Recommended: notes, notes,notify_user (defaults to true).

Load funds into the user's MassPay wallet. The user then withdraws on their own timeline via whatever payout method they've set up - bank, card, cash, crypto - without any further action from you. MassPay handles all routing, delivery method logic, and country-specific restrictions on the backend.

Why this approach works better for most platforms:‍

No banking or card details to collect, validate, or store
MassPay manages all routing decisions and country restrictions
Funds consolidate across the user's platforms in a single wallet
Withdrawal timing is fully user-controlled
No fee charged to load a wallet
Reduced compliance overhead for your team
Better error handling - delivery failures are resolved by the user, not your support queue

Option B: Direct Payout (When You Need to Control the Destination)

Use when you need to specify exactly how and where funds are delivered. This requires four sub-steps.

Step 2a - Get available payout routes for the destination country

GET /country/{country_code}/best?amount={amount}&only_generic_payers=true

Returns available destination_token options with fees, exchange rates, estimated availability, and delivery type. Use only_generic_payers=true to return clean generic options (e.g., "Bank Deposit") rather than individual bank listings. Filter by using payer_name with multiple values separated by a pipe (|).

The response also tells you whether a fee is variable, what the min/max transaction limits are, and how many cash pickup locations exist for that payer - useful for displaying routing options to your users.

Step 2b - Get required fields for the selected route

GET /attribute/{user_token}/{destination_token}/{currency}

Returns the specific fields needed for that route - for example, account number, routing number, or ID document type. Fields include validation rules, expected formats, and whether each is optional or required.

Step 2c - Store the recipient's attributes

POST /attribute/{user_token}/{destination_token}/{currency}

Submit the required field values. Returns an attr_set_token - pass this into your payout initiation call. MassPay stores these attributes per user, so returning users don't need to re-enter their details.

Step 3 - Initiate the Payout

POST /payout/{user_token}

Required: client_transfer_id, destination_currency_code, source_token, destination_token, and either source_amount or destination_amount. Recommended: include attr_set_token

This returns a payout_token along with a full transaction preview - fee, exchange rate, estimated delivery time, source amount, destination amount. The payout is not processed yet. You must commit it within 2 minutes.

Step 4 - Commit the Payout

PUT /payout/{user_token}/{payout_token}

Confirms and executes the payout. You have a 2-minute window after initiating. After this call succeeds, the transaction processes. The response returns final status, any pickup codes (for cash payouts), and errors if any exist.

Build your commit call immediately after a successful initiate. Do not introduce user-facing confirmation steps or delays between the two calls - the 2-minute window is firm.

You can also check payout status at any time via GET /payout/{user_token}/{payout_token} , and retrieve a PDF confirmation once the payout is complete.

Wallets & Autopay

Beyond loading wallets manually, MassPay supports autopay rules - automated rules that route incoming wallet funds to a designated payout destination without manual intervention per transaction.

What you can do with the Wallet & Autopay API:

Retrieve all wallets associated with a user
View all autopay rules for a user, including destination token, autopay token, and percentage of incoming load to route
Add autopay rules to automatically transfer funds when a wallet receives a load
Delete autopay rules when they're no longer needed

This is particularly useful for freelancer platforms, affiliate programs, and subscription businesses that need recurring payouts without manual triggers.

Webhooks & Monitoring

You must set up listeners for two events before going live.

payout.created - fires when a payout is successfully committed. Record the payout_token and mark the transaction as pending in your system.

payout.status - fires on every status change throughout the payout lifecycle.

Important: a payout's status can change multiple times. In rare cases it may go from completed to cancelled, or even - very rarely - from cancelled back to completed. Set up alerts for these transitions so your finance or operations team can react appropriately. Do not treat a "completed" status as fully final without a reconciliation step.

Reconciliation

Reconcile your MassPay wallet balance against your internal ledger regularly. This is mandatory. Query GET /account/balance on a scheduled cadence and investigate any discrepancies immediately. MassPay's Dashboard provides real-time transaction views for your ops team alongside the API.payout.created.

KYC - Ongoing Identity Verification

KYC isn't just an onboarding step. Users can be asked to verify their identity at any point - not only during signup. This can be triggered by transaction behavior or flagged by third-party monitoring systems. It's part of keeping the platform compliant.

If a user is on a compliance hold, all payouts to that user will be rejected.

When this happens, the API error response includes a unique document upload link. You must have a process in place to either surface that link directly to the user (email, in-app notification, SMS), or route it to your compliance team. Once documents are approved, the hold releases and payouts resume. This workflow is required - build it before you go live.Important: a payout's status can change multiple times.

Contractor Tax Management

If you pay US-based contractors or non-US contractors with US-sourced income, MassPay's Contractor Tax Service handles the compliance burden.

For US citizens: payees provide their SSN (individuals) or EIN (businesses) for tax reporting.

For non-US citizens: payees may provide an ITIN (Individual Taxpayer Identification Number) instead. Tax obligations vary by residency status, income type, and applicable tax treaties.

What MassPay's tax API provides:

Full payee information including personal data, annual balances, and tax IDs via the Get Annual Balance endpoint
Filtering by total balance - useful for identifying payees above 1099 thresholds
Tax year filtering - specify the year or default to the prior year
End-of-year reporting support for 1099 and 1042-S forms

If contractor tax compliance is relevant to your use case, visit masspay.io/1099-1042s-tax-services for more detail

Security & Compliance

MassPay is built to enterprise security standards across all layers.

PCI-DSS Level 1 - the highest level of payment card industry certification. Covers encryption, network security, access controls, and regular penetration testing.

SOC 2 Type II - independently audited controls for security, availability, processing integrity, confidentiality, and privacy. Ongoing certification, not a one-time snapshot.

GDPR compliance - all international data transfers adhere to GDPR. Anonymization, access controls, and incident response plans are in place. Data deletion and access requests are processed promptly.

TLS 1.2 - all communication between clients and the MassPay API is encrypted in transit.

Two-Factor Authentication - available for all Dashboard users.

24/7 monitoring - MassPay's security team monitors systems around the clock and uses machine learning-based fraud detection to flag suspicious activity in real time.

KYB + KYC - every business on the platform is screened through KYB before activation. Every individual payee goes through identity verification including document checking and AI-assisted evaluation. Only legitimate businesses and verified individuals transact on the platform.

Go-Live Checklist

Before switching to production, confirm every item:

KYB completed and approved
Production API key received
Sandbox tested end-to-end
Users created in production environment
Wallet funded with sufficient balance
Payout routes confirmed for target countries
Minimum payout amounts verified per route
Recipient attributes collected and validated
Webhook listeners live and tested (payout.created and payout.status)
Reconciliation process in place
KYC compliance hold workflow implemented
Contractor tax workflow set up (if applicable)
Server IPs whitelisted in Dashboard

‍

If contractor tax compliance is relevant to your use case, visit masspay.io/1099-1042s-tax-services for more detail

Resources

Before switching to production, confirm every item:

Full API reference and documentation: developers.masspay.io
SDKs: PHP, C#, Ruby, JavaScript - developers.masspay.io/page/sdks
Platform status: status.masspay.io
Questions: Your Account Manager is your first stop for anything integration-related.
Urgent issues: VIPSupport@masspay.io

MassPay Integration Guide

Send payouts Everywhere.
Integrate in Hours.

Who Uses MassPay?

Before You Code: Account Setup

Required

Recommended

Base URLs

Headers

Payout Methods: What's Available

The Integration Flow

Wallets & Autopay

Webhooks & Monitoring

Reconciliation

KYC - Ongoing Identity Verification

Contractor Tax Management

Security & Compliance

Go-Live Checklist

Resources

Ready for a payment solution built just for you?

MassPay Integration Guide

Send payouts Everywhere. Integrate in Hours.

Who Uses MassPay?

Before You Code: Account Setup

Required

Recommended

Base URLs

Headers

Payout Methods: What's Available

The Integration Flow

Wallets & Autopay

Webhooks & Monitoring

Reconciliation

KYC - Ongoing Identity Verification

Contractor Tax Management

Security & Compliance

Go-Live Checklist

Resources

Ready for a payment solution built just for you?

Send payouts Everywhere.
Integrate in Hours.