SCA on your platform - Mangopay docs

Mangopay must ensure that your platform’s interactions with its services are compliant with SCA. In cases where your platform is taking SCA-triggering actions under proxy from users, your platform needs to use a second authentication factor. The API key that your platform uses to authenticate API calls serves as a knowledge-based factor. The second factor Mangopay uses is mTLS authentication, which is a possession-based factor that your platform needs to set up and integrate as described below. Integration of mTLS authentication is only necessary if your platform is using proxy management.

Mutual TLS authentication

Mutual Transport Security Layer (mTLS) is a standard protocol that enables two-way secure authentication between your platform’s server and Mangopay’s server, ensuring both parties are authenticated before data is exchanged. The system works using public-key cryptography, which involves a public-private key pair – the private key is a secret that you must store securely like your existing API key.

Overview

For your platform, mTLS authentication requires you to:

Generate a private key
Generate a CSR
Request a certificate in the Mangopay Dashboard using the CSR and download it
Integrate mTLS in the SDK using the certificate, your private key, and a new base URL (with api-mtls in the hostname)
Renew your certificate before it expires after 12 months

An overview of the whole process is given in the diagram below:

1. Generate a private key

Your platform will need to generate a private key. You can do this using OpenSSL, which is a widely used software library for cryptographic functions. The following command, for example, creates a file named private.key in the directory where the command is run. This command generates an RSA key, which uses a popular algorithm for public-key cryptography. The length of the key is 2048 bits, a common standard.

openssl genrsa -out private.key 2048

You should generate one key for Sandbox and one for Production to enhance security.

Note - Store the private key securelyThe private key is a long string or small file and you must store it securely, in the same way as an API key.Do not share the private key with Mangopay. Only the CSR is shared with Mangopay.

2. Create a CSR

Once you have the private key, you can use it to generate a Certificate Signing Request (CSR). A CSR is an encoded file that contains a public key and information about your server, and your private key is used to create a secure digital signature. The OpenSSL commands below create a CSR called client.csr using the private.key for a generic ClientId. Before running the commands, update the variables for your file names and Client ID. You can find the same commands with your ClientId prepopulated in the Mangopay Dashboard (Developers > mTLS certificates).

Linux / MacOS

Sandbox

openssl req -new -key private.key -out client.csr \
  -subj "/CN=ClientId.sandbox.mangopay.com/O=Mangopay/C=LU" \
  -addext "subjectAltName=DNS:ClientId.sandbox.mangopay.com" \
  -addext "extendedKeyUsage=clientAuth"

Production

openssl req -new -key private.key -out client.csr \
  -subj "/CN=ClientId.prod.mangopay.com/O=Mangopay/C=LU" \
  -addext "subjectAltName=DNS:ClientId.prod.mangopay.com" \
  -addext "extendedKeyUsage=clientAuth"

Windows (PowerShell, CMD, Git Bash)

Sandbox

openssl req -new -key private.key -out client.csr -subj "/CN=ClientId.sandbox.mangopay.com\O=Mangopay\C=LU" \
  -addext "subjectAltName=DNS:ClientId.sandbox.mangopay.com" \
  -addext "extendedKeyUsage=clientAuth"

Production

openssl req -new -key private.key -out client.csr -subj "/CN=ClientId.prod.mangopay.com\O=Mangopay\C=LU" \
  -addext "subjectAltName=DNS:ClientId.prod.mangopay.com" \
  -addext "extendedKeyUsage=clientAuth"

3. Request a certificate

Once you have your CSR, you can use it to request and download the certificate:

Connect to the Mangopay Dashboard
Navigate to Developers > mTLS certificates
Click Request certificate in the top right
Paste your CSR content or upload the .csr file
Click Generate certificate
On the mTLS certificates page, navigate to the Certificates tab, where you should see your certificate as ACTIVE
To download the certificate, hover over the table line, click the kebab icon (⋮) on the right, and click Download

The certificate file that you download is a .pem file containing only the certificate. You will need both the .pem file and your private .key file from Step 1 to complete the SDK integration.

4. Integrate mTLS in the SDK

Mangopay’s server-side SDKs support mTLS authentication as an additional authentication layer on top of the API key and Client ID. The SDKs use TLS 1.2+ for mTLS, which is required by the API.

Secrets management

Caution – Manage your secrets safelyIn your integration, ensure you manage all secrets securely, including your API key, Client ID, private .key, and .pem certificate.

Where possible, the SDKs allow you to use Base64-encoded strings, so you can encode the content of the .pem file and .key file to store then in your secrets manager, and use the variables in your environment. The SDKs contain features to simplify integration and Sandbox testing, including handling local file paths. If two sets of SDK properties are available, the file-path ones take precedence to facilitate testing. In Production, you must ensure your secrets are handled safely, using encoded variables and dedicated secrets managers.

Prerequisites

To use mTLS authentication in the SDK you need:

The mTLS certificate, which is the .pem file downloaded from the Mangopay Dashboard
The private key (.key file) used to generate the CSR which you used to request the certificate

The integration guidance differs depending on your SDK language. The SDK version on which the mTLS features were implemented is given in each case.

Minimum Java SDK version: 2.61.0

Set the base URL for mTLS

Using mTLS authentication requires your integration to call a base URL with a different hostname from the standard API:

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

Note – Use mTLS hostname for all API callsIf using mTLS, your integration should use the api-mtls base URLs for all API calls, including OAuth token generation.

Caution – Set the mTLS base URLEnsure you set the Sandbox or Production mTLS base URL with api-mtls in the hostname. If you don’t, Mangopay will not receive your mTLS certificate correctly and your integration will result in an error (when mTLS is enforced).

For the Java SDK, set the base URL using the setBaseUrl() method on the Configuration object attached to your MangoPayApi instance:

MangoPayApi api = new MangoPayApi();
api.getConfig().setBaseUrl("https://api-mtls.sandbox.mangopay.com/");

Convert the certificate to PKCS12

For the Java SDK, you need to convert your certificate to the PKCS12 format. For Java, the .p12 file format is more common (rather than .pfx).You can do this using OpenSSL, for example:

openssl pkcs12 -export \
  -in certificate.pem \
  -inkey private.key \
  -out client.p12 \
  -name "client-cert" \
  -passout pass:your-cert-password

Configure the SDK’s mTLS properties

The Java SDK uses the standard java.security.KeyStore with the p.12 file to manage mTLS certificates.Two setters on com.mangopay.core.Configuration control mTLS:

Setter	Type	Description
`setKeyStore(KeyStore)`	`java.security.KeyStore`	A loaded PKCS12 keystore holding the client certificate and private key.
`setKeyStorePassword(char[])`	`char[]`	Password that protects the entry inside the keystore.

Both methods are synchronized. This means that they automatically invalidate the cached SSLContext so that the following request rebuilds it with the new values.

import java.io.InputStream;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.security.KeyStore;

KeyStore keyStore = KeyStore.getInstance("PKCS12");
try (InputStream ks = Files.newInputStream(Paths.get("client.p12"))) {
    char[] password = "your-cert-password".toCharArray();
    keyStore.load(ks, password);
}
api.getConfig().setKeyStore(keyStore);
api.getConfig().setKeyStorePassword("your-cert-password".toCharArray());

Minimum .NET SDK version: 3.40.0

Set the base URL for mTLS

Using mTLS authentication requires your integration to call a base URL with a different hostname from the standard API:

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

Note – Use mTLS hostname for all API callsIf using mTLS, your integration should use the api-mtls base URLs for all API calls, including OAuth token generation.

Convert the certificate to PKCS12

For the .NET SDK, you need to convert your certificate to the PKCS12 format. For .NET, the .pfx file format is more common (rather than .p12).You can do this using OpenSSL, for example:

openssl pkcs12 -export \
  -out client.pfx \
  -inkey private.key \
  -in certificate.pem \
  -name "client-cert" \
  -passout pass:your_cert_password \

Configure the SDK’s mTLS properties

The .NET SDK allows you to load Base64-encoded strings from your environment variables. You can also load locally stored file paths, which may be useful during testing.Caution: The file path properties take precedence if both are set.

Base64-encoded strings

When your .pfx certificate is stored as a BAse64-encoded string in a secrets manager, you can load it using the ClientCertificateString, along with ClientCertificatePassword for its password (non-encoded).Best practice: Use this option in Production.

using MangoPay.SDK;
using MangoPay.SDK.Core;

var api = new MangoPayApi();
api.Config.ClientId = "your-mangopay-client-id";
api.Config.ClientPassword = "your-mangopay-api-key";
api.Config.BaseUrl = "https://api-mtls.sandbox.mangopay.com"; // mTLS base URL

// Base64-encoded PFX/PKCS#12 bytes
api.Config.ClientCertificateString = Environment.GetEnvironmentVariable("CLIENT_PFX_B64");

// Optional: password string (omit if the certificate has no password)
api.Config.ClientCertificatePassword = Environment.GetEnvironmentVariable("YOUR_CERT_PASSWORD");

File paths

If your .pfx and its password are stored locally, for example during testing, you can load them using X509Certificate2.Caution: If the X509Certificate2 property is set, it takes precedence and the ClientCertificateString and ClientCertificatePassword are ignored.

using System.Security.Cryptography.X509Certificates;
using MangoPay.SDK;
using MangoPay.SDK.Core;

var cert = new X509Certificate2("path/to/client.pfx", "your-cert-password");

var api = new MangoPayApi();
api.Config.ClientId = "your-mangopay-client-id";
api.Config.ClientPassword = "your-mangopay-api-key";
api.Config.BaseUrl = "https://api-mtls.sandbox.mangopay.com"; // mTLS base URL
api.Config.ClientCertificate = cert;

Minimum Node.js SDK version: 1.67.0

Set the base URL for mTLS

Using mTLS authentication requires your integration to call a base URL with a different hostname from the standard API:

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

Note – Use mTLS hostname for all API callsIf using mTLS, your integration should use the api-mtls base URLs for all API calls, including OAuth token generation.

Configure the SDK’s mTLS properties

The Node.js SDK allows you to load Base64-encoded strings from your environment variables. You can also load locally stored file paths, which may be useful during testing.Caution: The file path properties take precedence if both are set.

Base64-encoded strings

When your .pem certificate and private .key are stored as encoded strings in a secrets manager, you can load them using the following configuration properties.Best practice: Use this option in Production.

Property	Type	Description
`cert`	string	Base64-encoded string of the certificate `.pem` file content.
`key`	string	Base64-encoded string of the private `.key` file content.
`ca`	string (optional)	Base64-encoded string of the private or custom certificate authority, if used.
`passphrase`	string (optional)	String of the passphrase for an encrypted private key.

const mangopay = new Mangopay({
  clientId: 'your-mangopay-client-id',
  clientApiKey: 'your-api-key',
  baseUrl: 'https://api-mtls.sandbox.mangopay.com', // mTLS base URL
  cert: process.env.CERTIFICATE_PEM_B64,      // Base64-encoded
  key: process.env.PRIVATE_KEY_B64,        // Base64-encoded 
  ca: process.env.YOUR_CUSTOM_CA,          // Base64-encoded (optional)
  passphrase: process.env.YOUR_CERT_PASSPHRASE, // String or path
});

File paths

If your .pem certificate and private .key are stored locally, for example during testing, you can load them using the following properties.Caution: If the file path properties are set, they take precedence and the Base64-encoded equivalents are ignored.

Property	Type	Description
`certFilePath`	string	Path to the certificate `.pem` file.
`keyFilePath`	string	Path to the private `.key` file.
`caFilePath`	string (optional)	Path to the private or custom certificate authority, if used.
`passphrase`	string (optional)	String of the passphrase for an encrypted private key.

const mangopay = new Mangopay({
  clientId: 'your-mangopay-client-id',
  clientApiKey: 'your-api-key',
  baseUrl: 'https://api-mtls.sandbox.mangopay.com', // mTLS base URL
  certFilePath: '/path/to/certificate.pem',
  keyFilePath: '/path/to/private.key',
  caFilePath: '/path/to/custom-ca.crt',          // optional
  passphrase: 'your-cert-passphrase',   // optional
});

Minimum PHP SDK version: 3.51.0

Set the base URL for mTLS

Using mTLS authentication requires your integration to call a base URL with a different hostname from the standard API:

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

Note – Use mTLS hostname for all API callsIf using mTLS, your integration should use the api-mtls base URLs for all API calls, including OAuth token generation.

Caution – Ensure you set the mTLS base URLEnsure you set the Sandbox or Production mTLS base URL with api-mtls in the hostname. If you don’t, Mangopay will not receive your mTLS certificate correctly and your integration will result in an error (when mTLS is enforced).

Configure the SDK’s mTLS properties

The PHP SDK allows you to load Base64-encoded strings from your environment variables. You can also load locally stored file paths, which may be useful during testing.Caution: The file path properties take precedence if both are set.

Base64-encoded strings

When your .pem certificate and private .key are stored as encoded strings in a secrets manager, you can load them using the following configuration properties.Prerequisite: The Base64-encoded string properties require PHP ≥ 8.1 compiled against libcurl ≥ 7.71.0.If this prerequisite is not met, the SDK will throw an exception at runtime because of the CURLOPT_SSLCERT_BLOB and CURLOPT_SSLKEY_BLOB used under the hood.

Property	Type	Description
`ClientCertificateString`	string	Base64-encoded string of the certificate `.pem` file content.
`ClientCertificateKeyString`	string	Base64-encoded string of the private `.key` file content.
`ClientCertificateKeyPassword`	string (optional)	String of the passphrase for an encrypted private key.

$api = new MangoPay\\MangoPayApi();
$api->Config->ClientId = 'your-mangopay-client-id';
$api->Config->ClientPassword = 'your-mangopay-api-key';
// mTLS base URL
$api->Config->BaseUrl = 'https://api-mtls.sandbox.mangopay.com';

// Base64-encoded .pem certificate content
$api->Config->ClientCertificateString = 'MANGOPAY_PEM_B64'

// Base64-encoded private .key content
$api->Config->ClientCertificateKeyString = 'MANGOPAY_KEY_B64'

// Optional: passphrase if the private key is password-protected
$api->Config->ClientCertificateKeyPassword = 'YOUR_CERT_PASSWORD';

Typical example with a secrets manager:

$cert = $secretsManager->getSecret('MANGOPAY_PEM_B64');
$key  = $secretsManager->getSecret('MANGOPAY_KEY_B64');

$api->Config->ClientCertificateString    = $cert;
$api->Config->ClientCertificateKeyString = $key;

File paths

Property	Type	Description
`ClientCertificatePath`	string	Path to the certificate `.pem` file.
`ClientCertificateKeyPath`	string	Path to the private `.key` file.
`ClientCertificateKeyPassword`	string (optional)	String of the passphrase for an encrypted private key.

$api = new MangoPay\\MangoPayApi();
$api->Config->ClientId = 'your-mangopay-client-id';
$api->Config->ClientPassword = 'your-mangopay-api-key';

// Path to the .pem certificate file
$api->Config->ClientCertificatePath = '/path/to/certificate.pem';

// Path to the private .key file
$api->Config->ClientCertificateKeyPath = '/path/to/private.key';

// Optional: passphrase if the private key is password-protected
$api->Config->ClientCertificateKeyPassword = 'your-cert-password';

Minimum Python SDK version: 3.55.0

Set the base URL for mTLS

Using mTLS authentication requires your integration to call a base URL with a different hostname from the standard API:

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

Note – Use mTLS hostname for all API callsIf using mTLS, your integration should use the api-mtls base URLs for all API calls, including OAuth token generation.

Configure the SDK’s mTLS properties

The Python SDK allows you to load the .pem and .key file paths in the global configuration or in the per-request handler.

Property (global / per-request)	Type	Description
`mtls_cert` / `cert`	string	Path to the certificate `.pem` file.
`mtls_private_key` / `key`	string	Path to the private `.key` file.

Caution: The per-request properties cert and key take precedence if set and the global ones are ignored (mangopay.mtls_cert and mangopay.mtls_private_key).The certificate files must be accessible at runtime; the SDK does not validate their content at initialization time.When both are provided, the SDK sets session.cert = (cert, key) on the underlying requests.Session. If a combined certificate is provided (bundling the key), the SDK sets session.cert = cert.

Global configuration

The global properties allow you to set the certificate and key before making any API calls. The certificate is used for all requests made through the default handler.

import mangopay

mangopay.client_id = 'your-mangopay-client-id'
mangopay.apikey = 'your-mangopay-api-key'
mangopay.api_sandbox_url = 'https://api-mtls.sandbox.mangopay.com/v2.01/'
sandbox = True
# mangopay.api_url = 'https://api-mtls.mangopay.com/v2.01/'
mangopay.mtls_cert = '/path/to/certificate.pem'
mangopay.mtls_private_key = '/path/to/private.key'

Per-request handler

Caution: The per-request values take precedence over the global values.Each APIRequest instance maintains its own requests.Session, so mTLS certificates are scoped to that instance and do not leak between handlers.

from mangopay.api import APIRequest

handler = APIRequest(
    client_id='your-mangopay-client-id',
    apikey='your-mangopay-api-key',
    api_sandbox_url = 'https://api-mtls.sandbox.mangopay.com/v2.01/' # mTlS base URL
		sandbox = True
		# mangopay.api_url = 'https://api-mtls.mangopay.com/v2.01/'
    cert='/path/to/certificate.pem',
    key='/path/to/private.key'
)

Then pass the handler when making API calls:

from mangopay.resources import NaturalUser, Wallet

user = NaturalUser.get(user_id, handler=handler)
wallet = Wallet.get(wallet_id, handler=handler)

Minimum Ruby SDK version: 3.47.0

Set the base URL for mTLS

Using mTLS authentication requires your integration to call a base URL with a different hostname from the standard API:

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

Note – Use mTLS hostname for all API callsIf using mTLS, your integration should use the api-mtls base URLs for all API calls, including OAuth token generation.

Configure the SDK’s mTLS properties

The Ruby SDK’s mTLS properties accept one of:

Base64-encoded string – To load the certificate content from environment variables
File path – To point to the locally stored file, for example during testing

Property	Type	Description
`mtls_cert`	string	Base64-encoded string of the certificate content or path to the certificate `.pem` file.
`mtls_private_key`	string	Base64-encoded string of the private key content or path to the private `.key` file.
`mtls_key_passphrase`	string (optional)	String of the passphrase if the private key is encrypted.

Base64-encoded strings

MangoPay.configure do |c|
  c.client_id    = 'your-mangopay-client-id'
  c.client_apiKey = 'your-mangopay-api-key'
  c.root_url = 'https://api-mtls.sandbox.mangopay.com' # mTLS base URL
  c.preproduction = true

  c.mtls_cert           = ENV['CERTIFICATE_PEM_B64']  # Base64-encoded string
  c.mtls_key            = ENV['PRIVATE_KEY_B64']   # Base64-encoded string
  c.mtls_key_passphrase = ENV['YOUR_CERT_PASSPHRASE'] # optional, if encrypted
end

File paths

MangoPay.configure do |c|
  c.client_id    = 'your-mangopay-client-id'
  c.client_apiKey = 'your-mangopay-api-key'
  c.root_url = 'https://api-mtls.sandbox.mangopay.com' # mTLS base URL
  c.preproduction = true

  c.mtls_cert           = '/path/to/certificate.pem' # file path
  c.mtls_key            = '/path/to/private.key' # file path 
  c.mtls_key_passphrase = 'your-cert-passphrase' # optional, if encrypted
end

5. Renew your certificate

The .pem certificate provided by Mangopay is valid for 12 months, after which point it expires. Before it expires, you need to generate a new one following the same process as above, starting with a new private key.

​Mutual TLS authentication

​Overview

​1. Generate a private key

​2. Create a CSR

​Linux / MacOS

Sandbox

Production

​Windows (PowerShell, CMD, Git Bash)

Sandbox

Production

​3. Request a certificate

​4. Integrate mTLS in the SDK

​Secrets management

​Prerequisites

​Set the base URL for mTLS

​Convert the certificate to PKCS12

​Configure the SDK’s mTLS properties

​Set the base URL for mTLS

​Convert the certificate to PKCS12

​Configure the SDK’s mTLS properties

​Base64-encoded strings

​File paths

​Set the base URL for mTLS

​Configure the SDK’s mTLS properties

​Base64-encoded strings

​File paths

​Set the base URL for mTLS

​Configure the SDK’s mTLS properties

​Base64-encoded strings

​File paths

​Set the base URL for mTLS

​Configure the SDK’s mTLS properties

​Global configuration

​Per-request handler

​Set the base URL for mTLS

​Configure the SDK’s mTLS properties

​Base64-encoded strings

​File paths

​5. Renew your certificate

Mutual TLS authentication

Overview

1. Generate a private key

2. Create a CSR

Linux / MacOS

Windows (PowerShell, CMD, Git Bash)

3. Request a certificate

4. Integrate mTLS in the SDK

Secrets management

Prerequisites

Set the base URL for mTLS

Convert the certificate to PKCS12

Configure the SDK’s mTLS properties

Set the base URL for mTLS

Convert the certificate to PKCS12

Configure the SDK’s mTLS properties

Base64-encoded strings

File paths

Set the base URL for mTLS

Configure the SDK’s mTLS properties

Base64-encoded strings

File paths

Set the base URL for mTLS

Configure the SDK’s mTLS properties

Base64-encoded strings

File paths

Set the base URL for mTLS

Configure the SDK’s mTLS properties

Global configuration

Per-request handler

Set the base URL for mTLS

Configure the SDK’s mTLS properties

Base64-encoded strings

File paths

5. Renew your certificate