Guides

How cashback is paid

Cashback comes out of your wallet and goes to the customer's wallet in one hop. There are two routes — instant and claim — and which one runs is decided by what your checkout knew about the customer.

Configure the rate once with PUT /api/merchants/cashback/config. percentage is a FRACTION between 0.01 and 0.10 (0.03 means 3%), and max_per_transaction caps any single payout in sats. Cashback cannot be enabled until an NWC wallet is connected.

Instant path — pass customer_lightning_address when you create the payment. When the sale settles, Trevi instructs your wallet to pay that address immediately. This is the best experience and should be used whenever your checkout knows a Lightning address.

Claim path — pass customer_email instead. Trevi reserves the cashback and emails the customer a one-time claim link, valid for 30 days. The link carries no funds; it is an invitation. When the customer opens it and names any Lightning address, your wallet pays them then and there. If they never claim, the reservation is released on expiry and nothing moves, because nothing ever left your wallet.

Pass neither field and no cashback is offered for that sale.

Cover is verified before anything is promised. Trevi checks your wallet's live balance and remaining daily limit — minus everything already reserved and not yet paid — and covers the cashback AND the 1% fee together, since both spend the same limit. If the cover is not there, no offer is made. Trevi never promises a payout it cannot see the funds for.

The fee is Trevi's 1% of the cashback amount, paid by your wallet as a separate payment after the customer has their sats. It is never deducted from what the customer receives.

Reserved-but-unsent cashback is visible at GET /api/v2/wallet/activity?type=reserved, and paid cashback at ?type=cashback_payout.

Example

# Instant: your checkout knows a Lightning address.
curl --request POST "https://api.trevi.cash/api/v2/payments" \
  --header "Content-Type: application/json" \
  --header "X-API-Key: $TREVI_API_KEY" \
  --data '{ "amount_sats": 150000, "external_order_id": "order-1",
            "customer_lightning_address": "alice@getalby.com" }'

# Claim: you only know an email. Trevi emails a 30-day claim link.
curl --request POST "https://api.trevi.cash/api/v2/payments" \
  --header "Content-Type: application/json" \
  --header "X-API-Key: $TREVI_API_KEY" \
  --data '{ "amount_sats": 150000, "external_order_id": "order-2",
            "customer_email": "alice@example.com" }'

Was this page helpful?

Quickstart: a sale, end to end

Receive webhooks