Estorno de Pedidos: Total, Parcial e Regras de Negócio

Este artigo detalha como realizar o estorno de valores de um pedido via API e as regras de comportamento do sistema para diferentes cenários de pagamento.

Endpoint: POST/pedidos/estorno/pedidoId

1.Cenários Suportados via API

A. Pagamento Único via Gateway

O estorno automatizado via API funciona integralmente para pedidos realizados com apenas uma forma de pagamento externa.

• Estorno Total: Valor enviado no JSON = 100% do valor do pedido.
• Estorno Parcial: Valor enviado no JSON < valor total do pedido.

📘

Conectores Compatíveis: Wake Gateway, Adyen, Pagar.me 2.0, Pagamento Customizado, Maxipago By Rede, Cielo, Braintree, Pagbank, KOIN, Pagaleve, Paypal BCDC e Mercado Pago.

B. Pedidos com Saldo de Conta Corrente (Crédito Interno)

O Saldo de Conta Corrente é tratado como um crédito da loja e é compatível com a API pública, mesmo quando combinado com um Gateway. Se a configuração “Devolver saldo de conta corrente em estornos de pedidos” estiver ativa, o sistema segue esta ordem de prioridade:

• Prioridade 1: O valor é devolvido primeiro para o saldo de conta corrente do cliente na loja.
• Prioridade 2: Caso o valor a ser estornado seja maior que o saldo utilizado, o restante é estornado via Gateway (Cartão/PIX).

Exemplo Prático:

• Pedido: R$ 300,00 (R$ 100,00 Saldo Interno + R$ 200,00 Cartão)
• Ação: Solicitação de estorno de R$ 250,00 via API.
• Resultado: R$ 100,00 retornam para a conta corrente e R$ 150,00 são estornados no cartão.

C. Pedidos com Saldo de Carteira de crédito

O Saldo de Carteira de Crédito é tratado como um crédito da loja e é totalmente compatível com a API pública de estorno, inclusive em cenários de pagamento combinado com Gateway (ex.: Pix, cartão de crédito).

Isso significa que pedidos pagos parcialmente com carteira de crédito podem ser estornados de forma total ou parcial por método de pagamento, diretamente via API.

Caso de uso:

Um cliente realiza um pedido de R$ 200,00 utilizando dois métodos de pagamento:

R$ 100,00 via Carteira de Crédito R$ 100,00 via Pix Nesse cenário, são possíveis as seguintes operações de estorno via API:

D. Múltiplas formas de pagamento via gateway

Pedidos híbridos (ex: Cartão + Pix, dois cartões) agora suportam estorno via API — total ou parcial. O sistema identifica cada transação individualmente e dispara o reembolso para a adquirente referenciando apenas o ID da transação específica, sem cancelar as demais.

Cenário: Cliente realizou um pedido de R$ 300,00 pagando R$ 150,00 via Pix e R$ 150,00 via Cartão. A loja precisa cancelar o pedido inteiro.

Como fazer: Enviar a requisição de estorno sem o campo formaPagamento (ou com null). O Gateway identifica as duas transações automaticamente e dispara o reembolso para cada adquirente.

Resultado: R$ 150,00 estornados no Pix + R$ 150,00 estornados no Cartão.

Pedidos com split e duas formas de pagamento também são suportados.

Regras de uso do campo formaPagamento:

• Estorno de uma forma de pagamento específica: informe o campo formaPagamento com a forma desejada. O Gateway processará o reembolso apenas da transação correspondente.

• Estorno total do pedido (todas as formas de pagamento): omita o campo formaPagamento ou envie-o como null. O Gateway irá interpretar automaticamente como estorno total, varrer todas as transações vinculadas ao pedido e processar o reembolso de cada uma.

⚠️ Para estornos parciais em pedidos híbridos, o campo formaPagamento é obrigatório. Sem ele, o Gateway assumirá que a intenção é estornar o pedido completo.

2.Estorno Automático em Falhas de Checkout

O sistema possui regras nativas para devolução de valores em transações que não foram concluídas com sucesso (antes do faturamento):

3.Estrutura da Requisição

Request Body

{
  "contaCorrente": {
    "referencia": "string"
  },
  "valor": 0
}

Parâmetros

• valor (Obrigatório): Valor decimal (ex: 100.00). Deve ser igual ou menor que o saldo disponível para estorno no pedido.
• contaCorrente.referencia (Opcional): Texto alfanumérico para identificação na conciliação financeira quando há saldo interno envolvido.

Importante: Após ativar configurações de saldo de conta corrente, aguarde até 10 minutos para a atualização do cache antes de processar novos estornos.