mTLS Configuration
Learn how to set up a secure connection with Payrails through mTLS.
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. 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:
- Open a terminal or command prompt.
- 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 organizationCommon Name
: Domain of Payrails' API for that environment as Common Name- Staging:
yourCompany-api.staging.payrails.io
- Live:
api.yourCompany.payrails.io
- Staging:
Step 2: Create a certificate with your CSR
Once you have the CSR:
- Log in to Organization > System Configurations > mTLS Certificates page,
- Create a certificate by uploading your CSR,
- 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.
- If the private key requires a passphrase, you will also need to provide it with
Client ID
andClient 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
- Log in to Organization > System Configurations > mTLS Certificates page,
- Select the certificate,
- 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 environmentCRT 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
).
Updated 9 days ago