Programação Por Equipe DevBras

Capa do artigo: SDK de pagamento: o que gravar no pedido e no log

SDK de pagamento: o que gravar no pedido e no log

Depois de integrar o SDK de pagamento, guarde só id da transação, status e últimos dígitos. Testamos o filtro de log que deixa passar cartão com espaço.

Integrar o SDK de pagamento resolve a chamada ao provedor, mas não decide o que o seu sistema guarda em volta dela. O pedido, o log de erro, a fila e o banco de homologação recebem dados a cada cobrança, e é ali que o número do cartão costuma aparecer sem ninguém ter decidido gravar. Este texto trata desse entorno, já com o cartão capturado pelo provedor. A captura em si, com tokenização no navegador, está em pagamento sem o cartão passar pelo servidor, e o caso específico do Mercado Pago em checkout transparente sem guardar o cartão.

A regra que orienta tudo vem do PCI DSS. Número de cartão gravado em qualquer lugar puxa o banco, o log e o backup para o escopo do padrão. O código de segurança é mais grave: o PCI Security Standards Council o classifica como dado sensível de autenticação, que não pode ser guardado depois da autorização, nem mesmo criptografado. Testamos também o filtro de log mais comum nesse tipo de integração e ele deixa passar cartão escrito com espaço.

O que a tabela de pagamentos precisa ter

Para atender o suporte, estornar e conciliar o financeiro, a loja precisa do identificador da transação no provedor, da referência própria enviada a ele, do status e da data vindos do provedor, do valor em centavos, da bandeira e dos quatro últimos dígitos, se o provedor devolver, e do ambiente. Em MySQL:

CREATE TABLE pagamentos (
  id              BIGINT AUTO_INCREMENT PRIMARY KEY,
  pedido_id       BIGINT NOT NULL,
  ambiente        ENUM('sandbox','producao') NOT NULL,
  provedor_tx_id  VARCHAR(64) NOT NULL,
  status          VARCHAR(32) NOT NULL,
  valor_centavos  INT NOT NULL,
  moeda           CHAR(3) NOT NULL DEFAULT 'BRL',
  bandeira        VARCHAR(20) NULL,
  ultimos4        CHAR(4) NULL,
  atualizado_em   DATETIME NOT NULL,
  UNIQUE KEY uk_tx (ambiente, provedor_tx_id)
);

Não há coluna de número, validade ou código. A chave única por ambiente e transação impede que o mesmo aviso do provedor crie duas linhas. "Refazer a cobrança" se resolve com o recurso do provedor, como cartão salvo no cofre dele, assinatura ou novo link de pagamento, e não com um número guardado do seu lado.

Para conferir um banco que já existe, a busca por nome de coluna acha os casos óbvios:

SELECT table_name, column_name
FROM information_schema.columns
WHERE table_schema = DATABASE()
  AND (column_name LIKE '%cart%' OR column_name LIKE '%card%'
       OR column_name LIKE '%cvv%' OR column_name LIKE '%cvc%'
       OR column_name LIKE '%valid%' OR column_name LIKE '%venc%');

O resultado traz falsos positivos, como validade_cupom, e é para ser lido com calma. Coluna com nome genérico, como dados ou payload_json, não aparece nessa busca e precisa da varredura de conteúdo da seção sobre log.

O payload montado campo a campo

O caminho mais comum para o cartão chegar ao banco é a atribuição em massa: o pedido recebe $request->all(), e qualquer campo do formulário com nome igual ao de uma coluna é gravado. A OWASP recomenda lista explícita dos campos aceitos. Com o SDK vale o mesmo:

<?php
// nunca $request->all() nem $_POST inteiro
$payload = [
    'referencia' => (string) $pedido->id,
    'valor'      => $pedido->valor_centavos,
    'token'      => $_POST['token_do_provedor'],   // gerado pelo script do provedor
    'comprador'  => ['nome' => $cliente->nome, 'email' => $cliente->email],
];

Da resposta do provedor, grave só o que a tabela tem. Guardar o JSON cru "para depurar depois" leva junto tudo o que o provedor devolver, inclusive campos que ele venha a acrescentar numa versão futura.

Log: o filtro que deixa passar cartão com espaço

O guia de logging da OWASP põe dados de cartão na lista do que não deve ir para o log sem ser removido ou mascarado. O filtro que se costuma usar troca qualquer sequência de 13 a 19 dígitos por um marcador, com o padrão \b\d{13,19}\b. Testamos esse padrão contra amostras de log, ao lado de uma versão que aceita espaço e hífen entre os dígitos e só mascara o que passa no dígito verificador de Luhn, usado nos números de cartão:

amostra                  filtro antigo                            filtro novo
só dígitos               cartao=[digitos-mascarados]              cartao=[cartao-mascarado]
com espaços              cartao=4111 1111 1111 1111               cartao=[cartao-mascarado]
com hífens               cartao=4111-1111-1111-1111               cartao=[cartao-mascarado]
Amex com espaços         cartao=3782 822463 10005                 cartao=[cartao-mascarado]
id de transação (16)     tx=[digitos-mascarados]                  tx=2026110500001234
código de barras (44)    boleto=23793381286000782713695000063305975520000370000 boleto=23793381286000782713695000063305975520000370000
CPF                      cpf=123.456.789-09                       cpf=123.456.789-09

O filtro antigo deixa passar o cartão digitado no formato impresso, com espaços ou hífens, que é exatamente como ele chega de campo de formulário ou de mensagem de suporte. E mascara o identificador de transação de 16 dígitos, que é o dado de que o suporte precisa. A versão com Luhn acerta os dois casos e não mexe em CPF nem em linha de boleto. Em PHP, com preg_replace_callback:

<?php
function luhnValido(string $d): bool
{
    $soma = 0;
    foreach (array_reverse(str_split($d)) as $i => $c) {
        $n = (int) $c;
        if ($i % 2) { $n = $n * 2 > 9 ? $n * 2 - 9 : $n * 2; }
        $soma += $n;
    }
    return $soma % 10 === 0;
}

function mascararCartao(string $texto): string
{
    return preg_replace_callback('/\b(?:\d[ -]?){12,18}\d\b/', function ($m) {
        $d = preg_replace('/\D/', '', $m[0]);
        $tam = strlen($d);
        return ($tam >= 13 && $tam <= 19 && luhnValido($d)) ? '[cartao-mascarado]' : $m[0];
    }, $texto);
}

O teste rodou em Python com os mesmos padrões, que são compatíveis com o PCRE do PHP. Um identificador numérico qualquer passa no Luhn em cerca de 1 a cada 10 casos, então um ou outro id de transação ainda pode ser mascarado. É o erro aceitável para esse filtro. A mesma função serve para varrer os logs antigos: rode sobre os arquivos do último mês e conte quantas trocas ela faria antes de pôr no ar. Remoção por nome de chave, para senha, token e documento, está em log sem senha.

O filtro é rede de segurança. Se ele achar um cartão, a correção é no fluxo que deixou o número chegar ao servidor, e depois na limpeza de log, fila e backup que já o receberam.

Sandbox e produção separados de verdade

Usar o mesmo banco para os dois ambientes, trocando só a chave na configuração, faz pedido de teste aprovado aparecer como venda no relatório. O risco inverso é pior: a chave de produção num servidor de homologação cobra cartão real de quem estava testando. Credenciais em variáveis separadas e falha explícita quando o ambiente não está definido:

<?php
$ambiente = getenv('PAGAMENTO_AMBIENTE');          // 'sandbox' ou 'producao'
if (!in_array($ambiente, ['sandbox', 'producao'], true)) {
    throw new RuntimeException('PAGAMENTO_AMBIENTE invalido');
}
$credencial = getenv($ambiente === 'producao'
    ? 'PAGAMENTO_TOKEN_PRODUCAO'
    : 'PAGAMENTO_TOKEN_SANDBOX');

A coluna ambiente fecha a separação: o fechamento do mês filtra ambiente = 'producao'.

O status vem do provedor

A página de "pagamento aprovado" é só o navegador voltando para o seu site, e quem manipula a URL de retorno consegue chegar nela sem pagar. O status que muda o pedido é o da notificação do provedor, conferida pela assinatura ou por uma consulta à API dele com o identificador da transação. A rota de notificação recebe o mesmo aviso mais de uma vez e precisa ignorar a repetição; a validação da assinatura está em webhook com segredo.

Os requisitos detalhados estão no PCI DSS e no contrato com o seu provedor. Este texto não substitui a avaliação de quem cuida de conformidade.

Avalie este artigo

Referência: https://github.com/pagseguro/pagseguro-php-sdk