> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mangopay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# SCA on your platform

> Integrating the mTLS certificate factor required for platforms taking SCA action under proxy

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](/guides/sca/proxy-management) from users, your platform needs to use a second authentication factor.

The [API key](/api-reference/overview/api-keys) 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](/guides/sca/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:

1. [Generate a private key](#1-generate-a-private-key)
2. [Generate a CSR](#2-create-a-csr)
3. [Request a certificate](#3-request-a-certificate) in the Mangopay Dashboard using the CSR and download it
4. [Integrate mTLS in the SDK](#4-integrate-mtls-in-the-sdk) using the certificate, your private key, and a new base URL (with `api-mtls` in the hostname)
5. [Renew your certificate](#5-renew-your-certificate) before it expires after 12 months

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

<div className="block dark:hidden">
  ```mermaid theme={null}
  %%{
    init: {
      'theme': 'base',
      'themeVariables': {
        'primaryColor': '#FFFFFF',
        'primaryTextColor': '#2D0F37',
        'primaryBorderColor': '#2D0F37',
        'lineColor': '#2D0F37',
        'secondaryColor': '#FFFFFF',
        'tertiaryColor': '#FFFFFF',
        'fontSize': '32px',
        'fontFamily': 'Inter',
        'noteBorderColor': "#E0DBE1",
        'noteBkgColor': "#E0DBE1",
        'noteTextColor': '#2D0F37'
      }
    }
  }%%
  sequenceDiagram
      participant P as Your platform
      participant MD as Mangopay Dashboard
      participant API as Mangopay API

      P->>P: (1) Generate private key (.key file)
      Note right of P: Do not share secret key
      P->>P: (2) Generate CSR (.csr file)

      P->>MD: (3) Request certificate using CSR
      MD->>MD: Mangopay signs CSR to <br/>generate certificate (.pem file)
      MD-->>P: Download certificate (.pem file)
      Note right of P: Store secret .pem and .key securely

      P->>P: (4) Use .pem and .key files <br/>to integrate mTLS in SDK
      P->>API: Call API (api-mtls base URL)
      API<<-->>P: Client-server mutual TLS handshake
      Note right of P: (5) Renew certificate before 12 months
  ```
</div>

<div className="hidden dark:block">
  ```mermaid theme={null}
  %%{
    init: {
      'theme': 'base',
      'themeVariables': {
        'primaryColor': "#090D0D",
        'primaryTextColor': "#FFFFFF",
        'primaryBorderColor': "#FFFFFF",
        'lineColor': "#FFFFFF",
        'secondaryColor': "#090D0D",
        'tertiaryColor': "#090D0D",
        'fontSize': '32px',
        'fontFamily': 'Inter',
        'noteBorderColor': "#12282F",
        'noteBkgColor': "#090D0D",
        'noteTextColor': "#FFFFFF"
      }
    }
  }%%
  sequenceDiagram
      participant P as Your platform
      participant MD as Mangopay Dashboard
      participant API as Mangopay API

      P->>P: (1) Generate private key (.key file)
      Note right of P: Do not share secret key
      P->>P: (2) Generate CSR (.csr file)

      P->>MD: (3) Request certificate using CSR
      MD->>MD: Mangopay signs CSR to <br/>generate certificate (.pem file)
      MD-->>P: Download certificate (.pem file)
      Note right of P: Store secret .pem and .key securely

      P->>P: (4) Use .pem and .key files <br/>to integrate mTLS in SDK
      P->>API: Call API (api-mtls base URL)
      API<<-->>P: Client-server mutual TLS handshake
      Note right of P: (5) Renew certificate before 12 months
  ```
</div>

## 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.

```bash theme={null}
openssl genrsa -out private.key 2048
```

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

<Note>
  **Note - Store the private key securely**

  The 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.
</Note>

## 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 <a href="https://hub.mangopay.com" target="_blank">Mangopay Dashboard (Developers > mTLS certificates)</a>.

#### Linux / MacOS

##### Sandbox

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
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 <a href="https://hub.mangopay.com" target="_blank">Mangopay Dashboard</a>
* 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

<Warning>
  **Caution – Manage your secrets safely**

  In your integration, ensure you manage all secrets securely, including your API key, Client ID, private `.key`, and `.pem` certificate.
</Warning>

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 <a href="https://hub.mangopay.com" target="_blank">Mangopay Dashboard</a>
* 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.

<Tabs>
  <Tab title="Java">
    Minimum [Java SDK](/sdks/java) 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>
      **Note – Use mTLS hostname for all API calls**

      If using mTLS, your integration should use the `api-mtls` base URLs for all API calls, including OAuth token generation.
    </Note>

    <Warning>
      **Caution – Set the mTLS base URL**

      Ensure 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).
    </Warning>

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

    ```java theme={null}
    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:

    ```bash theme={null}
    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.

    ```java theme={null}
    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());
    ```
  </Tab>

  <Tab title=".NET">
    Minimum [.NET SDK](/sdks/net) 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>
      **Note – Use mTLS hostname for all API calls**

      If using mTLS, your integration should use the `api-mtls` base URLs for all API calls, including OAuth token generation.
    </Note>

    <Warning>
      **Caution – Set the mTLS base URL**

      Ensure 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).
    </Warning>

    ### 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:

    ```bash theme={null}
    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.

    ```csharp theme={null}
    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.

    ```csharp theme={null}
    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;
    ```
  </Tab>

  <Tab title="Node.js">
    Minimum [Node.js SDK](/sdks/nodejs) 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>
      **Note – Use mTLS hostname for all API calls**

      If using mTLS, your integration should use the `api-mtls` base URLs for all API calls, including OAuth token generation.
    </Note>

    <Warning>
      **Caution – Set the mTLS base URL**

      Ensure 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).
    </Warning>

    ### 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.                         |

    ```jsx theme={null}
    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.        |

    ```jsx theme={null}
    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
    });
    ```
  </Tab>

  <Tab title="PHP">
    Minimum [PHP SDK](/sdks/php) 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>
      **Note – Use mTLS hostname for all API calls**

      If using mTLS, your integration should use the `api-mtls` base URLs for all API calls, including OAuth token generation.
    </Note>

    <Warning>
      **Caution – Ensure you set the mTLS base URL**

      Ensure 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).
    </Warning>

    ### 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.        |

    ```php theme={null}
    $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:

    ```php theme={null}
    $cert = $secretsManager->getSecret('MANGOPAY_PEM_B64');
    $key  = $secretsManager->getSecret('MANGOPAY_KEY_B64');

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

    #### 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                                            |
    | ------------------------------ | ----------------- | ------------------------------------------------------ |
    | `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. |

    ```php theme={null}
    $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';
    ```
  </Tab>

  <Tab title="Python">
    Minimum [Python SDK](/sdks/python) 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>
      **Note – Use mTLS hostname for all API calls**

      If using mTLS, your integration should use the `api-mtls` base URLs for all API calls, including OAuth token generation.
    </Note>

    <Warning>
      **Caution – Set the mTLS base URL**

      Ensure 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).
    </Warning>

    ### 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.

    ```python theme={null}
    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.

    ```python theme={null}
    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:

    ```python theme={null}
    from mangopay.resources import NaturalUser, Wallet

    user = NaturalUser.get(user_id, handler=handler)
    wallet = Wallet.get(wallet_id, handler=handler)
    ```
  </Tab>

  <Tab title="Ruby">
    Minimum [Ruby SDK](/sdks/ruby) 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>
      **Note – Use mTLS hostname for all API calls**

      If using mTLS, your integration should use the `api-mtls` base URLs for all API calls, including OAuth token generation.
    </Note>

    <Warning>
      **Caution – Set the mTLS base URL**

      Ensure 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).
    </Warning>

    ### 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

    ```ruby theme={null}
    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

    ```ruby theme={null}
    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
    ```
  </Tab>
</Tabs>

## 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.