Merchants send request parameters to PayEase and receive payment details synchronously. Use these details to initiate the respective payment method and receive asynchronous notifications upon final order status.
https://apis.5upay.com/onlinePay/order
| Parameter Name | Type& Length | Description | Requirement |
|---|---|---|---|
| merchantId | varchar(9) | Unique ID assigned by PayEase, available in merchant portal. | M |
| orderAmount | varchar(18) | Unit: cents (1 RMB = 100 cents) | M |
| orderCurrency | varchar(15) | Default: CNY | M |
| requestId | varchar(50) | Unique merchant-generated order ID. Cannot reuse if already paid or canceled. | M |
| partnerId | varchar(9) | Unique ID for service providers, available in merchant portal | C |
| notifyUrl | varchar(200) | PayEase sends order final status notifications to this server URL. E.g.http://www.5upay.com/callback.action | M |
| callbackUrl | varchar(200) | User redirected here after successful payment, returns merchantId and requestId.
Returned callbackUrl sample： https://demo.5upay.com/sdk/callback?requestId=1446633831896&merchantId=890000593 |
M |
| productDetails | Json(Array) | Details of the products being paid for. See table below. | M |
| payer | Json | This field is optional but must not be omitted entirely. It should follow this format: "payer": {"idType": "IDCARD"}. See table below for details. | M |
| cashierVersion | varchar(100) | STANDARD – Standard version (no identity or trade information required) | C |
| DECLARE – Declaration version (identity and trade information required) | |||
| forUse | varchar(50) | GOODSTRADE – Goods trade | C |
| PLANETICKET – Airfare | |||
| HOTELACCOMMODATION – Hotel accommodation | |||
| STUDYABROAD – Overseas study | |||
| TRAVEL – Travel | |||
| LOGISTICS – Logistics | |||
| OTHER – Other | |||
| splitMark | Fixed Value | DO_SPLIT – Enable split settlement | C |
| NOT_DO_SPLIT – No split (default if not provided) | |||
| clientIp | varchar(100) | Public IP address of the client (merchant must collect user's IP) | C |
| paymentModeCode | varchar(50) | >Required in non-cashier mode. Refer to payment method codes. | C |
| openId | varchar(100) | User’s WeChat openId or Alipay buyer_id. Required for official accounts, WeChat Mini Programs, or Alipay Lifestyle accounts with direct connection./td> | C |
| reportTerminalNo | varchar(8) | Mandatory for barcode (code-scanning) payments. | C |
| payMerchantId | varchar(9) | Payer Merchant ID. Required when paying via corporate account. | C |
| serialNumber | varchar(50) | Remittance reference number. Mandatory when using "Exclusive Account Remittance - Pro Version" as the payment method. | C |
| appId | varchar(100) | Merchant’s own appId. | O |
| needOpenLink | varchar(1) | 1 – Return openLink | O |
| 0 – Do not return openLink | |||
| Default: Do not return openLink | |||
| remark | varchar(300) | Merchant remarks. Will be returned in the payment result. | M |
| Mandatory when cashierVersion is DECLARE. | |||
| For DECLARE version, trade background info must follow the format below: Goods Trade: Product Name, Quantity, Logistics Tracking Number, Courier Name, Customs Involved (Yes/No), Invoice Number, Contract Number; Example: XXX,1,768883888883,XX Courier,No,3333,4444 Hotel: Hotel Name, Address, Guest Name, Check-in Date, Check-out Date, Room Type; Example: XXX, XX Street, Zhang San, 2025-07-01, 2025-07-03, XX Room Other: Product Name, Product Type, Invoice Number, Contract Number; Example: XXX Game Card, Game, 3333, 4444 |
|||
| authCode | varchar(50) | Authorization code from wallet, such as WeChat/Alipay payment code. | O |
| timeout | Int(4) | Timeout duration for the order (in minutes, max 24 hours). For example, value “10” means the order will expire in 10 minutes. Set according to your business scenario. | O |
| merchantUserId | varchar(30) | Used for card binding in quick payments. This ID must be unique per user under the merchant. Required to allow returning users to reuse previously bound cards. | O |
| reportSerialNo | varchar(50) | Registration serial number (please consult your business account manager). | O |
| subOrders | JSON (Array) | List of sub-orders. See sub-order table for details. | O |
| projectId | varchar(50) | Merchant-defined project ID used to distinguish between different business types. | O |
| limitAccType | varchar(200) | Restricted account types. Multiple values should be separated by a comma (,). See table below for available types. | O |
| subsidyMark | Fixed Value | DO_SUBSIDY – Subsidy applied | O |
| NOT_DO_SUBSIDY – No subsidy | |||
| Default: No subsidy | |||
| subsidyAmount | decimal(18) | Subsidy amount in cents (1 RMB = 100 cents). | O |
| isBackUsersSign | Fixed Value | 1 – Return user identifier | O |
| 0 – Do not return user identifier | |||
| Empty value defaults to not returning | |||
| This parameter specifies whether the user's identifier should be returned after a successful transaction. Applies only to WeChat, Alipay, and Webox Pay. | |||
| languageType | Fixed Value | ZH – Chinese | O |
| EN – English | |||
| Effective for cashier-based transactions only. If not provided, the language will follow the user's browser settings. | |||
| weboxParams | JSON | Required for Webox Pay with facial recognition. See Webox parameter table. | O |
| instalmentParams | JSON | Required for installment payments. See installment parameter table. | O |
| subsidyDetail | JSON (Array) | Used in marketing subsidy scenarios to specify subsidy contributors. If not provided, the default contributor will be used. Up to 5 entries allowed. | O |
| bindCardId | varchar(50) | Card binding ID. Currently not in use. | O |
| hmac | varchar(500) | Signature of the request generated by the merchant. Refer to the encryption guide for how to generate the HMAC. | M |
Note: All the above parameter values must not contain the following special characters: ' " & < > ( ) space
| Parameter | Type& Length | Description | Required/th> |
|---|---|---|---|
| name | varchar(500) | Product name. Must reflect the actual product being sold. | M |
| quantity | long | Product quantity. | M |
| amount | long | Unit price in cents (1 RMB = 100 cents). Represents the price of a single item. | M |
| receiver | varchar(200) | Receiver name. If not provided, the registered name will be used by default. | O |
| description | varchar(500) | Product description. | O |
| Parameter | Type& Length | Description | Required/th> |
|---|---|---|---|
| name | varchar(100) | Payer's full name. Required in DECLARE mode. Must be provided together with ID type and ID number when payer restriction applies. | C |
| phoneNum | varchar(50) | Mobile number. Required in DECLARE mode. | C |
| idType | varchar(20) | ID type (e.g., IDCARD). Required in DECLARE mode. Must be provided with name and ID number when payer restriction applies. | C |
| idNum | varchar(100) | 18-digit ID number only. Required in DECLARE mode. Must be provided with name and ID type when payer restriction applies. | C |
| bankCardNum | varchar(100) | Bank card number. Required in DECLARE mode. May be used for UnionPay WAP payment passthrough. Must be provided when using bank card payment. | C |
| varchar(50) | Email address. | O |
| Parameter | Type& Length | Description | Required/th> |
|---|---|---|---|
| requestId | varchar(100) | Sub-order ID. | O |
| orderAmount | varchar(100) | Sub-order amount in cents (1 RMB = 100 cents). | O |
| limitAccType Enum Value | Description | Applicable Scenario | Value Requirements |
|---|---|---|---|
| ALIPAY_HB_FQ_NUM_3 | Alipay Huabei Installments – 3 months | Alipay Huabei installment payments | Only one of these can be used Can be combined with non-Huabei values, separated by commas (,) Example: ALIPAY_HB_FQ_NUM_3,ONLY_BANKCARD_PAY |
| ALIPAY_HB_FQ_NUM_6 | Alipay Huabei Installments – 6 months | Alipay Huabei installment payments | |
| ALIPAY_HB_FQ_NUM_12 | Alipay Huabei Installments – 12 months | Alipay Huabei installment payments | |
| DISABLE_CREDIT_CARD | Disallow credit card payments | Webox Pay, Gateway payments |
Only one of these can be used Can be combined with Huabei installment values, separated by commas (,) Example as above |
| ONLY_BANKCARD_PAY | Allow only bank card payments | Online payments, Webox Pay | |
| ONLY_DEBIT_CARD | Allow only debit card payments | Online payments, Webox Pay |
| Parameter | Type& Length | Description | Required/th> |
|---|---|---|---|
| payAuthType | Fixed Value | FORCE_FACE_SCAN – Facial authentication required for Webox payments. | O |
| Mandatory face authentication when using Webox Pay. |
| Parameter | Type& Length | Description | Required/th> |
|---|---|---|---|
| interestType | Fixed Value | USER_INTEREST – Interest paid by the user | C |
| MERCHANT_INTEREST – Interest subsidized by the merchant | |||
| Defaults to USER_INTEREST for non-direct integrations. Required for direct integrations. | |||
| suppBankCodes | varchar(1024) | Comma-separated list of supported bank codes. See attached "Bank Code List" for reference. | O |
| limitNum | varchar(50) | Comma-separated list of allowed installment periods. Example: 3,6,9,12 | O |
| storeNo | varchar(100) | Store number used to identify the merchant’s store. | O |
| storeName | varchar(15) | Store name. Must be provided together with storeNo. |
O |
| Parameter | Type & Length | Description | Required |
|---|---|---|---|
| subsidyMerchantId | varchar(30) | Merchant ID of the subsidy provider. | O |
| subsidyDetailAmount | varchar(18) | Subsidy amount in cents (1 RMB = 100 cents). | O |
| Name | Description |
|---|---|
| merchantId | Same as request parameter. |
| requestId | Same as request parameter. |
| partnerId | Same as request parameter. |
| status | Request Statu SUCCESS – Request successfully received. |
| FAILED – Request failed. | |
| ERROR – System error (see error response section for details). | |
| REDIRECT – Redirection required. | |
| realBankRequestNumber | Bank Order Number. Unique transaction ID assigned by the bank. |
| payeeInfo | Returned only when status = SUCCESS and the payment method is offline bank transfer. See payeeInfo table for details. |
| redirectUrl | Required when status = REDIRECT. Specifies the URL to which the user should be redirected. |
| walletId | Webox wallet ID. Returned only when using Webox QR code payment. |
| scanCode | Returned when status = SUCCESS. A Base64-encoded QR code used in direct QR payments. Merchants must convert this to an image for display. |
| scanCodeUrl | Returned when status = SUCCESS. Direct QR scan payment URL. |
| appParams | Returned when status = SUCCESS and payment is initiated via App. Used to invoke the mobile SDK. |
| jsString | WeChat Payment Signature Data. Returned after successful WeChat pre-order. Contains a JSON object required for invoking WeChat payment via JavaScript. |
| wechatId | WeChat Original App ID. Returned when status = REDIRECT and the payment is initiated through WeChat Mini Program (non-direct). Used to launch the Mini Program from the original WeChat app. Note: Returned only for channel-based Mini Program payments. No appId needed in the request. |
| tradeNo | Alipay Transaction ID. Returned when status = SUCCESS after a successful Alipay pre-order in Mini Program or Lifestyle Account. Required to invoke Alipay payment. |
| token | >Webox Payment Token. 当status为SUCCESS，Returned when status = SUCCESS for Webox Pay, Webox QR Pay, or Webox Official Account Pay. This token is used to invoke payment through the Webox SDK or service account on iOS/Android. Refer to integration guide for usage and result callbacks. |
| openLink | WeChat Mini Program openLink. Returned when status = REDIRECT and needOpenLink = 1 in WeChat Mini Program non-direct payments. Used in browser via location.href = openLink to trigger Mini Program. Only available for channel-based payments. No appId required in request. |
| payMerchantId | Payer merchant ID. Returned when payment is made via enterprise account. |
| hmac | HMAC signature generated by PayEase. Refer to the decryption/signature verification guide for details. |
| Name | Description |
|---|---|
| accountNumber | Bank account number of the payee. |
| bankUnionNumber | Bank union number |
| branchBank | Name of the account-opening bank branch. |
| payee | Full name of the payee. |
| postscriptNumber | Remarks for remittance. Note: This parameter is not returned when using Dedicated Account Transfer. |
| remittancesAddress | Receiving address of the remittance. |
1. For non-split orders, one asynchronous notification is sent after payment is completed, which may not include the service fee amount. A second notification is sent after billing is successful, including the service fee.
2. For split orders, one asynchronous notification is sent after payment is completed, which may not include the splitable amount and service fee. A second notification is sent after billing is completed, including the splitable amount and service fee. Each notification must be handled according to the asynchronous response handling guidelines. Be sure to return the appropriate HTTP response.
| Name | Description |
|---|---|
| merchantId | Same as request parameter. |
| requestId | Same as request parameter. |
| partnerId | Same as request parameter. |
| serialNumber | >Unique transaction ID assigned by the platform. |
| totalRefundCount | Total number of refund transactions for this order. |
| totalRefundAmount | Total refunded amount for this order. |
| orderCurrency | Default: CNY (Chinese Yuan) |
| Total refunded amount for this order. | |
| orderAmount | Order Amount |
| In cents. 1 RMB = 100 cents. | |
| status | Order Status |
| SUCCESS – Payment completed successfully | |
| CANCEL – Order cancelled | |
| FAILED – Payment failed | |
| completeDateTime | Date and time when the payment was completed. |
| clearingOrg | NUCC – NetsUnion Clearing Corporation |
| UNION_PAY China UnionPay | |
| paymentModeAlias | Payment Method B2C Personal Online Banking |
| B2B – Corporate Online Banking | |
| UNION_SCANCODE_PAY – UnionPay QR Code Payment | |
| EXPRESS_PAY – Express Payment | |
| CREDIT_EXPRESS_PAY – Credit Card Express Payment | |
| DEBIT_EXPRESS_PAY – Debit Card Express Payment | |
| ALI_SCANCODE_PAY – Alipay QR Code Payment | |
| ALIPAY_OFFICIAL_PAY – Alipay Official Account Payment | |
| WEIXIN_SCANCODE_PAY – WeChat QR Code Payment | |
| WEIXIN_OFFICIAL_PAY – WeChat Official Account Payment | |
| MINIAPPS_WEIXIN_PAY – WeChat Mini Program Payment | |
| APPLE_PAY – Apple Pay | |
| ALIPAY_WAP_PAY – Alipay WAP Payment | |
| APP_ALIPAY – Alipay App Payment | |
| ALIPAY_B2C_PAY – Alipay B2C Payment | |
| MINIAPPS_ALI_PAY – Alipay Mini Program Payment | |
| SCANCODE-EQRCODE_PAY-ALI – E-QR Alipay | |
| SCANCODE-EQRCODE_PAY-WEIXIN – E-QR WeChat | |
| SCANCODE-EQRCODE_PAY-WEBOX – E-QR Webox | |
| SCANCODE-EQRCODE_PAY-UNION – E-QR UnionPay | |
| AGREEMENT_PAY – Agreement-Based Payment | |
| WAP – UnionPay WAP Payment | |
| APP_UNION – UnionPay App Payment | |
| WEBOX_APP – Webox App Payment | |
| WEBOX_CSP – Webox QR Code Payment | |
| WEBOX_SVC – Webox Official Account Payment | |
| APP_WEIXIN – WeChat App Payment | |
| MERCHANT_ACCOUNT_PAY – Enterprise Account Payment | |
| realBankSerialNumber | Bank transaction serial number. |
| realBankRequestNumber | Order ID assigned by the bank. |
| bindCardId | >User’s bound card ID. |
| orderSplitAmount |
Total amount eligible for split for this order (in cents). If billing type is "real-time": splitableAmount = orderAmount - merchantFeeOtherwise: splitableAmount = orderAmount
|
| canSplitAmount | Remaining Splitable Amount. Remaining amount eligible for split (in cents).canSplitAmount = orderSplitAmount - settledSplitAmount - pendingRefundCollection |
| payMerchantId | Payer Merchant ID. Returned when payment is made via enterprise account. |
| errorMessage | Error Message |
| remark | Remark submitted by the merchant during order creation. |
| cardType | DEBIT_CARD – Debit Card |
| CREDIT_CARD – Credit Card | |
| Indicates the card type actually used by the user. | |
| Returned only if the payment channel supports it. | |
| usersSign | User Identifier. Returned if isBackUsersSign was set in the request and the payment succeeded.Applicable only to WeChat, Alipay, and Webox payments. |
| finalPaymentType | Final Payment Type BANK_CARD - Bank Card |
| BALANCE – Balance | |
| Indicates the actual payment type used by the user. | |
| Returned only if enabled via merchant configuration. | |
| payerNameMd5 | MD5 hash of the payer's name. Returned only if supported by the payment channel and enabled via merchant configuration. |
| bankCardNumberMd5 | MD5 hash of the actual bank card number used by the user. Returned only when the payment type is bank card, the acquiring merchant has enabled this feature, and the payment channel supports it. |
| bankCardNumber | Masked format of the actual bank card number used by the user. Returned only when the payment type is bank card, the acquiring merchant has enabled this feature, and the payment channel supports it. |
| bankCode | Code of the bank associated with the actual bank card used for the payment. Returned only when the payment type is bank card, the acquiring merchant has enabled this feature, and the payment channel supports it. |
| feeAmount | The service fee charged by PayEase for this transaction, in cents (1 RMB = 100 cents). Returned after successful transaction. |
| feeBear | Indicates who bears the service fee for the transaction. Returned after successful transaction. MERCHANT – Borne by the merchant PARTNER – Borne by the service provider |
| deliveryStatus | Delivery Status Applicable only when paymentModeAlias = MINIAPPS_WEIXIN_PAY. Can be ignored for all other payment methods. |
| CANCELED – Delivery canceled (typically after payment failure) | |
| PENDING – Pending delivery confirmation (payment successful and delivery required) | |
| DELIVERED – Delivered successfully (after confirmation of delivery) | |
| NOREQUIRED – Delivery not required (payment successful, delivery not applicable) | |
| When WeChat Mini Program triggers delivery management, refer to the official WeChat documentation:
Order Delivery Management Integration Guide Delivery Feature Overview and Integration Plan |
|
| deliveryDateTime | Delivery Timestamp Format：yyyy-mm-dd hh:mm:ss Returned only if deliveryStatus = DELIVERED.
|
| hmac | Signature generated by PayEase. Refer to the decryption and verification guide for signature validation process. |
Note: When processing response messages returned by PayEase, merchants should implement forward compatibility for potential future fields. This ensures that the system does not encounter errors or parsing issues due to newly added fields in future responses.