OpenCashier Merchant Integration

Workflow

1. Inspect the target codebase first. Reuse existing order, payment, callback, and configuration modules instead of creating a separate demo structure.
2. Collect only the minimum integration inputs:
   • apiBaseUrl
   • appId
   • appSecret
   • the merchant system's notifyUrl
   • optional returnUrl
   • the required allowedChannels for this product flow
3. Choose the implementation path based on runtime:
   • Node/TypeScript: use @opencashier/sdk first. Initialize OpenCashierClient, use resource methods such as orders.create, orders.getByMerchantOrderNo, refunds.create, and notifications.verify.
   • Non-Node runtimes: port the signing and notification-verification protocol from the public docs. Reuse the same request and notification contract; do not invent a different merchant API shape.
4. Implement the minimum server-side capabilities first:
   • OpenCashier config loading
   • create order / query order
   • optional close order / refund
   • one merchant notification endpoint that returns plain text success after successful verification and processing
5. Finish the product loop before adding extras:
   • persist merchantOrderNo, platformOrderNo, cashierUrl, and expireTime when creating the order
   • open cashierUrl directly from the frontend or redirect layer
   • use query-order as the fallback for result pages and background reconciliation instead of trusting the browser return alone
6. Ship reliability rules together with the first version:
   • all write APIs must use stable Idempotency-Key values
   • merchant notification handling must be idempotent
   • payment success must be determined by notification or order query, not by redirect completion
7. Only add these extensions when explicitly needed:
   • custom cashier UI: GET /api/v1/cashier/{cashierToken}
   • app-scoped provider bootstrap: use the SDK providers module or the equivalent admin API pattern, mainly for local integration and demos

Integration Rules

• Default to hosted cashier. Do not rebuild Alipay or Stripe redirect logic inside the merchant system.
• The merchant system should not receive provider callbacks directly. It should only receive the OpenCashier merchant notification.
• If the business flow already knows the exact payment brand, pass a narrow allowedChannels set.
• If the target stack is Node/TypeScript, prefer the official SDK over handwritten signing, header injection, notification verification, or error parsing.
• If the target stack is not Node.js, port the signing and verification protocol, not the TypeScript syntax.
• Provider config is an operator concern. Do not treat the quickstart bootstrap path as a required production integration step for merchants.

Done When

The first integration version is complete only when all of these are true:

1. The target system can create a real OpenCashier order
2. The user can be sent to cashierUrl
3. The merchant side can verify and process PAY_SUCCESS
4. The system can query orders when notification delivery is delayed or fails
5. If refunds are in scope, POST /api/v1/refunds and refund query are integrated