mTLS Configuration (OLD)

Set up and exchange mTLS Certificates

Mutual Transport Layer Security (mTLS) is a protocol that enhances security in communications between the client and the server. mTLS verifies the identities of both the client and the server, ensuring that data is both securely sent and received by the correct parties. In order to integrate with Payrails and use our tooling, you will need to set up and exchange mTLS certificates with us.

Generating a certificate

To use mTLS, you'll need to generate a private key and a certificate signing request (CSR) that you'll use to obtain a certificate.

The command to do this depends on the tool you're using. With OpenSSL, for example, you might use:

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

This command will guide you through the process of creating a new private key (domain.key) and a certificate signing request (domain.csr).
Fill in your company's information when prompted: put your organization name as Organization, and the domain of Payrails' API as Common Name (ex:

Exchange certificates with Payrails

After you've created your files with the command above, you need to send your Certificate Signing Request (.csr) to us. We will then provide you with your certificate. Please be sure to send us only that file, never share your private key with anyone (domain.key).

Contact your account manager at Payrails to receive your certificate.

Use mTLS with Postman

Postman is a widely-used tool for API testing. If you haven't already, download and install it from the official website or via brew.

See the guide here from about working with certificates in Postman: setup the certificate provider by payrails as a client certificate and your private key as the key.

Using mTLS with CLI

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

In this command, domain.pem is your certificate file sent by Payrails and domain.key is your private key file.

Creating mTLS Certificates with Portal


A guide on creating mTLS certificates using the Merchant Portal is coming soon!