Skip to main content

Master Merchant Accounts

Run Peer Pay for other businesses as sub merchants, earn fees on the payments they take and the payouts they make, and hand each one to its new owner when you sell it.

A Master Merchant Account runs Peer Pay for other businesses, the way a payment service provider does. Your account gets a Sub Merchants page. Each sub merchant is its own Peer Pay merchant account that you create, set up and integrate. You can keep running a sub merchant yourself, or transfer it to its new owner by email. After a transfer you keep a manager seat on it and your master merchant fees.

Get access​

Master Merchant Accounts are only available on the Concierge plan, and the Peer team turns yours on by request.

  1. Move to Concierge if you are not on it yet. The account owner requests it under Settings, Billing on the live workspace, or email sales@pay.peer.xyz. What Concierge includes is in plans and support.
  2. Request Master Merchant Account access. Email sales@pay.peer.xyz or ask in your Concierge support group. Tell us roughly how many sub merchants you plan to run and the master merchant fees you have in mind.

Once access is on, Sub Merchants appears in the sidebar of your live workspace. The team may also set a maximum payment fee and a maximum payout fee for your account. When one is set, the Sub Merchants page shows it.

Your account needs to be live, on a plan, with payout wallets set up. A sub merchant cannot itself become a Master Merchant Account.

Create a sub merchant​

Only the account owner can create sub merchants. Managers of your account can see the Sub Merchants page but cannot change anything on it, and they can open a sub merchant only once they are on its team.

  1. Open Sub Merchants and choose New sub merchant.
  2. Enter the Sub merchant name, your Payment fee (%) and your Payout fee (%). Enter 0 for a fee you don't charge.
  3. Check the fee preview. It shows the configured fees on payments for each payment app and for crypto: Peer's fee plus your payment fee.
  4. Choose Create sub merchant.
  5. Choose Set up now to switch into the new sub merchant and start its onboarding, or Later to stay on Sub Merchants and come back to it any time.

A new sub merchant starts with:

  • Your plan and payment settings, copied from your account: the plan and its fees, who pays the fee, the max fee configuration, the enabled payment apps and Apple Pay, the checkout currency, the payout chain, token and sweep, the verification route, how staking is covered, order size limits, dynamic orders, in person checkout and Peer branding removal.
  • Your payout wallets. Payments on the sub merchant settle to your wallet until you transfer it.
  • You as its owner.
  • No logo and the default checkout colors. Add its logo under Settings, Account and its colors under Settings, Checkout.

Your own account's fee splits are not copied. The sub merchant carries only your master merchant fees.

Set up a sub merchant​

A sub merchant is a normal merchant account, so you set it up the same way as your own. Choose Set up now when you create it, Open on its row, or pick it in the workspace menu at the top of the sidebar.

You always know which account you are working in:

  • In the workspace menu, each sub merchant is marked Sub merchant of your account, and while you are in one the menu reads Sub merchant under its name. This stays after you transfer it and keep a manager seat.
  • Onboarding a sub merchant shows a banner saying which sub merchant you are setting up, with a link back to your own account. Your own account's onboarding and settings are not touched.

In the sub merchant:

  • Settings, Developer: copy its API key for its integration, and add webhooks.
  • Settings, Account: its name and logo, and its team.
  • Settings, Checkout: checkout colors.
  • Settings, Payments: payment apps, who pays the fee, the checkout currency and the max fee.

Connect the sub merchant's site with its API key, the same way as any merchant: WooCommerce, Shopify, the SDK, payment links or the Telegram bot. See merchant setup.

How the fees work​

You charge each sub merchant two fees, and you set them separately:

  • Payment fee, on every payment the sub merchant takes.
  • Payout fee, on every payout the sub merchant sends.

Both are paid to your wallet. Together they are your master merchant fees.

Payment fee​

Every payment on a sub merchant carries two fees:

  • Peer's software fee, set by the sub merchant's plan, which it copies from your account.
  • Your payment fee, a percentage you choose per sub merchant. It is added on top of Peer's fee on every payment, whether the customer pays with a payment app or with crypto.

For example, if Peer's fee on a payment is 6% and the sub merchant's payment fee is 2%, that payment carries 8% in configured fees: 6% to Peer and 2% to your wallet. Peer's fee can differ by payment app and order size, as the fee preview shows. The peer's spread is separate, as on any order. If the sub merchant has spread-inclusive pricing, the spread comes out of Peer's 6%, never out of your 2%.

  • Paid with each payment. On payment app payments your fee settles onchain to your wallet at settlement, so there is nothing to invoice. On crypto and Apple Pay payments it is charged as an app fee by the provider that routes the payment, such as Relay, and accrues to your wallet address in that provider's app fee balance until you claim it.
  • Who pays follows the order. Your fee is paid the same way as Peer's fee, under the order's fee model: the sub merchant's Who pays the fee setting, unless the order overrides it. With merchant pays it comes out of what the sub merchant receives, with buyer pays it is part of the customer's checkout total, and with split it is shared at the order's ratio. See fee models.
  • Limits. The fee can be from 0% to 50%, and no higher than your account's maximum payment fee when the team has set one. Zcash payments are refused when Peer's crypto fee plus yours is above 5%.
  • Max fee. When the merchant pays the fee and the sub merchant has a max fee configuration, Peer's fee plus yours has to fit under the cap on every payment app at every order size. Sub merchants with spread-inclusive pricing skip this check. When the fee does not fit, the sub merchant is not created or the fee is not saved, and the dashboard names the payment app and the amount range that fails.
  • New orders only. A fee change applies to orders created after it. Existing orders keep the fees they were created with.
  • Referrals. Your sub merchants also appear on your Referrals page.

Payout fee​

  • What it is. A percentage of each payout the sub merchant sends, from 0% to 10%, and no higher than your account's maximum payout fee when the team has set one. Peer's own payout fee, when the sub merchant has one, is separate.
  • Who pays. Like every payout fee, it comes out of the funding for the payout, so whoever funds the payout pays it. A 100 USDC payout with a 1% payout fee needs about 1% more funding.
  • Paid with each payout. Payouts are routed through Relay, so your payout fee is charged as a Relay app fee and accrues to your wallet address in Relay's app fee balance until you claim it, the same as your payment fee on crypto payments.
  • Shown on the payout. The sub merchant sees it on each payout's details as Master merchant fee, and integrations see it as masterMerchantPayoutFee on the payout.
  • New payouts only. A fee change applies to payouts created after it. Existing payouts keep the fee they were created with.

Change a sub merchant's fees​

Choose Edit fees on the sub merchant's row, change the payment fee, the payout fee or both, and choose Save fees. You can change them while you own the sub merchant and no transfer is pending. After it is transferred, only the Peer team can change its fees.

If the Peer team lowers your maximum after you set a fee, that fee stays as it is, and you can still change the other one. Only a fee you change has to fit the current maximum.

Transfer a sub merchant​

When you sell a sub merchant, transfer it so its new owner controls the account and receives its payouts.

  1. On Sub Merchants, choose Transfer on its row. You can also open the sub merchant and go to Settings, Account, Ownership.
  2. Enter the new owner's email. It cannot be your own.
  3. Read what changes, what you keep, and how the transfer affects its open orders. Then choose Send transfer.
  4. The confirmation shows the transfer link with a Copy button, and whether Peer emailed it to the new owner. If the email could not be sent, copy the link and send it yourself.

The link is shown only once. Peer keeps only a hashed copy, so it cannot show the link again. The link works for 7 days, and only for the email address you sent it to. A sub merchant can have one pending transfer at a time.

While a transfer is pending:

  • The sub merchant's row shows Transfer pending with Cancel transfer.
  • You cannot change its fees.
  • To send a new link, cancel the transfer and send a new one. The old link stops working.
  • If the Peer team changes either of its fees, the transfer is cancelled and you get an email asking you to send it again.

What the new owner does​

The new owner opens the link and:

  1. Signs in with the email address the transfer was sent to, using a one-time code. They do not need a Peer Pay account first: accepting makes the merchant account theirs.
  2. Reviews the transfer: they become the account's owner, payouts go to their wallet, you keep a manager seat they cannot remove, and the account keeps paying your payment and payout fees, which only the Peer team can change.
  3. Chooses Accept transfer. If their wallet is not set up to receive payouts yet, the button reads Set up wallet and accept and sets it up first.

The account then opens in their dashboard, as their own account. Opening the link while signed in with a different email shows a masked version of the address the transfer was sent to, so they can sign in with the right one.

If the account supplies its own stake instead of using Peer's, the new owner is told before accepting that it may need stake before it can take payments. See staking.

After the transfer​

  • The new owner owns the account, and new orders pay out to their wallet. A recipient override that names your wallet, per order or in the WooCommerce plugin, keeps sending payouts there until its integration is updated.
  • You keep a manager seat, marked Locked in its team. The new owner cannot remove it; only Peer support can. As a manager you can work on orders, checkout and payment settings, webhooks and the team. Refunds, API key rotation and payouts are the owner's.
  • Your master merchant fees keep paying your wallet: the payment fee on every payment and the payout fee on every payout.
  • The API key stays the same, so the integration keeps working. If the new owner rotates the key, the integration stops until it is updated with the new one.
  • Orders created before the transfer are marked Before transfer:
    • unpaid orders with no payment attempts are cancelled, with the usual cancellation webhook;
    • orders with earlier payment attempts, and partially paid orders, stop accepting new payments;
    • a payment recovered on one of these orders still pays out to the order's original recipient, your wallet by default;
    • no one can start a new refund on them; a refund started before the transfer keeps using your wallet.
  • On your Sub Merchants page, it shows Transferred with the new owner's email and the date.

If Master Merchant Account access is turned off​

Existing sub merchants keep working as they are, including your master merchant fees and your seats on them. The Sub Merchants page leaves your sidebar and you cannot create sub merchants, change their fees or send transfers. Any pending transfers are cancelled.

From the CLI​

The Peer Pay CLI covers the same actions: sub-merchants list, sub-merchants create, sub-merchants set-fees and sub-merchants fee-preview, then transfer send, transfer status, transfer cancel and transfer accept. See Sub merchants and Sub merchant transfers in the command reference.

transfer send prints the link only with --show-secrets, and it cannot be read again later. transfer accept cannot set up a wallet: when the new owner's wallet still needs setup, it prints the dashboard link to accept there.