README.md

Merchant Quickstart

中文说明

This directory is the repo-local merchant integration example for OpenCashier.

It covers:

• create order through the official Node SDK
• redirect the browser to cashierUrl
• verify merchant notifications from OpenCashier
• query the order again on the result page
• optionally bootstrap one app-scoped provider config before the HTTP server starts

Primary docs

Use public docs as the main onboarding path:

• Merchant Quickstart Guide
• Provider Config Reference
• Merchant Integration

Those pages are the source of truth for:

• required .env fields
• how to fill quickstart.config.jsonc
• provider-specific startup requirements
• first-run troubleshooting

Minimal repo run

cp examples/merchant-quickstart/quickstart.config.example.jsonc examples/merchant-quickstart/quickstart.config.jsonc
pnpm check:merchant-quickstart
pnpm dev:api
pnpm dev:merchant-quickstart

Open http://127.0.0.1:4100.

Repo-local notes

• pnpm dev:merchant-quickstart runs a provider-aware preflight before the server starts.
• bootstrapProviderConfig=true makes quickstart sync the active provider config into the target merchant app scope through:
  • PUT /api/v1/admin/merchants/:appId/platform-configs
  • POST /api/v1/admin/merchants/:appId/platform-configs/:configKey/validate
  • POST /api/v1/admin/merchants/:appId/platform-configs/:configKey/activate
• The default alipay_page path does not require apps/web.
• apps/web is still useful when you switch to QR-based channels such as alipay_qr, or when you want to manage provider config manually in the UI instead of letting quickstart write it.
• If you want the UI path, run pnpm dev:web and set "bootstrapProviderConfig": false in quickstart.config.jsonc.

Code map

Recommended reading order:

• src/main.ts
• src/config.ts
• src/server.ts
• src/client.ts

Supporting files:

• quickstart.config.example.jsonc
• .gitignore
• src/store.ts