Go to payrails.com

mTLS Configuration

Suggest Edits

🚧

Adding and revoking a certificate is currently only available for the production environment. For the staging environment, please send the Certificate Signing Request to your Payrails administrator. The Payrails team will then make the certificate available for you in the portal.

Introduction to Mutual TLS (mTLS) and its importance for Payrails and Merchants

Mutual TLS (mTLS) is a security protocol that enhances the authentication process by requiring both parties, the Payrails system, and the merchants, to present digital certificates. This ensures a secure and authenticated connection, reducing the risk of unauthorised access and data breaches.To integrate with Payrails and use our tooling, set up and exchange mTLS certificates with us.

Setting Up a Secure Connection with Payrails

Follow these three steps to establish a secure connection between your system and Payrails:

Step 1: Generate a Certificate Signing Request

To use mTLS, generate a private key and a certificate signing request (CSR) to obtain a certificate.

  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 (e.g. your-environment-api.staging.payrails.io)

Step 2: Add Certificate in Portal

📘

Only user with Admin role is able to manage mTLS certificates.

  1. Log in to the Payrails Merchant Portal.
  2. Navigate to the "mTLS certificates" section.

  1. Find the option to upload a certificate.

  2. Select your previously generated certificate file.

    📘

    The mTLS certificate's expiry date is set to 10 years and can't be changed.

    There can be only two active certificates at any point of time.

  3. Confirm the upload, and the certificate will be associated with your account. The certificate will be downloaded automatically after being created.

  4. After uploading, the system will store the PEM file that can be downloaded later.

Step 3: Start Using It by Calling Payrails API

The exact command to use mTLS with CLI depends on the tool you're using. Here's an example with curl in order to retrieve an auth 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>'

How to Download or Revoke a Certificate

  1. Log in to the Payrails Merchant Portal.
  2. Navigate to the "mTLS certificates" section.
  3. Select your previously created certificate.
  4. Download the certificate as a PEM file.

  1. Alternatively, you can REVOKE the certificate. For that, you need the correct user role and permissions assigned to you.

By following these steps, you can seamlessly integrate mTLS certificates into the Payrails Merchant Portal, ensuring a secure and authenticated connection between the platform and its users.

Updated about 2 months ago