# Charges

> Take USD₮ from a user who gave you a mandate. Idempotent, final in under a second, no nonce.

A charge moves USD₮ from a user's account to your server wallet, within the user's [mandate](/business/mandates). Your server signs it with the server key. The network checks the mandate, the limits and the balance, and seals it into a block before it answers.

```js
const tx = await usd.charge({ user: '0x7c1e…40ab', amount: '4.99', id: 'pack_1042', memo: 'Booster pack' });
// { hash, type: 'charge', status: 'final', from: user, to: server, amount: '4.99', fee: '0.01', id: 'pack_1042', block, time, idempotent: false }
```

| Field | Meaning |
| --- | --- |
| `user` | The account to charge |
| `amount` | USD₮, up to 6 decimals, written plainly (`"4.99"`, not `"4.990"`) |
| `id` | Your unique id for this payment, 1–64 characters: letters, digits, `_ - : .` |
| `memo` | Optional, up to 140 characters. The user sees it in their Activity. |

The user pays `amount`. Your server wallet receives `amount` and pays the 0.01 USD₮ fee from it, so you net `amount − 0.01`.

## Idempotency

Your `id` makes retries safe. Send the same `id` again (after a timeout, a crash, a double click) and you get back the transaction it already made, with `"idempotent": true` and HTTP `200` instead of `201`. Nothing is charged twice. Ids are remembered for 400 days per server wallet.

A charge that **failed** keeps its id too: retrying it returns the same failure. Use a new id for a new attempt, e.g. `pack_1042_2`.

## Results

| HTTP | `status` | Meaning |
| --- | --- | --- |
| `201` | `final` | Done. Deliver the goods. |
| `200` | either | A repeat of an id you used; this is the original result |
| `201` | `failed` | Accepted, but the block refused it (someone spent the balance a moment earlier); `error` says why |
| `402` | | The user doesn't have enough USD₮, or your server wallet can't pay the fee |
| `403` | | No active mandate, a limit is reached, the partner is paused, or the wallet isn't on a partner record |
| `401` | | The signature doesn't match your server wallet |
| `400` | | Malformed (amount, id, memo) |

Errors carry `{ "error": "…" }` in plain words, e.g. `Over the mandate's daily limit (20.01 USD₮ left today)`.

## Many at once

Charges have no nonce: send as many in parallel as you like, from one or several servers. The limit is 1,200 charges and payouts a minute per IP; ask us if you need more.

## A purchase, end to end

```js
app.post('/api/packs/:sku/buy', async (req, res) => {
  const user = await sessionUser(req);                    // address saved at connect
  const order = await db.orders.create({ user: user.id, sku: req.params.sku, price: '4.99' });
  try {
    const tx = await usd.charge({ user: user.address, amount: order.price, id: `order_${order.id}`, memo: 'Booster pack' });
    if (tx.status !== 'final') return res.status(402).json({ error: tx.error });
    await db.orders.paid(order.id, tx.hash);
    res.json({ cards: await openPack(order) });
  } catch (e) {
    if (e.status === 403) return res.status(403).json({ error: e.message, reconnect: true });  // limits reached or revoked
    if (e.status === 402) return res.status(402).json({ error: 'Top up your USD.NET wallet', topup: true });
    throw e;
  }
});
```
