The /api/v1 surface

Seller API (pp_sk_)

{
  "title": "Market report",          // required, <= 120 chars
  "description": "Optional note",    // optional, <= 1000 chars
  "amount": "5.00",                  // required, decimal string in "asset"
  "asset": "USDC" | "EURC",          // optional, default "USDC"
  "destinationWallet": "0x...",      // optional, defaults to your receiving wallet
  "linkType": "single" | "reusable", // optional, default "single"
  "metadata": { "orderId": "A-1042" },        // optional, flat string map
  "clientReferenceId": "order_1042",          // optional, <= 200 chars
  "returnUrl": "https://shop.example/thanks", // optional, https
  "cancelUrl": "https://shop.example/cart"    // optional, https
}

201 { "link": { "publicId", "payUrl", "title", "description",
  "amount", "amountUsdc", "amountUsdcMinor", "asset", "destinationWallet",
  "chainId", "linkType", "status", "metadata", "clientReferenceId",
  "returnUrl", "cancelUrl", "createdAt", "archivedAt" } }
422 { "error", "issues": [{ "path", "message" }] }

200 { "links": [ { ...link, "confirmedPaymentCount" } ] }

200 { "link": { ...link, "metadata", "clientReferenceId",
  "returnUrl", "cancelUrl", "confirmedPaymentCount",
  "attempts": [{ "id", "payerWallet", "expectedAmountUsdcMinor",
    "txHash", "status", "createdAt", "expiresAt",
    "confirmedAt", "failureReason", "simulated" }] } }
404 { "error": "Payment link not found." }

{
  "paymentSignature": "<PAYMENT-SIGNATURE header value>",
  "requirement": {
    "resource": "https://...", "network": "base-sepolia",
    "chainId": 84532, "assetAddress": "0x...",
    "amountUsdcMinor": "100000", "payTo": "0x...",
    "description": "optional"
  }
}

200 PAYMENT-RESPONSE success (settled + verified)
402 PAYMENT-RESPONSE failure (verification or settlement failed)
503 { "error" } when no facilitator key is configured

Link field limits

Validation happens before anything is stored; a violation returns 422 with an issues array naming the offending path. The same limits apply to the dashboard and to checkout.create() in the SDK.

metadata and clientReferenceId also travel on webhook payloads under data.link. The redirect URLs do not — they are only used to build the payer's return link, and the parameters GenesisPay appends to returnUrl are a UI hint, never proof of payment.

Subscription plans (pp_sk_)

A subscription plan is a reusable billing template: an amount, a period, and a hosted page the customer signs their mandate on. Plans used to be dashboard-only — these four routes create, read, and archive them with the same pp_sk_ key as everything else, scoped to your account. Public ids are prefixed sub_.

{
  "title": "Pro plan",              // required, <= 120 chars
  "description": "Monthly access",  // optional, <= 1000 chars
  "amountPerPeriod": "9.00",        // required, decimal string
  "periodDays": 30,                 // required, 1..366
  "prepaidCycles": 12,              // optional, 1..120, default 12
  "destinationWallet": "0x...",     // optional, defaults to your receiving wallet
  "asset": "USDC"                   // optional, "USDC" (default) or "EURC"
}

201 { "plan": { "id", "publicId", "title", "description", "asset",
  "amountPerPeriod", "amountPerPeriodMinor", "periodDays",
  "prepaidCycles", "capPerChargeMinor", "allowanceMinor",
  "destinationWallet", "chainId", "status",
  "checkoutUrl": "https://.../subscribe/sub_...",
  "createdAt", "archivedAt" } }
422 { "error", "issues": [{ "path", "message" }] }

200 { "plans": [ { ...plan } ] }

200 { "plan": { ...plan } }
404 { "error": "Subscription plan not found." }

200 { "plan": { ...plan, "status": "archived", "archivedAt": "..." } }
404 { "error": "Subscription plan not found." }

checkoutUrl is the hosted subscribe flow — the /subscribe/:publicId page where the customer reviews the plan and signs the permit that activates their mandate. Every plan response carries it, so you never build that URL yourself. Send it to the customer, and from then on renewals are the mandate scheduler's job — no per-period cron of your own.

Charging a mandate directly, checking entitlement, and revoking are documented in the subscriptions & metering guide.

List mandates (pp_sk_)

A mandate id used to reach you only through the mandate.active webhook — miss the delivery and the subscription was invisible, including to a customer asking you to cancel it. GET /api/v1/mandates is the read side: your mandates, newest first, filterable by plan and status.

?planId=sub_9lQ1x0m4Tz2vJfKq8Yb3dA  // optional, a plan's public id
&status=active                        // optional, one mandate status
&limit=25                             // optional, 1..100 (default 25)
&startingAfter=<mandate id>           // optional keyset cursor

200 { "mandates": [ { "id", "kind", "status", "asset", "chainId",
    "payerWallet", "destinationWallet", "subscriptionPlanId",
    "allowanceMinor", "capPerChargeMinor", "spentMinor",
    "remainingMinor", "amountPerPeriodMinor", "periodDays",
    "nextChargeAt", "permitDeadline", "permitTxHash",
    "createdAt", "activatedAt", "revokedAt" } ],
  "hasMore": false }
400 { "error", "issues": [{ "path", "message" }] }
400 { "error": "startingAfter is not a mandate of this account." }

Paging is keyset-based, not offset-based. Rows come back ordered by createdAt DESC, id DESC; startingAfter names the last mandate you saw and the next page starts strictly below it in that order. hasMore tells you whether another page exists — it is computed by reading one row past limit, so there is no total count to ask for. The tie-break on id is what keeps a mandate from being skipped or returned twice when two rows share a createdAt.

const baseUrl = process.env.PEERPAY_BASE_URL!;
const headers = { authorization: `Bearer ${process.env.PEERPAY_SELLER_KEY!}` };

const mandates = [];
let startingAfter: string | undefined;
let hasMore = true;

while (hasMore) {
  const url = new URL("/api/v1/mandates", baseUrl);
  url.searchParams.set("limit", "100");
  if (startingAfter) url.searchParams.set("startingAfter", startingAfter);

  const response = await fetch(url, { headers });
  if (!response.ok) throw new Error(await response.text());
  const page = await response.json();

  mandates.push(...page.mandates);

  // The cursor is the id of the LAST row you just read — not an offset and
  // not a page number. Guard on it too: hasMore with an empty page would
  // otherwise loop forever.
  startingAfter = page.mandates.at(-1)?.id;
  hasMore = page.hasMore && startingAfter !== undefined;
}

subscriptionPlanId on each mandate is the internal id of the plan it was signed on, or null when the mandate was proposed directly through POST /api/v1/mandates — that path never sets it, so a caller cannot attribute a mandate to a plan. Filter by plan with the planId query parameter (the public sub_ id), not by comparing this field. The same field travels on mandate webhooks under data.mandate.subscriptionPlanId.

Cancelling a subscription end to end — list a plan's subscribers, pick the mandate, revoke it — is walked through in the subscriptions guide. Proposing, activating, and charging mandates are documented there too.

Test mode: simulate a payment

simulate-payment records a confirmed payment on one of your links without any transaction happening, and fires the real webhooks — payment.confirmed, plus link.paid for a single-use link. That is the point: you can exercise your webhook handler end to end without a funded wallet.

{
  "payerWallet": "0x..."   // optional, defaults to
                           // 0xdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef
}

201 { "attempt": { "id", "payerWallet", "expectedAmountUsdcMinor",
    "txHash": null, "status": "confirmed", "simulated": true,
    "createdAt", "expiresAt", "confirmedAt", "failureReason" },
  "link": { ...link } }
400 { "error": "Request body must be valid JSON." }
403 { "error" }   // live key
404 { "error": "Not found." }               // mainnet deployment
404 { "error": "Payment link not found." }  // not your link
409 { "error" }   // single link already paid, or link archived
422 { "error", "issues": [{ "path", "message" }] }

Test keys only. The endpoint works exclusively with a pp_sk_test_… key; a live key gets 403 with a message saying so. Live keys can only ever record real, on-chain payments.

It does not exist on mainnet. A mainnet deployment answers 404, and that check runs before authentication — so a mainnet deployment never even confirms the route is there, whatever key you present. The two gates are deliberately independent: key mode is a convention of key creation, not an invariant a database row is forced to honour.

Simulated payments are labelled. The attempt carries txHash: null — there is no transaction, and a made-up hash would be a lie in a field other systems point a block explorer at. So txHash alone cannot tell you what you are looking at: a pending real attempt has no hash either. That is why every attempt carries a simulated boolean instead — in the webhook payload under data.attempt.simulated and on GET /api/v1/links/:publicId under attempts[].simulated. It is always present and false for real payments, so a handler can branch on it and analytics can exclude simulated revenue without guessing from the payer wallet.

Agent API (pp_ag_)

{
  "url": "https://api.example.com/report",  // required
  "maxAmountUsdc": "1.00",                  // optional ceiling for this call
  "description": "optional, <= 500 chars"
}

200 { "paymentId", "status": "settled", "txHash",
  "response": { "status", "headers", "bodyBase64", "mimeType" }, "payment" }
202 { "paymentId", "status": "pending_approval", "approvalUrl", "payment" }
400 invalid_url | invalid body
403 { "error", "code": "policy_blocked" }   // allowlist miss, hard block
422 amount_exceeds_max | payment_not_required | unsupported_payment_requirement
502 target_unreachable | { "status": "failed", "error", "payment" }

200 { "payment": { "id", "status", "amountUsdcMinor",
  "resourceUrl", "destinationWallet", "txHash", "failureReason",
  "approvalExpiresAt", "resolvedAt", "settledAt", ... } }
404 { "error": "Agent payment not found." }

200 same shape as /agent/pay when settled
404 not_found
409 not_approved | approval_expired | already_executing
502 { "status": "failed", "error", "payment" }

200 { "name", "walletAddress", "chainId", "status",
  "usdcBalance",                       // minor units string, null if RPC fails
  "policy": { "perPaymentCapUsdcMinor", "dailyCapUsdcMinor",
              "monthlyCapUsdcMinor", "allowlistEnabled" },
  "spentTodayUsdcMinor", "spentThisMonthUsdcMinor" }

Discovery (public)

?q=flight            // optional substring search (title/description/category)
&category=flights    // optional exact category filter
&limit=20            // optional, 1..50 (default 20)

200 { "listings": [{ "title", "description", "priceUsdc",
  "kind": "api" | "link", "resourceUrl", "category" }] }
400 { "error", "issues" }
429 { "error", "code": "rate_limited" }

The payment endpoint itself

Every link is payable directly over HTTP without any GenesisPay key: GET /pay/:linkId with JSON or agent headers returns 402 Payment Required with an x402 V2 PAYMENT-REQUIRED header. Retry with a PAYMENT-SIGNATURE header — either a signed EIP-3009 authorization (GenesisPay settles it on-chain when a facilitator key is configured) or a signature plus a broadcast txHash extension. Browsers hitting the same URL get the hosted checkout.

Webhook signatures are documented on the webhooks page.