Payouts
A payout pays one of your customers out. You set how much the customer receives in USDC and which token you fund it with. Peer Pay returns a one-off deposit address and an exact funding amount. Whatever you send there is converted to USDC on Base and delivered to the customer's Peer wallet. The customer is identified by email; you never need their wallet address. They then take the money through a payout app or as crypto.
| Endpoint | Auth | Use it when |
|---|---|---|
POST /api/v1/payouts | API key | A customer asks to withdraw |
GET /api/v1/payouts/{id} | API key | You want funding progress and status for one payout |
GET /api/v1/payouts | API key | You want a filtered page of payouts |
POST /api/v1/payouts/{id}/cancel | API key | You no longer want to fund a payout |
Every route returns the same PayoutView shape, and so do the
payout webhooks. Peer Pay detects your funding on its own; see
Funding.
Payouts are live-only: a sandbox key gets 403 PAYOUT_SANDBOX_UNSUPPORTED. Every payout app is
on by default under Settings → Payouts; with all of them off, creating a payout returns 403
PAYOUTS_DISABLED. See the merchant payouts guide.
Money rules
- The payout is owed and funded in USDC on Base (chain
8453, token0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913). The customer can take it as any supported coin and network. - The amount must be a whole multiple of your payout step, at least one step. You set the step under Settings → Payouts, from 10 to 1,000 USDC (100 by default). There is no maximum.
- Fees come out of what you deposit, so the funding amount is grossed up to cover them:
deposit = (payout + buffer) ÷ (1 − merchant fee − master merchant payout fee − Peer fee).
- Merchant fee: your own markup, 0–1000 bps of the amount funded, paid to your merchant wallet. Only enabled Master Merchant Accounts can set one.
- Master merchant payout fee: what a sub merchant of a Master Merchant Account pays that account, 0–1000 bps of the amount funded.
- Peer fee: set by Peer for your account. It is 0 unless you are on the Concierge plan.
- The buffer covers price movement while your deposit converts: 1% of the payout, capped at 5 USDC, when you fund with a stablecoin; 2%, capped at 10 USDC, for any other token, BTC included. Bitcoin converts only after the network confirms it, so its price can move for longer.
- The customer can use only payout apps that you turned on and Peer allows, and you can fund only
with tokens Peer allows for your account. Crypto networks use
relay_<chainId>rails andnear_intents_133701for Zcash, and the customer sees them as one Crypto option. See the rail values. - A payout keeps the payout apps, fees, fee wallets and payout step it was created with; a settings change applies to new payouts only. Peer can still remove a network from an open payout; see crypto payouts.
Payout currencies
Customers can receive the catalog currencies below on PayPal and Revolut; you still fund and see USD. Payout amounts, fees, limits, refunds and settlement accounting stay in USDC on Base. Fiat fields are information only; never use them to decide how much to fund or refund.
- USD is always 1.00 per USDC. Every other currency is priced by the protocol's onchain price oracle at 0% spread.
- Before a buyer starts paying, the customer sees a "≈" estimate. If the price can't be read, the estimate disappears, but the currency stays available and nothing is blocked. Once a buyer starts paying, their rate is fixed for that payment, even if the rest is paid later at another rate.
- PayPal and Revolut offer every currency in their catalog by default. No admin or merchant currency setting is required.
- If the customer changes the method or currency after listing, the listing is withdrawn, the
payout returns to
FUNDED, and parts already paid keep their original currency. - If a buyer pays the customer in a different currency, the payment is converted at a cross-currency penalty, which can leave a partial payment.
The catalog is exported as PAYOUT_RAIL_CURRENCIES and PAYOUT_CURRENCY_INFO from
@zkp2p/pay-shared. Every currency has two minor units. Rails lists the payout apps that pay
each currency.
| Code | Name | Prefix | Rails |
|---|---|---|---|
| USD | United States Dollar | $ | venmo, cashapp, paypal, wise, zelle, revolut, chime |
| EUR | Euro | € | paypal, wise, revolut |
| GBP | British Pound | £ | paypal, wise, revolut |
| AUD | Australian Dollar | A$ | paypal, wise, revolut |
| CAD | Canadian Dollar | C$ | paypal, wise, revolut |
| CHF | Swiss Franc | CHF | wise, revolut |
| CNY | Chinese Yuan | CN¥ | wise, revolut |
| MXN | Mexican Peso | MX$ | wise, revolut |
| NZD | New Zealand Dollar | NZ$ | paypal, wise, revolut |
| SGD | Singapore Dollar | S$ | paypal, wise, revolut |
| TRY | Turkish Lira | ₺ | wise, revolut |
| ZAR | South African Rand | R | wise, revolut |
The CHF prefix includes a trailing space. Limits are in USDC only; there are no per-currency
fiat limits.
Worked example
You ask for a 100 USDC payout, fund it with USDC and charge a 100 bps (1%) merchant fee, and Peer charges your account a 200 bps Peer fee.
- Buffer: 1% of 100 = 1. The conversion must deliver 100 + 1 = 101 USDC.
- Fees take 100 + 200 = 300 bps (3%) of the deposit, so the deposit is 101 ÷ 0.97 = 104.123712 USDC (rounded up to the last unit).
- Your merchant fee is 1% of 104.123712 = 1.041237 USDC (rounded down).
A 1,000 USDC payout hits the 5 USDC buffer cap: 1005 ÷ 0.97 = 1036.082475 funded, with a 10.360824 merchant fee.
A sub merchant whose Master Merchant Account charges a 100 bps payout fee, with the same Peer
fee, also funds 104.123712 USDC for a 100 USDC payout. It has no merchant fee of its own, and
masterMerchantPayoutFee is 1.041237 USDC.
The response carries the final numbers. Fund exactly funding.amount; don't recompute it.
Idempotency-Key header
POST /api/v1/payouts requires an Idempotency-Key header: 8–128 letters, digits, _ or -.
Use one key per withdrawal and reuse it on retries.
| You send | You get |
|---|---|
| A new key | 201 and a new payout, with checkoutUrl and idempotentReplay: false |
| The same key and the same body | 200 with the existing payout, a current checkoutUrl and idempotentReplay: true |
| The same key and a different body | 409 IDEMPOTENCY_KEY_CONFLICT |
| The same key while the first request is still running | 409 IDEMPOTENCY_REQUEST_IN_PROGRESS |
checkoutUrl is the link you give the customer. The customer can act through it until the payout
ends (settled, cancelled or expired); after that it only shows how the payout ended. If Peer
rotates the key that signs these links, earlier links stop working; replaying the create request
returns a working link, and owners and managers can copy one from the payout's dashboard page
while the payout is open.
Create a payout
POST /api/v1/payouts
X-API-Key: <your key>
Idempotency-Key: <your key for this withdrawal>
Content-Type: application/json
Request body
| Field | Type | Description |
|---|---|---|
customerEmail | string | The customer's email, up to 254 characters. Lower-cased |
payout.amount | string | USDC owed to the customer, a decimal with at most 6 decimals |
payout.chainId | number | Must be 8453 |
payout.tokenAddress | string | Must be Base USDC |
funding.chainId | number | Chain you fund from: Ethereum (1), Optimism (10), BNB Smart Chain (56), Polygon (137), World Chain (480), Hyperliquid (999), Arc (5042), Base (8453), Arbitrum (42161) or Bitcoin (8253038) |
funding.tokenAddress | string | Token you fund with. Use 0x0000000000000000000000000000000000000000 for a chain's native token, and bc1qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqmql8k8 for BTC on Bitcoin |
funding.refundAddress | string? | Where your funds go back if they can't be converted. Required for Bitcoin: a Bitcoin address you control (bc1…, 1… or 3…; bc1 is stored lower-case). On EVM chains, omit it to refund the sending wallet; set it when you fund from an exchange, because exchange wallets are not refunded |
merchantReference | string? | Your own reference, 1–128 characters. List matches it exactly |
returnUrl | string? | An https:// URL the customer returns to when done |
rails | PayoutRailType[]? | Narrows the payout apps and networks offered to the customer. Requested rails that aren't available are dropped; it never adds a rail you or Peer turned off. If none remain: 422 PAYOUT_REQUESTED_RAILS_UNAVAILABLE |
Unknown fields are rejected. Unknown rail ids (including the retired crypto), an empty rails
list or a repeated rail return 400. Rail order doesn't matter for idempotency, but a different
set of rails is a different body.
Response
{
"success": true,
"message": "Payout created",
"responseObject": {
"payoutId": "cmg1x7k2p0003s60h4f9z2q8d",
"merchantReference": "withdrawal-8841",
"status": "AWAITING_FUNDING",
"fundingStatus": "AWAITING_FUNDING",
"payout": {
"amount": "100.00",
"chainId": 8453,
"tokenAddress": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
"decimals": 6
},
"merchantFee": { "bps": 100, "amount": "1.041237" },
"masterMerchantPayoutFee": { "bps": 0, "amount": "0.00" },
"funding": {
"chainId": 8453,
"tokenAddress": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
"decimals": 6,
"amount": "104.123712",
"depositAddress": "0xe69f55d15f396f82e5da402a475d5fa72c3bd3db",
"quoteExpiresAt": "2026-09-25T18:06:36.911Z",
"receivedAmount": "0.00",
"sentAmount": "0.00",
"missingAmount": "104.123712",
"expectedAmount": "101.00"
},
"depositAmount": null,
"paidAmount": "0.00",
"payoutCurrency": null,
"partialFills": [],
"settlement": null,
"attempt": null,
"payoutTransfer": null,
"cancelSource": null,
"returnUrl": "https://casino.example.com/cashier",
"expiresAt": "2026-09-25T18:06:36.911Z",
"fundedAt": null,
"settledAt": null,
"cancelledAt": null,
"createdAt": "2026-09-24T18:06:36.911Z",
"checkoutUrl": "https://pay.peer.xyz/c/cmg1x7k2p0003s60h4f9z2q8d?t=…",
"idempotentReplay": false
},
"statusCode": 201
}
Send funding.amount of funding.tokenAddress on funding.chainId to funding.depositAddress,
in one or more transfers, before funding.quoteExpiresAt. See Funding.
Never send funds after quoteExpiresAt. Create a new payout with a new idempotency key.
PayoutView fields
| Field | Description |
|---|---|
payoutId, merchantReference, returnUrl | The payout id, your reference and your return URL |
status | See lifecycle |
fundingStatus | AWAITING_FUNDING, PARTIALLY_FUNDED, FUNDED, or FUNDING_EXPIRED |
payout | The requested payout: amount, chainId, tokenAddress, decimals |
merchantFee | bps, and amount in USDC estimated from the quoted deposit, rounded down. The bps applies to what is actually deposited |
masterMerchantPayoutFee | The master merchant payout fee, estimated like merchantFee. { "bps": 0, "amount": "0.00" } when none applies |
funding.chainId, funding.tokenAddress, funding.decimals | The funding chain, token and token decimals |
funding.amount | What you send, in the funding token |
funding.depositAddress | Where you send it. null once the deadline passes, the payout is funded, or it is cancelled or expired; never send when it is null |
funding.receivedAmount | USDC that has reached the customer's wallet on Base so far, after conversion and fees |
funding.sentAmount | What you sent before the deadline, in the funding token. A Bitcoin transfer counts once the conversion service records it, which can wait for confirmation |
funding.missingAmount | funding.amount minus funding.sentAmount, never below 0 |
funding.expectedAmount | The USDC the quote delivers on Base: the payout plus the buffer |
funding.quoteExpiresAt, expiresAt | The funding deadline (both always equal); see Funding |
depositAmount | The USDC the payout pays out, set when it is funded; null until then. See deposit size |
paidAmount | USDC buyers have paid the customer across every listing, partial payments included. A crypto payout never counts here |
payoutCurrency | The fiat currency of the customer's chosen payout method, or null for crypto or no method |
partialFills | One entry per buyer payment that paid only part of a listing, oldest first: amount (USDC), txHash (on Base, lower-case), paidAt, and fiat ({ currency, amount } at that payment's rate, or null if unknown). See partial payments |
settlement | Set only when SETTLED, in USDC: buyerPaidAmount, sentAmount (sent as crypto), returnedAmount (left in or returned to the customer's Peer wallet), dustAmount (a small rest the escrow swept when it closed the listing) and refundFeeAmount (lost on bridge refunds). buyerPaidFiat totals buyer payments per currency (null if any is unknown, [] if no buyer paid). sentTo is the customer's crypto address (EVM lower-case), or null |
attempt | The latest payout attempt, { kind, rail, status }, or null. kind is ESCROW for a buyer-paid listing and CRYPTO for a crypto payout, whose rail is the network, such as relay_42161. status is ACTIVE, CLOSED, SETTLED or FAILED |
payoutTransfer | Set only when SETTLED with crypto sent, including a remainder sent to an address: destination chainId, tokenAddress, decimals, the customer's address (EVM checksummed), the delivered amount in the destination token, the delivering txHash, the Base usdcTxHash, and provider (RELAY, NEAR_INTENTS, or null for direct Base USDC) |
cancelSource | Once cancelled: MERCHANT (you) or PEER_APP (the customer withdrew or spent the money in the Peer app); otherwise null |
fundedAt, settledAt, cancelledAt, createdAt | When the payout was funded, settled, cancelled or created; null until it happens |
The view never includes the customer's email, wallet, payee handle or the Peer fee.
Lifecycle
status | Meaning | Webhook when it starts |
|---|---|---|
AWAITING_FUNDING | Waiting for your funds | PAYOUT_ORDER_CREATED |
FUNDED | The USDC is in the customer's Peer wallet; they haven't picked a payout method that is ready | PAYOUT_ORDER_FUNDED |
READY | The customer's payout method is ready to confirm, or a confirmed crypto payout is on its way | none |
LISTING | Listed for buyers to pay what is left, or a remainder is on its way as crypto | none, or PAYOUT_ORDER_PARTIALLY_PAID when it returns after a partial payment |
PAYING | A buyer is paying. The customer can't change the payout method | PAYOUT_ORDER_MATCHED |
SETTLED | The payout ended; settlement says where the USDC went | PAYOUT_ORDER_SETTLED |
CANCELLED | Ended before any buyer paid part of it; see cancelSource | PAYOUT_ORDER_CANCELLED |
EXPIRED | No USDC arrived before the funding deadline | PAYOUT_ORDER_EXPIRED |
If a buyer's payment lapses, the payout goes back from PAYING to LISTING without a webhook,
and the next buyer sends a new PAYOUT_ORDER_MATCHED.
Partial payments
A buyer can pay part of a listing. Peer Pay records it in paidAmount and partialFills, sends
PAYOUT_ORDER_PARTIALLY_PAID, and the payout returns to LISTING. Partial payments can repeat.
See after a partial payment for how the rest is paid.
After any partial payment, the payout always ends SETTLED, never CANCELLED, with the
breakdown in settlement.
Funding
- You send the funding token to the deposit address.
- Relay, the conversion service behind the address, converts it and delivers USDC on Base to the customer's Peer wallet.
- Peer Pay reads the USDC that reached the wallet on Base and updates the payout. You call nothing; read the payout or listen for the payout webhooks.
| What has happened | fundingStatus | status | Webhook |
|---|---|---|---|
USDC covering the payout arrived, or you sent the full funding.amount and the conversion finished | FUNDED | FUNDED | PAYOUT_ORDER_FUNDED |
Some USDC arrived, below the payout, and you sent less than funding.amount | PARTIALLY_FUNDED | AWAITING_FUNDING | PAYOUT_ORDER_PARTIALLY_FUNDED, again each time more arrives |
| The deadline passed with some USDC received and nothing still converting | FUNDED | FUNDED | PAYOUT_ORDER_FUNDED; the deposit is what arrived |
| As above, with a transfer still converting | PARTIALLY_FUNDED | AWAITING_FUNDING | None until it lands |
| A transfer failed or was refunded to your refund address | Unchanged | Unchanged | None. The payout waits for funds until the deadline, and the refund is recorded as a funding issue |
| The deadline passed, nothing arrived and nothing is converting | FUNDING_EXPIRED | EXPIRED | PAYOUT_ORDER_EXPIRED |
The funding deadline is 24 hours after the payout is created. Each time more USDC arrives on time, it moves to 24 hours after that, if later, so a top-up always has a full day. Only transfers that started by the deadline count, and the payout waits while one of them is still converting. A Bitcoin transfer starts when it is first seen in the mempool, so a transaction broadcast before the deadline counts even if it confirms later. Funds that arrived are never sent back to you: the customer gets whatever arrived when the deadline passes.
Never send funds after quoteExpiresAt. Create a new payout with a new idempotency key.
Deposit size
depositAmount is set when the payout becomes FUNDED, from the USDC received by the deadline:
- If it covers the payout, the deposit is the payout. It never exceeds the payout.
- If it is at most 1 USDC above a whole payout step, it is rounded down to that step.
- Otherwise the deposit is the amount received.
For a 200 USDC payout with a 100 USDC step:
| USDC received | depositAmount | Why |
|---|---|---|
| 200.30 | 200.00 | Covers the payout |
| 199.96 | 199.96 | 99.96 above the 100 step, more than 1 USDC |
| 100.80 | 100.00 | 0.80 above the 100 step, so rounded down |
The last two happen when the conversion delivered less than the payout or the deadline passed before the rest arrived.
If the customer withdraws the listing in the Peer app, depositAmount becomes what the withdraw
returned to their wallet. A later listing or crypto payout pays depositAmount minus
paidAmount minus any earlier bridge refund losses.
Funding issues: late funds, overpayment and route refunds
Money that reaches a payout outside the normal funding path is recorded as a funding issue:
| Kind | When |
|---|---|
| Overpayment | You sent more than funding.amount and more USDC than quoted arrived; the issue is the extra USDC. The conversion delivering slightly over its quote is not an overpayment |
| Late funds | USDC arrived after the payout left AWAITING_FUNDING, or from a transfer that started after the deadline |
| Route refund | Relay could not convert a transfer and sent it back to your refund address (on EVM, the sending wallet if you set none), in the token you sent. Exchange wallets are not refunded |
funding.receivedAmount keeps growing, but the payout never reopens and the money never moves
to another payout. Each issue shows on the payout's dashboard page. Peer support contacts you to
return the funds or record that they were claimed.
Only the quoted route is watched. Funds sent in another token or on another chain are not detected; contact Peer support.
Get a payout
GET /api/v1/payouts/{id}
X-API-Key: <your key>
Returns the PayoutView. A payout that isn't yours returns 404 PAYOUT_NOT_FOUND.
List payouts
GET /api/v1/payouts?customerEmail=customer@example.com&status=AWAITING_FUNDING
X-API-Key: <your key>
| Parameter | Type | Description |
|---|---|---|
customerEmail | string? | Exact match, case-insensitive |
status | string? | One status value |
merchantReference | string? | Exact match |
page, limit | number? | See pagination |
Unknown parameters return 400. The response is { items: PayoutView[], page, limit, total },
newest first.
Cancel a payout
POST /api/v1/payouts/{id}/cancel
X-API-Key: <your key>
You can cancel only while status and fundingStatus are both AWAITING_FUNDING and the
conversion service has no record of any transfer to the deposit address, including failed or
refunded ones. Otherwise the payout keeps waiting and expires at the funding deadline
if no USDC arrives. On success the view comes back CANCELLED with cancelSource: "MERCHANT",
and PAYOUT_ORDER_CANCELLED fires.
Customer checkout
Send the customer to checkoutUrl. The page shows your name, logo and checkout theme from
Settings → Checkout, and the amount: the payout until it is funded, then what the customer
actually receives. You never call the API behind the page.
- Sign in. The customer signs in to their Peer account with a one-time code sent to the payout's email. Another Peer account can't act on the payout.
- Choose how to withdraw. The page offers the fiat payout apps on the payout, one Crypto option for its networks, and Peer app, which leaves the money in the customer's Peer wallet to manage there. When PayPal, Wise or Revolut is offered, the customer also picks a currency.
- Connect, where needed. Venmo, Cash App and PayPal ask the customer to verify the account; on most devices they can also continue without verifying, unless the PayPal account is new to Peer and needs its first connection to register it. Wise asks once, only for a Wisetag new to Peer, and each buyer proves their payment. Zelle, Revolut and Chime have no connect step. See how customers connect.
- Confirm. The customer signs each transfer with their Peer account; Peer submits it and
pays the gas. The unpaid USDC is listed for buyers (
LISTING), or sent as crypto. - Receive. A buyer pays (
PAYING), and the payout settles once the listing is paid.
The checkout has no cancel: the money is already in the customer's own Peer wallet.
A listing is split into the fewest equal lots no larger than the platform's maximum lot, and each buyer pays one lot:
| Platform | Maximum lot (USDC) |
|---|---|
| Venmo | 600 |
| Cash App | 400 |
| PayPal | 300 |
| Zelle | 800 |
| Revolut | 500 |
| Chime | 600 |
| Wise | 500 |
For example, Venmo lists 650 USDC as 2 × 325, and Cash App lists 950 USDC as 4 × 237.50. A
listing must be at least 10 USDC; below that the customer must choose another method. What is left
after a partial payment is listed at any size. An odd amount, such as a short funding, can leave a
dust rest that the escrow sweeps with the last lot; it shows in settlement.dustAmount.
Before any buyer has paid part of the payout, and while no buyer is paying, the customer can
change the payout method: the listing is withdrawn and the payout returns to FUNDED.
The customer can also leave through the Peer app: by withdrawing the listing, or by spending the
funded USDC so their wallet no longer covers the payout. Before any partial payment, the payout
becomes CANCELLED with cancelSource: "PEER_APP" and PAYOUT_ORDER_CANCELLED fires; after
one, it settles with settlement.returnedAmount and PAYOUT_ORDER_SETTLED fires. A customer
whose wallet no longer covers the payout can't confirm it, and the payout closes within a few
minutes.
The page's help link is the customer support link from Settings → Payouts. Without one, the page shows no contact line; it never sends customers to Peer support, because only you can act on their payout. My withdrawals in the page header lists the customer's payouts from you.
Crypto payouts
When the payout's rails include crypto networks, the customer can choose a coin, network and address instead of a payout app. The picker shows only the networks on that payout:
| Rail id | Network | Coins |
|---|---|---|
relay_1 | Ethereum | ETH, USDC, USDT, PYUSD, WBTC |
relay_10 | Optimism | ETH, USDC, USDT |
relay_56 | BNB Smart Chain | BNB, USDC, USDT, WBTC |
relay_137 | Polygon | USDC, USDT, WBTC |
relay_480 | World Chain | ETH, USDC |
relay_999 | Hyperliquid | HYPE, USDC, USDH |
relay_5042 | Arc | USDC |
relay_8453 | Base | ETH, USDC, USDT, SOL, WBTC |
relay_42161 | Arbitrum | ETH, USDC, USDT, WBTC |
relay_8253038 | Bitcoin | BTC |
relay_728126428 | Tron | USDT |
relay_792703809 | Solana | SOL, USDC, USDT, PYUSD |
near_intents_133701 | Zcash | ZEC |
A crypto payout has no buyer, LISTING, PAYING or PAYOUT_ORDER_MATCHED, and the 10 USDC
listing minimum doesn't apply. USDC on Base is a direct transfer, with gas paid by Peer. Every
other coin and network goes through Relay, including swaps on Base, except ZEC, which goes
through NEAR Intents.
- The customer enters an address. Pay checks its format for the network and refuses zero addresses, the customer's own Peer wallet, escrow contracts and token contracts. Smart-contract wallets are accepted.
- The customer reviews what they receive: the exact USDC on Base, or a "≈" estimate for a bridged coin, since network and bridge fees come out of the payout. They must confirm the address can receive that coin on that network.
- On confirmation, Pay sends the unpaid USDC from the customer's wallet. A direct payout settles
when that transfer lands. A bridged payout stays
READY(orLISTINGfor a remainder) until delivery to the destination is proven; the Base transfer alone sends no webhook. - Delivery settles the payout:
PAYOUT_ORDER_SETTLEDwith aCRYPTOattempt on the network rail,payoutTransfer.amountin the destination token andsettlement.sentAmountin USDC.
If the bridge refunds, the USDC returns to the customer's wallet less the bridge's refund fee, and
the payout returns to READY with no merchant webhook. The customer gets an email and can try
again or choose another method; there is no automatic retry. The loss is deducted from what is
paid out next and reported in settlement.refundFeeAmount when the payout settles.
Peer can remove a network, including from open payouts; the customer then chooses another one. A
transfer already on its way finishes or refunds as usual. Use the create request's rails to
narrow the networks yourself. If a route is unavailable or the amount is too small to send as the
chosen coin, the customer is asked to pick another coin or network.
ZEC on Zcash
ZEC payouts go through NEAR Intents to transparent Zcash addresses (t1… or t3…); shielded and
unified addresses are refused. Delivery usually takes up to 30 minutes, and price movement is
bounded by the quote's minimum output. If the transfer can't start in time for the quote, nothing
is sent: a whole payout stays READY so the customer can confirm again, and a remainder settles
with the USDC left in the customer's wallet. ZEC can't fund a payout.
After a partial payment
Each paid lot before the last is a partial payment. Whole lots of the rest stay listed for the next buyer. When a buyer pays only part of a lot, the rest is smaller than the lot and nobody can take it until the customer opens the checkout (from the email link) and presses Resume to relist it. Peer Pay never relists automatically.
While no buyer is paying, the customer can instead:
- Send the rest to a crypto address, if the payout includes a crypto network. It is sent like a
crypto payout, and the payout settles with
settlement.sentAmount,settlement.sentToandpayoutTransfer. - Change the payout method. The listing is withdrawn and the payout returns to
FUNDED; only the unpaid amount is listed or sent next, at any size. - Move the rest in the Peer app. The payout settles with
settlement.returnedAmount.
If a withdrawal lands while a buyer is paying, the listing stops taking new buyers. If that buyer then pays only part, the rest isn't listed again; the customer chooses one of the options above.
Embedding the customer checkout
Pass checkoutUrl through ensureEmbedModeUrl from @zkp2p/pay-sdk/embedded, which adds
embed=true. Inside a frame, the page drops its outer padding, border and shadow. Embedded mode is
in beta; use the hosted page for production.
The checkout posts events to the parent window on channel zkp2p_checkout_embed_v1:
| Event | payload | Meaning |
|---|---|---|
checkout.success | { payoutId, status: "LISTING" } | First listing: listed, not yet paid |
checkout.success | { payoutId, status: "SETTLED" } | The payout settled. A crypto payout posts only this one |
checkout.failed | { payoutId, reason } | reason is EXPIRED or LINK_INVALID |
A Peer-app exit posts nothing. The payment checkout posts its own events.
Customer emails
The customer gets these emails, each linking back to the checkout:
| When | Subject |
|---|---|
| The payout is funded | Your {amount} from {merchant} is ready |
| A buyer paid part of it | You were paid part of your withdrawal from {merchant} |
| It settled | You received {amount} from {merchant}, or Your withdrawal from {merchant} is complete when there were partial payments or part of the money went back to the wallet |
| The customer moved the money in the Peer app before any partial payment | Your withdrawal from {merchant} is closed |
| A connection lapsed | Verify {Rail} again to keep your withdrawal moving |
| A buyer dropped out | Your {amount} withdrawal is still waiting |
| A crypto payout was refunded | Your withdrawal didn’t reach {Network} |
A partial-payment email says whether the rest is waiting for a buyer, needs the customer to press Resume, or needs them to open the checkout. Cancelling before funding sends no email. Once a payout ends, its links only show how it ended.
Errors
Failures use the standard envelope with success: false. The merchant failures below carry an
errorCode; validation failures (400, details in responseObject.fieldErrors),
authentication failures (401), rate limits (429) and unexpected 500s don't.
| Status | errorCode | When |
|---|---|---|
| 400 | INVALID_IDEMPOTENCY_KEY | The Idempotency-Key header is missing or malformed |
| 400 | PAYOUT_TOKEN_UNSUPPORTED | payout is not USDC on Base |
| 400 | PAYOUT_NOT_STEP_MULTIPLE | The payout is below one payout step or not a whole multiple of it |
| 400 | PAYOUT_FUNDING_TOKEN_UNSUPPORTED | The funding token is unsupported, switched off by Peer, or not allowed for your account |
| 403 | IP_NOT_ALLOWED | Your IP allowlist refused the request |
| 403 | PAYOUT_SANDBOX_UNSUPPORTED | The API key belongs to a sandbox account |
| 403 | PAYOUTS_DISABLED | No payout apps are turned on in your payout settings |
| 403 | PAYOUT_MERCHANT_WALLET_MISSING | You charge a merchant fee but have no merchant wallet to receive it |
| 403 | PAYOUT_MASTER_MERCHANT_WALLET_MISSING | Your Master Merchant Account charges a payout fee but has no wallet to receive it. Contact Peer support |
| 404 | PAYOUT_NOT_FOUND | No payout with this id for your account |
| 409 | MERCHANT_CONFIG_MISSING | Your account setup isn't finished |
| 409 | IDEMPOTENCY_KEY_CONFLICT | The key was already used with a different body |
| 409 | IDEMPOTENCY_REQUEST_IN_PROGRESS | A request with this key is still being processed |
| 409 | PAYOUT_NOT_CANCELLABLE | status or fundingStatus is no longer AWAITING_FUNDING. responseObject is { status, fundingStatus } |
| 409 | PAYOUT_FUNDING_DETECTED | A transfer to the deposit address was recorded, even a failed or refunded one, so the payout can't be cancelled |
| 422 | PAYOUT_REQUESTED_RAILS_UNAVAILABLE | None of the request's rails is available |
| 422 | PAYOUT_NO_RAILS_AVAILABLE | Peer has switched off every payout app and network you turned on |
| 422 | PAYOUT_ROUTE_UNQUOTABLE | This funding route can't be priced for the requested payout |
| 422 | PAYOUT_FUNDING_AMOUNT_TOO_LOW | The payout is too small to route from this funding token. Choose a larger payout or another token |
| 502 | PAYOUT_PRIVY_WALLET_FAILED | The customer's wallet could not be prepared. Retry with the same key |
| 502 | PAYOUT_RELAY_QUOTE_FAILED | The funding route could not be quoted. Retry with the same key; if it keeps failing, use another funding token |
| 502 | PAYOUT_RELAY_STATUS_FAILED | Funding could not be checked before cancelling. Retry the cancel |
A request body that fails validation returns 400 before the idempotency key is checked. For
example, Bitcoin funding without refundAddress returns Bitcoin funding needs a refund address
in responseObject.fieldErrors.funding; an invalid Bitcoin refund address returns
Must be a Bitcoin address, a wrong BTC token address Must be the BTC token address, and a
non-EVM token address on another chain Must be an EVM address.
The customer checkout shows its own error messages. They come from the checkout's API, which you never call; if a customer reports one, check the payout's status and timeline in the dashboard.