Payment Flow

Payment APIs return request-level results in result_code and business results in biz_response.result_code. HTTP 200 does not mean the payment succeeded. All payment requests are initiated from an activated customer terminal identity.

Customer terminalMUWE OpenAPIPayment providerConsumer

1

Terminal submits signed pay, pre-create, or pushed order request with `terminal_sn`.

2

MUWE validates terminal credentials, merchant scope, idempotency key, and provider route.

3

Provider handles payment authorization or returns the consumer payment payload.

4

Consumer completes payment in the configured channel or at the bound POS terminal.

5

MUWE returns success, failure, or in-progress business status.

6

If the result is uncertain, query before delivery, cancel, refund, or retry decisions.

Merchant-Initiated Payment

Customer terminalCreates order and calls `POST /upay/v2/pay` with a unique `client_sn`.

MUWE OpenAPIValidates terminal signature, routes the request, and returns business result.

Provider / consumerCompletes payment or leaves the order in progress.

1. Cashier, POS, or merchant MIS starts the payment request from an activated customer terminal.
2. Client submits POST /upay/v2/pay with a unique client_sn.
3. If biz_response.result_code is PAY_SUCCESS, deliver goods.
4. If it is PAY_IN_PROGRESS, or the network fails after the request may have reached MUWE, query by client_sn.
5. If the order cannot reach a final state within the merchant timeout, call POST /upay/v2/cancel.
6. Never reuse the same client_sn for a new payment attempt after a failed or uncertain pay request.

MIS-to-POS Order Push

Merchant MISCreates an order for a selected bound POS terminal.

Bound POS terminalReceives the order and drives the consumer payment flow.

MUWE / providerProcesses payment and exposes the final result by notification or query.

1. Merchant MIS or cashier system creates an order for a bound POS terminal.
2. The POS receives the order and drives the consumer-facing payment flow.
3. MUWE processes the payment through the configured provider.
4. The client receives notification or polls POST /upay/v2/query until a final order status is reached.

QR Pre-create

Customer terminalCalls `POST /upay/v2/precreate` for a merchant order.

MUWE OpenAPIReturns `qr_code` or provider payment payload.

Consumer appScans or opens the payment payload and completes payment.

1. Client calls POST /upay/v2/precreate.
2. MUWE returns qr_code or a provider payment payload.
3. Merchant renders the QR code or payment URL.
4. Customer completes payment in the provider app.
5. Client waits for notification or polls POST /upay/v2/query.

Refund

Refunds are idempotent by refund_request_no.

1. Query the order and confirm it is refundable.
2. Call POST /upay/v2/refund with either sn or client_sn and a unique refund_request_no.
3. If the refund result is uncertain, query using the original order identity and refund_request_no.
4. Do not submit a replacement refund with a new refund_request_no until the first one is final.

Cancel Recovery

cancel is for unpaid or uncertain orders. Use it when the client cannot prove that a payment failed but must prevent later success.

If cancel returns CANCEL_SUCCESS, the order is closed. If it returns CANCEL_ERROR, CANCEL_ABORT_ERROR, or a network timeout, keep querying and escalate if the order does not reach a final state.

Revoke

revoke is not the same operation as cancel. Use POST /upay/v2/revoke only for same-day reversal of a paid order when the provider route explicitly supports it.

Final Statuses

Status	Meaning
PAID	Payment completed.
PAY_CANCELED	Payment failed and was canceled.
REFUNDED	Fully refunded.
PARTIAL_REFUNDED	Partially refunded.
CANCELED	Order canceled before payment completion.

Intermediate states such as CREATED, IN_PROG, ERROR_RECOVERY, and PRE_SUCCESS are not final. Query until a final state is returned or support intervention is required.