Order submission interface

Description

The merchant sends the request parameters of the foreign exchange purchase order to PayEase, receives the payment information returned synchronously and then uses this information to evoke the corresponding payment method, and finally receives the asynchronous notification result after the order is completed.

Request Endpoint

https://apis.5upay.com/foreignExchange/order

Name Type & Max Description Requirement
merchantId varchar(9) The unique identity of the merchant ID in PayEase system. After the merchant completes Payease system registration, the merchant can log in the merchant backend portal to check M
orderAmount varchar(18) UNIT: China fen，1 Yuan=100 Fen M
orderCurrency Fixed Value CNY, USD, JPY, EUR, CHF, GBP, CAD, AUD, HKD M
requestId varchar(50) The order number is generated by the merchant and the order number must be unique on the platform transaction. Request/order which had been paid or canceled in Payease's platform can't be submitted with same request ID. M
amount varchar(18) Unit: China fen, 1 Yuan=100 fen, foreign exchange purchase amount = foreign exchange purchase amount - handling fee; If the parameter is null, PayEase automatically purchases foreign exchange, minus the handling fee, and then returned final amount to the merchant O
currency Fixed Value CNY, USD, JPY, EUR, CHF, GBP, CAD, AUD, HKD M
forUse Fixed Value GOODSTRADE M
PLANETICKET
HOTELACCOMMODATION
STUDYABROAD
SOFTWARE
MEETING
EXHIBITION
TRAVEL
LOGISTICS
listPriceToken varchar(32) It is used to price foreign currencies, in which merchants firstly ask PayEase to give and lock a quotation price in the "Lock Price" interface, on which PayEase system converts the foreign currencies into CNY according to the quoted price at that time; And then merchant must send the Order request out to PayEase within a certain period of time. If merchant assigns the value to this field, the merchant will be able to convert the price of foreign currencies into CNY according to the price provided by PayEase system O
notifyUrl varchar(200) Server notification：Successful notification will be sent to the address after payment is successful.This address can take parameters，example:“www.5upay.com/callback.action?test=test”. Note: if the parameter value of notifyUrl is not filled, your server will not receive the notice of successful payment after payment is successful. M
callbackUrl varchar(200) Page callback: after the success of the payment, the page will jump to this address, callbackUrl return parameters include: merchantId, requestId. CallbackUrl; Returns the format example: https://demo.5upay.com/sdk/callback?requestId=1446633831896&merchantId=890000593 M
remark varchar(300) Merchant remarks the order; this remark will be returned to the merchant via asynchronized return fields. O
paymentModeCode varchar(50) Please refer to the section "Payment Code" C
appId varchar(100) The merchant passes the merchant's wechat appId to this parameter C
openId varchar(100) The merchant passes the merchant's wechat openId to this parameter C
productDetails Json Please refer to the table "Request Fields（Product Details）" M
payer Json Please refer to the table "Request Fields（payer）" C
cashierVersion Fixed Value STANDARD C
merchantUserId varchar(30) User's membership ID on the merchant's website (at least 2 characters; only uppercase and lowercase letters, and numbers are allowed). C
bindCardId varchar(100) Unique ID of card binding information returned by PayEase C
clientIp varchar(100) If the clientIp has been set the value, the related orders won't be allowed to be paid on any other IPs. C
timeout varchar(10) This parameter is used to set valid time for each order, for example, if merchants fill 10, this order will be valid for 10 minutes. The maximum valid time is 24 hours. O
ticketInfos Json Please refer to the table "Request Fields（ticketInfos）" C
studyAbroadInfo Json Please refer to the table "Request Fields（studyAbroadInfo）" C
hotelInfos Json Please refer to the table "Request Fields（hotelInfos）" C
softwareInfo Json Please refer to the table "Request Fields（softwareInfo）" C
meetingInfo Json Please refer to the table "Request Fields（meetingInfo）" C
exhibitionInfo Json Please refer to the table "Request Fields (exhibitionInfo)" C
travelInfos Json Please refer to the table "Request Fields (travelInfos)" C
logisticsInfos Json Please refer to the table "Request Fields (logisticsInfos)" C
fileName Json The name of the proof file, including the suffix, which cannot contain Chinese characters; E.g. testFile.zip. Merchants need to upload the proof file to the directory "/fe/proof/" via SFTP C
subOrders JSON Refer to "Request Fields（subOrders）". When the order currency is not CNY, this parameter is not supported. If this parameter is passed, the customs declaration interface will only support declarations using the sub-order number. C
hmac varchar(500) The result of parameter signature,generated by the merchant.For the method of obtaining hmac,please reference to the section "Developers" M

Request Fields（Product Details）

Name Type & Max Description Requirement
name varchar(500) Name of product M
quantity long quantity of product M
amount long UNIT: China fen，1 Yuan=100 Fen M
receiver varchar(200) Name of the receiver（If it is empty, the registered of the merchant name in PayEase will be automatically filled） O
description varchar(500) Product description O
logisticsNumber varchar(120) Logistics Number(logisticsNumber is a mandatory parameter if the value of the field "tradeType" is "纳入海关") C
logisticsCompany varchar(200) Logistics Company(logisticsCompany is a mandatory parameter if the value of the field "tradeType" is "纳入海关") C
tradeType Fixed Value 末纳入海关 M
纳入海关
invoiceNumber varchar(35) Invoice Number C
contractNumber varchar(20) Contract Number C

Request Fields（payer）

Name Type & Max Description Requirement
name varchar(100) Payer's Name C
idType Fixed Value IDCARD C
idNum varchar(18) ID Number C
bankCardNum varchar(20) Bankcard number C
phoneNum varchar(20) Phone Number C
email varchar(50) Email O
nationality varchar(3) please refer to the section "Counryt List" O

Request Fields（ticketInfos）

Name Type & Max Description Requirement
airlineName varchar(100) Name of airline C
crewName varchar(400) Name of passenger C
flight varchar(100) Flight no. C
freightSpaceClass varchar(40) Economy class C
fromTo varchar(200) The origin and destination are in 3-digit English code format separated by "-", for example: DXB-HKG C
departureArrivalTime varchar(200) The takeoff time and arrival time are in the format [yyyymmdd hh24:min], separated by "-", for example: 20170601 10:12-20170601 12:30 C

Request Fields（studyAbroadInfo）

Name Type & Max Description Requirement
name varchar(100) Student Name C
schoolName varchar(200) The name of the school to be paid C
studentNumber varchar(40) Student ID number; The merchant can pass the value of ID number, passport number, student number or other certificate number C
schoolWeb varchar(150) School website O
schoolCity varchar(100) City where the school is located O
major varchar(100) The major in which the student is enrolled O
academicDegree varchar(100) Doctor's degree or above, master's degree, bachelor's degree, Preparatory degree, high school, middle school, primary school, other training, which is for reference only, if there is other information, please refer to the actual situation O
studyAbroadTime varchar(10) One year or less O
More than one year
If no parameter is passed, the default value is "More than one year".

Request Fields（hotelInfos）

Name Type & Max Description Requirement
hotelName varchar(100) Hotel name C
hotelAddress varchar(200) Hotel address C
registrantName varchar(100) Registrant name C
checkInDate varchar(10) Check-in date; Format: YYYY-MM-DD C
checkOutDate varchar(10) Check-out date; Formate: YYYY-MM-DD C
roomType varchar(40) Room type C

Request Fields（softwareInfo）

Name Type & Max Description Requirement
softwareName varchar(100) Software Name C
softwarePerson varchar(200) Software purchaser ID C
softwareCount varchar(100) Software Count C
softwareDate varchar(10) Software service expiration date C
softwareWeb varchar(10) Software official website C
softwareCode varchar(40) Software product number C
softwareIp varchar(40) IP address C

Request Fields（meetingInfo）

Name Type & Max Description Requirement
meetingName varchar(100) Meeting Name C C
meetingCountry varchar(50) Meeting country C
meetingArea varchar(100) Meeting Area C
meetingPeople varchar(100) Attendee for the meeting C
meetingCount varchar(10) Number of attendees C
meetingStartDate varchar(10) Meeting Start Date; Format: YYYY-MM-DD C
meetingEndDate varchar(10) Meeting End Date; Format YYYY-MM-DD C

Request Fields（exhibitionInfo）

Name Type & Max Description Requirement
exhibitionName varchar(100) Exhibition Name C
exhibitionCountry varchar(50) Exhibition Country C
exhibitionArea varchar(100) Exhibition Area C
exhibitionPeople varchar(100) Attandees at the exhibition C
exhibitionCount varchar(10) Number of Attandees C
exhibitionStartDate varchar(10) Exhibition Start Date; Format YYYY-MM-DD C
exhibitionEndDate varchar(10) Exhibition End Date; Format: YYYY-MM-DD C

Request Fields（travelInfos）

Name Type & Max Description Requirement
subItem Fixed Value The tourism sub-item: GROEPTRAVEL (Group Tour) C
RENTALCARS
RENTING
country varchar(20) Destination of the Group Tour C
Place where the car is picked up
Location of the rented house
productName varchar(100) Product name + type E.g. Group Tour：Thailand 7 day group tour; Rent cars：Luxury SUV; Rent house：Shin Osaka-style Legal home stay C
startDateTime varchar(10) For group tour：date of departure; For renting cars：Date of pickup; For renting house：check-in date; Format: YYYY-MM-DD O
name varchar(50) For group tour：Name of contact person when placing order O
For renting cars：Driver's name when placing order
For renting house：The name of the person who reserves the house when placing the order
peopleNum varchar(10) For group tour：The number of people on this tour O
For renting cars：The number of people for renting cars this time
For renting house：The number of people renting the house this time

Request Fields（logisticsInfos）

Name Type & Max Description Requirement
country varchar(20) Receiving country/region C
goodsType varchar(10) The type of goods being sent E.g.Clothes, food, and etc. C
mailType varchar(10) E.g. air transportation、sea transportation, and etc. C
logisticsNumber varchar(50) Logistics Number O
name varchar(50) Recipient Name O

Request Fields（subOrders）

Name Type & Max Description Requirement
requestId varchar(100) Sub-order number O
orderAmount varchar(100) Sub-order amount, in cents O

Sample

{ "merchantId": "100000050", "orderAmount": "60000", "orderCurrency": "CNY", "requestId": "1528444599548", "amount": "100", "currency": "USD", "forUse": "GOODSTRADE", "notifyUrl": "http://127.0.0.1:14900/5upay/foreignexchange/OrderNotify.ashx", "callbackUrl": "http://127.9.0.1:14900/5upay/Callback.ashx", "remark": "备注", "payer": { "name": "付款人姓名", "idType": "IDCARD", "idNum": "13******26", "bankCardNum": "62*******02", "phoneNum": "139********67", "email": "cc@cc.com", "nationality": "156" }, "productDetails": [{ "name": "产品名称", "quantity": 100, "amount": 200.0, "receiver": "收款人姓名", "description": "产品描述" }], "hmac": "UZYjA/bik4TNL9aYSHajULOJxDSJkFyYfDNFxJxYCG1Zyi9s16uvSRmj07M3ax76JG 6STpWc/kyb36mWmg8X8gduvd39NupWK/zJErbgYffOmOd6YpmrvTQhbPioxLN8Ras9J9zkL7uQ3 cTOaLAHOeAQh7Aps3EFJ8MMh+sY4UwIl25h3PEkbBy2sBoug+ZpgLYDXTULrBY7OQ7cLTczfe5D OxJHLGSMpinHaVFOvQaodR8yZdAygDyfDPm16mKDBBV9NsRsGc0pNXZq+gz0hvTq1dLw+WygTVH 8VPFN01bPVHQjxJd3M041kE9ABF/vAP1ExXtSNCevRrAjyyRi4Q==" }

Synchronous Returned Field

Name Description
merchantId The unique identity of the merchant ID in PayEase system. After the merchant completes Payease system registration, the merchant can log in the merchant backend portal to check
requestId The order number is generated by the merchant and the order number must be unique on the platform transaction. Request/order which had been paid or canceled in Payease's platform can't be submitted with same request ID.
status SUCCESS
FAILED
ERROR
REDIRECT
redirectUrl When "status" is "REDIRECT"，the "redirectUrl" will be the address the user will visit on the browser.
scanCode When "status" is "SUCCESS" ，the Base64-based two-dimensional code should be converted into picture. It is the parameter returned by Direct QR code scanning
appParams When "status" is "SUCCESS" ，This will only be returned if the App pay is used，which is used to envoke the mobile terminal's SDK
jsString When "status" is "SUCCESS" ，This json data will be returned by wechat when the order is placed successfully，which is used to envoke WechatPay
payeeInfo When "status" is "SUCCESS"，it will be returned only if the payment method is offline bank transfer; Please refer to the table "Reponse Fields（payeeInfo）".
subOrders Refer to "Request Fields（subOrders）"
hmac The result of parameter signature,generated by the merchant.For the method of obtaining hmac,please reference to the section "Developers"

Reponse Fields（payeeInfo）

Name Description
accountNumber Payee's bank account number
bankUnionNumber Payment lines number
branchBank Name of opening bank account
payee Payee's name
postscriptNumber Remittance postscript
remittancesAddress Addresse to remit

Sample

{ "redirectUrl": "https://5upay.ehking.com/cashier/receipt/index/2c93a983638692180163b4cb9a8f05b4 ", "merchantId": "890000593", "requestId": "1527746602492", "hmac": "UZYjA/bik4TNL9aYSHajULOJxDSJkFyYfDNFxJxYCG1Zyi9s16uvSRmj07M3 ax76JG6STpWc/kyb36mWmg8X8gduvd39NupWK/zJErbgYffOmOd6YpmrvTQhbPioxLN8R as9J9zkL7uQ3cTOaLAHOeAQh7Aps3EFJ8MMh+sY4UwIl25h3PEkbBy2sBoug+ZpgLYDXT ULrBY7OQ7cLTczfe5DOxJHLGSMpinHaVFOvQaodR8yZdAygDyfDPm16mKDBBV9NsRsGc0 pNXZq+gz0hvTq1dLw+WygTVH8VPFN01bPVHQjxJd3M041kE9ABF/vAP1ExXtSNCevRrAjyyRi4Q==", "status": "REDIRECT" }

Asynchronous Return Fields

Name Description
merchantId The unique identity of the merchant ID in PayEase system. After the merchant completes Payease system registration, the merchant can log in the merchant backend portal to check
requestId The order number is generated by the merchant and the order number must be unique on the platform transaction. Request/order which had been paid or canceled in Payease's platform can't be submitted with same request ID.
serialNumber Serial Number of the request in Payease's system
totalRefundCount Total Refund Count
totalRefundAmount Total Refund Amount
orderCurrency Please refer to the table "Currency List"
orderAmount Transaction Amount，Unit: China Fen
remark remark
payment Please refer to the table "Response Fields（payment）"; Note: this parameter is returned after the successful payment
foreignExchange Please refer to the table "Response Fields（foreignExchange）"; Note: this parameter is returned after the successful purchase of foreign exchan
clearingOrg NUCC Clearing institution( Network )
UNION_PAY Clearing institution (UnionPay)
paymentModeAlias B2C "Personal Internet Banking"
B2B "Enterprise Internet Banking
UNION_SCANCODE_PAY "UnionPay scan code"
EXPRESS_PAY "Express Payment"
CREDIT_EXPRESS_PAY "Credit Card Express payment"
DEBIT_EXPRESS_PAY "Debit Card Express payment"
ALI_SCANCODE_PAY "Alipay scan code payment"
WEIXIN_SCANCODE_PAY "Wechat scan code payment"
WEIXIN_OFFICIAL_PAY " WeChat Subscription Payment"
APPLE_PAY "Apple Pay"
ALIPAY_WAP_PAY "Alipay payment on mobile's web page
APP_ALIPAY "Alipay APP payment"
OFFLINE-P2P "Offline bank remittance"
realBankSerialNumber Bank Serial Number
needReview true; false
reviewStatus INIT waiting for uploading
UPLOADED waiting for reviewing
CANCEL cancel
SUCCESS review passed
REFUSE Rejected after review
reviewRemark Returned when review/audit rejected
hmac The result of parameter signature,generated by the merchant.For the method of obtaining hmac,please reference to the section "Developers"

Response Fields（payment）

Name Description
amount Unit: China Fen，1 YUAN=100 Fen
currency Please refer to the section "Currency List"
status SUCCESS
FAILED
ERROR
completeDateTime Order completion date
bindCardId Unique ID of card binding information returned by PayEase

Response Fields(foreignExchange)

Name Description
amount Unit: China Fen，1 Yuan=100 Fen
currency Please refer to the section "Currency List"
status SUCCESS
FAILED
ERROR
listprice list price
deductionAmount Unit: China Fen，1 YUAN=100 Fen
completeDate Time Completion time of foreign exchange purchase

Response Fields(subOrders)

Name Description
requestId Sub-order number
orderAmount Sub-order amount, in cents
serialNumber Sub-order Serial Number

Sample

{ "merchantId": "100000050", "requestId": "1487151097417", "serialNumber": "ba3567eef3f743b2a5282c37b6250bb9", "totalRefundCount": "0", "totalRefundAmount": "0", "orderCurrency": "CNY", "orderAmount": "100", "remark": " 备 注 ", "payment": { "amount": "100", "currency": "CNY", "status": "SUCCESS", "completeDateTime": "2018-05-15 17:40:07" }, "foreignExchange": { "amount": "10", "currency": "USD", "status": "SUCCESS", "listprice": "68916", "deductionAmount": "69", "completeDateTime": "2018-05-15 17:59:31" }, "hmac":"UZYjA/bik4TNL9aYSHajULOJxDSJkFyYfDNFxJxYCG1Zyi9s16uvSRmj07M3ax 76JG6STpWc/kyb36mWmg8X8gduvd39NupWK/zJErbgYffOmOd6YpmrvTQhbPioxLN8Ras9 J9zkL7uQ3cTOaLAHOeAQh7Aps3EFJ8MMh+sY4UwIl25h3PEkbBy2sBoug+ZpgLYDXTULrB Y7OQ7cLTczfe5DOxJHLGSMpinHaVFOvQaodR8yZdAygDyfDPm16mKDBBV9NsRsGc0pNXZq +gz0hvTq1dLw+WygTVH8VPFN01bPVHQjxJd3M041kE9ABF/vAP1ExXtSNCevRrAjyyRi4Q==" }