Documentation
Start typing to search…

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

Updated 3 days ago