Dynamic Orders

Dynamic Orders help recover a checkout when no bank or payment-app liquidity can cover the exact order amount. Peer Pay shows the customer specific nearby amounts that are currently available. If the customer selects one, Peer Pay updates the order and reloads payment options for the new amount.

Dynamic Orders are sometimes called dynamic quotes. The feature is based on Curator's nearby quotes, but it also handles the Peer Pay order update, checkout experience, pricing checks, and merchant webhook.

Enable Dynamic Orders

Dynamic Orders are disabled by default. A merchant owner or manager can enable them in the Merchant Dashboard:

1. Open Settings → Payments.
2. Turn on Dynamic orders.
3. Select Save defaults.

The setting becomes the default for new orders. It does not change orders that already exist.

If your account contains multiple merchant profiles, select each profile and enable the setting separately.

Create an order

The recommended integration is to omit dynamicOrdersEnabled when calling createCheckout. New orders then inherit the merchant setting:

import { createCheckout } from '@zkp2p/pay-sdk';

const checkout = await createCheckout(
  {
    requestedFiatAmount: '100.00',
    requestedFiatCurrency: 'USD',
    destinationChainId: 8453,
    destinationToken: 'USDC',
  },
  {
    apiBaseUrl: 'https://api.pay.peer.xyz',
    apiKey: process.env.ZKPAY_API_KEY!,
  },
);

The optional field is a per-order override:

Value	Behavior
Omitted	Inherits the merchant's Dynamic Orders setting.
false	Disables Dynamic Orders for this order.
true	Enables the feature only when it is already enabled for the merchant. If the merchant setting is off, order creation returns 400 DYNAMIC_ORDERS_DISABLED.

The resolved value is saved on the order at creation time. Changing the merchant setting later does not alter that order.

Customer experience

When no supported fiat payment method can cover the original amount, checkout can display Pay less and Pay more options. Each option is a specific amount backed by a nearby quote; it is not a continuous range.

After the customer selects an amount, Peer Pay:

1. Confirms the order is still eligible to change.
2. Updates its requested and remaining USDC amounts.
3. Reloads payment methods for the selected amount.
4. Emits an ORDER_RESIZED webhook.

The merchant receives the amount on the resized order, not the amount originally submitted to createCheckout.

Curator nearby quotes

Curator supplies nearby liquidity suggestions when an exact quote is unavailable. Dynamic Orders add the Peer Pay workflow around those suggestions:

• merchant and per-order enablement;
• Peer Pay fee, rail, order-size, and pricing checks;
• the customer-facing amount selector;
• safe order resizing and quote refresh;
• the ORDER_RESIZED webhook for merchant reconciliation.

Dynamic Orders do not create additional liquidity. They turn Curator's discrete nearby quotes into actionable checkout options. Merchants using hosted checkout do not need to call Curator's nearby-quote API directly.

Handle resized orders

Your webhook handler should treat the amounts in data.order and data.resize as authoritative:

{
  "type": "ORDER_RESIZED",
  "data": {
    "order": {
      "id": "ord_456",
      "requestedUsdcAmount": "95.000000",
      "remainingUsdcAmount": "95.000000"
    },
    "resize": {
      "previousAmountUsdc": "100.000000",
      "newAmountUsdc": "95.000000"
    }
  }
}

Update the corresponding merchant cart, deposit, or account credit to the new amount. See the complete ORDER_RESIZED payload and follow the normal webhook verification and idempotency guidance.

When suggestions do not appear

Nearby amounts are shown only when Peer Pay can safely resize the order and at least one suggestion survives its pricing and order-limit checks. They may not appear when:

• Dynamic Orders were disabled when the order was created;
• an exact fiat payment quote is still available;
• the order has a payment attempt that can still settle, or has been partially settled;
• the checkout is an in-person order;
• the payout requires conversion outside Base USDC;
• no nearby quote satisfies the merchant's enabled rails, order-size limits, or fee settings.

Because liquidity is discrete and changes over time, Peer Pay shows executable nearby amounts rather than a minimum-to-maximum wallet range.