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

# Payments - Refunds and Manual Settlement

## Open charge

To create a charge without charging right away, and let the customer choose how to pay in the embedded checkout, use `open: true` with `allowed_methods`. The step-by-step is in the [embedded checkout guide](/docs/embedded-checkout).

## Refund

Refunds a payment paid by card or PIX and returns the amount to the customer:

```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 } }'
```

A payment can only be refunded if it is:

- `status: "paid"`;
- paid by card (`credit`) less than 350 days ago, or by PIX (`pix`) less than 90 days ago;
- covered by enough balance in your account for the refund.

Bank slips and manual settlements cannot be refunded through the API. The payment's `can_refund` field tells whether it can be refunded right now.

When it cannot, the API responds with **422** `REFUND_NOT_ALLOWED`, with the reason in `message` (already refunded, past the deadline, insufficient balance, refund already requested...).

### Tracking the refund

Card refunds are usually immediate: the payment becomes `reversed` and the `payment.updated` webhook is sent. PIX refunds may stay in processing; fetch the payment with its refunds:

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

Each item in `refunds` has `id`, `method`, `value` (cents), `status` and the dates. The `status` goes from `new` and `processing` to `completed` (returned) or `failed`. While a refund is `processing`, another request for the same payment is rejected.

## Manual settlement

Marks as paid a payment that the customer settled outside NinePay (in cash or by bank transfer, for example):

```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` (the default) keeps the payment amount; `zero` settles it with an amount of 0 (a waived payment, for example).
- Only valid for `unpaid` or `unauthorized` payments. For others, the API responds with **400** `INVALID_STATE_ERROR`.
- The payment becomes `paid` with `method: "manual"`, and the `payment.updated` webhook is sent.
- Because it is `manual`, it cannot be refunded through the API.