Merchant guide
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. |
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. Dynamic orders then offers nearby amounts and fires an order resized webhook. More enabled platforms widen the pool in the first place.
Verification routes
Peer never sits inside your customer's transfer. The payment happens in their own app, and an enclave verifies privately that it happened before onchain settlement completes. The two flows differ in who supplies the evidence.
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.
The enclave reads 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.
Turn it on with Request SAR under Settings, Checkout. Owners and managers can request it; the team configures your account.
Trade off
An account set to run SAR exclusively removes the other fiat platforms, leaving Venmo, Cash App, Wise and PayPal. Crypto and relay 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 sweeps 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
Ask the team to enable recipient overrides first. Settlement can then point at any address you control, at three levels of precedence.
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.
The Recipient Address field in the WooCommerce plugin settings. Applies to every order that store creates, and loses to a per order address.
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 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 at docs.pay.peer.xyz/webhooks.
| 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 is done. The customer can start a new one. |
ORDER_CANCELLED | Close the order in your system. |
ORDER_RESIZED | The customer resized a dynamic order. Reconcile against the new amount. |
Two rules that prevent most incidents
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.
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. |
| Manager | Orders, payment and checkout settings, webhooks, billing. |
| 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.
Requirements
At least one of Venmo, Cash App, Wise or PayPal enabled, and Seller Automated Release configured to settle automatically.
Plans and support
| Plan | Includes |
|---|---|
| Basic | Free. Sandbox Mode gives you end to end test orders, the whole dashboard and every integration. No live orders. |
| Concierge | Live payments, with a software fee built around your usage. Integration and priority support, checkout optimization, OTC offramping, custom embedded flows. |
Contact
Telegram @PeerConcierge is the fastest line to the team, or email concierge@peer.xyz. For a specific order, send the order ID and when it was created.
Support: @PeerConcierge on Telegram, or concierge@peer.xyz.
Peer Pay is a peer-to-peer payment marketplace. Peer never takes custody of merchant funds.