Pagamentos

Esta área reúne o lado financeiro do pagamento de um pedido: o registro de cada cobrança nos gateways, o estorno quando é preciso devolver o dinheiro, a divisão do valor entre sellers, o custo do gateway, a configuração do PIX e as disputas abertas pelos clientes.

São as rotas do administrador da loja. O cliente paga pelo checkout da loja; o dinheiro dos sellers sai pelos repasses.

Como funciona

O caminho de um pagamento

Divisão entre sellers

Um pedido com itens de sellers diferentes gera uma divisão: uma fatia por seller e uma da loja, com a comissão descontada. A divisão é o registro do que cada um tem a receber daquele pagamento.

Disputas

O cliente contesta um pedido; o seller responde; sem acordo, o operador decide. Uma decisão com reembolso gera o estorno ao cliente e cobra o seller.

Conceitos-chave

Gateway

É a empresa que processa o pagamento (Pagar.me, Getnet e outras). Cada forma de pagamento da loja aponta para um gateway. O estorno é pedido a esse gateway.

Transação de pagamento

Uma tentativa de cobrança ou um estorno. Um pedido pode ter várias (tentativas que falharam, a que deu certo, estornos parciais).

Estorno parcial

A soma de todos os estornos de um pedido nunca passa do valor da cobrança. Ao cobrir o saldo, a cobrança original vira R.

Endpoints

Erros comuns

• Usar o id do pedido no estorno. A rota recebe o id da transação de pagamento.
• Repetir um estorno depois de uma resposta perdida. Não há idempotência; confira a lista antes.
• Filtrar transações por status=paid. Vira A e deixa de fora as concluídas (C). Use a letra.
• Ler os contadores por estado de payment-splits/stats. Voltam 0; use o total da lista filtrada.
• Enviar [] em PUT /payment-fees. Apaga todas as taxas.
• Ligar o PIX sem segredo de webhook. Nenhum pagamento é confirmado e os pedidos expiram.
• Tentar recusar uma disputa fora de escalated. A recusa só vale na mediação do operador.
• Esperar 404 em UUID inexistente ou malformado. Várias rotas respondem 500 ou 400; leia o detail.

Próximos passos