@vobs/payment 0.1.1 → 0.3.0

package/dist/alipay-official.js

@@ -59,7 +59,7 @@ export function createAlipayOfficialDriver(store, options) {
             .map((k) => `${k}=${params[k]}`)
             .join('&');
     }
-    async function gateway(method, bizContent) {
+    async function gateway(method, bizContent, notifyUrl = '') {
         const params = {
             app_id: options.appId,
             method,
@@ -68,12 +68,13 @@ export function createAlipayOfficialDriver(store, options) {
             timestamp: nowTimestamp(),
             version: '1.0',
             biz_content: JSON.stringify(bizContent),
+            ...(notifyUrl ? { notify_url: notifyUrl } : {}),
         };
         params['sign'] = rsaSign(sortParams(params));
         const res = await fetchImpl(baseUrl, {
             method: 'POST',
-            headers: { 'Content-Type': 'application/json' },
-            body: JSON.stringify(params),
+            headers: { 'Content-Type': 'application/x-www-form-urlencoded;charset=UTF-8' },
+            body: new URLSearchParams(params).toString(),
         });
         const body = (await res.json());
         if (!res.ok) {
@@ -81,7 +82,7 @@ export function createAlipayOfficialDriver(store, options) {
         }
         return body;
     }
-    function buildPageUrl(method, bizContent) {
+    function buildPageUrl(method, bizContent, notifyUrl) {
         const params = {
             app_id: options.appId,
             method,
@@ -91,7 +92,7 @@ export function createAlipayOfficialDriver(store, options) {
             version: '1.0',
             biz_content: JSON.stringify(bizContent),
             return_url: '',
-            notify_url: '',
+            notify_url: notifyUrl,
         };
         params['sign'] = rsaSign(sortParams(params));
         const qs = Object.keys(params)
@@ -108,7 +109,7 @@ export function createAlipayOfficialDriver(store, options) {
         };
         if (input.scene === 'pc') {
             // Face-to-face (scan) payment
-            const body = await gateway('alipay.trade.precreate', biz);
+            const body = await gateway('alipay.trade.precreate', biz, input.notifyUrl);
             const resp = body.alipay_trade_precreate_response;
             if (resp?.code !== '10000' || !resp.qr_code) {
                 throw new Error(`alipay_precreate_failed:${resp?.sub_code ?? resp?.msg ?? 'unknown'}`);
@@ -120,21 +121,27 @@ export function createAlipayOfficialDriver(store, options) {
             };
         }
         // h5 / miniapp: mobile web payment (redirect to cashier)
-        return { kind: 'redirect', payUrl: buildPageUrl('alipay.trade.wap.pay', biz) };
+        return { kind: 'redirect', payUrl: buildPageUrl('alipay.trade.wap.pay', biz, input.notifyUrl) };
     }
     function verifyCallback(payload, _headers) {
         // Async notify is a form-encoded string: a=1&b=2&sign=... (URL-decoded)
         let params;
         if (typeof payload === 'string') {
             params = {};
-            for (const pair of payload.split('&')) {
-                const eq = pair.indexOf('=');
-                if (eq > 0) {
-                    const k = decodeURIComponent(pair.slice(0, eq));
-                    const v = decodeURIComponent(pair.slice(eq + 1));
-                    params[k] = v;
+            try {
+                for (const pair of payload.split('&')) {
+                    const eq = pair.indexOf('=');
+                    if (eq > 0) {
+                        const decode = (value) => decodeURIComponent(value.replace(/\+/gu, ' '));
+                        const k = decode(pair.slice(0, eq));
+                        const v = decode(pair.slice(eq + 1));
+                        params[k] = v;
+                    }
                 }
             }
+            catch {
+                return { ok: false, reason: 'bad_payload' };
+            }
         }
         else {
             const obj = payload;
@@ -146,6 +153,9 @@ export function createAlipayOfficialDriver(store, options) {
         }
         // notify_id anti-replay (channel self-verification path)
         const notifyId = params['notify_id'] ?? '';
+        if (notifyId.length === 0) {
+            return { ok: false, reason: 'bad_payload' };
+        }
         if (!store.addNonce(`ali:${notifyId}`)) {
             return { ok: false, reason: 'nonce_reused' };
         }
@@ -187,6 +197,7 @@ export function createAlipayOfficialDriver(store, options) {
     return {
         name: 'alipay_official',
         scenes: ['pc', 'h5', 'miniapp'],
+        callbackVerification: 'driver',
         createOrder,
         verifyCallback,
         queryOrder,

package/dist/handlers.d.ts

@@ -27,10 +27,19 @@ export interface HttpRequestContext {
     readonly headers?: Readonly<Record<string, string | undefined>>;
     readonly body?: string;
 }
-type RouteResult = HttpResponse;
-/** Create a dispatch function (pure logic, no framework dependency). */
+export type PaymentProtectedRoute = 'status' | 'close' | 'confirm';
 export interface PaymentHttpDispatchOptions {
-    readonly authorize?: (action: 'close' | 'confirm', orderId: string, context: HttpRequestContext) => boolean | Promise<boolean>;
+    /**
+     * Authorizes order reads and mutations. The dispatcher denies these routes when omitted;
+     * the host owns authentication, CSRF protection, and order ownership checks.
+     */
+    readonly authorize?: (context: {
+        readonly route: PaymentProtectedRoute;
+        readonly orderId: string;
+        readonly request: HttpRequestContext;
+    }) => boolean | Promise<boolean>;
 }
+type RouteResult = HttpResponse;
+/** Create a dispatch function (pure logic, no framework dependency). */
 export declare function paymentHttpDispatch(manager: PaymentManager, options?: PaymentHttpDispatchOptions): (ctx: HttpRequestContext) => Promise<RouteResult>;
 export {};

package/dist/handlers.js

@@ -28,17 +28,13 @@ function errorStatus(err) {
             return 409;
         case 'channel_unavailable':
             return 503;
-        case 'configuration_error':
-            return 500;
         default:
             return 500;
     }
 }
+/** Create a dispatch function (pure logic, no framework dependency). */
 export function paymentHttpDispatch(manager, options = {}) {
-    const authorize = options.authorize;
-    async function isAuthorized(action, orderId, context) {
-        return (await authorize?.(action, orderId, context)) === true;
-    }
+    const authorize = async (route, orderId, request) => (await options.authorize?.({ route, orderId, request })) === true;
     return async function dispatch(ctx) {
         const { method, path } = ctx;
         if (method === 'GET' && path === '/payment/available-methods') {
@@ -52,7 +48,7 @@ export function paymentHttpDispatch(manager, options = {}) {
             catch {
                 return json(400, { error: 'bad_json' });
             }
-            if (!req || typeof req !== 'object' || Array.isArray(req)) {
+            if (typeof req !== 'object' || req === null || Array.isArray(req)) {
                 return json(400, { error: 'bad_request' });
             }
             const outcome = await manager.createOrder(req);
@@ -64,6 +60,8 @@ export function paymentHttpDispatch(manager, options = {}) {
         const statusMatch = path.match(/^\/api\/payment\/orders\/([^/]+)\/status$/);
         if (statusMatch && method === 'GET') {
             const orderId = statusMatch[1];
+            if (!(await authorize('status', orderId, ctx)))
+                return json(403, { error: 'forbidden' });
             const status = manager.getStatus(orderId);
             if (!status)
                 return json(404, { error: 'order_not_found' });
@@ -72,9 +70,8 @@ export function paymentHttpDispatch(manager, options = {}) {
         const closeMatch = path.match(/^\/api\/payment\/orders\/([^/]+)\/close$/);
         if (closeMatch && method === 'POST') {
             const orderId = closeMatch[1];
-            if (!(await isAuthorized('close', orderId, ctx))) {
+            if (!(await authorize('close', orderId, ctx)))
                 return json(403, { error: 'forbidden' });
-            }
             const status = manager.close(orderId);
             if (!status)
                 return json(404, { error: 'order_not_found' });
@@ -83,9 +80,8 @@ export function paymentHttpDispatch(manager, options = {}) {
         const confirmMatch = path.match(/^\/api\/payment\/orders\/([^/]+)\/confirm$/);
         if (confirmMatch && method === 'POST') {
             const orderId = confirmMatch[1];
-            if (!(await isAuthorized('confirm', orderId, ctx))) {
+            if (!(await authorize('confirm', orderId, ctx)))
                 return json(403, { error: 'forbidden' });
-            }
             const status = manager.confirm(orderId);
             if (!status)
                 return json(404, { error: 'order_not_found' });

package/dist/index.d.ts

@@ -14,12 +14,13 @@
  *
  * const manager = createPaymentManager({
  *   apiKey: process.env.PAYMENT_API_KEY!,
- *   getNotifyUrl: (driver) => `https://pay.example.com/payment/callback/${driver}`,
  *   getOrderAmount: (orderId) => orderDao.find(orderId)?.amount,  // server-side pricing (red line)
  *   onVerified: ({ orderId }) => orderDao.markPaid(orderId),       // idempotent
  * })
  * manager.registerDriver(createMockDriver(store))                  // swap in a real channel driver for P1
- * const dispatch = paymentHttpDispatch(manager, { authorize: requireAdmin })
+ * const dispatch = paymentHttpDispatch(manager, {
+ *   authorize: ({ route, orderId, request }) => access.canPay(request, route, orderId),
+ * })
  * // in your server: app.post('/api/payment/orders', async (req) => dispatch({ method:'POST', path:'/api/payment/orders', body: await req.text() }))
  * ```
  */

package/dist/index.js

@@ -14,12 +14,13 @@
  *
  * const manager = createPaymentManager({
  *   apiKey: process.env.PAYMENT_API_KEY!,
- *   getNotifyUrl: (driver) => `https://pay.example.com/payment/callback/${driver}`,
  *   getOrderAmount: (orderId) => orderDao.find(orderId)?.amount,  // server-side pricing (red line)
  *   onVerified: ({ orderId }) => orderDao.markPaid(orderId),       // idempotent
  * })
  * manager.registerDriver(createMockDriver(store))                  // swap in a real channel driver for P1
- * const dispatch = paymentHttpDispatch(manager, { authorize: requireAdmin })
+ * const dispatch = paymentHttpDispatch(manager, {
+ *   authorize: ({ route, orderId, request }) => access.canPay(request, route, orderId),
+ * })
  * // in your server: app.post('/api/payment/orders', async (req) => dispatch({ method:'POST', path:'/api/payment/orders', body: await req.text() }))
  * ```
  */

package/dist/jeepay.js

@@ -197,6 +197,7 @@ export function createJeepayDriver(_store, options) {
     return {
         name: 'jeepay',
         scenes: ['pc', 'h5', 'miniapp'],
+        callbackVerification: 'driver',
         createOrder,
         verifyCallback,
         queryOrder,

package/dist/lakala.js

@@ -234,6 +234,7 @@ export function createLakalaDriver(_store, options) {
     return {
         name: 'lakala',
         scenes: ['pc', 'h5', 'miniapp'],
+        callbackVerification: 'driver',
         createOrder,
         verifyCallback,
         queryOrder,

package/dist/manager.d.ts

@@ -16,7 +16,7 @@
  */
 import type { AuditEntry, CallbackResult, CreateOrderRequest, CreateOrderResult, GetOrderAmount, OrderState, OrderStatus, PaymentAlert, PaymentConfig, PaymentDriver, PaymentScene, VerifiedResult } from './types.js';
 import { type PaymentStore } from './store.js';
-export type OrderErrorCode = 'order_not_found' | 'amount_mismatch' | 'amount_exceeds_limit' | 'order_conflict' | 'channel_unavailable' | 'configuration_error' | 'bad_request';
+export type OrderErrorCode = 'order_not_found' | 'amount_mismatch' | 'amount_exceeds_limit' | 'order_conflict' | 'channel_unavailable' | 'bad_request';
 export type OrderError = {
     readonly error: OrderErrorCode;
     readonly message?: string;
@@ -30,8 +30,8 @@ export interface PaymentManagerOptions {
     readonly store?: PaymentStore;
     /** Callback signature key (HMAC-SHA256). Inject via KMS/env in production. */
     readonly apiKey?: string;
-    /** Build the public callback URL for a channel driver. Required for non-zero-amount orders. */
-    readonly getNotifyUrl?: (driverName: string) => string;
+    /** Server-owned callback URL, or a resolver for channel-specific callback URLs. */
+    readonly notifyUrl?: string | ((driverName: string) => string);
     /** Server-pricing hook (business: orderId → amount in fen; undefined = order not found). */
     readonly getOrderAmount?: GetOrderAmount;
     /** Business action after booking (deliver/activate) — must be idempotent; on failure the business must retry or compensate manually. */
@@ -56,6 +56,8 @@ export interface PaymentManager {
         readonly orderId: string;
         readonly state: OrderState;
     }[];
+    /** Retries a persisted pending business delivery. Returns undefined when the order is missing. */
+    retryDelivery(orderId: string): Promise<boolean | undefined>;
     handleCallback(driverName: string, ctx: {
         readonly headers: Readonly<Record<string, string | undefined>>;
         readonly body: string;

package/dist/manager.js

@@ -17,22 +17,103 @@
 import { applyClose, applyConfirm, applyPaidCallback } from './state-machine.js';
 import { createMemoryStore } from './store.js';
 import { verifySignedCallback } from './verify.js';
+function isValidAmount(value) {
+    return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0;
+}
+function isValidCreateOrderRequest(req) {
+    if (typeof req !== 'object' || req === null || Array.isArray(req))
+        return false;
+    const value = req;
+    return (typeof value.orderId === 'string' &&
+        value.orderId.trim().length > 0 &&
+        typeof value.subject === 'string' &&
+        value.subject.trim().length > 0 &&
+        isValidAmount(value.amount) &&
+        (value.idempotencyKey === undefined ||
+            (typeof value.idempotencyKey === 'string' && value.idempotencyKey.length > 0)));
+}
 export function createPaymentManager(options = {}) {
     const config = options.config ?? {};
-    const store = options.store ?? createMemoryStore();
+    const store = options.store ??
+        createMemoryStore({
+            ...(config.idempotencyTtlMs === undefined ? {} : { retentionMs: config.idempotencyTtlMs }),
+        });
     const apiKey = options.apiKey;
+    const configuredNotifyUrl = options.notifyUrl;
     const getOrderAmount = options.getOrderAmount;
-    const getNotifyUrl = options.getNotifyUrl;
     const drivers = new Map();
-    const orderLocks = new Map();
+    const pendingOrderCreates = new Map();
+    const pendingIdempotencyCreates = new Map();
+    const pendingDeliveries = new Map();
     const notifyVerified = options.onVerified;
     const notifyAlert = options.onAlert;
+    const notifyUrlFor = (driverName) => {
+        const value = typeof configuredNotifyUrl === 'function'
+            ? configuredNotifyUrl(driverName)
+            : configuredNotifyUrl;
+        return typeof value === 'string' ? value : '';
+    };
     const audit = (entry) => {
         store.appendAudit(entry);
     };
     const alert = (alert) => {
         notifyAlert?.(alert);
     };
+    const verifiedResultFor = (order) => ({
+        orderId: order.orderId,
+        state: 'paid',
+        ...(order.paidAt ? { paidAt: order.paidAt } : {}),
+        ...(order.channelTxnId ? { channelTxnId: order.channelTxnId } : {}),
+    });
+    async function deliverVerified(order) {
+        if (notifyVerified === undefined || order.deliveryState === 'delivered')
+            return true;
+        order.deliveryState = 'pending';
+        delete order.deliveryError;
+        store.saveOrder(order);
+        try {
+            await notifyVerified(verifiedResultFor(order));
+            order.deliveryState = 'delivered';
+            store.saveOrder(order);
+            audit({ operation: 'delivery', orderId: order.orderId, reason: 'delivered', at: Date.now() });
+            return true;
+        }
+        catch (error) {
+            order.deliveryState = 'pending';
+            order.deliveryError = String(error);
+            store.saveOrder(order);
+            audit({ operation: 'delivery', orderId: order.orderId, reason: 'failed', at: Date.now() });
+            alert({
+                level: 'error',
+                code: 'delivery_failed',
+                message: String(error),
+                orderId: order.orderId,
+            });
+            return false;
+        }
+    }
+    function scheduleDelivery(order) {
+        const pending = pendingDeliveries.get(order.orderId);
+        if (pending !== undefined)
+            return pending;
+        const delivery = deliverVerified(order)
+            .catch((error) => {
+            alert({
+                level: 'error',
+                code: 'delivery_failed',
+                message: String(error),
+                orderId: order.orderId,
+            });
+            return false;
+        })
+            .finally(() => {
+            if (pendingDeliveries.get(order.orderId) === delivery) {
+                pendingDeliveries.delete(order.orderId);
+            }
+        });
+        pendingDeliveries.set(order.orderId, delivery);
+        return delivery;
+    }
     function driverOf(name) {
         const driver = drivers.get(name);
         if (!driver)
@@ -51,36 +132,39 @@ export function createPaymentManager(options = {}) {
             createdAt: Date.now(),
         };
     }
-    async function withOrderLock(orderId, operation) {
-        const previous = orderLocks.get(orderId);
-        let release;
-        const current = new Promise((resolve) => {
-            release = resolve;
-        });
-        orderLocks.set(orderId, current);
-        await previous;
-        try {
-            return await operation();
+    function createOrder(req) {
+        if (!isValidCreateOrderRequest(req)) {
+            return Promise.resolve({ error: 'bad_request', message: 'Invalid payment order request' });
         }
-        finally {
-            release?.();
-            if (orderLocks.get(orderId) === current)
-                orderLocks.delete(orderId);
+        const pendingByKey = req.idempotencyKey === undefined
+            ? undefined
+            : pendingIdempotencyCreates.get(req.idempotencyKey);
+        if (pendingByKey !== undefined)
+            return pendingByKey;
+        const pendingByOrder = pendingOrderCreates.get(req.orderId);
+        if (pendingByOrder !== undefined)
+            return pendingByOrder;
+        const operation = createOrderInternal(req);
+        pendingOrderCreates.set(req.orderId, operation);
+        if (req.idempotencyKey !== undefined) {
+            pendingIdempotencyCreates.set(req.idempotencyKey, operation);
         }
+        const releasePending = () => {
+            if (pendingOrderCreates.get(req.orderId) === operation) {
+                pendingOrderCreates.delete(req.orderId);
+            }
+            if (req.idempotencyKey !== undefined &&
+                pendingIdempotencyCreates.get(req.idempotencyKey) === operation) {
+                pendingIdempotencyCreates.delete(req.idempotencyKey);
+            }
+        };
+        void operation.then(releasePending, releasePending);
+        return operation;
     }
-    async function createOrder(req) {
-        return withOrderLock(req.orderId, () => createOrderLocked(req));
-    }
-    async function createOrderLocked(req) {
+    async function createOrderInternal(req) {
         const orderId = req.orderId;
-        if (!orderId || !req.subject || !Number.isSafeInteger(req.amount) || req.amount < 0) {
-            return {
-                error: 'bad_request',
-                message: 'orderId, subject, and a non-negative integer amount are required',
-            };
-        }
-        if (!getOrderAmount) {
-            return { error: 'configuration_error', message: 'getOrderAmount is required' };
+        if (getOrderAmount === undefined) {
+            return { error: 'bad_request', message: 'Server-side order pricing is required' };
         }
         // ① idempotency: same idempotencyKey returns the same order
         if (req.idempotencyKey) {
@@ -98,103 +182,122 @@ export function createPaymentManager(options = {}) {
                 }
             }
         }
-        // ② server-side pricing: amount from business (security red line — never trust the client amount)
-        const expected = await getOrderAmount(orderId);
-        if (expected === undefined) {
-            return { error: 'order_not_found' };
-        }
-        if (!Number.isSafeInteger(expected) || expected < 0) {
-            return {
-                error: 'configuration_error',
-                message: 'getOrderAmount must return a non-negative integer amount',
-            };
-        }
-        if (req.amount !== expected) {
-            return { error: 'amount_mismatch', expected };
-        }
-        // ③ per-order limit: reject over-limit (avoids channel errors/risk control)
-        if (config.maxAmount && expected > config.maxAmount) {
-            return { error: 'amount_exceeds_limit', max: config.maxAmount };
-        }
-        // ④ duplicate guard: an unpaid order already exists
         const existingOrder = store.getOrder(orderId);
-        if (existingOrder && existingOrder.state === 'created') {
-            const strategy = req.duplicateStrategy ?? config.duplicateOrderStrategy ?? 'ask';
-            if (strategy === 'ask') {
-                return {
-                    kind: 'duplicate',
-                    existingOrderId: existingOrder.orderId,
-                    existingAmount: existingOrder.amount,
-                };
+        const reserved = existingOrder === undefined && store.reserveOrder(orderId);
+        if (existingOrder === undefined && !reserved) {
+            return { error: 'order_conflict', message: `order is being created for ${orderId}` };
+        }
+        try {
+            // ② server-side pricing: amount from business (security red line — never trust the client amount)
+            const expected = await getOrderAmount(orderId);
+            if (expected === undefined)
+                return { error: 'order_not_found' };
+            if (!isValidAmount(expected)) {
+                return { error: 'bad_request', message: 'Invalid server-side order amount' };
+            }
+            if (req.amount !== expected)
+                return { error: 'amount_mismatch', expected };
+            // ③ per-order limit: reject over-limit (avoids channel errors/risk control)
+            if (config.maxAmount !== undefined && expected > config.maxAmount) {
+                return { error: 'amount_exceeds_limit', max: config.maxAmount };
+            }
+            // ④ duplicate guard: an unpaid order already exists
+            if (existingOrder && existingOrder.state === 'created') {
+                const strategy = req.duplicateStrategy ?? config.duplicateOrderStrategy ?? 'ask';
+                if (strategy === 'ask') {
+                    return {
+                        kind: 'duplicate',
+                        existingOrderId: existingOrder.orderId,
+                        existingAmount: existingOrder.amount,
+                    };
+                }
+                if (strategy === 'reuse') {
+                    return {
+                        kind: 'ok',
+                        driver: existingOrder.driver,
+                        orderId: existingOrder.orderId,
+                        state: existingOrder.state,
+                        ...(existingOrder.init ? { init: existingOrder.init } : {}),
+                    };
+                }
+                if (strategy === 'reject') {
+                    return { error: 'order_conflict', message: `active order exists for ${orderId}` };
+                }
+                existingOrder.state = 'closed';
+                store.saveOrder(existingOrder);
+                audit({
+                    operation: 'close',
+                    orderId,
+                    from: 'created',
+                    to: 'closed',
+                    reason: 'duplicate_replace',
+                    at: Date.now(),
+                });
+            }
+            // ⑤ zero-amount: skip the channel, mark paid directly
+            if (expected === 0) {
+                const driver = driverOf(req.driver ?? availableDrivers()[0]?.name ?? '');
+                const record = newOrder({ orderId, amount: 0, subject: req.subject, scene: req.scene ?? 'pc', notifyUrl: '' }, driver, 'paid');
+                record.paidAt = new Date().toISOString();
+                store.saveOrder(record);
+                if (req.idempotencyKey)
+                    store.setIdempotencyKey(req.idempotencyKey, orderId);
+                audit({ operation: 'create', orderId, to: 'paid', reason: 'zero_amount', at: Date.now() });
+                void scheduleDelivery(record);
+                return { kind: 'ok', driver: driver.name, orderId, state: 'paid' };
             }
-            if (strategy === 'reuse') {
+            // ⑥ place the order via the channel
+            const driver = driverOf(req.driver ?? availableDrivers()[0]?.name ?? '');
+            const notifyUrl = notifyUrlFor(driver.name);
+            if (driver.callbackVerification === 'driver' && notifyUrl.length === 0) {
                 return {
-                    kind: 'ok',
-                    driver: existingOrder.driver,
-                    orderId: existingOrder.orderId,
-                    state: existingOrder.state,
-                    ...(existingOrder.init ? { init: existingOrder.init } : {}),
+                    error: 'bad_request',
+                    message: 'A server-owned notifyUrl is required for driver-verified callbacks',
                 };
             }
-            if (strategy === 'reject') {
-                return { error: 'order_conflict', message: `active order exists for ${orderId}` };
+            let init;
+            try {
+                init = await driver.createOrder({
+                    orderId,
+                    amount: expected,
+                    subject: req.subject,
+                    scene: req.scene ?? 'pc',
+                    notifyUrl,
+                });
             }
-            // 'replace': close old and create new
-            existingOrder.state = 'closed';
-            audit({
-                operation: 'close',
-                orderId,
-                from: 'created',
-                to: 'closed',
-                reason: 'duplicate_replace',
-                at: Date.now(),
-            });
-        }
-        // ⑤ zero-amount: skip the channel, mark paid directly
-        if (expected === 0) {
-            const driver = driverOf(req.driver ?? availableDrivers()[0]?.name ?? '');
-            const record = newOrder({ orderId, amount: 0, subject: req.subject, scene: req.scene ?? 'pc', notifyUrl: '' }, driver, 'paid');
-            record.paidAt = new Date().toISOString();
-            store.saveOrder(record);
-            if (req.idempotencyKey)
-                store.setIdempotencyKey(req.idempotencyKey, orderId);
-            audit({ operation: 'create', orderId, to: 'paid', reason: 'zero_amount', at: Date.now() });
-            void notifyVerified?.({ orderId, state: 'paid', paidAt: record.paidAt });
-            return { kind: 'ok', driver: driver.name, orderId, state: 'paid' };
-        }
-        // ⑥ place the order via the channel
-        const driver = driverOf(req.driver ?? availableDrivers()[0]?.name ?? '');
-        const notifyUrl = getNotifyUrl?.(driver.name);
-        if (!notifyUrl) {
-            return { error: 'configuration_error', message: 'getNotifyUrl is required for paid orders' };
-        }
-        let init;
-        try {
-            init = await driver.createOrder({
+            catch (error) {
+                alert({
+                    level: 'error',
+                    code: 'channel_error',
+                    message: String(error),
+                    driver: driver.name,
+                });
+                return { error: 'channel_unavailable', message: String(error) };
+            }
+            const record = newOrder({
                 orderId,
                 amount: expected,
                 subject: req.subject,
                 scene: req.scene ?? 'pc',
                 notifyUrl,
-            });
+            }, driver, 'created');
+            record.init = init;
+            store.saveOrder(record);
+            if (req.idempotencyKey)
+                store.setIdempotencyKey(req.idempotencyKey, orderId);
+            audit({ operation: 'create', orderId, to: 'created', at: Date.now() });
+            return {
+                kind: 'ok',
+                driver: driver.name,
+                orderId,
+                state: 'created',
+                ...(init ? { init } : {}),
+            };
         }
-        catch (error) {
-            alert({ level: 'error', code: 'channel_error', message: String(error), driver: driver.name });
-            return { error: 'channel_unavailable', message: String(error) };
+        finally {
+            if (reserved)
+                store.releaseOrderReservation(orderId);
         }
-        const record = newOrder({ orderId, amount: expected, subject: req.subject, scene: req.scene ?? 'pc', notifyUrl }, driver, 'created');
-        record.init = init;
-        store.saveOrder(record);
-        if (req.idempotencyKey)
-            store.setIdempotencyKey(req.idempotencyKey, orderId);
-        audit({ operation: 'create', orderId, to: 'created', at: Date.now() });
-        return {
-            kind: 'ok',
-            driver: driver.name,
-            orderId,
-            state: 'created',
-            ...(init ? { init } : {}),
-        };
     }
     function availableDrivers() {
         return Array.from(drivers.values()).map((d) => ({ name: d.name, scenes: d.scenes }));
@@ -213,6 +316,7 @@ export function createPaymentManager(options = {}) {
         const { state, ok } = applyClose(order.state);
         if (ok) {
             order.state = state;
+            store.saveOrder(order);
             audit({ operation: 'close', orderId, from: before, to: state, at: Date.now() });
         }
         return { state: order.state, ...(order.paidAt ? { paidAt: order.paidAt } : {}) };
@@ -226,13 +330,9 @@ export function createPaymentManager(options = {}) {
         if (ok) {
             order.state = state;
             order.paidAt = new Date().toISOString();
+            store.saveOrder(order);
             audit({ operation: 'confirm', orderId, from: before, to: state, at: Date.now() });
-            void notifyVerified?.({
-                orderId,
-                state: 'paid',
-                paidAt: order.paidAt,
-                ...(order.channelTxnId ? { channelTxnId: order.channelTxnId } : {}),
-            });
+            void scheduleDelivery(order);
         }
         return { state: order.state, ...(order.paidAt ? { paidAt: order.paidAt } : {}) };
     }
@@ -253,6 +353,7 @@ export function createPaymentManager(options = {}) {
                 if (transition.state === 'paid') {
                     order.paidAt = new Date().toISOString();
                 }
+                store.saveOrder(order);
                 audit({
                     operation: 'callback',
                     orderId,
@@ -262,12 +363,7 @@ export function createPaymentManager(options = {}) {
                     at: Date.now(),
                 });
                 if (transition.state === 'paid') {
-                    void notifyVerified?.({
-                        orderId,
-                        state: 'paid',
-                        ...(order.paidAt ? { paidAt: order.paidAt } : {}),
-                        ...(order.channelTxnId ? { channelTxnId: order.channelTxnId } : {}),
-                    });
+                    void scheduleDelivery(order);
                 }
             }
         }
@@ -282,6 +378,7 @@ export function createPaymentManager(options = {}) {
                 const { state, ok } = applyClose(order.state);
                 if (ok) {
                     order.state = state;
+                    store.saveOrder(order);
                     audit({
                         operation: 'close',
                         orderId: order.orderId,
@@ -304,10 +401,10 @@ export function createPaymentManager(options = {}) {
         const timestamp = ctx.headers['x-timestamp'];
         const nonce = ctx.headers['x-nonce'];
         const signature = ctx.headers['x-signature'];
-        const isGenericProtocol = Boolean(timestamp && nonce && signature);
+        const isGenericProtocol = driver.callbackVerification !== 'driver';
         if (isGenericProtocol) {
-            if (!apiKey) {
-                return { ok: false, status: 500, body: { ok: false, error: 'api_key_not_configured' } };
+            if (apiKey === undefined || apiKey.length === 0) {
+                return { ok: false, status: 500, body: { ok: false, error: 'server_configuration' } };
             }
             // generic verification protocol (X-* headers + HMAC-SHA256): for mock/self-built backends
             const verified = await verifySignedCallback({
@@ -384,14 +481,10 @@ export function createPaymentManager(options = {}) {
                 ...(transition.reason ? { reason: transition.reason } : {}),
                 at: Date.now(),
             });
+            store.saveOrder(order);
         }
-        if (transition.state === 'paid' && !('idempotent' in transition && transition.idempotent)) {
-            void notifyVerified?.({
-                orderId: order.orderId,
-                state: 'paid',
-                ...(order.paidAt ? { paidAt: order.paidAt } : {}),
-                ...(order.channelTxnId ? { channelTxnId: order.channelTxnId } : {}),
-            });
+        if (order.state === 'paid' && order.deliveryState !== 'delivered') {
+            void scheduleDelivery(order);
         }
         if (transition.state === 'frozen') {
             alert({
@@ -433,6 +526,12 @@ export function createPaymentManager(options = {}) {
         confirm,
         syncOrderStatus,
         scanExpiredOrders,
+        async retryDelivery(orderId) {
+            const order = store.getOrder(orderId);
+            if (order === undefined)
+                return undefined;
+            return scheduleDelivery(order);
+        },
         handleCallback,
         auditLog: () => store.auditLog(),
     };

package/dist/mock-driver.js

@@ -18,6 +18,7 @@ export function createMockDriver(store, options) {
     return {
         name,
         scenes: ['pc', 'h5'],
+        callbackVerification: 'manager-hmac',
         createOrder(input) {
             if (!alwaysSucceed) {
                 return Promise.reject(new Error('channel_unavailable'));

package/dist/store.d.ts

@@ -9,6 +9,10 @@
 import type { AuditEntry, OrderRecord } from './types.js';
 export interface PaymentStore {
     getOrder(orderId: string): OrderRecord | undefined;
+    /** Atomically reserves an order id before a channel call. Returns false when it is already reserved or persisted. */
+    reserveOrder(orderId: string): boolean;
+    /** Releases an unpersisted reservation after a failed create attempt. */
+    releaseOrderReservation(orderId: string): void;
     saveOrder(order: OrderRecord): void;
     /** Iterate all orders (for expiry scans; production implementations should paginate/index). */
     allOrders(): readonly OrderRecord[];
@@ -19,5 +23,11 @@ export interface PaymentStore {
     appendAudit(entry: AuditEntry): void;
     auditLog(): readonly AuditEntry[];
 }
-/** In-memory implementation (single process; use an internal mutex for concurrent safety). */
-export declare function createMemoryStore(): PaymentStore;
+export interface MemoryStoreOptions {
+    /** Retention for callback nonces and idempotency keys. Defaults to 24 hours. */
+    readonly retentionMs?: number;
+    /** Maximum retained audit entries. Defaults to 10,000. */
+    readonly maxAuditEntries?: number;
+}
+/** In-memory implementation. Production stores must back reserveOrder with a unique constraint or transaction. */
+export declare function createMemoryStore(options?: MemoryStoreOptions): PaymentStore;

package/dist/store.js

@@ -6,36 +6,68 @@
  * Order storage abstraction (P0 in-memory; for a production DB see the design doc's production checklist:
  * unique constraints back idempotency, row locks/CAS prevent concurrent double-writes, idempotency records and nonces with TTL).
  */
-/** In-memory implementation (single process; use an internal mutex for concurrent safety). */
-export function createMemoryStore() {
+/** In-memory implementation. Production stores must back reserveOrder with a unique constraint or transaction. */
+export function createMemoryStore(options = {}) {
+    const retentionMs = options.retentionMs ?? 24 * 60 * 60 * 1000;
+    const maxAuditEntries = options.maxAuditEntries ?? 10_000;
     const orders = new Map();
-    const nonces = new Set();
+    const reservations = new Set();
+    const nonces = new Map();
     const idempotency = new Map();
     const audit = [];
+    const pruneExpired = (now) => {
+        for (const [nonce, expiresAt] of nonces) {
+            if (expiresAt <= now)
+                nonces.delete(nonce);
+        }
+        for (const [key, entry] of idempotency) {
+            if (entry.expiresAt <= now)
+                idempotency.delete(key);
+        }
+    };
     return {
         getOrder(orderId) {
             return orders.get(orderId);
         },
+        reserveOrder(orderId) {
+            if (orders.has(orderId) || reservations.has(orderId))
+                return false;
+            reservations.add(orderId);
+            return true;
+        },
+        releaseOrderReservation(orderId) {
+            reservations.delete(orderId);
+        },
         saveOrder(order) {
             orders.set(order.orderId, order);
+            reservations.delete(order.orderId);
         },
         allOrders() {
             return Array.from(orders.values());
         },
         addNonce(nonce) {
+            const now = Date.now();
+            pruneExpired(now);
             if (nonces.has(nonce))
                 return false;
-            nonces.add(nonce);
+            nonces.set(nonce, now + retentionMs);
             return true;
         },
         getOrderByIdempotencyKey(key) {
-            return idempotency.get(key);
+            const now = Date.now();
+            pruneExpired(now);
+            return idempotency.get(key)?.orderId;
         },
         setIdempotencyKey(key, orderId) {
-            idempotency.set(key, orderId);
+            const now = Date.now();
+            pruneExpired(now);
+            idempotency.set(key, { orderId, expiresAt: now + retentionMs });
         },
         appendAudit(entry) {
             audit.push(entry);
+            if (audit.length > maxAuditEntries) {
+                audit.splice(0, audit.length - maxAuditEntries);
+            }
         },
         auditLog() {
             return audit;

package/dist/types.d.ts

@@ -37,10 +37,17 @@ export type OrderInit = {
     readonly kind: 'redirect';
     readonly payUrl: string;
 };
+/** Callback authentication owner. Unspecified drivers use the manager HMAC protocol. */
+export type PaymentCallbackVerification = 'manager-hmac' | 'driver';
 /** Unified payment driver contract (three capabilities: createOrder / verifyCallback / queryOrder). */
 export interface PaymentDriver {
     readonly name: string;
     readonly scenes: readonly PaymentScene[];
+    /**
+     * Declares who authenticates callbacks. Real channel drivers use `driver`; custom drivers
+     * default to the manager HMAC protocol and therefore require the X-* callback headers.
+     */
+    readonly callbackVerification?: PaymentCallbackVerification;
     /** Place an order: call the payment channel → return one-time payment params. */
     createOrder(input: CreateOrderInput): Promise<OrderInit>;
     /** Channel callback verification + normalization: NOTIFY request → verify channel signature → normalize order result. */
@@ -83,6 +90,9 @@ export interface OrderRecord {
     channelTxnId?: string;
     /** Large-amount audit pending reason (audit). */
     auditReason?: string;
+    /** Business delivery state after a paid transition. Failed delivery remains pending for retry. */
+    deliveryState?: 'pending' | 'delivered';
+    deliveryError?: string;
 }
 /** Global policy config (PaymentManager-level, driver-agnostic). */
 export interface PaymentConfig {
@@ -145,9 +155,9 @@ export interface PaymentAlert {
     readonly orderId?: string;
     readonly driver?: string;
 }
-/** Operation audit entry (create/callback-book/freeze/confirm all logged). */
+/** Operation audit entry (create/callback-book/freeze/confirm/delivery all logged). */
 export interface AuditEntry {
-    readonly operation: 'create' | 'callback' | 'close' | 'confirm' | 'freeze';
+    readonly operation: 'create' | 'callback' | 'close' | 'confirm' | 'freeze' | 'delivery';
     readonly orderId?: string;
     readonly from?: OrderState;
     readonly to?: OrderState;

package/dist/wechat-official.js

@@ -123,10 +123,6 @@ export function createWechatOfficialDriver(store, options) {
         if (Math.abs(Date.now() / 1000 - Number(ts)) > timeWindowSec) {
             return { ok: false, reason: 'timestamp_expired' };
         }
-        // nonce anti-replay (channel self-verify path; the driver dedups via the store)
-        if (!store.addNonce(`wx:${nonce}`)) {
-            return { ok: false, reason: 'nonce_reused' };
-        }
         // optional: platform-cert verification (signed string = timestamp\nnonce\nbody\n)
         if (platformKey) {
             const rawBody = typeof payload === 'string' ? payload : JSON.stringify(payload);
@@ -157,6 +153,10 @@ export function createWechatOfficialDriver(store, options) {
                 decipher.final(),
             ]).toString('utf8');
             const data = JSON.parse(plain);
+            // Only consume the nonce after platform authentication and AES-GCM decryption succeed.
+            if (!store.addNonce(`wx:${nonce}`)) {
+                return { ok: false, reason: 'nonce_reused' };
+            }
             if (data['trade_state'] !== 'SUCCESS') {
                 return { ok: false, reason: `trade_state:${String(data['trade_state'])}` };
             }
@@ -199,6 +199,7 @@ export function createWechatOfficialDriver(store, options) {
     return {
         name: 'wechat_official',
         scenes: ['pc', 'h5', 'miniapp'],
+        callbackVerification: 'driver',
         createOrder,
         verifyCallback,
         queryOrder,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vobs/payment",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "description": "Payment factory backend SDK for vobs — channel drivers, order state machine, callback verification (signature + replay protection), server-side pricing and amount risk control (Experimental).",
   "type": "module",
   "publishConfig": {
@@ -28,7 +28,7 @@
     "vitest": "^4.1.11"
   },
   "engines": {
-    "node": ">=20.19.0"
+    "node": ">=22.12.0"
   },
   "bugs": {
     "url": "https://github.com/vobsjs/vobs/issues"