Users and money

Mandates

The permission a user signs that lets your server wallet charge them, within limits, until a date - and optionally see their balance.

A mandate is the user's own signed permission, recorded on USD Network, for one of your server wallets to charge their account. The network enforces its limits on every charge; you can't go over them and neither can anyone holding your server key.

What a mandate holds

FieldMeaning
spenderThe server wallet allowed to charge
perTxMost one charge can take
dailyMost all charges can take in one UTC day
totalMost it can ever take; "0" means no lifetime limit
untilWhen it ends (ms since 1970), at most 400 days ahead
readWhether that server wallet may read the account's balance and the payments between them
partnerYour partner id, so the user's wallet shows your name

Rules: perTx ≤ daily, and daily ≤ total when there is a total. An account can hold up to 50 mandates, one per spender; a new one for the same spender replaces the old and starts its counters again.

How users give one

With USD.NET Connect: USDNet.connect({ partner, mandate: { … } }). The user sees, for example:

Wallets and scripts can also sign one directly (POST /mandate, the mandate message).

Check one

JavaScript
const m = await usd.mandate(user);        // null if none, or revoked
// { spender, perTx: "25", daily: "100", total: "500", until, read: true,
//   spent: "4.99", dayUsed: "4.99", leftToday: "95.01", leftTotal: "495.01", charges: 1, active: true }

GET /mandate/:owner/:spender, signed by either side (x-usd-read). Your server wallet's read pass works for every mandate that names it, with or without read.

When it ends

  • The user presses Revoke in Settings → Connected apps: a revoke transaction, final at once. You get mandate.revoked.
  • until passes.
  • You remove the server wallet from your partner record, or pause the record.

After that, charges answer 403 and, if it had read, reads of the account return nothing.

Reading a user's account

With read: true, your server wallet can read:

JavaScript
const u = await usd.user(user);
// { address, grant: true, balance: "95.01", frozen: false, mandate: { … }, transactions: [ only those between them and you ] }

…and their deposit addresses on other chains. It never sees anything else in their account: other payments, other businesses, other balances.

Good practice

  • Ask for what you need. A pack shop with packs at 4.99 asks for maybe 25 per charge and 100 a day, not 10,000.
  • Show users what they've allowed and link to usd.net/wallet/settings to revoke.
  • When a charge fails with 403 because a limit is reached, ask the user to connect again with new limits.