---
updatedAt: 2026-08-07T17:43:10.000Z
agentTools:
  projectIndex: https://developers.masspay.io/llms.txt
---

# Overview

# 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](https://developers.masspay.io/page/sdks).

New to MassPay? Start with [Authentication](https://developers.masspay.io/reference/authentication), [register for staging API keys](https://dev.clients.masspay.io/v2/register), and make your first calls against the staging environment (see [Testing](https://developers.masspay.io/reference/testing)). For sequence diagrams of common integration flows, see [Swimlanes](https://developers.masspay.io/reference/swimlanes).

***

## Base URL

All API requests use the following base URL:

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

| Parameter     | Values                                      | Default  |
| ------------- | ------------------------------------------- | -------- |
| `environment` | `api` (production), `staging-api` (staging) | `api`    |
| `version`     | `v1.0.0` (current), `v0.1.4` (legacy)       | `v1.0.0` |

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](https://developers.masspay.io/reference/versioning) for how the two interact and how to upgrade, and the [Changelog](https://developers.masspay.io/changelog) for what has changed between releases.

***

## Authentication

Every request must be authenticated. See [Authentication](https://developers.masspay.io/reference/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](https://developers.masspay.io/reference/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](https://developers.masspay.io/reference/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](https://developers.masspay.io/reference/webhooks) for payload formats and delivery behavior, or manage subscriptions programmatically with the [webhook configuration endpoints](https://developers.masspay.io/reference/post-payout-account-webhooks).

***

## 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](https://dev.clients.masspay.io/v2/register) to get your staging API keys, and see [Testing](https://developers.masspay.io/reference/testing) for how to simulate transaction outcomes.

***

## Resources

* [Changelog](https://developers.masspay.io/changelog) — release notes and API updates
* [Status page](https://status.masspay.io/) — live platform status and incident history
* [SDKs](https://developers.masspay.io/page/sdks) — official client libraries
* [PCI](https://developers.masspay.io/reference/pci) — compliance information
* Support — <support@masspay.io>