Carrinho, checkout e pedidos

Sequência

Totalizadores

Itens, frete, descontos de item/carrinho, descontos de frete, benefícios de pagamento e total geral permanecem identificáveis. A interface pode apresentá-los agrupados, mas o backend não perde a origem do cálculo.

Pedido operacional

O painel permite acompanhar status comercial, financeiro e fulfillment. Eventos formam a timeline; atualizações relevantes preservam ator, visibilidade e payload operacional.

Snapshot de fechamento

O pedido conserva itens, valores, cliente, endereço, opção logística, pagamento e promoções usados na confirmação. Alterações posteriores em catálogo ou campanha não reescrevem o histórico.

Pagamento composto e vale-presente

O checkout aceita um vale-presente como fonte complementar. Exemplo: um pedido de R$ 600 usa R$ 400 de vale e deixa R$ 200 para Pix, boleto ou outro método habilitado. O navegador informa o código apenas durante a confirmação; o backend nunca o grava no OrderForm nem no snapshot do pedido.

• commerce_gift_cards guarda hash do código, referência mascarada, saldo e status;
• commerce_gift_card_reservations reserva saldo por pedido com expiração configurável no painel;
• commerce_gift_card_ledger registra emissão, reserva, captura, liberação, reembolso e ajuste;
• a reserva acontece na mesma transação PostgreSQL da criação do pedido e da reserva de estoque;
• confirmação financeira captura o vale; cancelamento, falha ou expiração devolvem o saldo;
• o painel exibe somente a referência mascarada, como •••• 1234. O código completo aparece uma única vez na emissão.

O gerenciamento está em Plataforma > Vales-presente e o comportamento no checkout em Plataforma > Métodos de pagamento. As permissões gift_cards.manage, gift_cards.adjust, payments.manage e payments.audit.read devem ser concedidas somente a perfis financeiros autorizados.

Preparação para adquirentes, Visa e Mastercard

Cartão não pode ser digitado, processado ou armazenado pela aplicação. Para preservar um escopo compatível com PCI DSS SAQ A, os campos de cartão devem vir diretamente de um provedor PCI DSS compatível por página hospedada ou campos hospedados/tokenizados. A aplicação recebe somente token, referência do provedor, estado e dados mínimos de auditoria.

1. Escolha um PSP/adquirente que ofereça Pix dinâmico, tokenização de cartão e webhooks assinados.
2. Armazene chaves exclusivamente no ambiente de runtime; não use panel_settings, código, logs ou payloads do navegador para segredos.
3. Crie uma tentativa de pagamento idempotente por pedido e envie o token ao adaptador do PSP.
4. Trate authorized, paid, failed, cancelled e refunded como estados distintos.
5. Atualize o status financeiro e capture estoque/vale somente após webhook validado com assinatura e referência do PSP.
6. Use EMV 3-D Secure quando o adquirente indicar desafio ou autenticação adicional.

Referências oficiais: PCI SSC SAQ A, Visa Secure, Mastercard Identity Check, Pix dinâmico Asaas e cobrança Pix Efí.

Validação

• não aceite total enviado pelo navegador como verdade;
• revalide estoque, preço, promoção e frete no fechamento;
• use token público opaco para rastreio;
• proteja leitura administrativa com orders.manage;
• aceite somente métodos habilitados no painel ao recalcular promoções;
• use idempotência, tokenização e webhook assinado antes de integrar um provedor de pagamento real.