Skip to main content

🔐 mTLS Onboarding

Instructions for accessing the api-secure.<environment>.lbpay.com.br endpoint with mutual TLS authentication (mTLS).

LBPay environments: STG, SDB, PROD.

What you need to do​

  1. Generate a private key and a certificate signing request (CSR) locally
  2. Send only the CSR to LBPay
  3. Receive your signed certificate from LBPay
  4. Configure your HTTP client to use the files in requests

Important: your private key must never leave your infrastructure. Send only the CSR.

Prerequisites​

  • OpenSSL installed (openssl version)
  • Information to provide to LBPay during onboarding:
    • Client identifier (this will be the certificate CN, for example acme-bank)
    • Public source IPs that will make the requests
    • Technical contact email responsible for the certificate

Step 1 — Generate the private key​

In a secure directory:

openssl genrsa -out client.key 4096

Result: client.key file (4096-bit RSA).

Store it securely (secrets manager, Vault, etc.) with restricted access. Do not share it with anyone, not even LBPay.

Step 2 — Generate the CSR​

Replace <YOUR_CLIENT_ID> with the identifier agreed with LBPay and <YOUR_COMPANY_NAME> with your organization name:

openssl req -new -key client.key -out client.csr \
  -subj "/C=BR/O=<YOUR_COMPANY_NAME>/OU=mTLS-<ENVIRONMENT>/CN=<YOUR_CLIENT_ID>" \
  -sha256

Example:

openssl req -new -key client.key -out client.csr \
  -subj "/C=BR/O=Acme Bank/OU=mTLS-SDB/CN=acme-bank" \
  -sha256

Validate the content:

openssl req -in client.csr -noout -subject

It must return exactly the subject you configured.

Step 3 — Send the CSR to LBPay​

Send only the client.csr file through the agreed channel.

You will receive one file back:

  • <your_client_id>.crt — your signed certificate, valid for 365 days

Step 4 — Configure your HTTP client​

You will have 2 files in total:

FileSource
client.keygenerated by you in step 1
<your_client_id>.crtreceived from LBPay

curl

curl --cert <your_client_id>.crt \
     --key client.key \
     https://api-secure.<environment>.lbpay.com.br/<route>

Python (requests)

import requests

resp = requests.get(
    "https://api-secure.<environment>.lbpay.com.br/<route>",
    cert=("<your_client_id>.crt", "client.key")
)

Validation​

After configuring your client, test with:

curl --cert <your_client_id>.crt --key client.key \
  https://api-secure.<environment>.lbpay.com.br/

Expected response: HTTP 200 with body OK.

Common errors​

ErrorLikely cause
certificate requiredYou forgot --cert / --key in the client
unknown CAThe client certificate was not signed by the expected LBPay CA, or the wrong certificate/key pair is being used
403 ForbiddenYour source IP is not authorized. Contact LBPay
connection refusedCheck whether api-secure.<environment>.lbpay.com.br resolves in your DNS

Renewal and revocation​

  • Validity: 365 days per certificate.
  • Renewal: generate a new key and a new CSR, then follow the same process. Both certificates may coexist for a few days to avoid downtime.
  • In case of compromise: notify LBPay immediately for revocation. The old certificate will be revoked and you must generate a new pair.

IP change​

Changed your source IP? Inform LBPay of the new IP. It will be added to the allowlist without requiring a certificate change.

LBPay contact​

For questions or additional information, contact:

  • Support: faleconosco@lbpay.com.br