YouEZPay-JSSDK
Merchant Integration Development Guide
1. Integration Preparation Conditions
| Type | Description |
|---|---|
| merchantId | Merchant ID, the unique identifier of the merchant |
| merchantKey | Merchant key, used for MD5 signature generation and encryption, to validate the data |
2. Embedded Checkout Order Interface
Conditions for initiating API requests:
- Apply for merchantId and merchantKey.
- Import the JavaScript SDK file on the order payment page (needed for payment page rendering and 3DS verification).
- Use the signature mechanism to generate a digital signature.
- Call the API.
Description:
The payment request is a transaction where the transaction information between the transaction requester (such as a merchant or payment gateway) and YouEZPay is transmitted via an API interface. It is an asynchronous transaction method that requires user participation. After a successful payment, the YouEZPay platform will send a backend notification to the merchant. Merchants must implement the backend notification interface to synchronize the order payment status. This embedded API mode only renders the necessary page elements (such as overlays, loading indicators) and will not cause URL redirection (redirection only happens after payment is successful).
Checkout Order Request:
JavaScript request API:
uooShopPay.toCheckOut(payOrder)The
payOrder JSON object contains the following information:| Parameter | Type | Required | Description |
|---|---|---|---|
| merchantId | String | Yes | Merchant ID |
| signature | String | Yes | MD5 signature, a 32-character uppercase string generated by concatenating the JSON string of the order request body (orderBody) with the merchant key, and then performing MD5 on the resulting string MD5(orderBody+merchantKey)e.g., MD5(JSON.stringify(orderBody)+merchantKey) |
| orderBody | JsonObject | No | The order request body data object |
| version | String | Yes | API version, default value is 1.0 |
The
orderBody JSON object contains the following information:| Parameter | Type | Required | Description |
|---|---|---|---|
| merOrderNo | String | Yes | Merchant order number or order ID. This parameter will be carried during the payment status callback from the platform |
| merAmount | String | Yes | Order amount, up to two decimal places, e.g., “145.50” |
| merCurrency | String | Yes | The ISO 4217 standard three-letter currency code |
| notifyUrl | String | Yes | The URL address that receives payment result notifications |
| notifyJumpUrl | String | Yes | Redirect URL, automatically redirects to the merchant’s specified URL after payment is successful |
| errorAction | String/function(errText) | No | Specifies how to handle errors. If an error occurs, the browser will remain on the order submission page. String: A corresponding to the ID of a page element (e.g., "errDivId") will place the error message in that element.e.g., document.getElementById("errDivId ").innerText="error info" .function(errText): the system will invoke a specified callback function to handle the error message. The default action is to display an alert message ( alert("Error message description")) if no action is specified. |
| billInfo | JsonObject | No | Billing information. If not provided, default to using the shipping information. |
| shipInfo | JsonObject | Yes | Order shipping information |
| cardInfo | JsonObject | Yes | Credit card payment information |
| goodsInfo | JsonArray | Yes | The list of order item details |
billInfo and shipInfo include the following information:
| Parameter | Type | Required | Description |
|---|---|---|---|
| firstName | String | Yes | First name |
| lastName | String | Yes | Last name |
| country | String | Yes | Country code, corresponding to two uppercase letters in ISO 3166-1 |
| state | String | No | State, corresponding to ISO 3166-2 |
| city | String | Yes | City |
| address | String | Yes | Address |
| zip | String | Yes | Zip code |
| phone | String | No | Phone number |
| String | Yes | Email address |
cardInfo includes the following credit card information:
| Parameter | Type | Required | Description |
|---|---|---|---|
| cardNo | String | Yes | Credit card number |
| securityCode | String | Yes | Security code (CVV) |
| expireYear | String | Yes | Expiration year, represented by two digits, e.g., “22” for 2022 |
| expireMonth | String | Yes | Expiration month, represented by two digits, e.g., “08” for August |
| nameOnCard | String | No | Name on the card |
goodsInfo (
JsonArray) includes the following product details:| Parameter | Type | Required | Description |
|---|---|---|---|
| productName | String | Yes | Product name |
| productNum | String | Yes | Product quantity |
| productPrice | String | Yes | Product price, up to two decimal places, e.g., “145.50” |
| skuAttribute | String | No | SKU attribute |
Example code:
uooShopPay.toCheckOut({
"merchantId": "1008",
"signature": "15B1C402C44155DB59B6096F9367E0DF",
"version": "1.0",
"orderBody": {
"merOrderNo": "UMF20180513151635295421",
"merAmount": "128.50",
"merCurrency": "USD",
"notifyUrl": "https://www.myshop.sale/callback/?orderid=SD23070422100",
"notifyJumpUrl": "https://www.myshop.sale/thankyou/?orderid=SD23070422100",
"errorAction": "errDivId",
"billInfo": {
"firstName": "",
"lastName": "",
"country": "",
"state": "",
"city": "",
"address": "",
"zip": "",
"phone": "",
"email": ""
},
"shipInfo": {
"firstName": "",
"lastName": "",
"country": "",
"state": "",
"city": "",
"address": "",
"zip": "",
"phone": "",
"email": ""
},
"cardInfo": {
"cardNo": "",
"securityCode": "",
"expireYear": "",
"expireMonth": "",
"nameOnCard": ""
},
"goodsInfo": [{
"productName": "NIKE shoes",
"productNum": "1",
"productPrice": "139.50"
}]
}
});
JSON.stringify(orderBody) =
'{"merOrderNo":"UMF20180513151635295421","merAmount":"128.50","merCurrency":"USD","notifyUrl":"https://www.myshop.sale/callback/?orderid=SD23070422100","notifyJumpUrl":"https://www.myshop.sale/thankyou/?orderid=SD23070422100","errorAction":"#errDivId","billInfo":{"firstName":"","lastName":"","country":"","state":"","city":"","address":"","zip":"","phone":"","email":""},"shipInfo":{"firstName":"","lastName":"","country":"","state":"","city":"","address":"","zip":"","phone":"","email":""},"cardInfo":{"cardNo":"","securityCode":"","expireYear":"","expireMonth":"","nameOnCard":""},"goodsInfo":[{"productName":"NIKE shoes","productNum":"1","productPrice":"139.50"}]}'
If the merchant key is "eS3343k3", the signature is:
signature=MD5(JSON.stringify(orderBody)+merchantKey)
signature=MD5('{"merOrderNo":"UMF20180513151635295421","merAmount":"128.50","merCurrency":"USD","notifyUrl":"https://www.myshop.sale/callback/?orderid=SD23070422100","notifyJumpUrl":"https://www.myshop.sale/thankyou/?orderid=SD23070422100","errorAction":"#errDivId","billInfo":{"firstName":"","lastName":"","country":"","state":"","city":"","address":"","zip":"","phone":"","email":""},"shipInfo":{"firstName":"","lastName":"","country":"","state":"","city":"","address":"","zip":"","phone":"","email":""},"cardInfo":{"cardNo":"","securityCode":"","expireYear":"","expireMonth":"","Nameoncard":""},"goodsInfo":[{"productName":"NIKE 鞋子","productNum":"1","productPrice":"139.50"}]}eS3343k3')=15B1C402C44155DB59B6096F9367E0DF
3. Payment Result Notification Callback
Description:
After the order is successfully paid, YouEZPay initiates a post request to the merchant to notify them of the payment result. The merchant, upon receiving the payment result, should update the order status and respond with an HTTP status of 200. If the HTTP status is not 200, the platform will retry the notification at intervals of 5 seconds, 10 seconds, 15 seconds, 20 seconds, 40 seconds, 80 seconds, 120 seconds, and 300 seconds.
Request:
POST : The URL provided during checkout to receive the payment result notification (notifyUrl).The request parameters include the following:
| Parameter | Type | Required | Description |
|---|---|---|---|
| merchantId | String | Yes | Merchant ID |
| signature | String | Yes | MD5 signature, 32-character uppercase string, generated by concatenating the JSON string of the notification request body (notifyBody) with the merchant key, then performing MD5 (MD5(notifyBody+merchantKey))e.g., MD5(JSON.stringify(notifyBody)+merchantKey) |
| notifyBody | JsonObject | Yes | Notification request body data object |
The
notifyBody contains the following information:| Parameter | Type | Required | Description |
|---|---|---|---|
| merOrderNo | String | Yes | Merchant order number |
| transactionID | String | Yes | Payment transaction ID |
| orderStatus | String | Yes | Order payment status: S for successful F for failed R for refunded |
Example code:
curl -s -X POST notifyUrl
-H "Content-Type:application/json"
# 请求参数
-d '{
"merchantId": "1008",
"signature": "6FC0057889D98924EB12C61254C17998",
"notifyBody": {
"merOrderNo": "UMF20180513151635295421",
"transactionID": "20230715175225857504",
"orderStatus": "S"
}
}' JSON.stringify({ "merOrderNo": "UMF20180513151635295421", "transactionID": "20230715175225857504", "orderStatus": "S" })='{"merOrderNo":"UMF20180513151635295421","transactionID":"20230715175225857504","orderStatus":"S"}' If the merchant key is "eS3343k3", the signature is: signature=MD5(JSON.stringify(notifyBody)+merchantKey) signature=MD5('{"merOrderNo":"UMF20180513151635295421","transactionID":"20230715175225857504","orderStatus":"S"}eS3343k3')=6FC0057889D98924EB12C61254C17998
4. Integration Test Account
| Parameter | Description | Test Account |
|---|---|---|
| merchantId | Merchant ID | 0000 |
| merchantKey | Merchant Key | mz2h77f8jva9zny9 |
| Expected Result | Credit Card Number |
|---|---|
| Simulate direct payment success | 4000000000000001 |
| Simulate triggering 3DS verification and successful payment | 4000000000000002 |
| Simulate payment failure | Any card number not equal to 4000000000000001 or 4000000000000002 will result in a failed transaction. |
Note:
When using the test merchant number for simulated transactions, CVV, expiration year, and expiration month are not subject to legality checks (as long as the year and month format is correct and non-empty). Only the card number will be validated. During failed card tests, the returned error message will be “Card issuer declines transaction (test error message)“.