Introduction

The Mangopay API is based on REST principles, providing a simple and secure way to process payment flows.

To integrate Mangopay’s API endpoints, refer to our server-side SDK libraries for your prefered language. The API reference contains examples of SDK functions for each endpoint.

Environments

Mangopay provides two environments:

Production	Sandbox
https://api.mangopay.com	https://api.sandbox.mangopay.com

Note – Proxy management for SCA requires mTLS base URL

If your platform is using proxy management to take SCA-triggering actions on behalf of users, you need to use mTLS authentication.

This integration requires a different base URL, with api-mtls in the hostname. The mTLS base URL should be used for all API calls, including OAuth token generation.

If you are not using proxy management, you need to use the base URLs shown above.

Request and response format

Unless stated otherwise on an endpoint page, the Mangopay API accepts and returns:

Content-Type	application/json
Encoding	UTF-8 JSON

application/json

UTF-8 JSON

Note – Endpoints requiring a different Content-Type

There are two endpoints that require the application/x-www-form-urlencoded Content-Type:

The OAuth token endpoint – see OAuth 2.0 authentication
The Tokenize the card endpoint, which is a URL returned by the API

OpenAPI conventions

Mangopay publishes this API reference from an OpenAPI specification. This specification exists primarily to power this documentation website and has been optimized for human-readable clarity.

As a result, it follows these noteworthy conventions for OpenAPI features:

Constraints in descriptions — For string and integer formats, any constraints on format, length, and allowed values are documented in the property’s description. The spec does not currently use validation keywords such as format, maxLength, pattern, or enum for those rules.
Undiscriminated unions — The spec uses oneOf to describe different request and response schemas where relevant, but these variants are not discriminated with the discriminator property. Any conditional logic is described in property and schema descriptions where relevant.

This approach aims to ensure consistency with historically used documentation standards while allowing for future iterations.

The OpenAPI definition of any endpoint is available by appending .md to any endpoint page URL.

For integration and testing, Mangopay’s server-side SDKs provide unit tests and facilitate your integration by defining properties and data types specific to each language and environment. See the latest SDK releases →

Note for UK platforms

Previously, Mangopay required platforms that contracted with Mangopay’s UK entity to include an HTTP header in all API requests in Production.

This is no longer the case. The header x-tenant-id (with values eu (default) or uk) is deprecated and ignored by Mangopay if sent.

In the SDKs, there was a UK header flag boolean which, when true, set the header value to uk.

The tenant notion was replaced with the Licensor field of the API’s Client object, and it is set automatically by Mangopay.