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.
| Endpoint | Auth | Use it when |
|---|---|---|
POST /api/v1/checkout-grants | API key | A 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
| Field | Type | Description |
|---|---|---|
kind | "PAYOUT" or "ONRAMP" | What the user may create. PAYOUT needs a live key, like payouts |
merchantReference | string? | Your own reference, 1–128 characters. Copied to the payout, or to notes.merchantReference on the order |
returnUrl | string? | 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 |
expiresInSeconds | number? | 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.
| Status | errorCode | When |
|---|---|---|
| 400 | none | The body failed validation; details in responseObject.fieldErrors |
| 400 | GRANT_AMOUNT_LIMIT_INVALID | amountLimit is malformed, has min above max, or holds no multiple of your payout step |
| 401 | none | Missing or invalid API key |
| 403 | IP_NOT_ALLOWED | Your IP allowlist refused the request |
| 403 | MERCHANT_SUSPENDED | Your account is suspended |
| 429 | CHECKOUT_GRANT_MINT_RATE_LIMITED | More 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:
kind | Codes |
|---|---|
PAYOUT | PAYOUT_SANDBOX_UNSUPPORTED, PAYOUTS_DISABLED, PAYOUT_NO_RAILS_AVAILABLE, MERCHANT_CONFIG_MISSING, PAYOUT_MERCHANT_WALLET_MISSING, PAYOUT_MASTER_MERCHANT_WALLET_MISSING; see payout errors |
ONRAMP | MERCHANT_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
kind | Creates | How it differs from one you create yourself |
|---|---|---|
PAYOUT | A payout for the Peer account the user signed in to | The user funds it and always names a refund address. You can still read and list it, and its webhooks fire as usual |
ONRAMP | A fixed-amount order | The 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.