Guides
Go to payrails.com
Start typing to search…

mTLS Configuration

Learn how to set up a secure connection with Payrails through mTLS.

Overview

Mutual TLS (mTLS) adds certificate‑based authentication to your API traffic with Payrails. In addition to OAuth client credentials, mTLS verifies the calling system by requiring a valid client certificate during the TLS handshake. This strengthens inbound authentication and helps meet enterprise security and compliance requirements.

This guide covers two flows:

  • Certificate exchange: request, issue, download, rotate, and revoke mTLS client certificates in the Payrails Portal.
  • Use and test: configure Postman (or another HTTP client) to present the certificate and validate calls.

Certificates are scoped per environment.

  • Production: certificate issuance and download are automatic after request.
  • Staging: issuance runs asynchronously; you receive an email when the certificate is ready to download.

Prerequisites

  • Admin or Developer role in the Payrails Portal.
  • Existing API credentials (Client ID/Secret) for your service if you also use OAuth. See API credentials
  • A secure place to store private keys and certificates (for example, your secrets manager or key vault).
  • Postman desktop app (for the test flow) or an HTTP client that supports client certificates.

Configuration steps

Request and manage mTLS certificates

Create a client certificate for your service and download it for installation.


  1. In the Payrails Portal, go to Settings → mTLS certificates.

  2. Select Create certificate and provide a description if desired: owner, rotation policy or related service.

  3. Provide organization details to generate the CSR command:

    • Organization name: your legal company name.
    • Country and state/province: if unsure, use your headquarters. These inputs are not binding.

  4. Generate your private key and CSR:

    • The interface displays a pre‑filled OpenSSL command. Copy it and run it in your terminal from the directory where you want the files saved.
    • The command creates two files: a private key and a Certificate Signing Request (CSR).
    • Store the private key securely; you will use it when configuring your client later.
    • Keep the CSR file ready for submission in the next step.

  5. Submit the CSR generated in step 4.

  6. Receiving the certificate:

    • Production: the certificate is issued automatically after submission.
    • Staging: issuance is asynchronous. You will receive an email when the certificate is ready.

  7. When the status is Issued, download the client certificate package.

  8. Install the certificate in your service or keep it ready for local testing (see the Postman section below).

Validate and test

Configure Postman to use mTLS

From certificate details


  1. Open the certificate from the list to view Certificate details.
  2. Select Download <certificate>.pem and save the file.
  3. Select Configure in Postman to open the guided steps.

Step 1 of 3 — Test with cURL (optional)

  • Copy the cURL command shown in the interface and run it in your terminal from the directory where your <merchant>-####.key and <merchant>-####.pem are saved.
  • Replace placeholders with a valid Client ID and Client Secret from your API credentials.
  • On success, the response includes an access token. If it fails, verify the credentials and that both the key and certificate paths are correct.

Step 2 of 3 — Configure in Postman

  1. Open Postman and go to Settings → Certificates, then select Add certificate.
  2. Host: enter the host value shown in the interface for your environment.
  3. CRT file: select the downloaded <merchant>-####.pem certificate from Payrails.
  4. KEY file: select the previously saved <merchant>-####.key private key you generated during the CSR step.
  5. Select Add to save the certificate mapping.

Step 3 of 3 — Test in Postman

  1. Create a POST request to the endpoint indicated in the interface (for example, /token).
  2. Include your API credentials as instructed on screen (for example, client_id in path variables and client_secret in authorization details).
  3. Send the request. A successful TLS handshake and authorization returns an access token.

Confirm usage in the Portal

  1. Return to Settings → Security → mTLS certificates.
  2. Locate the certificate and check Last used or recent activity.
  3. If telemetry is available, confirm successful handshakes or recent calls.

Troubleshooting

  • Certificate not available (Staging): issuance is asynchronous. Wait for the notification email, then download from the list.
  • Handshake failed in Postman:
    • Verify the host and port match the values shown in the interface.
    • Ensure the client certificate is attached to that host entry and imported correctly.
    • If a passphrase was shown at download time, confirm it is entered correctly.
  • 401/403 after handshake: OAuth or API authorization failed. Acquire a valid access token and ensure the calling client has required permissions.
  • Revoked certificate: issuance of a new certificate is required; revoked certificates cannot be re‑enabled.

Updated 20 days ago