device-voice-h5/openspec/changes/update-july-h5-c-iteration/specs/backend-driven-payment/spec.md

ADDED Requirements

Requirement: Payment options SHALL be rendered from backend permissions

The H5/C client SHALL use allowed_payment_methods from asset information and the recharge-check response to determine which payment methods are visible and selectable. It SHALL support the backend values wallet, wechat, and alipay where returned, and SHALL not hard-code a card/device payment-method matrix.

Scenario: Asset payment methods are returned

• WHEN asset information returns a non-empty allowed_payment_methods list
• THEN the package payment UI SHALL render exactly the methods allowed by that list
• AND the client SHALL not offer a method absent from the list

Scenario: Recharge permissions differ from asset permissions

• WHEN /api/c/v1/wallet/recharge-check returns its own allowed_payment_methods value
• THEN the wallet recharge UI SHALL use the recharge-check value for that recharge attempt
• AND the client SHALL not reuse a stale package-payment method list

Requirement: Payment creation SHALL submit the selected method and the required WeChat app type

The client SHALL submit identifier, the relevant package or amount fields, and the user-selected payment_method to the applicable creation endpoint. It SHALL submit app_type only when payment_method = wechat, using the endpoint-defined value official_account or miniapp.

Scenario: Create a package order

• WHEN the user submits an allowed package payment method
• THEN the client SHALL call POST /api/c/v1/orders/create with identifier, package_ids, and the selected payment_method
• AND the client SHALL include app_type for WeChat payment as required

Scenario: Create a wallet recharge

• WHEN the user submits an allowed recharge method and an amount within backend limits
• THEN the client SHALL call POST /api/c/v1/wallet/recharge with the integer amount in cents, identifier, and selected payment method
• AND the client SHALL include app_type only for WeChat payment

Scenario: User-facing currency conversion

• WHEN an amount is returned by an API in cents
• THEN the client SHALL display the corresponding yuan value
• AND the client SHALL submit the original integer-cent representation to the API

Requirement: Recharge submission SHALL honor the backend pre-check

The client SHALL call GET /api/c/v1/wallet/recharge-check?identifier=... before starting a recharge. When need_force_recharge = true, it SHALL use force_recharge_amount, min_amount, max_amount, and message from the response to guide or block the recharge flow.

Scenario: Force recharge is required

• WHEN recharge-check returns need_force_recharge = true
• THEN the client SHALL present the backend force-recharge amount and message
• AND the client SHALL not submit a normal recharge that violates the returned requirement

Scenario: Recharge is permitted normally

• WHEN recharge-check returns need_force_recharge = false and the amount is within the returned range
• THEN the client SHALL allow the user to select an allowed method and submit the recharge order

Requirement: Payment results SHALL be confirmed by backend order state

After order creation, the client SHALL preserve existing handling for pay_config and payment_link, and SHALL use an order or recharge status query to confirm completion. A successful frontend redirect or payment-link return alone SHALL not be treated as proof of payment.

Scenario: Backend returns WeChat payment parameters

• WHEN a creation response contains pay_config
• THEN the client SHALL invoke the existing WeChat payment flow
• AND the client SHALL refresh backend payment status after the flow returns

Scenario: Backend returns a web payment link

• WHEN a creation response contains payment_link
• THEN the client SHALL use the existing payment-link presentation/handling
• AND the client SHALL confirm the resulting order or recharge state through the backend