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.
Referência: https://github.com/pagseguro/pagseguro-php-sdk