Skip to main content

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.

EndpointAuthUse it when
POST /api/v1/payoutsAPI keyA customer asks to withdraw
GET /api/v1/payouts/{id}API keyYou want funding progress and status for one payout
GET /api/v1/payoutsAPI keyYou want a filtered page of payouts
POST /api/v1/payouts/{id}/cancelAPI keyYou 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, token 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913). 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 and near_intents_133701 for 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.

CodeNamePrefixRails
USDUnited States Dollar$venmo, cashapp, paypal, wise, zelle, revolut, chime
EUREuro€paypal, wise, revolut
GBPBritish Pound£paypal, wise, revolut
AUDAustralian DollarA$paypal, wise, revolut
CADCanadian DollarC$paypal, wise, revolut
CHFSwiss FrancCHF wise, revolut
CNYChinese YuanCN¥wise, revolut
MXNMexican PesoMX$wise, revolut
NZDNew Zealand DollarNZ$paypal, wise, revolut
SGDSingapore DollarS$paypal, wise, revolut
TRYTurkish Lira₺wise, revolut
ZARSouth African RandRwise, 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.

  1. Buffer: 1% of 100 = 1. The conversion must deliver 100 + 1 = 101 USDC.
  2. 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).
  3. 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 sendYou get
A new key201 and a new payout, with checkoutUrl and idempotentReplay: false
The same key and the same body200 with the existing payout, a current checkoutUrl and idempotentReplay: true
The same key and a different body409 IDEMPOTENCY_KEY_CONFLICT
The same key while the first request is still running409 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​

FieldTypeDescription
customerEmailstringThe customer's email, up to 254 characters. Lower-cased
payout.amountstringUSDC owed to the customer, a decimal with at most 6 decimals
payout.chainIdnumberMust be 8453
payout.tokenAddressstringMust be Base USDC
funding.chainIdnumberChain 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.tokenAddressstringToken you fund with. Use 0x0000000000000000000000000000000000000000 for a chain's native token, and bc1qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqmql8k8 for BTC on Bitcoin
funding.refundAddressstring?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
merchantReferencestring?Your own reference, 1–128 characters. List matches it exactly
returnUrlstring?An https:// URL the customer returns to when done
railsPayoutRailType[]?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​

FieldDescription
payoutId, merchantReference, returnUrlThe payout id, your reference and your return URL
statusSee lifecycle
fundingStatusAWAITING_FUNDING, PARTIALLY_FUNDED, FUNDED, or FUNDING_EXPIRED
payoutThe requested payout: amount, chainId, tokenAddress, decimals
merchantFeebps, and amount in USDC estimated from the quoted deposit, rounded down. The bps applies to what is actually deposited
masterMerchantPayoutFeeThe master merchant payout fee, estimated like merchantFee. { "bps": 0, "amount": "0.00" } when none applies
funding.chainId, funding.tokenAddress, funding.decimalsThe funding chain, token and token decimals
funding.amountWhat you send, in the funding token
funding.depositAddressWhere 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.receivedAmountUSDC that has reached the customer's wallet on Base so far, after conversion and fees
funding.sentAmountWhat 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.missingAmountfunding.amount minus funding.sentAmount, never below 0
funding.expectedAmountThe USDC the quote delivers on Base: the payout plus the buffer
funding.quoteExpiresAt, expiresAtThe funding deadline (both always equal); see Funding
depositAmountThe USDC the payout pays out, set when it is funded; null until then. See deposit size
paidAmountUSDC buyers have paid the customer across every listing, partial payments included. A crypto payout never counts here
payoutCurrencyThe fiat currency of the customer's chosen payout method, or null for crypto or no method
partialFillsOne 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
settlementSet 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
attemptThe 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
payoutTransferSet 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)
cancelSourceOnce cancelled: MERCHANT (you) or PEER_APP (the customer withdrew or spent the money in the Peer app); otherwise null
fundedAt, settledAt, cancelledAt, createdAtWhen 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​

statusMeaningWebhook when it starts
AWAITING_FUNDINGWaiting for your fundsPAYOUT_ORDER_CREATED
FUNDEDThe USDC is in the customer's Peer wallet; they haven't picked a payout method that is readyPAYOUT_ORDER_FUNDED
READYThe customer's payout method is ready to confirm, or a confirmed crypto payout is on its waynone
LISTINGListed for buyers to pay what is left, or a remainder is on its way as cryptonone, or PAYOUT_ORDER_PARTIALLY_PAID when it returns after a partial payment
PAYINGA buyer is paying. The customer can't change the payout methodPAYOUT_ORDER_MATCHED
SETTLEDThe payout ended; settlement says where the USDC wentPAYOUT_ORDER_SETTLED
CANCELLEDEnded before any buyer paid part of it; see cancelSourcePAYOUT_ORDER_CANCELLED
EXPIREDNo USDC arrived before the funding deadlinePAYOUT_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​

  1. You send the funding token to the deposit address.
  2. Relay, the conversion service behind the address, converts it and delivers USDC on Base to the customer's Peer wallet.
  3. 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 happenedfundingStatusstatusWebhook
USDC covering the payout arrived, or you sent the full funding.amount and the conversion finishedFUNDEDFUNDEDPAYOUT_ORDER_FUNDED
Some USDC arrived, below the payout, and you sent less than funding.amountPARTIALLY_FUNDEDAWAITING_FUNDINGPAYOUT_ORDER_PARTIALLY_FUNDED, again each time more arrives
The deadline passed with some USDC received and nothing still convertingFUNDEDFUNDEDPAYOUT_ORDER_FUNDED; the deposit is what arrived
As above, with a transfer still convertingPARTIALLY_FUNDEDAWAITING_FUNDINGNone until it lands
A transfer failed or was refunded to your refund addressUnchangedUnchangedNone. 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 convertingFUNDING_EXPIREDEXPIREDPAYOUT_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 receiveddepositAmountWhy
200.30200.00Covers the payout
199.96199.9699.96 above the 100 step, more than 1 USDC
100.80100.000.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:

KindWhen
OverpaymentYou 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 fundsUSDC arrived after the payout left AWAITING_FUNDING, or from a transfer that started after the deadline
Route refundRelay 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>
ParameterTypeDescription
customerEmailstring?Exact match, case-insensitive
statusstring?One status value
merchantReferencestring?Exact match
page, limitnumber?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.

  1. 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.
  2. 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.
  3. 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.
  4. 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.
  5. 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:

PlatformMaximum lot (USDC)
Venmo600
Cash App400
PayPal300
Zelle800
Revolut500
Chime600
Wise500

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 idNetworkCoins
relay_1EthereumETH, USDC, USDT, PYUSD, WBTC
relay_10OptimismETH, USDC, USDT
relay_56BNB Smart ChainBNB, USDC, USDT, WBTC
relay_137PolygonUSDC, USDT, WBTC
relay_480World ChainETH, USDC
relay_999HyperliquidHYPE, USDC, USDH
relay_5042ArcUSDC
relay_8453BaseETH, USDC, USDT, SOL, WBTC
relay_42161ArbitrumETH, USDC, USDT, WBTC
relay_8253038BitcoinBTC
relay_728126428TronUSDT
relay_792703809SolanaSOL, USDC, USDT, PYUSD
near_intents_133701ZcashZEC

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.

  1. 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.
  2. 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.
  3. 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 (or LISTING for a remainder) until delivery to the destination is proven; the Base transfer alone sends no webhook.
  4. Delivery settles the payout: PAYOUT_ORDER_SETTLED with a CRYPTO attempt on the network rail, payoutTransfer.amount in the destination token and settlement.sentAmount in 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.sentTo and payoutTransfer.
  • 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:

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

WhenSubject
The payout is fundedYour {amount} from {merchant} is ready
A buyer paid part of itYou were paid part of your withdrawal from {merchant}
It settledYou 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 paymentYour withdrawal from {merchant} is closed
A connection lapsedVerify {Rail} again to keep your withdrawal moving
A buyer dropped outYour {amount} withdrawal is still waiting
A crypto payout was refundedYour 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.

StatuserrorCodeWhen
400INVALID_IDEMPOTENCY_KEYThe Idempotency-Key header is missing or malformed
400PAYOUT_TOKEN_UNSUPPORTEDpayout is not USDC on Base
400PAYOUT_NOT_STEP_MULTIPLEThe payout is below one payout step or not a whole multiple of it
400PAYOUT_FUNDING_TOKEN_UNSUPPORTEDThe funding token is unsupported, switched off by Peer, or not allowed for your account
403IP_NOT_ALLOWEDYour IP allowlist refused the request
403PAYOUT_SANDBOX_UNSUPPORTEDThe API key belongs to a sandbox account
403PAYOUTS_DISABLEDNo payout apps are turned on in your payout settings
403PAYOUT_MERCHANT_WALLET_MISSINGYou charge a merchant fee but have no merchant wallet to receive it
403PAYOUT_MASTER_MERCHANT_WALLET_MISSINGYour Master Merchant Account charges a payout fee but has no wallet to receive it. Contact Peer support
404PAYOUT_NOT_FOUNDNo payout with this id for your account
409MERCHANT_CONFIG_MISSINGYour account setup isn't finished
409IDEMPOTENCY_KEY_CONFLICTThe key was already used with a different body
409IDEMPOTENCY_REQUEST_IN_PROGRESSA request with this key is still being processed
409PAYOUT_NOT_CANCELLABLEstatus or fundingStatus is no longer AWAITING_FUNDING. responseObject is { status, fundingStatus }
409PAYOUT_FUNDING_DETECTEDA transfer to the deposit address was recorded, even a failed or refunded one, so the payout can't be cancelled
422PAYOUT_REQUESTED_RAILS_UNAVAILABLENone of the request's rails is available
422PAYOUT_NO_RAILS_AVAILABLEPeer has switched off every payout app and network you turned on
422PAYOUT_ROUTE_UNQUOTABLEThis funding route can't be priced for the requested payout
422PAYOUT_FUNDING_AMOUNT_TOO_LOWThe payout is too small to route from this funding token. Choose a larger payout or another token
502PAYOUT_PRIVY_WALLET_FAILEDThe customer's wallet could not be prepared. Retry with the same key
502PAYOUT_RELAY_QUOTE_FAILEDThe funding route could not be quoted. Retry with the same key; if it keeps failing, use another funding token
502PAYOUT_RELAY_STATUS_FAILEDFunding 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.