Segurança de transações

O Minstrel aplica limites por conta e por chave, com contadores compartilhados entre as instâncias da API. Novas cobranças e validações de cartão têm orçamentos próprios. A matriz pagadora não aumenta o limite de uma franquia.

Limites e retentativa

A equipe Minstrel ajusta os limites conforme o volume contratado e o perfil da operação. Consulte a configuração em Configurações → Segurança. O limite específico de uma chave pode ser menor que o da conta; ambos valem.

Os padrões iniciais são:

Uma rajada permite consumir parte do orçamento de uma vez. Ele se recompõe gradualmente; o limite por minuto não libera outra rajada inteira na virada do relógio. Fallbacks e automações também respeitam a proteção da adquirente. Há ainda limites globais da instalação e por IP de transporte.

Quando um limite é atingido, a API devolve 429 e Retry-After, em segundos. Os limites gerais também aparecem em RateLimit-Limit e RateLimit-Remaining. Espere o prazo, acrescente uma pequena variação aleatória e repita o mesmo pedido com a mesma Idempotency-Key. Não abra várias tentativas paralelas. Uma resposta idempotente já concluída não consome outra cobrança ou sinal de risco, embora a requisição continue sujeita ao limite geral da API.

Se o serviço de proteção estiver indisponível, novas chamadas podem receber 503. Reutilize a mesma chave ao retentar. Consultar uma cobrança existente é a forma de confirmar o resultado depois de um timeout.

Identificação da transação e do dispositivo

Toda nova cobrança recebe security.transactionFingerprint, uma referência pseudonimizada estável dessa transação. Ela também aparece no detalhe do pagamento no painel e nos eventos que representam o pagamento.

Para correlacionar tentativas do checkout, envie deviceId, um identificador opaco de 16 a 128 caracteres (A-Z, a-z, números, _ ou -). Ele deve representar a sessão ou o dispositivo do seu checkout, sem conter nome, e-mail, CPF, dados de cartão ou segredo de autenticação.

Exemplo no navegador, gerando uma referência apenas para essa sessão:

let deviceId = sessionStorage.getItem('checkout-device-id');
if (!deviceId) {
  deviceId = crypto.randomUUID();
  sessionStorage.setItem('checkout-device-id', deviceId);
}
// Envie o deviceId ao SEU backend junto do pedido.
// A chave secreta Minstrel permanece no servidor.

No seu backend:

{
  "amount": 14990,
  "currency": "BRL",
  "customerId": "cus_01HQ8M5X7P2K3N4R5T6V7W8X9Y",
  "paymentMethodId": "pm_01HQ8M5X7P2K3N4R5T6V7W8X9Y",
  "deviceId": "9d82509d-bfd5-453e-a18c-e1b48b05745c",
  "clientIp": "198.51.100.10"
}

O Minstrel guarda HMACs específicos da conta para correlacionar os sinais. O identificador de cartão usa o fingerprint do conector quando disponível; caso contrário, usa uma referência derivada do token e da conta do conector. Dois tokens diferentes podem representar o mesmo cartão físico: não são uma prova de cartões distintos. Nunca envie PAN ou CVV para gerar um fingerprint.

deviceId e clientIp são sinais declarados pelo checkout, sujeitos a alteração. Eles não comprovam identidade. O IP de transporte é observado separadamente; headers encaminhados só são considerados quando o operador configura um proxy confiável. O SDK não coleta canvas, fontes ou identificadores entre sites.

Monitoramento de padrões suspeitos

A análise combina respostas de negócio da adquirente, quantidade de identificadores de cartão, recorrência de recusas e valores baixos. Falhas técnicas e desafios ainda pendentes não contam como cartões recusados. Por padrão, são analisados até cinco minutos, mantendo no máximo as duas mil respostas mais recentes por sinal; dez respostas com pelo menos 80% de recusas e cinco referências distintas geram suspeita de teste de cartões. Cinco recusas repetidas do mesmo cartão também podem gerar bloqueio temporário.

Bloqueios automáticos atingem o sinal envolvido, como cliente ou referência de cartão, por até 15 minutos no padrão inicial. IP e dispositivo declarados complementam esses controles. Um alerta agregado da conta não bloqueia todos os clientes. A equipe Minstrel pode pausar novas cobranças e Zero Auth de uma conta durante investigação; consultas, capturas e estornos continuam disponíveis.

Não altere a retentativa de uma recusa irreversível para contornar um bloqueio. As regras ABECS continuam valendo.

Relatórios e investigação

Os relatórios aparecem em Configurações → Segurança para proprietários e administradores da conta e na aba Segurança da administração Minstrel. O sino no cabeçalho indica relatórios abertos. Sandbox e produção são identificados e consultados separadamente.

Avisos do mesmo padrão são consolidados por conta e ambiente a cada 15 minutos, evitando um e-mail para cada sinal durante um ataque. Os detalhes continuam disponíveis no painel.

O envio de e-mail usa uma fila persistida, com retentativas e destinatários individuais. Administradores da conta e da plataforma recebem o aviso; a permissão é conferida novamente antes do envio. A tela mostra quantos e-mails foram enviados, estão pendentes ou falharam. Sem transporte de e-mail configurado, o alerta permanece no painel e a entrega aguarda configuração.

Reconheça o relatório para marcar a investigação, ou resolva com um motivo. Resolver não remove um bloqueio vigente: use a ação explícita de desbloqueio depois de conferir o checkout e o comportamento esperado. Todas essas ações entram na auditoria. A suspeita indica uma anomalia e não confirma fraude.