Earnings and payouts

#How a sale settles

1. A buyer's call succeeds, and they get a signed receipt straight away.
2. Moments later, settlement credits your settlement wallet with the price less the platform fee, rounded down to the micro-dollar. At 5% a $1.00 sale adds "950000" ($0.95) and a $0.001 sale adds "950".
3. A failed call earns nothing: the buyer was refunded.
4. If Zanora reverses a successful call (a buyer complaint, within 30 days of the purchase), what you were paid for it is debited from your settlement wallet, and you get a signed refunded receipt for that transactionId. If you've already paid it out, your balance can go negative until later sales cover it. See Reversed purchases.

The fee is the one in force when the buyer paid. An increase is announced at least 30 days ahead by email and on Seller → Earnings; GET /v1/fees returns the fees in force and any scheduled change.

curl -s "https://api.zanora.dev/v1/receipts?limit=50" -H "x-api-key: $ZANORA_API_KEY"   # your sales
curl -s https://api.zanora.dev/v1/wallets/$SETTLEMENT_WALLET/balance -H "x-api-key: $ZANORA_API_KEY"

In the console: Seller → Sales and Seller → Earnings. Your settlement wallet id came back at signup (tenant.walletId). GET /v1/wallets with your provider key also returns it.

#The clearing period

Buyers can pay with a card, and a card payment can be disputed weeks later. So each sale's earnings clear before you can pay them out: 7 days by default wherever card top-ups are enabled. clearingPeriodMs on the balance says what this gateway uses. 0 means earnings are available as soon as they settle. They count in your balance as soon as the sale settles, but you can't withdraw them until they clear.

curl -s https://api.zanora.dev/v1/wallets/$SETTLEMENT_WALLET/balance -H "x-api-key: $ZANORA_API_KEY"
# → {"balanceMicros":"97000000","availableMicros":"97000000","withdrawableMicros":"48500000","clearingMicros":"48500000","clearingPeriodMs":604800000,"currency":"USD"}

withdrawableMicros is how much you can pay out now. heldForDisputesMicros is anything on hold for a card dispute. clearingMicros is how much of your balance is earnings still in the clearing period. A returned payout clears straight away, because it isn't a sale. Seller → Earnings shows both.

#Holds for card disputes

If a buyer who paid you funded the purchase with a card top-up, and then disputes that card payment with their bank, what you earned from them since that top-up is held. It's at most the disputed amount, and you can't withdraw it while the dispute is open. Seller → Earnings shows a notice with the amount.

• Dispute decided in the platform's favour: the hold is released automatically.
• Dispute lost: Zanora reviews it. Usually the hold is released to you. If the purchase was part of the fraud, the held earnings go back to the buyer's wallet. The buyer is refunded the amount paid to you (the price less Zanora's platform fee), never more than you still hold. Zanora's platform fee is non-refundable and isn't returned to the buyer.

#Register a payout destination

You register a destination once, per rail and asset. In the console: Seller → Settings → Payout address. Or from the API:

curl -s -X PUT https://api.zanora.dev/v1/providers/$PROVIDER_ID/payout-destination \
  -H "x-api-key: $ZANORA_API_KEY" -H 'content-type: application/json' \
  -d '{"destination":"0x…","asset":"USDC","chain":"base"}'

GET /v1/providers/$PROVIDER_ID/payout-destinations lists what's registered and when each becomes usable.

#Request a payout

curl -s -X POST https://api.zanora.dev/v1/payouts -H "x-api-key: $ZANORA_API_KEY" \
  -H 'content-type: application/json' \
  -d '{"walletId":"'"$SETTLEMENT_WALLET"'","amountMicros":"97000000","rail":"usdc_base"}'

You don't send a destination: the payout goes to the one registered for that rail. In the console: Seller → Earnings → Pay out.

#The payout fee and the minimum

amountMicros is what leaves your settlement wallet. The payout fee in force when you ask (payoutFeeMicros on GET /v1/fees, $0.25) comes out of it, and the rest is sent. A "20000000" payout with a $0.25 fee sends $19.75 of USDC. The payout row says so: creditedAmountMicros is what was sent, feeMicros the fee. If the payout fails or comes back, the fee is returned with it.

The smallest payout is $10 by default (minimums.payoutMicros on GET /v1/rail/providers).

A payout isn't finished when the call returns:

Follow it with GET /v1/rail/transactions. Each payout records the destination it was sent to. In the console, Seller → Earnings → Money out shows it, with a button to copy it.

#Why a payout might be refused