Estornar um Pagamento

A API Cloud suporta a devolução de fundos a um cliente por meio de duas operações distintas. A escolha do método correto depende se o cliente está fisicamente presente com o cartão ou se você está processando um estorno administrativo remoto.

Método 1: Estorno Referenciado (Sem Necessidade de Cartão)

Este é o método mais comum para devoluções administrativas. Ele permite estornar uma transação de forma programática usando o Order ID original (pedidoBase), sem exigir que o cliente insira o cartão no terminal.

• Endpoint: /devolucion
• Método: POST
• Caso de Uso: Estornos de back-office, devoluções de e-commerce ou correção de erros após a saída do cliente.

Passo 1: Enviar a Requisição de Estorno

Você deve fornecer o pedidoBase (o Order ID exclusivo gerado pela API durante a venda original) e o valor a ser estornado.

{
  "info": {
    "comercio": "777888991",
    "terminal": 1,
    "timestamp": "20250428 140000",
    "datosOperacion": {
      "importe": "5.00",
      "factura": "REFUND-001",
      "pedidoBase": "916548"
    }
  },
  "signature": "YOUR_CALCULATED_SIGNATURE"
}

Estornos Parciais: Você pode estornar um valor menor que o da transação original (Estorno Parcial). No entanto, não é possível estornar um valor superior ao original.

Passo 2: Receber a Resposta

Como não há necessidade de interação física, essa operação geralmente é concluída de forma síncrona, retornando o resultado diretamente no payload da resposta, em caso de sucesso.

Exemplo de Resposta de Sucesso:

{
  "info": {
    "resultado": { "codigo": "0" },
    "resultadoDevolucion": {
      "importe": "5.00",
      "resultado": "Autorizada",
      "estado": "F",
      "pedidoBase": "916548"
    }
  },
  "signature": "SERVER_SIGNATURE"
}

Método 2: Estorno com Cartão Presente

Se a política do seu negócio exigir que o cliente esteja presente para verificar o cartão, use o método de Cartão Presente. Esse fluxo aciona o terminal para solicitar a inserção do cartão.

• Endpoint: /devolucionTarjeta
• Método: POST
• Caso de Uso: Devoluções em loja onde a verificação do cartão é obrigatória.

Passo 1: Enviar a Requisição

O payload é quase idêntico ao do estorno referenciado, mas você deve incluir uma URL de notificação porque o processo se torna assíncrono (aguardando o terminal).

{
  "info": {
    "comercio": "777888991",
    "terminal": 1,
    "timestamp": "20250428 143000",
    "notificacion": {
      "urlNotificacion": "https://your-server.com/api/webhooks/refunds"
    },
    "datosOperacion": {
      "importe": "5.00",
      "factura": "REFUND-STORE-002",
      "pedidoBase": "916548"
    }
  },
  "signature": "YOUR_CALCULATED_SIGNATURE"
}

Passo 2: Tratar a Notificação

A API enviará uma requisição POST para a sua urlNotificacion assim que o cartão for lido e o banco autorizar a devolução.

Requisitos do Recibo

Os recibos de estorno possuem um requisito específico de conformidade que difere dos recibos de vendas.

Assinatura do Estabelecimento Obrigatória: Para recibos de estorno fornecidos ao cliente, você deve imprimir um campo para assinatura. Diferente de uma venda onde o cliente assina, o estabelecimento deve assinar ou carimbar o recibo de estorno para reconhecer a devolução dos fundos ao cliente.

Solução de Problemas

Próximos Passos

• Consultar Histórico de Transações: Verifique o estado do pedido original para obter o pedidoBase correto antes de realizar o estorno.
• Especificações de Impressão de Recibos: Veja o layout específico para os comprovantes de estorno.