Formas de pagamento

Uma forma de pagamento é uma opção que o cliente vê no checkout: PIX, boleto, cartão de crédito, pagamento na entrega, boleto faturado. Cada uma tem um tipo (como o dinheiro é cobrado), um gateway (o serviço que processa o pagamento, como Pagar.me, Braspag ou Getnet) e regras que decidem quando ela aparece: valor mínimo e máximo do pedido, grupos de clientes, estados, formas de envio e dependências.

Como funciona

1. Consulte os gateways e tipos disponíveis.
2. Crie a forma com nome, slug, provider (o tipo) e gateway.
3. Opcionalmente restrinja por valor, grupo de clientes, estado e envio, e configure dependências.
4. No checkout, a plataforma lista só as formas cujas regras o carrinho atende.

Tipos e processadores

Boleto faturado

Quando processor_type é invoiced, o campo config.installment_plans define os planos de prazo (por exemplo 30/60/90). Cada plano tem name, installments e terms_days (um prazo em dias por parcela, crescente). Um plano inconsistente volta 400 invalid_installment_plan.

Dependências

Uma dependência liga a forma a uma condição do carrinho, require (só aparece se for verdade) ou exclude (some se for verdade), sobre forma de envio, grupo de usuários, número mínimo de itens ou país.

Endpoints

Erros comuns

• Tentar trocar provider, slug ou vendor_id com PUT. Volta 400 immutable_field (antes o campo era descartado em silêncio).
• Mandar is_active e status contraditórios. O PUT aceita is_active, active e enabled como apelidos de status; se discordarem entre si, volta 400 invalid_payment_method_status.
• Mínimo maior que o máximo. min_order_amount acima de max_order_amount volta 400 min_exceeds_max.
• Gateway que a loja não pode usar. O gateway custom só existe em loja com customização que o declare: volta 422 gateway_not_available.
• Esperar que a lista traga só o que o cliente vê. A lista de admin traz todas, ativas e inativas, de todos os donos.
• Ler payment_id, payment, template. São apelidos que repetem outros valores e acompanham cada forma; use id, name e code.

Próximos passos