Advanced merchant guide
Every setting that changes what an order costs, who verifies it, where the money lands, and who can touch it.
Fee models
One setting prices every checkout: Fee Payer, under Settings, Payments. It is the default for new orders, and the SDK can override it per order.
| Mode | Pricing | Use when |
|---|---|---|
| Merchant pays | The customer is charged what you asked for. The fee comes out of what settles to you. | Displayed prices must match the charge. Retail and ecommerce. |
| Buyer pays | You receive the full amount. The fee is added on top at checkout. | Funding an account or invoice, where the credited balance has to be exact. |
Capping the fee you pay
Max Fee Configuration is your ceiling on an order, and applies only when the merchant pays. When the customer pays, the price they accept already includes the fee.
| Cap type | Behavior |
|---|---|
| Flat threshold | One maximum percentage on every order. The right start for a narrow range of basket sizes. |
| Dynamic tranches | Ceilings by order size in USD. Each tranche starts where the last ends, and the last covers everything above it. Pay up for fast fills where your volume is. |
Raise the cap if orders sit unfilled, lower it if they fill instantly and you would rather keep the margin. The checkout reads the current cap when it prepares a quote and creates a payment, so an edit can change availability for an existing unpaid order.
If nothing inside your cap fits the amount, the order will not fill. Dynamic orders then offers nearby amounts and fires an order resized webhook. More enabled platforms widen the pool in the first place.
Verification routes
The payment happens in your customer's own app, and a cryptographic proof verifies it before settlement completes. The two flows differ in who supplies the evidence.
Buyer verified
The default, and it works on every platform you can enable. Your customer confirms their own payment, on most platforms through the Peer app and on some through the PeerAuth extension. They log in to their provider directly, as they would on that provider's own site, and Peer never sees those credentials. That means they have to be able to log in to the account the money came from.
Seller Automated Release
Peer verifies on the receiving side instead, so your customer installs nothing. It matters most for in person and first time customers, and it is what lets Scan to Pay settle at the counter. On PayPal the checkout may show a suggested memo for the payment note, and the customer enters the payer name to verify. If a submission fails, the checkout offers the app or extension route as a second chance.
It comes with the Pro plan: selecting Pro sets your account to prefer Seller Automated Release and fall back to buyer verified when a submission fails. Base runs buyer verified. Concierge accounts are configured by the team, including SAR exclusive mode.
An account set to run SAR exclusively removes the other fiat platforms, leaving Venmo, Cash App, Wise and PayPal. Crypto options stay available when enabled. If losing a fiat rail costs you a market, ask to keep both routes.
Payout routing
Every order settles as USDC on Base, the fastest and cheapest path. Change it only if your treasury lives somewhere else.
Another chain or token
Under Settings, Payments, switch on Enable receiving outside Base USDC, accept the conversion terms, and pick a default chain and token. Owner only. API and SDK orders that omit them use the current defaults; the Telegram bot instead snapshots chain, token and recipient at /link, so unlink and relink after a change. Solana payouts are forwarded after settlement on Base to the linked Solana wallet under Settings, Account.
Payouts outside Base USDC are bridged, so the amount that arrives can differ slightly from the quote. Reconcile on the settled amount in the webhook.
Recipient overrides
Settlement can point at any address you control, at three levels of precedence.
Per order
The destination address field on the order your backend creates. Highest precedence, and the only way to route dynamically:
- Per user deposit addresses. Gaming platforms, poker rooms and onramps generate an address per customer, so a completed order credits that account automatically.
- Treasury and multisig. Revenue lands in the company wallet instead of being swept later.
- Contracts and vaults. Route into a protocol that can receive the token.
- Cold storage. Move takings out of a hot wallet on settlement.
Per store
The Recipient Wallet Address field in the WooCommerce plugin settings. Applies to every order that store creates, and loses to a per order address.
Account default
The linked wallet under Settings, Account. Applies to everything that does not override it.
Funds sent to a wrong address cannot be recovered. Confirm the destination supports the token on your settlement chain, and test with a small order first.
Checkout configuration
Appearance and currency
Under Settings, Checkout, start from the default, dark or light preset, then edit any color to move into custom mode: background, panel, text, accent, border and buttons, with a live preview. Business name and logo come from Settings, Account.
Default Customer Payment Currency sets what the checkout quotes first. On Auto it follows the customer's location; pin it when your customers are in one market.
Per order controls
| Control | Does |
|---|---|
| Amount | Price in USDC, or in fiat and let the API convert. |
| Enabled rails | Restrict one order to a subset of your platforms. |
| Preselected method | Open with one platform already chosen. |
| Success URL | Where the customer returns after paying. |
| Notes | Your order or customer IDs, so webhooks reconcile with your system. |
| Dynamic orders | Opts one order out of resizing. It cannot opt one in when the account default is off. |
Enable pay with crypto adds a wallet option to exact token checkouts across eleven chains, including Base, Ethereum, Solana, Bitcoin and Tron.
API keys and webhooks
Your API key lives under Settings, Developer and authenticates order creation. Server side only, never in frontend code or a public repository. Owners can rotate it there. Rotation kills the old key at once, so update every integration first, including the Telegram bot and any store plugin.
Webhooks are how your system learns an order is real. Add an endpoint, choose events, copy the signing secret shown on creation, and verify the signature before acting on a request. Payload shapes are in the webhooks docs.
| Event | What to do with it |
|---|---|
ORDER_FULFILLED | Release goods or credit the account. Build on this one. |
PAYMENT_SETTLED | Reconcile the settled amount. Fulfillment still follows the order event. |
PAYMENT_EXPIRED | The window closed. Do not cancel the order automatically; a late settlement can follow. |
PAYMENT_FAILED | That attempt failed. The customer can start a new one; a stalled crypto attempt can still settle if its deposit lands late. |
ORDER_CANCELLED | Close the order in your system. |
ORDER_RESIZED | The customer resized a dynamic order. Reconcile against the new amount. |
PAYMENT_CHARGEBACKED | A settled payment was disputed and charged back. Record it against the order without touching its fulfilled status. |
ORDER_CHARGEBACKED, ORDER_PARTIALLY_CHARGEBACKED | Every, or only some, settled payments on the order carry a chargeback. Read the snapshot in the event; the state is not monotonic. |
Never fulfill on a browser redirect: landing on your success URL does not mean they paid. And keep your handler idempotent, because an event can arrive more than once.
Staking
Venmo and PayPal payments are protected by USDC stake during their dispute windows; other platforms need none. If Peer covers your account, you never see the Staking page. If your account supplies its own stake, the page appears in the sidebar and stake is required to process volume on those platforms. Concierge accounts are covered once their setup is complete; any earlier stake or locks release on their own schedule.
When the stake is yours, the page shows available, locked and at-risk stake, every lock tied to an order and when it becomes releasable, the risk window per platform, and your chargeback history. Owners deposit and withdraw free stake from the merchant wallet on Base; managers see the page read only.
- A protected payment locks stake for the full amount when the customer starts paying, and releases it if that attempt expires or is cancelled.
- On settlement the lock shrinks to the settled amount and holds for the platform's risk window. Once the window has passed, the lock is released.
- A successful dispute is paid from that lock and recorded on the order as a chargeback.
Free stake can be withdrawn at any time, but platforms that need stake stop filling once it is gone. Leave enough to cover the orders you expect in flight.
Chargebacks
A chargeback is an additive fact. The order and payment keep their fulfilled and settled statuses and gain a separate chargeback status: none, partially charged back, or charged back. Orders shows it as its own badge, and the events above deliver it to your server with full order and payment snapshots. Refund and bridge history is not rewritten. Payload shapes are in the webhooks docs.
Roles and Scan to Pay
Invite teammates by email under Settings, Account.
| Role | Can do |
|---|---|
| Owner | Everything: API key rotation, wallet key export, payout conversion, plan selection and Concierge requests, stake deposits and withdrawals. |
| Manager | Orders, payment and checkout settings, webhooks, refunds. Billing is view only; changing the plan is an owner action. Staking read only, when shown. |
| Cashier | Scan to Pay, Orders, cashier Resources and their own settings. Can copy checkout links, open support tickets and cancel eligible in person orders. No refunds, keys, payouts or integration config. |
Scan to Pay
The counter flow. Enter an amount or tap a preset, and the screen shows a QR code the customer scans to open the checkout. After they pay, the cashier scans their confirmation to read the transaction ID, or types it. On PayPal the checkout may show a suggested memo for the payment note, and the cashier enters the payer name to verify.
Owners and managers working the counter can turn on cashier mode under Settings, Scan to Pay. It collapses that browser to the cashier view so business information stays off screen, without changing anyone's role.
A Pro or Concierge plan (sandbox is always allowed), at least one of Venmo, Cash App, Wise or PayPal enabled, and Seller Automated Release configured to settle automatically. On the Base plan, creating an in-person order is rejected with 403 IN_PERSON_CHECKOUT_PRO_REQUIRED.
Plans and support
Every account starts in free Sandbox Mode: end to end test orders, the whole dashboard and every integration, no live orders and no plan needed. Live orders need one of these, selected under Settings, Billing or at the go-live step of onboarding.
| Plan | Price | Includes |
|---|---|---|
| Base | 2.95% fiat / 1% crypto per successful payment | Up to $10K fiat volume and 50 fiat orders per month; crypto-only orders never count. Every platform; Venmo and PayPal need staking. Buyer verified. Instant settlement, merchant funded refunds. |
| Pro | 4.95% fiat / 1% crypto per successful payment | Up to $30K fiat volume and 100 fiat orders per month; crypto-only orders never count. Everything in Base, plus Seller Automated Release by default, Scan to Pay, and priority support. Checkout branding removal is configured by the team. |
| Concierge | Custom pricing | Unlimited volume and orders. No staking required. Negotiated rate or flat fee invoicing, full integration support, named support in a dedicated group, custom embedded checkout and integrations. |
Fiat quotes show the complete price, the software fee plus the peer's rate, before your customer pays. Base and Pro are self serve and can be switched between at any time; Concierge is set up with the team.
Monthly caps
Base and Pro caps count fiat-paid orders per UTC calendar month. An order counts once any fiat payment on it (Venmo, Cash App, Zelle, PayPal, Revolut, Wise, Monzo, N26, Chime) has settled, attributed to the month the order was created in, at its full requested amount. Orders paid only with crypto (Relay, Coinbase Apple Pay, Zcash via NEAR Intents) never count toward either cap, and neither does an abandoned checkout. Sandbox orders are never capped. The check runs when an order is created, before your customer picks how to pay, so a new order's amount is tested against your fiat usage regardless of how it is later paid. When a new live order would cross the cap, creation is rejected with 403 and the code MERCHANT_MONTHLY_ORDER_LIMIT_EXCEEDED or MERCHANT_MONTHLY_VOLUME_LIMIT_EXCEEDED; the message names the limit. Dynamic orders will not grow an order past the volume cap either. Upgrade under Settings, Billing to continue in the same month.
Contact: email sales@peer.xyz, the fastest line to the team. For a specific order, send the order ID and when it was created.
Back to merchant setup, or the developer reference.