---
updatedAt: 2026-03-13T17:01:00.000Z
agentTools:
  projectIndex: https://developers.masspay.io/llms.txt
---

# MassPay Integration – Best Practices

# MassPay Integration – Best Practices

## Introduction

This guide walks you through the full MassPay Payout Integration Flow. It highlights what’s required, what’s optional – but smart – and how to best configure and integrate your MassPay environment.

***

## Account Setup

### Mandatory

* Complete KYB Application
* Get API Access (You’ll receive your API key and MassPay Dashboard login credentials from your Account Manager)

### Recommended

* Use your MassPay Sandbox environment for pre-launch testing. This environment mirrors your production environment.
* Add an extra layer of protection by whitelisting your server IPs with MassPay.

***

## Environment & Authentication

### Base URLs

* **Staging**: `https://staging-api.masspay.io/v1.0.0/payout/`
* **Production**: `https://api.masspay.io/v1.0.0/payout/`

### Headers

* **Mandatory**: Include your `apiKey` in every request
* **Recommended**: Add `Idempotency-Key` (e.g., `Client_transfer_id`) for safe retries

***

## Check Your Wallet Balance

`GET /account/balance`

* Returns wallet token & balance
* Use the token in Step 6 (payout)

***

## Locate or Create Users

### Step 1: Lookup User

`GET /user/lookup` with: `internal_user_id`, `first_name`, `email`

* Returns `user_token` for steps 4–7
* Recommended: Store `user_token` to avoid repeated lookups

### Create User (if not found)

`POST /user` with: `internal_user_id`, `country`, `first_name`, `last_name`, `email`

* Recommended: Add optional fields now to save time later
* Returns `user_token`

***

## Choose Payout Method

You can either load a wallet (recommended) or send a direct payout.

### Option 1: Wallet Load (Recommended)

`POST /load/{user_token}`

* Required: `client_load_id`, `source_token`
* Recommended: `notes`, `notify_user` (defaults to true)

**Why Wallet Load is Recommended:**

* No need to store or validate banking/payout details
* MassPay manages routing, delivery method, and country restrictions
* Funds stay in one wallet across platforms
* Withdrawal timing is user-controlled
* Free to load wallets (no added fees)
* Better error handling and reduced compliance overhead

### Option 2: Direct Payout

#### Step 1: Get Payout Routes

`GET /country/{country_code}/best`

* Recommended: `only_generic_payers=true` to return only the general option
* Optional: `payer_name=Bank Deposit|Interac` to filter by name

#### Step 2: Get Attributed

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

* Returns required fields for selected route

#### Step 3: Store Attributed

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

* Input all required `attr_token` and values
* Returns an `attr_set_token`

#### Step 4: Initiate Payout

`POST /payout/{user_token}`

* Required: `client_transfer_id`, `destination_currency_code`, `source_token`, `destination_token`, `source_amount` or `destination_amount`
* Recommended: `attr_set_token`
* Returns: `payout_token`

#### Step 5: Commit Payout

`PUT /payout/{user_token}/{payout_token}` within 2 minutes

* Returns final status, pickup code, or error

***

## Webhooks & Monitoring

### Mandatory

Set listeners for:

* `payout.created`
* `payout.status`

### Notes

* `payout.status` can change multiple times during the lifecycle of a payout.
* Rare cases: status may flip between `completed` ↔ `cancelled`.
* Recommended: set alerts so your finance/ops team can react.

***

## Reconciliation & Confirmation

### Mandatory

* Reconcile balances and statuses regularly

### Recommended

* `GET /payout/{user_token}/{payout_token}` for PDF confirmation

***

## Go-Live Checklist

* KYB completed
* API key received
* Sandbox tested
* Users created
* Wallet funded
* Best route checked
* Minimums confirmed
* Attributes validated
* Webhooks working
* Reconciliation plan in place

***

## KYC Reminder

Users might be asked to provide verification documents (e.g., ID or bank statement) at any time. Triggers include behavior patterns or third-party alerts. If locked, transactions will be rejected.

### Requirements

* Share the error response’s unique doc-upload link with the user or relevant internal team
* This is required to unlock the user for future transactions

***

## Resources

* [Full Documentation](https://developers.masspay.io)
* Questions? Contact your Account Manager
* Emergencies: <Support@masspay.io>