🔐 O que é o certificado mTLS?

O certificado mTLS (Mutual TLS) é um mecanismo de segurança utilizado para garantir autenticação mútua entre cliente e servidor durante a comunicação com a API.

Diferente do HTTPS tradicional, onde apenas o servidor apresenta um certificado para provar sua identidade, no mTLS ambas as partes se autenticam:

• O servidor comprova que é realmente a infraestrutura da Paytime.
• O cliente comprova que está autorizado a consumir a API.

Isso impede acessos não autorizados, reduz riscos de fraude e aumenta significativamente a segurança das integrações financeiras, especialmente em operações sensíveis como PIX, TED e pagamentos.

Durante a conexão:

1. O cliente envia seu certificado digital.
2. O servidor valida se o certificado foi assinado pela autoridade certificadora autorizada pela Paytime.
3. Apenas após essa validação a comunicação é liberada.

📋 Como será implementado

O processo de implementação do certificado mTLS seguirá o fluxo abaixo:

🔹 Etapa 1 — geração da chave privada e CSR

O parceiro deverá gerar localmente:

• Uma chave privada (client.key)
• Uma requisição de assinatura de certificado (client.csr)

A chave privada permanece exclusivamente sob responsabilidade do parceiro e nunca deve ser compartilhada.

Comando:

openssl req -new -newkey rsa:2048 -nodes -keyout client.key -out client.csr -subj "/C=BR/ST=Sao Paulo/L=Sao Paulo/O=Minha Empresa/CN=meu-servico.meudominio.com/UID=token-de-integracao"

Explicação dos parâmetros:

Campos do -subj:

🔹 Etapa 2 — envio da CSR para a Paytime

O arquivo client.csr deverá ser enviado para análise e assinatura.

📧 E-mail: [email protected] com o assunto: Certificado mTLS - API Paytime - CNPJ: [Informe o cnpj]

A CSR funciona como uma solicitação formal para emissão do certificado do cliente.

🔹 Etapa 3 — assinatura do certificado

A Paytime atuará como Autoridade Certificadora (CA) da integração.

Após validação, será retornado:

• sing-cert.crt → certificado assinado pela Paytime

Nesse momento, o parceiro possuirá:

🔹 Etapa 4 — utilização do certificado nas chamadas da API

As requisições para APIs protegidas por mTLS deverão enviar:

• URL para request rotas Payout: https://banking.paytime.com.br
• Certificado do cliente
• Chave privada correspondente

Exemplo:

curl -X POST https://banking.paytime.com.br \
  --cert client.crt \
  --key client.key \
  --header 'integration-key: d0a' \
  --header 'x-token: 4d3c49111' \
  --header 'establishment_id: 155085' \
  --header 'Authorization: Bearer ey' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "document": "11299221000129"
  }'

🔒 Benefícios do mTLS

O uso do mTLS traz vantagens importantes para integrações financeiras:

• Validação forte de identidade do parceiro
• Restrição de acesso apenas a clientes autorizados
• Redução de ataques de interceptação e spoofing
• Comunicação criptografada ponta a ponta
• Camada adicional de segurança além de tokens e autenticação Bearer

⚠️ Pontos importantes

O certificado possui validade de 1 ano

• Necessário para ambiente de produção
• Em caso de comprometimento da chave privada, a revogação deve ser solicitada imediatamente
• O arquivo client.key nunca deve ser enviado para terceiros ou versionado em repositórios Git

🔐 Recomendação de segurança

Restrinja o acesso à chave privada:

chmod 600 client.key

Resumo rápido do fluxo

1. Cliente gera client.key + client.csr
2. Cliente envia client.csr para Paytime
3. Paytime assina o certificado
4. Cliente recebe sing-cert.crt
5. Cliente utiliza sing-cert.crt + client.key nas chamadas HTTPS
6. API valida o certificado antes de permitir acesso