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: Who pays the fee, 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.
Split	The customer covers the chosen share of total fees and you cover the remainder.	Sharing quote costs at a fixed buyer:merchant ratio.

Choose Split to set the buyer share of fees with the slider or number input (0% to 100%, in 10% steps). The displayed ratio is buyer:merchant: 0:100 means you pay all fees, 30:70 means the buyer covers 30%, and 100:0 means the buyer pays all fees. It applies to fiat, Apple Pay, and crypto and is saved on each new order. A new split selection defaults to 50:50. See split payment fees.

Capping the fee you pay

Max fee configuration applies to merchant pays, buyer pays, and split for standard fiat pricing. It caps the configured fee plus spread before allocating costs by the buyer share. New accounts start at 20%. Accounts using spread-inclusive pricing retain their configured fee budget instead. For standard buyer-pays, a larger deposit can also qualify when its actual buyer total fits the cap. The merchant still receives the full order amount; Peer keeps the scheduled fee plus the surplus, with rounding dust left to the merchant.

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.

Tuning

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, and dynamic orders then offers the customer nearby amounts and fires ORDER_RESIZED. More enabled platforms widen the pool in the first place.

How the cap is checked

For ordinary standard quotes, checkout adds the configured fees (your plan's software fee plus any referral split), the peer's spread over the market rate, and any bridge spread. A quote whose sum exceeds your cap is not shown. This additive check is not a literal limit on the buyer's markup: an 85 USDC buyer-paid order with a 9.25% fee and 10% spread passes a 20% cap (19.25% additive) while costing the buyer $103.04.

Larger buyer-paid deposits use a separate actual-total check. The same 85 USDC order with a 20% cap may cost at most $102.00, including spread. A fixed 100 USDC deposit at 1:1 qualifies: the merchant receives 85 USDC and Peer collects 15 USDC, preserving its 9.25 USDC scheduled fee and collecting 5.75 USDC surplus. Smaller releases cannot reduce that scheduled fee. Flat all-in pricing keeps its configured fee budget and ignores the maximum-fee setting.

The full buffer matrix explains how merchant pays, buyer pays, split, all-in pricing, and explicitly cleared caps differ. Three consequences of the ordinary cap follow.

• The fee is the floor. A cap at or below your plan's fee leaves no room for a spread, so only peers priced at or better than market can match and the option will rarely appear. On Base, a 3% cap allows a spread of 0.05%.
• Lowering the cap trades availability for cost. Each point you take off removes the peers priced above it. It does not make the remaining peers cheaper. What the fills you do get have cost is in what to expect in practice.
• One peer fills one payment. The amount has to fit inside a single peer's available balance and order range, so a large order needs a deeper peer than a small one at the same cap. Availability is a function of the amount as much as of the cap.

To decide per checkout rather than per account, call quote availability with the amount, currency and rails you will use before showing Peer as a payment option, and offer another payment method when it returns unavailable.

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 Venmo, Cash App and PayPal the checkout shows a suggested memo for the payment note and confirms the payment automatically by matching it. When the match fails, PayPal asks for the name on the customer's PayPal account and every other rail asks for the transaction ID, typed or read off a screenshot. If that submission fails too, 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.

Trade off

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, expand Advanced, switch on Receive outside Base USDC, accept the conversion terms, and pick a payout chain and token. Owner only. API and SDK orders that omit them use the current defaults; the Telegram bot instead snapshots chain and token at /link, so unlink and relink after a change. Bot orders never name a recipient, so they always pay your current wallet for the chosen chain. Solana payouts are forwarded after settlement on Base to the linked Solana wallet under Settings, Account.

Amounts can move

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.

Check the address

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

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.

These colors, with your business name and logo, also apply to payout checkouts, including ones already open.

Currency

Both currency controls live under Settings, Payments, not Checkout.

Default currency sets what the checkout quotes first. On Auto it follows the customer's location; pin it when your customers are in one market.

Let customers change currency decides whether the customer sees a currency dropdown. With it off, checkout picks the currency for them, your default first, then the order's requested currency, then their region, and only offers the dropdown when that currency has no usable payment method.

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. See dynamic orders.

Pay with crypto

Crypto, in the Payment methods list, adds a wallet option to exact token checkouts across thirteen chains: Base, Ethereum, Optimism, Arbitrum, Polygon, BNB Smart Chain, World Chain, Hyperliquid, Arc, Solana, Bitcoin, Tron, and Zcash through NEAR Intents. Zcash is offered only when the order pays out in USDC on Base. The rail identifier for each chain is in payment platforms.

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.

Owners can also pin the key to your servers with the API key IP allowlist on the same page: add public IPv4/IPv6 addresses or CIDR blocks and save. Calls from anywhere else get 403 IP_NOT_ALLOWED, and the response names the address that was rejected so you can add it. Live and sandbox keys keep separate lists, and dashboard access is never affected. The Peer Telegram bot is exempt, so linking the bot keeps working with an allowlist on. See the API reference for the exact rules and response shape.

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.

Four events carry the work:

Event	What to do with it
ORDER_FULFILLED	Release goods or credit the account. Build on this one.
PAYMENT_SETTLED	Reconcile the settled amount. For Relay crypto payments, re-read fee fields from the Payments API a few minutes later. Fulfillment still follows the order event.
PAYMENT_EXPIRED	The window closed. Do not cancel the order automatically; a late settlement can follow.
ORDER_CANCELLED	Close the order in your system.

The rest, including the failure, resize, bridge and chargeback events and every payload shape, are in webhook events.

Two rules

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, Your stake shows the total and splits it into Available (covers new payments or can be withdrawn), In use for payments, and Ready to unlock (its lock period has passed but it is not yet released). Below it are Stake lock durations per platform, Stake locks with every lock tied to an order and when it becomes releasable, and your Chargeback history. Owners use Add stake and Withdraw with 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. If the customer never pays, the lock is released 30 minutes after the attempt expires, when Peer cancels it; a cancelled attempt releases it when it 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.

Withdrawing to zero

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

Venmo and PayPal are the two platforms whose payments can be disputed after they settle. Cash App is non-chargebackable and needs no stake. A successful dispute is paid from your stake and recorded on the order.

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 PAYMENT_CHARGEBACKED, ORDER_CHARGEBACKED and ORDER_PARTIALLY_CHARGEBACKED deliver it to your server with full order and payment snapshots, so keep fulfillment and chargeback state apart in your own system. The state is not monotonic, so read the snapshot in the event instead of incrementing your own counter. Refund and bridge history is not rewritten. Payload shapes are in the webhooks docs.

Seller disputes

When a seller reports a Venmo or PayPal case on one of your orders and no buyer stake covers it, you're asked to send the seller the USDC their deposit released, from your Peer Pay wallet on the Disputes page, within 7 days. DISPUTE_OPENED, DISPUTE_PAID and DISPUTE_ESCALATED deliver each step to your server. A dispute is separate from a chargeback: chargebacks are paid from buyer stake on-chain. Payload shapes are in the webhooks docs.

Roles and Scan to Pay

Invite teammates by email under Settings, Account.

Role	Can do
Owner	Everything: refunds, API key rotation, wallet key export, payout conversion, plan selection and Concierge requests, stake deposits and withdrawals.
Manager	Orders, payment and checkout settings, webhooks. Billing is view only; changing the plan is an owner action. Staking read only, when shown.
Cashier	Scan to Pay, Orders, cashier Help 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. On PayPal the cashier's screen shows a memo to read out to the customer for their payment note, and the cashier verifies by entering the name on the customer's PayPal account. Every other rail uses the transaction ID: after the customer pays, the cashier scans their confirmation to read it off, or types it.

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.

Requirements

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 on its live workspace with no plan selected, so live order creation is rejected until you pick one of these under Settings, Billing or at the go-live step of onboarding. Sandbox Mode is a separate free workspace paired with the live one, switched on from the workspace menu at the top of the sidebar: end to end test orders, the whole dashboard and every integration, no plan needed.

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 customer one final price before they pay; whether it includes the software fee and the peer's rate depends on who pays. Base and Pro are self serve and can be switched between at any time; Concierge is set up with the team. What an order costs in practice, with a worked example, what settles, and how refunds work is in fees, settlement and refunds.

Monthly caps

Base and Pro caps count fiat-paid orders per UTC calendar month. An order counts once any fiat payment on it has settled, attributed to the month the order was created in, at its full requested amount. Orders paid only with crypto 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.

Crossing the order cap can reject order creation with 403 MERCHANT_MONTHLY_ORDER_LIMIT_EXCEEDED. Crossing the volume cap always does, with 403 MERCHANT_MONTHLY_VOLUME_LIMIT_EXCEEDED. Either message names the limit it hit. Dynamic orders will not grow an order past the volume cap either. Upgrade under Settings, Billing to continue in the same month.

Watching your usage

Peer does not email you or send a webhook when you approach a cap, so build the check into your own flow.

• Dashboard. Settings, Billing shows a usage meter for this month's fiat volume and fiat orders, and the dashboard shows an account-wide warning once either reaches 80%.
• API. GET /api/v1/merchants/me/tier-usage with your API key returns the same numbers. responseObject carries:

{
  "tier": "BASE",
  "limits": { "volumeUsdc": "10000", "orderCount": 50 },
  "usage": { "volumeUsdc": "4250", "orderCount": 17 },
  "windowStart": "2026-09-01T00:00:00.000Z",
  "windowEnd": "2026-10-01T00:00:00.000Z"
}

limits is null when no cap applies, on Concierge and in sandbox. usage counts fulfilled and partially fulfilled orders with at least one settled fiat payment, each at its full requested USDC amount, attributed to the month the order was created in. Poll it from your own monitoring and alert at whatever margin suits your order size.

• At order creation. Treat the two 403 codes above as a routing signal rather than an error page: offer another payment method for the rest of the month, or upgrade under Settings, Billing, which lifts the cap at once.

Contact: email sales@pay.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.