PolyPay
Intermediate8 min read

Skill Quick Integration

A production-grade PolyPay integration Skill for Codex, Cursor, and other AI coding tools. It selects Hosted Checkout, SDK, REST, x402, MCP, or an official plugin by runtime and security boundary, then verifies the result through Sandbox and signed callbacks.

What This Skill Does

  • Detects browser, Node.js, PHP/Laravel, WordPress/WooCommerce, WHMCS, and Shopify host environments.
  • Uses Hosted Checkout by default; `/checkout` detects language, while `/{locale}/checkout` pins an explicit locale.
  • Uses the JavaScript SDK with a Public Key and server-generated signed parameters without exposing an API Key.
  • Uses `polypay/php-sdk` on PHP servers, REST for ordinary Node.js API Key orders, and `@polypay/sdk/x402` only for Node.js x402.
  • Requires Sandbox order, webhook signature, replay protection, idempotency, and reconciliation checks before production verification.
  • Runs x402 only on the server; the current standard exact flow supports Circle USDC on Base, Ethereum, Polygon, Arbitrum, and Optimism.
  • Uses `wallet_income` and `wallet_expense`, respects system-managed balance, security, subscription, and quota emails, and supports Email, Telegram, WhatsApp, Webhook, WeCom, Discord, Feishu, and other current channels. Telegram retries only replay-safe DNS, connection, 429, 408, and 5xx failures; uncertain outcomes remain available for manual review.
  • Supports least-privilege PolyPay MCP access to orders, Webhooks, x402 resources, and integration docs.
  • Keeps changes minimal and reports validation evidence, the Sandbox path, and remaining production checks.

Quick Install

Send the message below to the AI coding tool you are already using. The AI can choose the right install or reference method for Codex, Claude Code, Cursor, Windsurf, Cline, GitHub Copilot, or Gemini CLI.

Install and use the PolyPay SDK Integration Skill:
https://github.com/PolyPayAi/polypay-sdk-integration-skill

After it is available, integrate the official PolyPay SDK according to this project's structure.

View GitHub repository

Recommended Flow

  1. Enable the Skill inside the target project.
  2. The AI inspects runtime, order models, payment abstractions, callback routes, and validation commands.
  3. The AI chooses the smallest correct Hosted Checkout, browser Public Key, PHP SDK, Node.js REST, x402, MCP, or official-plugin mode.
  4. The AI adds environment-variable names, order identifier mapping, checkout redirect, and verified, replay-resistant, idempotent Webhook handling when required.
  5. The AI uses a Sandbox Key and covers paid, failed, expired, duplicate callback, and invalid signature cases.
  6. The AI runs typecheck/build/test and reports evidence, the manual path, and remaining production verification.

Example Prompts

Integrate PolyPay into my Laravel project. Use the PHP SDK to create orders and add webhook signature verification.

Add PolyPay frontend checkout to this Next.js project. Use @polypay/sdk to redirect to hosted checkout, and do not build a custom payment-method selection page.

Integrate PolyPay Notification Center into this project. Add Telegram wallet income/expense notification templates with both English and Chinese support.

Protect this Next.js server route with @polypay/sdk/x402. Verify the 402, signature, and single-settlement flow with mocks and protocol vectors before any explicitly authorized production settlement.

Configure least-privilege PolyPay MCP access for an AI client that may only read orders and integration docs.

Add a PolyPay payment entry to this WordPress plugin. Read the API Key from the admin settings instead of hardcoding it.

Security Boundaries

  • API Keys are server-side only and must never enter browser code.
  • Public Keys can be used in frontend code, but require a domain whitelist.
  • Browser Hosted Checkout requires server-generated signed parameters; finished code must not omit the signature or leave a placeholder.
  • Payment method selection belongs in PolyPay hosted checkout by default.
  • Verified Webhooks or authenticated server reconciliation are the source of truth, not redirects, popup closure, or client polling.
  • Webhook handlers verify the raw body, timestamp window, nonce, and signature, and fulfill each order only once.
  • Notification template content is locale-scoped, while template status is event-scoped across all locales and must not overwrite merchant-customized content. Subscription system notices cannot be overridden by templates.
  • The Skill writes environment-variable names, never commits real secrets, and does not execute production charges or settlements without authorization.

JavaScript SDK · API Key · PHP SDK

Previous
MCP Integration