Payouts, refunds and buy-backs
Pay users from your server wallet - refunds, card buy-backs, winnings, cash-outs - idempotent and in parallel.
A payout sends USD₮ from your server wallet to any USD.NET account. It works like a transfer, with two differences built for servers: no nonce, so you can send thousands at once, and an id, so the same payout is never sent twice. The user needs no mandate to receive.
const tx = await usd.payout({ user: '0x7c1e…40ab', amount: '12.5', id: 'buyback_card_88', memo: 'Charizard EX' });
// { type: 'payout', status: 'final', amount: '12.5', fee: '0.01', id: 'buyback_card_88', … }Your server wallet pays amount + 0.01. The user receives amount, final in under a second, and sees Received · from an app with your memo.
Refunds
There's no separate refund call: a refund is a payout with an id that points at the charge.
await usd.payout({ user, amount: order.price, id: `refund_${order.id}`, memo: `Refund for order ${order.id}` });Using refund_<order> as the id means an order can only ever be refunded once, whatever your retry logic does.
Buying cards back
app.post('/api/cards/:id/sell', async (req, res) => {
const user = await sessionUser(req);
const card = await db.cards.lockForSale(req.params.id, user.id); // removes it from the user's collection
const price = await priceOf(card); // e.g. "12.5"
const tx = await usd.payout({ user: user.address, amount: price, id: `buyback_${card.id}`, memo: card.name });
if (tx.status !== 'final') { await db.cards.unlock(card.id); return res.status(409).json({ error: tx.error }); }
res.json({ paid: price, hash: tx.hash });
});Winnings and cash-outs in bulk
const results = await Promise.all(winners.map((w) => usd.payout({ user: w.address, amount: w.prize, id: `prize_${round}_${w.id}` })));Results
Same as charges: 201 final, 200 for a repeat id, 201 failed with an error, 402 when the server wallet can't cover amount + 0.01, 403 for a frozen address.
Transfers
For anything that isn't a user payment, use a plain transfer: sweeping to your business wallet, or withdrawing to another chain through the USD Bridge (memo: "out:<chain>:<address>"). The SDK's usd.transfer({ to, amount, memo }) handles the nonce and sends them one at a time.