5.3 KiB
ADDED Requirements
Requirement: Payment creation SHALL use the stable C端 API contract
The client SHALL create package/strong-recharge orders through POST /api/c/v1/orders/create and wallet recharge orders through POST /api/c/v1/wallet/recharge. It SHALL submit the documented identifier, package or amount fields, and selected payment_method; it SHALL submit app_type only when required for WeChat payment and SHALL NOT submit a merchant ID.
Scenario: Package order creation uses the stable route
- WHEN a customer confirms a package or strong-recharge order
- THEN the client SHALL call
POST /api/c/v1/orders/create - AND the request SHALL not contain a client-selected merchant ID
Scenario: Wallet recharge creation uses the stable route
- WHEN a customer confirms a wallet recharge
- THEN the client SHALL call
POST /api/c/v1/wallet/recharge - AND the request SHALL contain the selected payment method and amount in the documented unit
Requirement: Merchant selection SHALL remain backend-owned
The system SHALL rely on the backend merchant pool to select a payment merchant. The client SHALL not rotate merchants, expose merchant selection, or retry the same creation request against another merchant automatically.
Scenario: Payment creation is accepted
- WHEN the backend receives a valid payment creation request
- THEN the client SHALL use the returned payment preparation data (
pay_config,payment_link, or wallet result) without attempting merchant selection locally
Requirement: Explicit pre-order failure SHALL be terminal for the current attempt
When a payment creation endpoint returns an explicit failure, the client SHALL treat that attempt as failed, display the API-defined error code/message, and SHALL NOT automatically switch merchants or create another payment.
Scenario: Package order pre-order fails
- WHEN
/api/c/v1/orders/createreturns an error response before payment preparation succeeds - THEN the current package/strong-recharge attempt SHALL end as failed
- AND the client SHALL surface the backend error without an automatic second creation request
Scenario: Wallet recharge pre-order fails
- WHEN
/api/c/v1/wallet/rechargereturns an error response before payment preparation succeeds - THEN the current recharge attempt SHALL end as failed
- AND the client SHALL not switch merchants or silently create a replacement recharge order
Requirement: Unknown payment-creation results SHALL not create duplicates
Timeouts, connection interruptions, and other results where the creation outcome is unknown SHALL be treated as indeterminate. The client SHALL not automatically switch merchants or repeat payment creation, and any status refresh SHALL be read-only.
Scenario: Creation request times out
- WHEN a payment creation request times out or the connection is interrupted before a definitive response is received
- THEN the client SHALL make no automatic replacement creation request
- AND the client SHALL allow the existing status-reconciliation flow to determine whether an order or recharge was created
Scenario: Status polling follows an unknown result
- WHEN the client polls or refreshes order/recharge status after an unknown result
- THEN it SHALL call only read-only status APIs
- AND it SHALL not count the refresh as a new payment creation attempt or invoke either creation endpoint
Requirement: Payment attempt accounting SHALL include every creation attempt
The client SHALL behave consistently with the backend rule that amount/attempt limits count every invocation of a payment creation endpoint, regardless of whether the resulting payment later succeeds. It SHALL not loop until success or assume a failed/unknown attempt is free.
Scenario: Explicit failure consumes an attempt
- WHEN a payment creation request is sent and the backend returns an explicit failure
- THEN the client SHALL finish the current flow without automatic repetition
- AND subsequent creation SHALL require a new deliberate user action
Scenario: Successful payment follows one creation attempt
- WHEN a payment creation request returns valid payment preparation data
- THEN the client SHALL proceed with the existing WeChat, Alipay, or wallet flow
- AND status polling or payment-link return handling SHALL not create an additional payment
Requirement: Existing payment result contracts SHALL remain compatible
The routing-policy change SHALL preserve existing WeChat pay_config, Alipay payment_link, wallet payment, submit-guard, and backend status-reconciliation behavior. API-defined error codes and messages SHALL remain authoritative.
Scenario: WeChat or Alipay preparation succeeds
- WHEN the backend returns valid
pay_configorpayment_link - THEN the client SHALL invoke the existing corresponding payment flow
- AND it SHALL determine final success from the existing backend status refresh rather than from a routing decision
Scenario: Backend returns a documented error
- WHEN the API returns a documented error code and message
- THEN the client SHALL preserve and present that error according to the existing error-handling behavior
- AND it SHALL not replace it with a merchant-specific or generic retry result