Checkout grants
A checkout grant lets one of your users create a payout or an on-ramp order on Peer's page, with the money details set by them and not by your server. The SDK has one call for your backend and two helpers for your app.
| Function | Runs in | Import from |
|---|---|---|
createCheckoutGrant | Your backend | @zkp2p/pay-sdk |
buildCheckoutGrantUrl | Your app | @zkp2p/pay-sdk |
listenForCheckoutGrantEvents | Your app | @zkp2p/pay-sdk/embedded |
Added in @zkp2p/pay-sdk 9.1.0.
Create a grant
import { createCheckoutGrant } from '@zkp2p/pay-sdk';
const grant = await createCheckoutGrant(
{
kind: 'PAYOUT', // or 'ONRAMP'
merchantReference: 'withdrawal_8731',
returnUrl: 'https://wallet.example.com/done',
amountLimit: { max: '500' },
},
{
apiBaseUrl: 'https://api.pay.peer.xyz',
apiKey: process.env.ZKPAY_API_KEY!,
},
);
// Send only these two to your app.
return { grantId: grant.grantId, token: grant.token };
This call sends your merchant API key in the X-API-Key header. Run it on your backend.
Every field but kind is optional; the API reference lists
them and the errors. There is nowhere to put an email, an address or a fee: the user supplies
those on Peer's page.
A failed call throws a PayApiError with the API's statusCode and errorCode.
Build the link
Build the link in your app, from the grantId and token your backend returned. Don't have your
backend build it: a server that hands over a finished URL is choosing the addresses in it.
import { buildCheckoutGrantUrl } from '@zkp2p/pay-sdk';
const nonce = crypto.randomUUID();
const url = buildCheckoutGrantUrl(
grant, // { grantId, token }
{
amount: '200',
refundAddress: userWalletAddress, // payout: where funds return if the conversion fails
},
{ checkoutBaseUrl: 'https://pay.peer.xyz', nonce },
);
const checkoutWindow = window.open(url);
if (!checkoutWindow) {
// The browser blocked the popup. Open the link from a click handler, or fall back to a new tab.
}
The second argument is the optional prefills. Each one is a starting value the user sees, can change and has to confirm:
| Prefill | Kind | Type |
|---|---|---|
amount | both | USDC decimal string |
email | payout | string |
fundingChainId | payout | number |
fundingTokenAddress | payout | string |
refundAddress | payout | string |
destinationAddress | on-ramp | string, an address on Base |
The third argument takes checkoutBaseUrl, an optional nonce that Peer's page echoes in every
event, and embed: true when the page will load in an iframe. A nonce is 1 to 128 letters, digits,
- or _; crypto.randomUUID() fits. Anything else is dropped and events then carry nonce: null.
Events
In a popup or an iframe, Peer's page tells your app what it created and, for a payout, where the
user should send funds. listenForCheckoutGrantEvents delivers only messages that come from the
checkout's origin, from the window you opened, for your grant and with your nonce.
import { listenForCheckoutGrantEvents } from '@zkp2p/pay-sdk/embedded';
const stop = listenForCheckoutGrantEvents({
checkoutOrigin: 'https://pay.peer.xyz',
source: checkoutWindow, // the window you opened, or iframe.contentWindow
grantId: grant.grantId,
nonce,
onCreated: (event) => {
// event.payoutId for a payout grant, event.orderId for an on-ramp grant
},
onFunding: (event) => {
// The user reviewed the terms and chose to fund. Offer the transfer in your wallet:
// event.missingAmount of event.tokenAddress on event.chainId, to event.depositAddress.
},
});
// When your flow ends:
stop();
| Event | Fields |
|---|---|
onCreated | grantId, nonce, kind, and payoutId or orderId |
onFunding | grantId, nonce, payoutId, depositAddress, amount, missingAmount, chainId, tokenAddress, decimals, quoteExpiresAt |
amount and missingAmount are decimal strings in the funding token's own units. onFunding
fires again when missingAmount changes, for example after part of the amount has arrived.
In a plain new tab there is no window to post to, so no events arrive. The user copies the deposit address from Peer's page or scans its QR code.
In an iframe, the payout or order checkout then keeps posting its usual
checkout.success and checkout.failed events on the
same channel. A popup receives only the two grant events above. Treat every event as a hint for
your interface; your backend learns the outcome from webhooks, where the payout or
order carries checkoutGrantId.
Types
import type {
CheckoutGrantKindType, // 'PAYOUT' | 'ONRAMP'
CheckoutGrantPrefills,
CreateCheckoutGrantRequest,
CreateCheckoutGrantResponse, // { grantId, token, expiresAt }
} from '@zkp2p/pay-sdk';
import type { CheckoutGrantCreatedEvent, CheckoutGrantFundingEvent } from '@zkp2p/pay-sdk/embedded';