Guides
Go to payrails.com
Start typing to search…

mTLS Configuration

🚧

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 unauthorized 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
    • Staging: yourCompany-api.staging.payrails.io
    • Live: api.yourCompany.payrails.io

Step 2: Add Certificate in Portal

You need to have the organization-admin or organization-developer role (roles & permissions) to access mTLS certificates from the organization context (organization).

  1. Log in to the Payrails Merchant Portal.
  2. Navigate to the organization context
  3. 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. In case you need more, please contact Payrails support.

  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>' \
// Please use the host as 'https://<yourCompanyName-api.staging.payrails.io>/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 need to also provide it with --pass argument.
  • Client ID and Client Secret are the API credentials. See how to retrieve them.

How to Download or Revoke a Certificate

  1. Log in to the Payrails Merchant Portal.
  2. If you are in workspace context, switch to organization context
  3. Navigate to the "mTLS certificates" section.
  4. Select your previously created certificate.
  5. Download the certificate as a PEM file.

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.

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)

Press Add and now calls to this environment should 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).

Updated 4 months ago