Skip to main content

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.

FunctionRuns inImport from
createCheckoutGrantYour backend@zkp2p/pay-sdk
buildCheckoutGrantUrlYour app@zkp2p/pay-sdk
listenForCheckoutGrantEventsYour 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 };
Server-side only

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 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:

PrefillKindType
amountbothUSDC decimal string
emailpayoutstring
fundingChainIdpayoutnumber
fundingTokenAddresspayoutstring
refundAddresspayoutstring
destinationAddresson-rampstring, 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();
EventFields
onCreatedgrantId, nonce, kind, and payoutId or orderId
onFundinggrantId, 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';