mTLS Configuration

Introduction

Mutual TLS (mTLS) is a security protocol that enhances the authentication process by requiring the Payrails system and the merchant's system to connect through digital certificates. It ensures a secure and authenticated connection, reducing the risk of unauthorized access and data breaches.

Before starting your integration with Payrails, you will set up the mTLS configuration. It is a setting on the organization level, and is not needed on the workspace level.

Setting up a secure mTLS connection

Only admin and developer roles can access the mTLS page in Settings. Check here for (roles & permissions) for more information.

Follow below three steps below to establish a secure connection between your system and Payrails. Please note that this setup is required for production only; for staging connection, please connect with [email protected].

Step 1: Generate a CSR (Certificate signing request)

To use mTLS, first, you will generate a private key and a CSR (certificate signing request) to obtain a certificate in the next steps. To generate:

1. Open a terminal or command prompt.
2. Use OpenSSL to generate a new private key and corresponding CSR:

openssl req -new -newkey rsa:4096 -nodes -keyout domain.key -out domain.csr

Follow the guide in your terminal and fill in your company's information when prompted. The following fields are required:

• Country name: ISO 3166-1 alpha-2 country code (e.g. DE)
• State or Province Name (full name): State or Province of your organization (e.g. Berlin)
• Organization Name: Name of your organization
• Common Name: Domain of Payrails' API for that environment as Common Name
  • Staging: yourCompany-api.staging.payrails.io
  • Live: api.yourCompany.payrails.io

Step 2: Create a certificate with your CSR

Once you have the CSR:

1. Log in to Organization > System Configurations > mTLS Certificates page,
2. Create a certificate by uploading your CSR,
3. Check the automatically downloaded certificate after its creation.

Step 3: Start using it

The exact command to use mTLS with CLI depends on the tool you're using. Here's an example with curl to retrieve an access token from Payrails API:

curl --cert domain.pem --key domain.key \
  --location --request POST 'https://<payrails-api-endpoint-url>/auth/token/<Client ID>' \
  --header 'Accept: application/json' \
  --header 'x-api-key: <Client Secret>'

• domain.pem: the certificate file downloaded (or sent to you) in Step 2,
• domain.key: the private key file generated in Step 1,
  • If the private key requires a passphrase, you will also need to provide it with --pass argument.
• Client ID and Client Secret are the API credentials. See how to retrieve them.

Important Notes

• There can be only two active certificates at any point in time. In case you need more, please contact [email protected].
• The mTLS certificate's expiry date is set to 10 years and can't be changed.
• The system will store the PEM file, which can also be downloaded later.

How to download or revoke a certificate

1. Log in to Settings > mTLS Certificates page,
2. Select the certificate,
3. Make the download or revocation of the certificate.

How to use mTLS with Postman?

In Postman you can configure your mTLS certificate by going to Postman > Settings > Certificates > Client certificates: click on Add Certificate...

• Host: URL to your environment
• CRT file: the certificate file downloaded (or sent to you) in Step 2 (domain.pem)
• KEY file: the private key file generated in Step 1 (domain.key)
• Passphrase: passphrase of the private key (if any)

Once it's added, this environment will use the mTLS certificate.

Common Errors

Error: error:0900006e:PEM routines:OPENSSL_internal:NO_START_LINE

When calling our API with MTLs, you can get an error mentioning OPENSSL_internal:NO_START_LINE, it can be because you use the certificate signing request (domain.csr) instead of the certificate file downloaded (or sent to you) in Step 2 (domain.pem).