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. 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.
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
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;
}
});