Merchant setup

Charge customers in the payment app they already use. Receive USDC on Base.

1. Set up your account

Merchant dashboard	merchant.pay.peer.xyz	Sign up, settings, orders.
Peer app	App Store, Google Play	Your wallet on your phone.
Developer documentation	docs.pay.peer.xyz	Adding Peer Pay to your checkout.
Product overview	pay.peer.xyz	What Peer Pay is.

Prefer the terminal?

The Peer Pay CLI lets you sign up with email, configure your merchant, and manage webhooks without opening the dashboard:

npm install -g @zkp2p/peer-pay-cli
peer-pay-cli login --profile live
peer-pay-cli setup --profile live

You can also test locally before creating an account.

Five steps

1. Sign up with your email. Every login sends a one time code there.
2. Add your business name, logo and industry. The name and logo appear on your customers' checkout.
3. Turn on your payment platforms. Settings, Payments. Only enabled platforms appear at checkout.
4. Set who pays the fee. Same screen. Who pays the fee is you, the buyer, or a split. Split adds a buyer percentage slider and number input. See fee models.
5. Run a test order. Sandbox Mode is a free workspace paired with your live account. Switch it on from the workspace menu at the top of the sidebar and it is created the first time you do; onboarding turns it on for you on the SDK, WooCommerce, Telegram and in-person paths. Walk the checkout yourself and confirm the order lands under Orders.

Before you go live

Your account starts on its live workspace with no plan selected, so live order creation is rejected with 403 MERCHANT_TIER_FORBIDDEN until you pick one. Choose Base or Pro yourself under Settings, Billing (onboarding asks at the go-live step), or ask for Concierge. Sandbox never needs a plan. Base and Pro carry monthly caps. See plans and support.

2. How your account works

The payment flow

Every order runs the same way, whichever integration created it.

1. You create an order with an amount and a checkout link.
2. Your customer opens the link and picks one of your platforms.
3. They pay from their own app.
4. A cryptographic proof verifies the payment privately.
5. USDC settles to your wallet on Base.

They need no Peer account and no crypto wallet.

Two verification flows

Step four runs one of two ways, and it sets how much work your customer does.

Flow	Your customer	Platforms
Buyer verified	Confirms the payment in the Peer app or the PeerAuth extension. Costs them an install or an in-app step.	Every platform you enable.
Seller Automated Release	Installs nothing. On Venmo, Cash App and PayPal the checkout matches the payment memo for them; otherwise they submit the transaction ID, or on PayPal the name on their PayPal account.	Venmo, Cash App, Wise, PayPal.

Which route your account runs, what the customer does on each platform, and the trade offs are in verification routes.

Creating orders

There are four ways to create orders.

Telegram bot

No code, no website. Create payment links in a chat and get notified there when they are paid.

1. Open the bot. Message @peer_pay_merchant_bot with /start.
2. Link your account. Send /link YOUR_API_KEY, using the key from Settings, Developer. Treat it like a password.
3. Create a link. /request 50 for 50 USDC, /request 50 EUR to price in fiat.

Command	Does
/link	Connects the bot to your account.
/help	Usage and the supported currencies.
/request	Amount, then optional currency, token, chain: /request 100 EUR USDT 42161.
/orders	Recent orders, five by default.
/active	Payments in flight, grouped by order.
/unlink	Disconnects the bot.

Fiat pricing covers USD, EUR, GBP, CAD, AUD, SGD, INR, BRL and MXN. The bot snapshots your recipient, chain and token when you run /link, so unlink and relink after changing those settings. You can also name a chain and token per request.

WooCommerce

Peer Pay becomes a payment method at checkout and order status flows back. Needs WordPress 5.8, WooCommerce 7.0, PHP 7.4 or later. USD totals go out as USDC; other currencies convert at the live rate.

1. Install the plugin. peer-pay-gateway.zip from the WordPress integration guide, then Plugins, Add New, Upload Plugin.
2. Add a webhook. In Settings, Developer, point one at https://yourstore.com/wc-api/WC_Gateway_Peer_Pay/ for ORDER_FULFILLED and ORDER_CANCELLED, and copy the secret.
3. Paste your credentials. WooCommerce, Settings, Payments, Peer Pay. The method stays hidden until the key and secret are set and the gateway is enabled.
4. Buy something cheap from your own store. The order should move from On Hold to Processing. If it sticks, check the webhook logs and the peer-pay log under WooCommerce, Status, Logs.

Classic and block checkouts both work, as one Peer Pay tile or split into one option per platform.

Shopify

The Peer Pay app plus a custom manual payment method. Shopify holds the order as pending, the customer pays through the link on the order status page, and the app marks it paid on fulfillment. Orders go out priced in the store's own currency and convert to USDC at the live rate, so non USD stores work too.

1. Create the payment method. In Shopify admin, add a custom manual payment method named exactly Peer Pay, with the instructions field pointing at the confirmation page.
2. Ask for the app. It is not listed publicly yet. Ask the team to install it and confirm the method name, using the contacts under plans and support.
3. Place a low value order. Confirm the link appears and Shopify marks the order paid once you pay.

Custom SDK

For any other site. Your backend creates the order and redirects the customer to the checkout URL it returns.

npm install @zkp2p/pay-sdk@8

import { createCheckout } from '@zkp2p/pay-sdk';

const { checkoutUrl } = await createCheckout(
  {
    requestedUsdcAmount: '50.00',
    successUrl: 'https://yoursite.com/success',
    notes: { merchantOrderId: 'order_123' },
  },
  {
    apiBaseUrl: 'https://api.pay.peer.xyz',
    checkoutBaseUrl: 'https://pay.peer.xyz',
    apiKey: process.env.ZKPAY_API_KEY,
  },
);

Send the customer to checkoutUrl. Anything you leave out falls back to your dashboard defaults, so most integrations send an amount and nothing else. Release goods on ORDER_FULFILLED, never on a redirect. Payloads and signature verification are in the webhooks docs.

Each order takes one of three amount modes: a USDC amount (requestedUsdcAmount), a fiat price (requestedFiatAmount and requestedFiatCurrency), or an open amount (openAmount).

Let the customer choose the amount. For deposits, top-ups and donations, send openAmount instead of an amount. The customer types the amount in checkout, within the limits and presets you set:

const { checkoutUrl } = await createCheckout(
  {
    openAmount: { currency: 'USD', minAmount: '10', maxAmount: '2000', presets: ['25', '50', '100'] },
    notes: { merchantOrderId: 'deposit_123' },
  },
  {
    apiBaseUrl: 'https://api.pay.peer.xyz',
    checkoutBaseUrl: 'https://pay.peer.xyz',
    apiKey: process.env.ZKPAY_API_KEY,
  },
);

The order has no amount until the customer starts a payment, and the customer can change it as long as no payment on the order can still complete. Credit the customer on ORDER_FULFILLED, using the amounts in its data.order. The Telegram bot, WooCommerce and Shopify always create fixed-amount orders. See open-amount orders.

To hand the work to a coding agent, use peer-pay-cli login --profile live, run peer-pay-cli setup to configure your merchant, then run peer-pay-cli handoff --profile live --project . from your codebase. The agent uses your CLI profile to configure the SDK and webhook handler, verify a sandbox delivery, and report remaining merchant actions. See CLI setup and let a coding agent integrate.

Payment platforms

Turn platforms on under Settings, Payments. Anything with no liquidity for a quote shows as unavailable.

• United States only. Venmo, Cash App, Zelle, Chime. Venmo is the highest volume rail, and Zelle covers selected banks that customers pick at checkout.
• One market. Monzo is UK only, N26 is euro only.
• Multi currency. PayPal, Revolut and Wise quote across the US, UK, Europe and beyond, Wise the widest.
• Pay with crypto. An optional wallet option across thirteen chains. See pay with crypto.

The identifier for each platform is in payment platforms.

Rates are variable

Peer Pay is a marketplace. Each order is filled by whoever is offering fiat liquidity for that platform, currency and size at that moment, so there is no fixed price list: under merchant pays, buyer pays, or split, Max fee configuration caps the configured fee plus spread before allocating costs by the buyer share. The default for new accounts remains 20%. See fee models, and dynamic orders for what happens when nothing inside your cap covers the amount.

3. Getting paid

Where the money lands

The default payout is USDC on Base. Your configured destination and any enabled automatic sweep determine where funds are delivered; payment settlement and destination delivery can be separate steps. To settle elsewhere, see payout routing. What comes off the top, and how to reconcile it, is in fees, settlement and refunds.

Timing

Each payment attempt runs against a countdown. If it runs out the order is not cancelled: the customer can start a fresh payment, or reach support from the checkout if they already paid, and you can cancel from Orders as long as no payment was attempted.

note

Ship on a fulfilled status, never on a customer saying they sent the money.

Statuses

Orders and their payment attempts carry separate statuses. An order outlives a failed attempt, so read both.

Order	Meaning
Created	Waiting on the customer.
Partially fulfilled	Part settled, the rest outstanding.
Fulfilled	Settled. The only status to act on.
Cancelled	Closed without settling.

Payment	Meaning
Created	Attempt started, countdown running.
Settled	Verified. USDC moved.
Expired	Window passed. The order stays open and can still settle late.
Failed	Did not verify. The customer can try again.
Cancelled	Cancelled before settling.

Every status, the transitions between them, and the payment window are in order status.

When something looks stuck

• Refresh the order to pull latest state.
• Ask the customer to open the support chat on their checkout. Most stuck payments are an unfinished verification step.
• If they paid and nothing settled, send the team the order ID before replacing it.

Chargebacks

Chargebacks, reversals and refunds on your transactions are yours, so keep order IDs, timestamps, customer messages and fulfillment records, and raise an issue early because elevated dispute rates can lead to limits or termination. How a dispute is recorded and delivered to your system is in chargebacks; refunds are yours to start and fund, and the steps are in fees, settlement and refunds.

Next: the advanced merchant guide, or send customers to how to pay.