name: pinme-uniwebpay description: Use when generating, modifying, or reviewing PinMe Worker (Cloudflare Worker TypeScript) code that accepts payments through UniwebPay — payment links, products/prices, checkout sessions, payment status reads, refunds, subscriptions, or handling UniwebPay webhooks with @uniwebpay/sdk in a PinMe project.

PinMe UniwebPay Payment Integration

Guides writing payment services in a PinMe Worker (Cloudflare Worker TypeScript) that call UniwebPay directly through @uniwebpay/sdk.

Core model: PinMe provisions the UniwebPay wallet and keys per PinMe user (not per project) and injects UNIWEB_* environment bindings at Worker deploy time; Worker code calls UniwebPay directly with the SDK — it does not go through PinMe payment proxy routes, and it must not call the legacy VibeCash APIs.

Environment Binding Contract

export interface Env {
  UNIWEB_SECRET: string;           // PinMe-provisioned sk_server_ key (server-side only)
  UNIWEB_WEBHOOK_SECRET?: string;  // wallet-level whsec_, used to verify webhook signatures
  UNIWEB_API_URL?: string;         // UniwebPay API endpoint override (default https://apiskill.uniwebpay.com)
  UNIWEB_PAY_URL?: string;         // UniwebPay checkout host override (default https://skill.uniwebpay.com)
  UNIWEB_WALLET_ID?: string;       // user-level wallet id (wal_), diagnostics/reconciliation only
  WORKER_URL?: string;             // this project's public URL: https://{projectName}.{platform api domain}
  PROJECT_NAME?: string;           // PinMe project name
  DB?: D1Database;                 // project D1 (if enabled)
}

import Uniweb, { verifyWebhook } from "@uniwebpay/sdk"; export interface Env { UNIWEB_SECRET: string; UNIWEB_WEBHOOK_SECRET?: string; UNIWEB_API_URL?: string; UNIWEB_PAY_URL?: string; UNIWEB_WALLET_ID?: string; WORKER_URL?: string; PROJECT_NAME?: string; DB?: D1Database; } type PaymentMethod = "card" | "wechat" | "alipay" | "paynow"; const VALID_PAYMENT_METHODS = new Set<PaymentMethod>(["card", "wechat", "alipay", "paynow"]); const CARD_CURRENCIES = new Set(["SGD", "USD", "EUR", "GBP", "JPY", "CNY", "HKD", "AUD", "MYR", "THB"]); // Single source of truth for the webhook path: shared by the router and the // webhookUrl construction so the address sent to UniwebPay always matches the // route the Worker actually serves. const WEBHOOK_PATH = "/api/pay/webhook"; function uniwebClient(env: Env): Uniweb { return new Uniweb(env.UNIWEB_SECRET, { baseUrl: env.UNIWEB_API_URL, payUrl: env.UNIWEB_PAY_URL, }); } function json(data: unknown, init: ResponseInit = {}): Response { return Response.json(data, init); } function assertAmountCents(value: unknown): number { const amount = Number(value); if (!Number.isInteger(amount) || amount < 10) { throw new Error("amountCents must be an integer minor-unit amount >= 10"); } return amount; } function normalizeCurrency(value: unknown): string { const currency = String(value || "SGD").toUpperCase(); if (!/^[A-Z]{3}$/.test(currency)) throw new Error("currency must be an ISO 4217 code"); return currency; } // QR methods (wechat/alipay/paynow) support SGD only; card supports 10 currencies. function defaultPaymentMethods(currency: string): PaymentMethod[] { if (currency === "SGD") return ["card", "wechat", "alipay", "paynow"]; if (CARD_CURRENCIES.has(currency)) return ["card"]; throw new Error(`unsupported currency: ${currency}`); } function normalizePaymentMethods(value: unknown, currency: string): PaymentMethod[] { const requested = Array.isArray(value) && value.length > 0 ? value : defaultPaymentMethods(currency); const methods = requested.map((m) => String(m).toLowerCase() as PaymentMethod); for (const method of methods) { if (!VALID_PAYMENT_METHODS.has(method)) { throw new Error("paymentMethodTypes contains an unsupported method"); } if (method !== "card" && currency !== "SGD") { throw new Error(`${method} only supports SGD payments`); } if (method === "card" && !CARD_CURRENCIES.has(currency)) { throw new Error(`card does not support ${currency}`); } } return Array.from(new Set(methods)); } // Prefer the PinMe-injected WORKER_URL (the project's platform subdomain, the // only public address available at runtime). request.url is only a fallback for // older deploys; cron/queue contexts have no request, so WORKER_URL is required. function projectWebhookUrl(env: Env, request?: Request): string { const base = env.WORKER_URL || request?.url; if (!base) throw new Error("WORKER_URL binding is missing"); return new URL(WEBHOOK_PATH, base).toString(); } // ---- One-time collection: payment link ---- async function createPaymentLink(request: Request, env: Env): Promise<Response> { if (request.method !== "POST") return json({ error: "method not allowed" }, { status: 405 }); let input: any; try { input = await request.json(); } catch { return json({ error: "invalid JSON body" }, { status: 400 }); } let amount: number, currency: string, paymentMethodTypes: PaymentMethod[]; try { amount = assertAmountCents(input.amountCents); currency = normalizeCurrency(input.currency); paymentMethodTypes = normalizePaymentMethods(input.paymentMethodTypes, currency); } catch (err) { return json({ error: (err as Error).message }, { status: 400 }); } const orderId = input.orderId || crypto.randomUUID(); const uniweb = uniwebClient(env); try { const link = await uniweb.links.create({ amount, currency, name: input.name || "Payment", description: input.description, successUrl: input.successUrl, cancelUrl: input.cancelUrl, webhookUrl: projectWebhookUrl(env, request), paymentMethodTypes, metadata: { orderId, projectName: env.PROJECT_NAME }, }); return json({ orderId, linkId: link.id, url: link.url }); } catch { return json({ error: "failed to create payment link" }, { status: 502 }); } } // ---- Dynamic orders: checkout session ---- // Note: checkout.create has no webhookUrl; the callback is set on the product. // Stable catalog items should create the product/price once and persist the // priceId — do not create new ones on every request. async function createCheckoutSession(request: Request, env: Env): Promise<Response> { if (request.method !== "POST") return json({ error: "method not allowed" }, { status: 405 }); let input: any; try { input = await request.json(); } catch { return json({ error: "invalid JSON body" }, { status: 400 }); } let amount: number, currency: string, paymentMethodTypes: PaymentMethod[]; try { amount = assertAmountCents(input.amountCents); currency = normalizeCurrency(input.currency); paymentMethodTypes = normalizePaymentMethods(input.paymentMethodTypes, currency); } catch (err) { return json({ error: (err as Error).message }, { status: 400 }); } const orderId = input.orderId || crypto.randomUUID(); const quantity = Math.max(1, Math.floor(Number(input.quantity || 1))); const uniweb = uniwebClient(env); try { const product = await uniweb.products.create({ name: input.productName, webhookUrl: projectWebhookUrl(env, request), metadata: { orderId, projectName: env.PROJECT_NAME }, }); const price = await uniweb.prices.create({ productId: product.id, amount, currency, type: "one_time", metadata: { orderId, projectName: env.PROJECT_NAME }, }); const session = await uniweb.checkout.create({ mode: "payment", lineItems: [{ priceId: price.id, quantity }], successUrl: input.successUrl, cancelUrl: input.cancelUrl, customerEmail: input.customerEmail, paymentMethodTypes, metadata: { orderId, projectName: env.PROJECT_NAME }, }); if (env.DB) { await env.DB.prepare( `INSERT INTO orders(order_id, checkout_session_id, status, amount_cents, currency, created_at) VALUES (?, ?, 'pending', ?, ?, ?) ON CONFLICT(order_id) DO UPDATE SET checkout_session_id = excluded.checkout_session_id`, ) .bind(orderId, session.id, amount * quantity, currency, Math.floor(Date.now() / 1000)) .run(); } return json({ orderId, checkoutSessionId: session.id, url: session.url }); } catch { return json({ error: "failed to create checkout session" }, { status: 502 }); } } // ---- Webhook handling ---- async function handleUniwebWebhook(request: Request, env: Env): Promise<Response> { if (request.method !== "POST") return json({ error: "method not allowed" }, { status: 405 }); if (!env.UNIWEB_WEBHOOK_SECRET) { return json({ error: "webhook verification is not configured" }, { status: 501 }); } const rawBody = await request.text(); let event: Awaited<ReturnType<typeof verifyWebhook>>; try { event = await verifyWebhook( rawBody, request.headers.get("uniweb-Signature") || "", env.UNIWEB_WEBHOOK_SECRET, ); } catch { return json({ error: "invalid signature" }, { status: 400 }); } try { if (env.DB) { const object = event.data.object as { metadata?: Record<string, unknown> }; const orderId = String(object?.metadata?.orderId || ""); const now = Math.floor(Date.now() / 1000); // event.id idempotency: duplicate deliveries become no-ops await env.DB.prepare( `INSERT INTO payment_events(event_id, event_type, order_id, raw_payload, created_at) VALUES (?, ?, ?, ?, ?) ON CONFLICT(event_id) DO NOTHING`, ) .bind(event.id, event.type, orderId, rawBody, now) .run(); if (event.type === "payment.succeeded" && orderId) { // Production code should verify amount/currency/order state here before fulfilling await env.DB.prepare( `UPDATE orders SET status = 'paid', paid_at = ?, updated_at = ? WHERE order_id = ? AND status != 'paid'`, ) .bind(now, now, orderId) .run(); } } return json({ ok: true }); } catch { // 500 makes UniwebPay retry on the 5m/30m/2h/12h schedule return json({ error: "processing error" }, { status: 500 }); } } // ---- Router ---- export default { async fetch(request: Request, env: Env): Promise<Response> { const url = new URL(request.url); // The webhook must come before any project auth guard: callbacks carry only // uniweb-Signature, never the project API_KEY. if (url.pathname === WEBHOOK_PATH) return handleUniwebWebhook(request, env); // The project's own auth guard goes after this point, on the business routes. if (url.pathname === "/api/pay/link") return createPaymentLink(request, env); if (url.pathname === "/api/pay/checkout") return createCheckoutSession(request, env); return json({ error: "not found" }, { status: 404 }); }, };

Scenario	Approach	Returns
Fixed-amount one-time collection	`uniweb.links.create(...)`	Permanent, reusable `/p/` link (one-time payments only)
Stable product catalog	`products.create` + `prices.create` once, store the `priceId`	Price carries a permanent `paymentUrl` (`/buy/` link)
Dynamic cart/order	Reuse or create a price, then `uniweb.checkout.create(...)`	`session.url` — one-time, expires in 24 hours
Subscriptions	Recurring price + `checkout.create({ mode: "subscription" })` or `subscriptions.create`	Same as above
Server-side payment status checks	`payments.get / list`	Server routes only

Method	Supported currencies
`card`	SGD, USD, EUR, GBP, JPY, CNY, HKD, AUD, MYR, THB (minimum 10 minor units)
`wechat`	SGD only
`alipay`	SGD only
`paynow`	SGD only

Mistake	Consequence / fix
Webhook route blocked by the project's `API_KEY` / bearer auth guard	Callbacks get 401/403 and orders stay pending forever. Exempt `WEBHOOK_PATH`; trust comes solely from signature verification
Forgetting to set `webhookUrl` on the link/product	Events fall through to PinMe's managed fallback and are discarded; the Worker never sees them. Business events must point per-link/per-product at this Worker
Passing `webhookUrl` to `checkout.create`	The field does not exist. Set it on the backing product
Fulfilling on a `successUrl` redirect	Forgeable. Fulfill only from verified webhooks or server-side verification
Hardcoding the callback host or relying only on `request.url`	Build from `env.WORKER_URL`; `request.url` is a fallback only
Pairing CNY with wechat/alipay	Source limits QR methods to SGD only; CNY can only use card
Creating a new product/price on every request	Create stable catalog items once, persist and reuse the `priceId`
Calling `webhooks.set/remove/rollSecret` or `wallet.update` in ordinary business flows	Mutates/rotates the wallet callback and `whsec_` shared by ALL of the user's projects. Generate only for explicit wallet-administration requests with admin authorization
Using floating-point major units for amounts	Always integer minor units
Using `process.env` in the Worker or importing the SDK in the browser	Use the `env` argument; the SDK rejects browser environments
Putting `UNIWEB_SECRET` / `whsec_` in `wrangler.toml`, source, logs, or D1	PinMe injects them at deploy time; locally use an uncommitted `.dev.vars` only
Reading the body more than once, or as JSON, before verification	Read with `request.text()` exactly once and pass the raw string to `verifyWebhook`

pinme-uniwebpay

Install

Related skills

PinMe UniwebPay Payment Integration

Environment Binding Contract

SDK Client

Choosing an Integration Path

Payment Methods and Currency Rules

SDK Surface Quick Reference

Webhook Integration

Callback URL: set it on the link/product, pointing at this Worker

Verification and Handling

Security Rules

Persistence Guidance (D1)

Worker Reference Implementation

Common Mistakes

Finish Checklist