# Charges

A charge is an authorized checkout that you capture. Capture moves money, posts fees and cashback, and is idempotent.

## Capture

```bash
curl -s -X POST https://api.fluense.social/charges/$AUTH/capture \
  -H "x-api-key: $KEY"
```

```json
{
  "journal_id": "019a…",
  "mdr_fee": 154,
  "buyer_amount": 0,
  "deferred_buyer_amount": 225,
  "recommender_amount": 75,
  "recommender_id": "019a…",
  "recommenders": [ { "user_id": "019a…", "amount": 75 } ]
}
```

| Field | Meaning |
| --- | --- |
| `mdr_fee` | Merchant discount rate: `(total - tax - cashback) x mdr_bps / 10000`. Default 200 bps (2%), overridable per merchant |
| `recommender_amount` | Cashback earned by the recommender at capture (0 when the purchase did not come from a recommendation) |
| `buyer_amount` | Always 0 at capture — the buyer's share is deferred |
| `deferred_buyer_amount` | The buyer's cashback share, earned when they recommend the product they bought |

Capture is **idempotent on the charge id**: retrying returns the same transaction reference and cashback, and never charges twice. Capture works with an API key or the owning consumer session; live capture requires an approved KYB for the org.

When a line's product matches an active buy-list entry, the recommender earns their share automatically. See [Cashback](/cashback).

## Void

`POST /charges/{id}/void` cancels an `AUTHORIZED` charge and releases the hold. Only `AUTHORIZED` charges can be voided.

```json
{ "ok": true }
```

## Return (refund)

`POST /charges/{id}/return` refunds a captured charge. Omit `items` for a full refund, or pass quantities for a partial one.

```bash
curl -s -X POST https://api.fluense.social/charges/$AUTH/return \
  -H "x-api-key: $KEY" \
  -H 'content-type: application/json' \
  -d '{"reason":"damaged on arrival","items":[{"product_id":"sku-1","qty":1}]}'
```

```json
{
  "return_id": "019a…",
  "refund": 9700,
  "buyer_cut": 225,
  "rec_cut": 75,
  "award_adjusted": true
}
```

| Field | Meaning |
| --- | --- |
| `refund` | Principal returned: goods + pro-rata shipping and tax |
| `buyer_cut` / `rec_cut` | Cashback shares removed from the return |
| `award_adjusted` | True when this return reduced or voided pending cashback |

Rules:

- Refund quantity is validated against captured quantity minus previous returns — over-returning is a `400`.
- Pending cashback shrinks with the return; cashback that has already landed is never clawed back.
- Returns are not idempotent: retry only if the previous attempt produced no response.