🔐 Onboarding mTLS

Instrucoes para acessar o endpoint api-secure.<ambiente>.lbpay.com.br com autenticacao mutua TLS (mTLS).

Ambientes LBPay: STG, SDB, PROD.

---

O que voce precisa fazer

1. Gerar localmente uma chave privada e um pedido de assinatura (CSR)
2. Enviar apenas o CSR para a LBPay
3. Receber o certificado assinado pela LBPay
4. Configurar seu HTTP client para usar os arquivos nas requisicoes

Importante: sua chave privada nunca deve sair da sua infraestrutura. Envie somente o CSR.

---

Pre-requisitos

• OpenSSL instalado (openssl version)
• Informacoes a passar para a LBPay no momento do onboarding:
  • Identificador do cliente (sera o CN do certificado, ex: acme-bank)
  • IPs publicos de origem que farao as chamadas
  • Email tecnico responsavel pelo certificado

---

Passo 1 — Gerar a chave privada

Em um diretorio seguro:

openssl genrsa -out client.key 4096

Resultado: arquivo client.key (RSA 4096 bits).

Armazene em local seguro (cofre de segredos, Vault, etc.) com acesso restrito. Nao compartilhe com ninguem, nem mesmo com a LBPay.

---

Passo 2 — Gerar o CSR

Substitua <SEU_CLIENT_ID> pelo identificador combinado com a LBPay e <NOME_DA_SUA_EMPRESA> pelo nome da sua organizacao:

openssl req -new -key client.key -out client.csr \
  -subj "/C=BR/O=<NOME_DA_SUA_EMPRESA>/OU=mTLS-<AMBIENTE>/CN=<SEU_CLIENT_ID>" \
  -sha256

Exemplo:

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

Valide o conteudo:

openssl req -in client.csr -noout -subject

Deve retornar exatamente o subject que voce configurou.

---

Passo 3 — Enviar o CSR para a LBPay

Envie apenas o arquivo client.csr pelo canal acordado.

Voce vai receber de volta um arquivo:

• <seu_client_id>.crt — seu certificado assinado, validade de 365 dias

---

Passo 4 — Configurar seu HTTP client

Voce tera 2 arquivos no total:

Arquivo	Origem
client.key	gerado por voce no passo 1
<seu_client_id>.crt	recebido da LBPay

curl

curl --cert <seu_client_id>.crt \
     --key client.key \
     https://api-secure.<ambiente>.lbpay.com.br/<rota>

Python (requests)

import requests

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

---

Validacao

Apos configurar seu client, teste com:

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

Resposta esperada: HTTP 200 com corpo OK.

---

Erros comuns

Erro	Causa provavel
certificate required	Voce esqueceu --cert / --key no client
unknown CA	O certificado de cliente nao foi assinado pela CA da LBPay esperada, ou o par certificado/chave esta errado
403 Forbidden	Seu IP de origem nao esta autorizado. Contate a LBPay
connection refused	Verifique se api-secure.<ambiente>.lbpay.com.br resolve no seu DNS

---

Renovacao e revogacao

• Validade: 365 dias por certificado.
• Renovacao: gere uma nova chave e um novo CSR, depois siga o mesmo processo. Ambos os certificados podem coexistir por alguns dias para evitar downtime.
• Em caso de comprometimento: notifique a LBPay imediatamente para revogacao. O certificado antigo sera revogado e voce devera gerar um novo par.

---

Mudanca de IP

Mudou o IP de origem? Comunique a LBPay com o novo IP. Ele sera adicionado a allowlist sem precisar trocar o certificado.

---

Contato LBPay

Para duvidas ou informacoes adicionais, entre em contato:

• Suporte: faleconosco@lbpay.com.br