sud.requestVirtualPayment

Starts a virtual payment request. All three artifacts — signData, paySig, and signature — must be produced by Game SVR. The client only relays them unchanged.

Parameters

Object object

Property	Type	Default	Required	Description
signData	string		Yes	Signature data constructed by Game SVR as a JSON string; see the signData table below
paySig	string		Yes	Payment-state signature: lowercase hexadecimal hmac_sha256(pay_sign_key, signData)
signature	string		Yes	User-state signature: lowercase hexadecimal hmac_sha256(session_key, signData), using the session_key Base64 string itself as the HMAC key without decoding it
success	function		No	Callback for a successful payment
fail	function		No	Callback for a failed payment
complete	function		No	Callback invoked when the call ends, after success, cancellation, or failure

Fields of signData

Field	Type	Default	Required	Description
mode	string		Yes	goods for direct item purchase, coin for game currency purchase
env	number		Yes	0 for production, 1 for testing
productId	string		Conditional	Required for direct item purchase
unitPrice	number		Yes	Item unit price in cents (required for direct item purchase)
quantity	number		Yes	Amount of game currency to purchase; must be one of the fixed tiers configured for the product
currency	string		Yes	Currency; only CNY is currently supported
outTradeNo	string		Yes	Business order number, generated by Game SVR and globally unique
attach	string		No	Business passthrough data, returned unchanged in the delivery webhook

Callback Parameters

success

Property	Type	Description
sudTradeNo	string	SUD business order number

fail

Property	Type	Description
errCode	number	Error code
errMsg	string	Error message

complete carries no arguments. It is invoked after success or fail, and runs only once per request.

Notes

• The client must not take part in assembling signData or computing signatures, and must never touch pay_sign_key or session_key. Game SVR issues the three artifacts and the client passes them to this API unchanged.
• signData must be passed in its original form, including its spaces and line breaks. Never sign first and then deserialize and re-serialize the JSON: any re-serialization can change spaces, key order, or escaping and cause signature verification to fail.
• The success callback only means the client-side payment flow ended; it does not mean the goods were delivered. Never grant assets based on success. Delivery must be driven by the webhook Game SVR receives. See section 5 of Virtual Payment Configuration - Direct IAP.
• Do not start the same order more than once concurrently. Block new order requests while a previous one is still awaiting confirmation.
• complete runs on success, user cancellation, and failure alike. Never treat complete as a success signal.

Example Code

// signData / paySig / signature all come from the Game SVR order endpoint; do not build them on the client
sud.requestVirtualPayment({
    signData: orderFromGameServer.signData,
    paySig: orderFromGameServer.paySig,
    signature: orderFromGameServer.signature,
    success: (res) => {
        // Only means the client-side payment flow ended; delivery is driven by the server webhook
        console.log('Client payment flow finished', res.sudTradeNo);
    },
    fail: (err) => {
        console.error('Payment failed or was cancelled', err.errCode, err.errMsg);
    },
    complete: () => {
        console.log('Payment call finished');
    },
});