Overview

Introduction

Welcome to the MassPay API! MassPay is a global financial orchestration platform for payins, payouts, and custody. Use the API to create users, run KYC, fund and hold wallet balances, and move money — payouts, payins, loads, and wallet-to-wallet transfers — through a single REST interface.

Every endpoint in the API reference includes runnable code samples in Shell (cURL), Ruby, Python, Java, and JavaScript; use the language tabs in the code panel to switch. Official client libraries are available on the SDKs page.

New to MassPay? Start with Authentication, register for staging API keys, and make your first calls against the staging environment (see Testing). For sequence diagrams of common integration flows, see Swimlanes.

---

Base URL

All API requests use the following base URL:

https://{environment}.masspay.io/{version}

For example, the production base URL for the current version is https://api.masspay.io/v1.0.0.

---

Versioning

The API version appears in the URL path, and the functionality available to you also depends on the version configured on your account. See Versioning for how the two interact and how to upgrade, and the Changelog for what has changed between releases.

---

Authentication

Every request must be authenticated. See Authentication for how to obtain your API credentials and include them with each call. Treat credentials as secrets: never embed them in client-side code or commit them to public repositories.

---

Making requests

All request and response bodies are JSON encoded. Include a Content-Type: application/json header on any request that has a body.

HTTPS is required. Requests must be made over HTTPS using TLS 1.2 or higher. Calls made over plain HTTP are rejected.

Compression

Add an Accept-Encoding: gzip header to your requests and any response body larger than 1 MB will be returned gzip-compressed.

---

Idempotency

Write operations accept an idempotency key. Retrying a request with the same key returns the result of the original call instead of performing the operation again — essential for making sure a network timeout never turns into a duplicate payout. See Idempotent Requests.

---

Errors

The API uses conventional HTTP status codes — 2xx for success, 4xx for problems with the request, 5xx for server-side issues — and returns structured JSON error responses. See Error codes for the full reference.

---

Webhooks

Many operations — payouts, payins, loads, KYC checks — complete asynchronously. Rather than polling for status, configure webhooks to receive real-time notifications when a transaction changes state. See Webhooks for payload formats and delivery behavior, or manage subscriptions programmatically with the webhook configuration endpoints.

---

Testing

Build and test your integration against the staging environment (https://staging-api.masspay.io/{version}) without moving real money. Register for a staging account to get your staging API keys, and see Testing for how to simulate transaction outcomes.

---

Resources

• Changelog — release notes and API updates
• Status page — live platform status and incident history
• SDKs — official client libraries
• PCI — compliance information
• Support — [email protected]