Skip to main content

Checkout grants

A checkout grant is permission for one user to create one payout or one on-ramp order on Peer's hosted page. You mint it from your backend; the user supplies the money details there. The checkout grants guide explains when to use one and what your app must do.

EndpointAuthUse it when
POST /api/v1/checkout-grantsAPI keyA user asks to cash out or to buy USDC

There is no read, list or cancel for grants. An unused grant expires by itself. Once it is used, you follow the payout or order it created, which carries checkoutGrantId.

Create a grant​

POST /api/v1/checkout-grants
X-API-Key: <your key>
Content-Type: application/json

Request body​

FieldTypeDescription
kind"PAYOUT" or "ONRAMP"What the user may create. PAYOUT needs a live key, like payouts
merchantReferencestring?Your own reference, 1–128 characters. Copied to the payout, or to notes.merchantReference on the order
returnUrlstring?An https:// URL the user returns to. Becomes the payout's returnUrl or the order's successUrl
amountLimit{ min?: string, max?: string }?USDC bounds for the amount the user may choose. Equal min and max fix the amount. For PAYOUT the range must contain a multiple of your payout step
expiresInSecondsnumber?How long the grant can wait for its first use: 60 to 3600, 900 by default

Unknown fields are rejected. In particular the request can't carry an email, a refund or destination address, payment methods or a fee: those are not yours to set on a grant.

Response​

{
"success": true,
"message": "Checkout grant created",
"responseObject": {
"grantId": "cmh2f9k3q0001s60h7n2x4v8b",
"token": "9f2c…",
"expiresAt": "2026-11-16T10:57:00.000Z"
},
"statusCode": 201
}

Hand grantId and token to your app. It builds the link itself:

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

See the link for the optional prefills. The token only opens the page; it can't read the payout or order the grant goes on to create.

Errors​

Failures use the standard envelope with success: false.

StatuserrorCodeWhen
400noneThe body failed validation; details in responseObject.fieldErrors
400GRANT_AMOUNT_LIMIT_INVALIDamountLimit is malformed, has min above max, or holds no multiple of your payout step
401noneMissing or invalid API key
403IP_NOT_ALLOWEDYour IP allowlist refused the request
403MERCHANT_SUSPENDEDYour account is suspended
429CHECKOUT_GRANT_MINT_RATE_LIMITEDMore than your hourly grant limit (600 by default)

A grant is also refused when you couldn't create the thing it is for. These carry the same codes as the direct call:

kindCodes
PAYOUTPAYOUT_SANDBOX_UNSUPPORTED, PAYOUTS_DISABLED, PAYOUT_NO_RAILS_AVAILABLE, MERCHANT_CONFIG_MISSING, PAYOUT_MERCHANT_WALLET_MISSING, PAYOUT_MASTER_MERCHANT_WALLET_MISSING; see payout errors
ONRAMPMERCHANT_CONFIG_MISSING, MERCHANT_TIER_FORBIDDEN, MERCHANT_IDENTITY_OVERDUE, NO_ELIGIBLE_PAYMENT_RAILS, MERCHANT_MONTHLY_ORDER_LIMIT_EXCEEDED

The same checks run again when the user submits, because your settings can change in between. Refusals at that point are shown to the user on Peer's page as "can't take this right now".

What a grant creates​

kindCreatesHow it differs from one you create yourself
PAYOUTA payout for the Peer account the user signed in toThe user funds it and always names a refund address. You can still read and list it, and its webhooks fire as usual
ONRAMPA fixed-amount orderThe destination is the user's address, always USDC on Base, and the amount can't be resized

Both carry checkoutGrantId: the grant's id on a payout or order made from a grant, null on every other one.

The page's own calls​

Peer's page talks to four more routes under /api/v1/checkout-grants/{id}, authenticated by the grant token plus the user's own proof (their Peer sign-in, or a secret held in their browser). They are not part of the merchant API: they accept no API key and answer only Peer's checkout.