# Charges

> Lifecycle of a Fina Pay charge: statuses, expiry, fees, cancellation and refunds.

### Lifecycle

1. Your backend calls `POST /charges`. The charge is `pending` and has a `payment_url`.
2. The customer opens `payment_url`, signs in to Fina and confirms with their wallet PIN.
3. The charge becomes `paid`; you receive `charge.paid` and `GET /charges/{id}` shows `paid_at`, `fee_minor` and `net_minor`.
4. Unpaid charges become `expired` at `expires_at` (24 h by default, `expires_in_seconds` to change it), or `cancelled` if you call `POST /charges/{id}/cancel`.

| Status | Meaning | Webhook |
| --- | --- | --- |
| `pending` | Waiting for the customer | — |
| `paid` | Money is in your Fina Pay wallet | `charge.paid` |
| `expired` | Not paid before `expires_at` | `charge.expired` |
| `cancelled` | You cancelled it while pending | `charge.cancelled` |
| `refunded` | A paid charge was returned to the customer (fully or partly) | `charge.refunded` |

### Fees

The customer always pays exactly `amount_minor`. Fina keeps the collection fee of your plan from what you receive: once paid, `fee_minor` is the fee and `net_minor = amount_minor − fee_minor` is what lands in your wallet. Before payment both are `null`.

### Idempotency

`reference` is unique per connection. Calling `POST /charges` again with the same `reference` returns the existing charge (same `id`, same `payment_url`) instead of charging twice — so you can safely retry on timeouts. Use your order id.

### Refunds

Refunds are issued from Fina (for example when a business rejects an order, cancels a table deposit or a subscription) and return the money — including the proportional fee — to the customer's wallet. There is no public refund endpoint yet; you are notified with `charge.refunded`.

### Get and cancel

**GET /charges/{id} — curl**

```bash
curl https://fina.do/api/wallet/v1/charges/CHARGE_ID \
  -H "Authorization: Bearer $FINA_SECRET_KEY"
```

**GET /charges/{id} — Response**

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "paid",
  "amount_minor": 150000,
  "fee_minor": 3750,
  "net_minor": 146250,
  "currency_code": "DOP",
  "reference": "order-42",
  "transfer_id": "8d2b…",
  "payment_url": "https://fina.do/pay/c/3f9c…",
  "expires_at": "2026-10-06T14:00:00.000Z",
  "paid_at": "2026-10-05T14:03:11.000Z"
}
```

**POST /charges/{id}/cancel — curl**

```bash
curl -X POST https://fina.do/api/wallet/v1/charges/CHARGE_ID/cancel \
  -H "Authorization: Bearer $FINA_SECRET_KEY"
```

Full request and response schemas: [Fina Pay API reference](https://fina.do/developers/api-fina-pay.md).

Source: https://fina.do/developers#charges