# 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.

```json
{
  "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:**

```json
{
  "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).

```json
{
  "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

| Código de Erro | Significado | Solução |
| :---- | :---- | :---- |
| **TPVPC0009** | O valor do estorno excede o original. | Verifique se o `importe` é menor ou igual ao saldo restante da transação original. |
| **TPVPC0100** | Operação não permitida. | Não é possível realizar um estorno no `pedidoBase` especificado (ex.: não existe ou é muito antigo). |
| **TPVPC0094** | Estado da operação inválido. | A transação original pode não estar em um estado finalizado (`F`). |

## Próximos Passos

* [**Consultar Histórico de Transações**](/pt/get-smart/get-smart-api-cloud/integration-guides/query-transaction-history)**:** Verifique o estado do pedido original para obter o `pedidoBase` correto antes de realizar o estorno.  
* [**Especificações de Impressão de Recibos**](/pt/get-smart/get-smart-api-cloud/reference/receipt-printing-specifications)**:** Veja o layout específico para os comprovantes de estorno.