---
agentTools:
  projectIndex: https://docs.ninepay.com.br/llms.txt
  projectSearch: https://docs.ninepay.com.br/agentSearch?query=term1%20term2
---

# Pagamentos - Estorno e Baixa Manual

## Cobrança em aberto

Para criar uma cobrança sem cobrar na hora, e deixar o cliente escolher como pagar no checkout embutido, use `open: true` com `allowed_methods`. O passo a passo está no [guia do checkout embutido](/docs/checkout-embutido).

## Estorno

Estorna um pagamento pago no cartão ou no PIX e devolve o valor ao cliente:

```bash
curl -X POST https://payments.cefis.com.br/api/v1/payment/reversal \
  -H "Authorization: Bearer $NINEPAY_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{ "payment": { "id": 1470491 } }'
```

Só pode ser estornado o pagamento:

- com `status: "paid"`;
- no cartão (`credit`), pago há menos de 350 dias, ou no PIX (`pix`), pago há menos de 90 dias;
- com saldo suficiente na sua conta para a devolução.

Boleto e baixa manual não têm estorno pela API. O campo `can_refund` do pagamento diz se ele pode ser estornado agora.

Quando não pode, a API responde **422** `REFUND_NOT_ALLOWED`, com o motivo em `message` (já estornado, fora do prazo, saldo insuficiente, estorno já pedido...).

### Acompanhando o estorno

O estorno do cartão costuma ser imediato: o pagamento passa a `reversed` e sai o webhook `payment.updated`. O do PIX pode ficar em processamento; consulte o pagamento com os reembolsos:

```bash
curl "https://payments.cefis.com.br/api/v1/payments/1470491?with[]=refunds" \
  -H "Authorization: Bearer $NINEPAY_TOKEN" \
  -H "Accept: application/json"
```

Cada item de `refunds` tem `id`, `method`, `value` (centavos), `status` e as datas. O `status` vai de `new` e `processing` para `completed` (devolvido) ou `failed`. Enquanto um estorno está em `processing`, outro pedido para o mesmo pagamento é recusado.

## Baixa manual

Marca como pago um pagamento que o cliente quitou por fora da NinePay (em dinheiro ou transferência, por exemplo):

```bash
curl -X POST https://payments.cefis.com.br/api/v1/payment/1470491/write-off \
  -H "Authorization: Bearer $NINEPAY_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{ "value_type": "normal" }'
```

- `value_type`: `normal` (o padrão) mantém o valor do pagamento; `zero` dá a baixa com valor 0 (um pagamento perdoado, por exemplo).
- Só vale para pagamentos `unpaid` ou `unauthorized`. Nos outros, a API responde **400** `INVALID_STATE_ERROR`.
- O pagamento passa a `paid` com `method: "manual"`, e sai o webhook `payment.updated`.
- Por ser `manual`, ele não tem estorno pela API.