Users and money

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.

JavaScript
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 }
FieldMeaning
userThe account to charge
amountUSD₮, up to 6 decimals, written plainly ("4.99", not "4.990")
idYour unique id for this payment, 1–64 characters: letters, digits, _ - : .
memoOptional, 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

HTTPstatusMeaning
201finalDone. Deliver the goods.
200eitherA repeat of an id you used; this is the original result
201failedAccepted, but the block refused it (someone spent the balance a moment earlier); error says why
402The user doesn't have enough USD₮, or your server wallet can't pay the fee
403No active mandate, a limit is reached, the partner is paused, or the wallet isn't on a partner record
401The signature doesn't match your server wallet
400Malformed (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

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