Skip to main content

Checkout grants

A checkout grant lets one of your users start a payout or an on-ramp on Peer's own page. Your server gives permission; the user sets every money detail. Use it when you run a wallet or any product where you must not be able to redirect, skim or hold a user's funds.

With the ordinary Payouts API and orders, your server sets the customer's email, the refund address and the destination wallet. With a grant it sets none of them.

Your serverThe user, on Peer's page
PayoutGrants permission, may cap the amountSigns in to their Peer account, sets the amount, the coin they fund with and a refund address
On-rampGrants permission, may cap the amountSets the amount and the wallet that receives the USDC

How it works​

  1. Your server mints a grant with your API key. The request carries no email, no address and no fee. See Create a grant.
  2. Your app builds the link from the grant id and token and opens it in a new tab, a popup or an iframe.
  3. Peer's page creates the payout or the order. The user reviews it there.
  4. The user funds the payout or pays for the order, and the usual payout or payment checkout takes over.

Example: Alice wants to cash out 200 USDC from your wallet.

  1. Your server mints a PAYOUT grant and returns { grantId, token } to her wallet.
  2. The wallet opens https://pay.peer.xyz/g/<grantId>?t=<token>&amount=200.
  3. Alice signs in to Peer with her email, picks USDC on Ethereum and enters a refund address.
  4. Peer creates the payout for Alice's Peer account and shows her the final terms.
  5. Alice continues, sees the deposit address and sends the funds from her wallet.
  6. The USDC arrives in her Peer account and she withdraws it to Venmo.

Your server never saw Alice's email, her refund address or the deposit address before she did.

https://pay.peer.xyz/g/<grantId>?t=<token>

That is a complete link. Everything else is an optional prefill: Peer's page shows each value, lets the user change it and asks for anything missing.

PrefillKindWhat it fills
amountbothUSDC, a decimal with at most 6 decimals
emailpayoutThe sign-in email field. A code is only sent when the user asks
fundingChainId, fundingTokenAddresspayoutThe coin and network the user will send. Ignored unless it is one of your allowed funding tokens
refundAddresspayoutWhere the funds return if the conversion fails. A mixed-case address must carry a correct checksum
destinationAddresson-rampThe wallet on Base that receives the USDC. An address written in mixed case must carry a correct checksum, as wallets produce; a mistyped one is refused
nbothA nonce you generate: 1 to 128 letters, digits, - or _. Peer's page echoes it in every event
embed=truebothRequired when the page is in an iframe

When destinationAddress comes from the link, the user must tick "This is my wallet on Base" before the order is created.

Two things your app must do

The protection only holds if your app keeps to both:

  • Build the link in the app, from { grantId, token }. Never open a URL your server sends. A server that supplies the whole URL is choosing the refund or destination address again.
  • Check every event as described under Events before acting on it.

What gets created​

A payout grant creates a normal payout for the Peer account the user signed in to. Its differences:

  • The user funds it. Your dashboard shows "The customer funds this payout from their own wallet. You don’t send anything." and offers no way to fund it or top it up. The deposit address stays listed among the payout's details.
  • A refund address is always required, on every network.
  • One grant creates one payout. To change the amount or the coin after it is created, the user starts again from your app with a new grant; the unfunded payout expires by itself.
  • The amount follows your payout step, and your payout fee and Peer's apply as on any payout. The user sees the fees before the deposit address.

An on-ramp grant creates a normal order with a fixed amount.

  • The USDC is always delivered on Base to the address the user gave.
  • Only the browser that created the order can start a payment on it. Every payment on the order needs the order's token, which your server never receives, so your server cannot choose the payment method or a refund address for the user.
  • Payment methods, fees and the buyer identity check are your account's settings, unchanged.
  • The amount is the order's USDC amount. If your account pays the fees, they come out of what arrives; set your account so the buyer pays them if the amount typed should be the amount received.

Both carry checkoutGrantId in API reads and webhooks, so you can match them to the grant you minted. Your merchantReference is copied to the payout; on an order it is in notes.merchantReference.

The first use ties the grant to whoever used it: the signed-in Peer account for a payout, the browser for an on-ramp. Opening the same link anywhere else shows "This link was already used" and never the payout or order behind it. The same account or browser can reload safely.

A grant must be used within 15 minutes by default (expiresInSeconds, 60 to 3600). After that the link shows "This link has expired".

Opening the page​

ModeEventsNotes
New tabNoneThe user copies the deposit address, or scans its QR code
Popup (window.open)To window.openerKeep a reference to the window you opened
IframeTo window.parentAdd embed=true. Signing in inside a frame depends on the browser allowing storage for the frame

Events​

Peer's page posts messages on the channel zkp2p_checkout_embed_v1, the same channel as the embedded checkout.

EventWhenpayload
grant.createdThe payout or order exists{ grantId, nonce, kind, payoutId } or { grantId, nonce, kind, orderId }
grant.fundingThe user pressed "Continue to fund", and again if the missing amount changes{ grantId, nonce, payoutId, depositAddress, amount, missingAmount, chainId, tokenAddress, decimals, quoteExpiresAt }

Amounts in grant.funding are decimal strings in the funding token's own units. Use missingAmount for what is still to send.

Before acting on a message, check all four:

  1. event.origin is the checkout's origin, https://pay.peer.xyz in production.
  2. event.source is the window or frame you opened.
  3. payload.grantId is the grant you started.
  4. payload.nonce is the nonce you put in the link.

listenForCheckoutGrantEvents applies these for you. The payout and order checkouts keep posting their own checkout.success and checkout.failed events afterwards.

Limits​

LimitValue
Grants you can mint600 per hour. Ask Peer support to change it
Payout attempts per user5 per hour, across all merchants
Time to first use15 minutes by default, 1 hour at most

Suspending your account stops unused grants as it stops everything else. Payouts and orders that already exist follow the usual rules.