StarPay Settlement MPM&Online - v1.5.4 API Specifications

StarPay MPM/Online Settlement API Specifications
StarPay
MPM / Online Settlement
API Specifications
Version 1.5.4
(English)
1 / 38
Table of Contents
1. OVERVIEW OF SERVICES ............................................................................................... 4
1-1. Interface Requirements ............................................................................................................................ 4
1-2. Interfaces Overview .................................................................................................................................. 4
1-3. Parameters Specifications ....................................................................................................................... 5
1-4. Digital Signature ........................................................................................................................................ 6

(1) Digital Signature Generation ..................................................................................................................... 6
(2) Generating a random character string ...................................................................................................... 8
1-5. Settlement Operation Flow....................................................................................................................... 9

(1) Payment via Scanning ............................................................................................................................... 9
(2) WeChat Pay Official Account Settlement ................................................................................................ 11
2. SERVICES PROVIDED BY THE INTERFACES ............................................................. 14
2-1. Order Request (order) ........................................................................................................................... 14
2-2. Payment Inquiry (payQuery) ................................................................................................................. 19
2-3. Close Order Request (close) ................................................................................................................ 22
2-4. Refund Request (refund) ...................................................................................................................... 24
2-5. Payment Result Notification .................................................................................................................. 27
2-6. Settlement in WeChat Official Account................................................................................................. 31

2-6-1. How to obtain an OpenID ................................................................................................................... 31
2-6-2. Execution of settlement in WeChat Official Account .......................................................................... 33
2-7 RMB Exchange Rate Inquiry (Deprecated Function)............................................................................ 34
2-8. Payment Types Inquiry for Merchants .................................................................................................. 36
2 / 38
Revision History
No. Version Revision Topic Details Author
No. Date
1 1.5.4 2020/03/31 - - -
2 1.5.4 2020/04/28 All Translation to English based on version Jeremiah Chan
1.5.4 JP and 1.5.4 ZH
3 / 38
1. Overview of Services
1-1. Interface Requirements
Subject Details
Data transmission Protocol HTTPS is adopted to ensure security.
Data transmission Method HTTP POST
Transmission Data Format JSON
Client Environment • Support Server Name Indication (SNI)

• Support Transport Layer Security (TLS) v1.2
Character Encoding UTF-8
Signature Digital signature is adopted to ensure data reliability and integrity.
Method of Signature Creation The character string of transmitted/received data is concatenated with an authorization
key and to hashed with MD5 in uppercase.
Refer to “1-4 Digital Signature” for the verification method using digital signature
1-2. Interfaces Overview
Interface Service Description

1. Order Request (order) The merchant initiates a request of payment reservation at the Wallet system (or Payment
Brand Gateway, e.g. WeChat Pay) through this interface and generates a QR code from
the returned response. Then, the customer scans the presented QR code to make the
payment.
2. Payment Inquiry (payQuery) Inquire the payment status. Use this interface to check the transaction process status
even if it’s an abnormality like network or server error.
3. Closing Request Close a payment transaction.
4. (close) If a merchant has failed to make a payment (as Transaction A) successfully and invoke
another payment with a new transaction number, the original payment (Transaction A)
must be closed by invoking this interface to prevent double settlements.
5. Refund Request (refund) Make refund request on succeeded payment transactions only. A fully refunded payment
transaction cannot be refunded.
Notes:
1) Payment transaction cannot be refunded after 7 days. The expiry of the refund validity
is relative to the date/time of payment transaction made.
2) The refund operation supports partial refunds. If the total refund amount exceeds the
payment transaction amount, the API responds with an error.
3) The operational process of Refund is not immediate. Refunding to Wallet user (e.g.
WeChat Pay user) take 1-3 business days for payment withdrawals from the bank
account.
4 / 38
6. Payment Notification Upon receiving of the payment approval, the StarPay server sends the payment result
with the payer information to the merchant. The merchant receives the notification shall
process it and feedback accordingly. The notification URL is the value of NotifyURL
parameter set in the Order Request API.
7. RMB Exchange Rate Inquiry Netstars provides the exchange rate information of Japanese Yen/Chinese Yuan, which
(Deprecated Function) rates are provided by WeChat daily.
8. Payment Type Inquiry for You can check the types of payments that is supported by StarPay multi-payment
Merchant available to participating merchants.
1-3. Parameters Specifications
(1) Amount
All amounts, as stated in the document, do not have a decimal point, and it is in Japanese Yen (JPY).
(2) Time
All times, as stated in the document, is based on Japan Standard Time. All times as stated in the document is
based on Japan Standard Time (JST).
(3) Trading number (or refund number)

The merchant who are using the API shall generate the payment/refund transaction number and transmits it
to Netstars StarPay server. Any transaction numbers (including the refund number) must be unique. It is
recommended for the transaction numbers to be generated from the system time. Any transaction number
generated and used in the past cannot be reused.
(4) Contents of API parameters

All API parameters do not contain comma (,) character.
5 / 38
1-4. Digital Signature
(1) Digital Signature Generation

Any data transmitted or received from Netstars server contains digital signature data.
When sending and receiving messages:
Sign = MD5(Combined Character string of API parameter names and values for
transmittion=authorization key).toUpperCase
Notes:
• The name of the method varies accordingly to the language.
• The authorization key for data will be provided separately.
1. Except for Sign parameter, all parameters are concatenated and arranged in ascending order limited
to ASCII characters.
Example:
param1=value1&param2=param2…&paramN=valueN&key=AuthKey
Notes:
• AuthKey is referring to the Authorization Key, which will be provided separately.
• Any empty data (including empty array) shall not be included in the signature generation.
2. Parameter name or value must not be URL encoded.
3. The authorization key (AuthKey) is appended to end of the concatenated string of parameters and
values and then hashed with MD5.
4. Lastly, convert the entire MD5 hashed string to uppercase.
Note:
For verification of your data received at our server, the hash value is also generated in the above-mentioned
method. When generating the hash value, the Sign parameter received will also be excluded by our server.
6 / 38
Signature Generation Example

If the following parameters are set for transmitted data,
MchId: 10000100
TradeNo: 1000
Desc: test
Nonce: ibuaiVcKdpRxkhJA
1. Arrange parameter names and values as in “param=value” and ascending order of ASCII and coupled.
stringA = "Desc=test&MchId=10000100&Nonce=ibuaiVcKdpRxkhJA&TradeNo=1000"
2. The authorization key is appended to the end of the “string A” and hashed with MD5.
Notes:
• The value of the authorization key shown below is just a sample.
• The function name varies accordingly to the programming language used.
stringSignTemp = stringA + "&key=123456"
Sign = MD5(stringSignTemp).toUpperCase()
= "D0A2E09F646AE53EE6E702CB51C640C0"
3. Finally, place the data into JSON format are created as follows:
{
"MchId":"10000100",
"TradeNo":"1000",
"Desc":"test",
"Nonce":"ibuaiVcKdpRxkhJA",
"Sign":"D0A2E09F646AE53EE6E702CB51C640C0"
}
7 / 38
(2) Generating a random character string
Any data transmitting or receiving by our server includes a random character string Nonce parameter, which
concatenates with other parameters to yield an unpredictable signature. To generate a signature, use the
function provided by the programming language framework to create a string of random characters is
recommended.
8 / 38
1-5. Settlement Operation Flow
(1) Payment via Scanning
Payment via Scanning is supported by WeChat Pay, UnionPay QR Code, Alipay, LINE Pay, Rakuten Pay,
PayPay, and J-Coin Pay.
The merchant presents a QR code for payment according to the rules of each payment. Subsequently, the
customer (or wallet user) scans the QR code with the QR code reader, which is a scanning function featured
by the wallet application, to complete the payment process.
This method is suitable for payment sites such as e-commerce websites, mobile terminals, vending machines,
game machines, printing kiosk, fully automatic online washing machines featuring payment terminal with
monitor, media advertisements, and retail stores.
The example below shown is an example of a settlement paid via WeChat Pay.
Step-1:
The merchant presents the QR code every time to the customer proceeds to make payment checkout, after
the confirming on the product info such as the product names and prices at EC site as an example.
9 / 38
Step-2:
After the buyer scans the QR code using the scan function, the payment information of the product has
been obtained by the WeChat Pay mobile application.
Step-3:
The customer also confirms the payment information on the mobile application and enters the payment
passcode set by himself/herself.
10 / 38
Step-4:
The mobile app displays the result upon successful payment. The merchant receives a notification of the
payment result as well and proceeds to the next stage of purchasing such as shipping delivery.
(2) WeChat Pay Official Account Settlement
For official account settlement, the merchant shall have a mobile website setup that conforms to HTML5
standards and an official account with WeChat Pay.
The customer opens a WeChat webpage on his mobile app by opening a URL or by scanning the QR code
from the site. Then, the merchant site will call WeChat Pay to complete the payment.
Note: This development method is suitable for those who have same implementation setup as WeChat Pay
Official Account.
11 / 38
Step-1:
The user opens the merchant's website and proceeds with the purchase.
Step-2:
Customer’s mobile payment app connects with WeChat Pay and prompts for entering his payment
passcode.
12 / 38
Step-3:
If the password verification returns positive, the customer proceeds to complete the payment, and the merchant
receives a notification of confirmed payment as well.
The following are about interacting with the server during settlement. Please design the payment logic with
these considerations.
(1) The customer opens the merchant's website, selects a product, and proceeds with the payment. Call the
getBrandWCPayRequest interface in JavaScript through the website, request the payment via the
WeChat Open Platform, and the customer proceeds with the payment.
(2) After the customer has successfully paid and clicked the Finish button, the merchant's site receives the
JavaScript return data and displays a static page on the successful payment.
(3) The merchant system receives the successful payment callback notification from the WeChat Pay open
platform and processes the transaction as successful payment.
Note: Point (2) and (3) do not guarantee a strict order. While JS API returning the data at point (2) is considered
a trigger to update the web page (or screen) on-site, whereas the merchant systems at point (3) shall process
the successful payments after the WeChat Pay Open Platform provides a successful payment callback
notification.
13 / 38
2. Services Provided by the Interfaces
2-1. Order Request (order)
Firstly, the merchant system initiates a request for a payment reservation at the payment gateway systems
through this API. Upon successful reservation, it receives a URL with the payment session data as the
response, which subsequently encoded into a displayable QR code image. The customer scans the presented
QR code with his wallet app (e.g. WeChat Pay) to proceed with the actual payment.
The validity of the payment reservation lasts for 1 hour.
Request URL: https://***.*****.**/*******/order
Request Parameters
Name Parameter Name Data Type Input Data Example Remarks
Required
Merchant ID MchId String(32) Required Nssonline ID allocated to each merchant
company who uses this API
Random Nonce String(32) Required 20151019190813
Character 999
String
Digital Sign String(32) Required 5251C29FCE771B
Signature 3C3067A613BCB5
4E76
Transaction TradeNo String(16) Required 160616203700 A unique value is required.

Number
Payment OrderAmount Int Required 1000 Payment amount in Japanese Yen
Amount
Payment Type TradeType String(16) Required NATIVE Refer to table “Payment Types” at
chapter “2-8 Payment Types Inquiry
for Merchants”
Product Desc String(32) Required Order product information. Product
Description name, category, etc.
Product Details Detail String(2048) -
Notification NotifyUrl String(256) Required http://x.x.x.x This is the callback URL of the
URL /notify payment result notification. If this is
not set, result notification will not be
delivered, and your system have to
confirm with the payQuery
interface.
14 / 38
Additional Attach String(127) - Can be set by the party who is

Information using this API.
Merchant SubOpenId String(128) Required ※ Require input only when the
Open ID ※ payment type is JSAPI / MINIPRO.
An official account of an overseas
corporation is a prerequisite.
You need to set here with the
account holder’s OpenID of official
account.
QR Code URL CodeType String(16) - web Applicable to LINE Pay only.
Type web: For online web payments,
which indicates it is a response
returns with a QR code URL for
web payment.
app: For payment within the App,
which indicates it is a response
returns with a QR code URL for the
application payment.
The default value is web.
Transition URL BackToMchUrl String(256) - http://x.x.x.x If this parameter is set, it transits to
/backtomchurl the specified URL after payment
completion.
If this parameter is not set, the
system transits to the default URL
set by the system.
Notes:
1) This setting is applicable only for
the following payment types: LNPAY
and ALMOB.
2) Upon transition, the transaction
number and payment status can be
passed as the URL parameters.
Request Example
{
"Nonce":"T8Uyw7kgfnhEdk5l",
"Sign":"EEC462A3BC580FBB68ED1E5C076C222D",
"Attach":"attach",
"Desc":"test",
"Detail":"category",
"MchId":"nssonline",
15 / 38
"NotifyUrl":"http://0.0.0.0/spOnlineNotify",
"OrderAmount":1,
"TradeNo":"160616203700",
"TradeType":"NATIVE"
}
Response Parameters
Name Parameter Data Type Input Data Example Remarks
Name Required
Random Character Nonce String(32) Required
String
Digital Signature Sign String(32) Required
Operation Result Result String(32) Required SUCCESS Refer to the table below,
“Operation Result Codes”
Operation Result ResultDesc String(512) Required
Description
If the value of Result is “SUCCESS”, the following parameters are included:

Name Required
Transaction TradeNo String(16) Required 160616203700 Same value as the request
Number parameter
QR Code URL CodeUrl String(512) Required weixin://wxpay/b When the payment type is
izpayurl?pr=cJwX NATIVE / ALQR / ALMOB /
tUK PAYPAYMPM / RKTPAY, the
QR code is generated
based on this value.
When the payment type is
LNPAY, the payment URL
for the web (which is the
default) or the payment
URL for the app is returned
based on the value of
CodeType.
* The expiry duration is one
hour. After the expiration
time, proceeding with the
actual payment requests
would fail.
16 / 38
Payment PrepayId String(64) Required wx20160527173526 Used when calling with the
Reservation 3473ff6285091902 JS interface, at which the
Session ID 3471 TradeType value is
JSAPI or MINIPRO. Its
validity duration is one
hour. Refer to details at
chapter 2-6-2.
If the TradeType value is
UPIMPM, it responds with
the value of the payment
barcode. The validity
duration is one hour.
Response Example, if the TradeType is “NATIVE”:

{
"CodeUrl":"weixin://wxpay/bizpayurl?pr=OgEqWHh",
"Nonce":"XTJfifwTQDkgzEM1",
"PrepayId":"wx20160616193939a314a204b80074682185",
"Result":"SUCCESS",
"ResultDesc":"Request Success",
"Sign":"37E0FC972E3374E86B2A36B76B8D04A0",
"TradeNo":"160616203700"
}
Response Example, if the TradeType is “UMIMPM”:

{
"CodeUrl": "UPIQRC",
"Nonce": "3aBcHujwIYLaALBD",
"PrepayId":
"00020101021215313939039200520446NETSNSSO00000005204472253033925402015802JP5916Test Online
Shop6005Tokyo62390125NETSNSSOPST20194E226445555706D4142363042C89",
"Result": "SUCCESS",
"ResultDesc": "Request Success",
"Sign": "9861277BFB1B500000000000766F0F040",
"TradeNo": "ST20191000000007"
}
17 / 38
Response Example, if the TradeType is “JSAPI/MINIPRO”:

{
"CodeUrl":"weixin://wxpay/bizpayurl?pr=OgEqWHh",
"Nonce":"XTJfifwTQDkgzEM1",
"PrepayId":"{'appId':'wx2421b1c4370ec43b','timeStamp':'1395712654',
'nonceStr':'e61463f8efa94090b1f366cccfbbb444',
'package':'prepay_id=u802345jgfjsdfgsdg888','signType':'MD5',
'paySign':'70EA570631E4BB79628FBCA90534C63FF7FADD89'}",
"Result":"SUCCESS",
"ResultDesc":"Request Success",
"Sign":"37E0FC972E3374E86B2A36B76B8D04A0",
"TradeNo":"160616203700"
}
Note: The value of PrepayId (in JSON format) is used for “2-6-2. Mobile Page Settlement”.
Operation Result Codes

Result Code Description
SUCCESS Successful payment
PARAM_ERROR Parameter error
MCH_SIGN_ERROR Digital signature error
MCH_STATE_ERROR The status of merchant is invalid
TRADE_NO_USED Due to duplication of transaction number or the payment request must have a new unique
transaction number.
SYSTEMERROR Communication failure or interface error, etc.
NOTENOUGH Insufficient amount balance
ORDERCLOSED The transaction has already been closed. Please make a new order all over again.
ORDERREVERSED The transaction has already been cancelled and the new order request must have a new
transaction number.
OTHER_ERROR Other error
18 / 38
2-2. Payment Inquiry (payQuery)

The interface inquires the status of request payment.
For example, use this when an error occurs in the system, or the network and operation result code of the
payment processing request cannot be received.
Note: In case of WeChat Pay payment, if you spam with the "Payment Inquiry" API to check for transaction
status, the session may respond by the WeChat Pay with SYSTEM ERROR. Hence, as a recommendation
from the WeChat Pay, please limit calling this interface at the intervals of 10 seconds.
Request URL: https://***.*****.**/*******/payQuery
Request Parameters
Name Required
Merchant ID MchId String(32) Required nssonline

Character String
Digital Signature Sign String(32) Required 5251C29FCE771B3C3
067A613BCB54E76
Transaction TradeNo String(16) Required The transaction number

Number created from Order
Request
Request Example
{
"Nonce":"AD1GERW4XKKveORj",
"Sign":"636ACE854F4FE97DB96003DC886DBAA4",
"TradeNo":"160530180300"
}
Response Parameters
Name Required
Character String
Digital Signature Sign String(32) Required DFF13146054EF9F5C
39D338247C0EB6D
Operation Result Result String(32) Required SUCCESS Refer to table “Operation
Result Codes” below
19 / 38
Operation Result ResultDesc String(512) Required Query SUCCESS

Description

Name Required
Transaction TradeNo String(16) Required Same value as request
Number parameter
Payment Type TradeType String(16) Required NATIVE Refer to table “Payment
Types” at chapter “2-8
Payment Types Inquiry for
Merchants”
Trade Status TradeState String(32) Required REFUND Refer to the table “Trade
Status Code” below
Payment OrderAmount Int Required 1080 Payment amount
Amount (Japanese Yen)
Additional Attach String(127) Required Attach Same value as request
Information parameter of request for
payment
Paying Bank BankType String(16) Required CFT Abbreviated name of the
bank used for the payment
Payment TradeTime String(16) Required 20160605191250 Format: yyyyMMddHHmmss
Completion Time
Response Example
{
"Attach":"attach",
"BankType":"CFT",
"Nonce":"jwDzr1fvKmLw81ji",
"OrderAmount":1,
"Result":"SUCCESS",
"ResultDesc":"Query SUCCESS",
"Sign":"00A736D319049CA13FF302E230840503",
"TradeNo":"160531220100",
"TradeState":"REFUND",
"TradeTime":"20160531210645",
"TradeType":"NATIVE"
}
20 / 38

Code Description
MCH_STATE_ERROR The merchant information is invalid
SYSTEMERROR Communication failure or occurrence of error in the interface, etc.
ORDERNOTEXIST The transaction number does not exist or cannot be identified
Trading Status Code

Code Description
REFUND Successful refund
NOTPAY Unpaid or the status where a user has cancelled the payment on the entry screen for passcode
input.
CLOSED Already closed
REVOKED Already cancelled
USERPAYING The user is paying or entering a payment passcode
PAYERROR Failure of payment due to other causes. Wrong passcode or error returned by the bank system,
etc.
21 / 38
2-3. Close Order Request (close)

Invoking of this interface is required under the following circumstances:
• When the merchant wants to fail the processing Order Request and make a new payment, the original
transaction requested must be closed to prevent double payments.
• If the user's payment times out after the system requests order processing, the system cannot accept
the payment and the transaction must be closed.
Note: Only unpaid transactions can be closed by the interface.
Request URL: https://***.*****.**/*******/close
Request Parameters
Name Required
Merchant ID MchId String(32) Required nssonline Merchant ID assigned by
StarPay to identify
merchant
Random Character Nonce String(32) Required 2015101919081399
String 9
Digital Signature Sign String(32) Required 5251C29FCE771B3C

3067A613BCB54E76
Transaction TradeNo String(16) Required Transaction number

Number created at the time of
Order Request process
Request Example
{
"Nonce":"FbtFwX6uqrrxQJ9N",
"Sign":"BBF7B0F805335FE02C43A3F22B149217",
"TradeNo":"160530180300"
}
22 / 38
Response Parameters
Name Required
String 2
Digital Signature Sign String(32) Required 7326D8E34F6EA840

E82A24DA4E721266
Operation Result String(32) Required SUCCESS Refer to table “Operation

Result Result Codes” below
Operation Result ResultDesc String(512) Required Close order
Description Success
Response Example
{
"Nonce":"pu1YG8aMaJDicmwA",
"Result":"SUCCESS",
"ResultDesc":"Close order Success.",
"Sign":"976F24EADDF760B1CE29C71E64DFED1D"
}

Code Description
ORDERNOTEXIST The transaction does not exist
ORDERCLOSED The transaction is already closed
ORDERPAID The transaction has already been paid and cannot be closed
23 / 38
2-4. Refund Request (refund)
Refunds are possible within a limited period after payment has been made.
After receiving the refund request, we process the refund according to the Refund Terms and Conditions (T&C)
for each payment.
WeChat Pay:
Within 3 business days for withdrawal from the bank account and within 20 minutes for the charge (of coin
function). Upon approval, the amount will be refunded to WeChat customer.
UnionPay Payment:
The customer's bank usually refunds to the user within 3 business days.
Alipay:
If the customer paid with Alipay wallet, the refund is immediate. In case of withdrawal from a bank
account, the amount will be refunded within 2-7 business days.
LINE Pay:
LINE Pay customer paid with its wallet will be refunded within 3 days. Refund expiry for other payment
methods is 30 days; if the refund proceeds after the expiry, the refund will be rejected.
For payment that supports partial refund, a payment transaction can be refunded multiple times (as multiple
refund transactions). The refund number of each refund transaction must be unique. If a refund request is
initiated and failed, use a new unique refund number for each refund transactions retries. Nevertheless, the
total refund amount cannot exceed the amount paid by the customer for each payment transaction.
Refer to chapter 2-8 " Payment Types Inquiry for Merchants" for details on the partial refund regulations.
Request URL: https://***.*****.**/*******/refund
Request Parameters
Name Required
Merchant ID MchId String(32) Required
String
067A613BCB54E76
Number created for Order
24 / 38
Request
Refund Number RefundNo String(16) Required A unique value is set.
Payment amount OrderAmount int Required The amount in Japanese
Yen
Refund Amount RefundFee int Required In Japanese Yen and
supports partial refund.
Sum of refund amounts
from multiple refunds
cannot exceed the
amount of its payment
transaction.
Request Example
{
"Nonce":"H1R9UzHKUkMzr8xF",
"Sign":"C7DE5C01ABB800A8AFB79AA14381537F",
"OrderAmount":1,
"RefundFee":1,
"RefundNo":"160530193100",
"TradeNo":"160530193100"
}
Response Parameters
Name Required
string
Digital Signature Sign String(32) Required C1FA1590C6C77EFE7
D8555C5C297514E
Operation Result Result String(32) Required SUCCESS Refer to the table

below
Description
25 / 38

Name Required
Number created at the time Order
Request
Refund Number RefundNo String(16) Required Same value as request
parameter
Payment Amount OrderAmount Int32 Required Payment amount in JPY
Refund Amount RefundAmount Int32 Required Refund amount in JPY
Refund Time RefundTime String(16) Required 20151104203522 Format:
yyyyMMddHHmmss
Response Example:
{
"Nonce":"up2bkTfJ0xLLRQpu",
"OrderAmount":"1",
"RefundAmount":"1",
"RefundNo":"160530193100",
"RefundTime":"20160530193721",
"Result":"SUCCESS",
"ResultDesc":"Refund Success",
"Sign":"B9CA2451F568C0154A8F69DA2EA6BA96",
"TradeNo":"160530193100"
}

Code Description
SUCCESS Success
SYSTEMERROR Communication failure or error returns on the interface, etc.
REFUND_FEE_INVALID The refund amount is invalid, or the total sum of refund amounts exceed the payment
transaction amount.
REFUND_NO_USED Duplication on the refund number used. A new unique refund number is needed.
TRADE_NO_INVALID The transaction number is invalid, the payment transaction referenced by the refund cannot be
found
REFUND_EXPIRE The time available for the refund has expired
FAIL For other refund failures. Please refer to the responded parameter "Operation Result
Description" for details.
26 / 38
2-5. Payment Result Notification
After receiving the approval of a payment, StarPay must send the payment result and user information of the
payment to the merchant who will subsequently process the receipt and feedback with a response.
When StarPay sends the notification to the merchant's server and cannot receive a feedback response, which
could due to timeout, StarPay determines that notification is a failure and will subsequently send the notification
periodically at an interval pattern (for example, 5 times in 30 minutes). Even though trying to maximize the
success rates as much as possible, StarPay cannot guarantee it is a definite success of the notifications. The
notification interval pattern is 15, 15, 30, 180, 1800 seconds.
It is possible to send same notifications to the merchant system multiple times, and the merchant system must
handle the receiving to prevent redundancy of double processing. It is recommended that when the merchant
system receives a notification, validate the status (and data) internally and determine whether the notification
has been already processed. If it has not been processed, it will be processed and responds with a "success".
If it has been processed, respond it with a "success" directly.
In consideration of security, the merchant system must always validate the received payment result notification
with a digital signature, which prevents financial loss due to receiving and processing fake notification.
Request URL: * It is the same as the NotifyUrl parameter value set in Order Request API.
Request Parameters
Name Required
String
Digital Signature Sign String(32) Required 93D744E27AFF34676
C23405EAE8612B4

“Operation Result
Codes” below
Operation Result ResultDesc String(512) Required Pay Success
Description
27 / 38

Name Required
Transaction TradeNo String(16) Required
Number
Additional Attach String(127) -
Information
Transaction Status TradeState String(32) Required SUCCESS
Payment Bank BankType String(127) Required BOC_DEBIT Respond with the paying
bank identification code, or
the payment method (fixed
string) for unsupported
payments
Payment Amount OrderAmount int Required In Japanese Yen (JPY)
Payment Time TradeTime String(16) Required Format: yyyyMMddHHmmss
Payment Type TradeType String(16) Required Refer to table “Payment
Types” at chapter “2-8
Payment Types Inquiry for
Merchants”
Payer Information WxOpenID String(32) - When TradeType is
NATIVE or JSAPI, it
responds the WeChat Pay
User ID. Otherwise, it
responds the encrypted
account information.
StarPay does not
guarantee the accuracy of
this information.
Request Example
{
"Attach":"attach",
"BankType":"BOC_DEBIT",
"Nonce":"WNPF70G762hNRDEc",
"OrderAmount":1,
"Result":"SUCCESS",
"ResultDesc":"Pay Success",
"Sign":"7AD6231C594A7277000E83040F5C6BCD",
"TradeNo":"160530194800",
"TradeState":"SUCCESS",
28 / 38
"TradeTime":"20160530185034",
"TradeType":"NATIVE",
"WxOpenID":"12345678901234567890123456789012"
}
Response parameters
Note: Below are the response parameters respond back to StarPay after processing by the system at merchant
side.
Name Required
String
Digital Signature Sign String(32) Required 93D744E27AFF34676
C23405EAE8612B4
Operation Result Result String(32) Required SUCCESS
Operation Result ResultDesc String(512) Required OK

Description
Response Example
{
"Nonce":"PutekroReM0fI9VV",
"Sign":"372F6C7E5A6200EB3D27414468D7FF58",
"Result":"SUCCESS",
"ResultDesc":"OK"
}

Code Description
SUCCESS The merchant has acknowledged receiving the notification with verification.
FAIL Failed
Setting the Transition URL after payment has been completed

(Applicable only to ALMOB and LNPAY payments.)
When using the Alipay online (TradeType = ALMOB) and LINE Pay (TradeType = LNPAY) at the merchant site,
the Transition URL (BackToMchUrl) can be set at Order Request API. If you set the Transition URL parameter
and after the customer completes the payment, the screen of the browser (or in-app embedded browser) used
for payment will automatically display the page with the set URL. If you do not set the Transition URL, it displays
the default URL defined on StarPay system.
29 / 38
When displaying the page with the Transition URL at runtime, the URL can be appended with the transaction
number and payment status as URL parameters (i.e. URL Query Strings)
Example:
BackToMchUrl?tradeno=xxxxxxxxxxxxxxx&osta=success&msg=paysuccess
Parameters
Parameter Description
tradeno Transaction number of the successful payment
osta Payment result
Msg Description of payment result
30 / 38
2-6. Settlement in WeChat Official Account
In order to support WeChat Pay payment on the mobile website (with HTML5) and payment/settlement in
Japanese Yen, it is necessary to use an official WeChat account for overseas companies. The official WeChat
account acquires the name of a company in Mainland China is not suitable for the payment interface and the
functions cannot be executed.
The merchant opens the web page (HTML5) in the WeChat browser and calls the payment process using
JavaScript. Please note that the WeixinJSBridge object in JavaScript is only compatible with WeChat
browsers and cannot be used with other browsers. The parameters are case sensitive, and since they are
case sensitive, the digital signature will cause the validation to fail.
To call this interface, you need to provide an account with the OpenID information associated with the official
WeChat account.
2-6-1. How to obtain an OpenID
The account's OpenID is the only identification for the WeChat Official Account and is only valid for use with
that official account. This specification describes only the basic method of acquiring OpenID.
(Supports HTML5 web page payment)
(1) The user who uses the WeChat official account will be guided to the following URL to obtain a necessary
value.
https://open.weixin.qq.com/connect/oauth2/authorize?appid=APPID&redirect_uri=REDIREC
T_URI&response_type=code&scope=SCOPE&state=STATE#wechat_redirect
Required Request Parameters

Parameter Input Remarks
Required
appid Required A unique symbol of WeChat official account. It can be confirmed by login to the platform
of WeChat official account.
redirect_uri Required A URI of redirection destination to which a screen moves after authorization.
Please perform URL encoding.
State A value which the merchant can set. It holds the value of state after redirection.
The developer can set any value of “a-z”, “A-Z” or “0-9”(128 bytes at a maximum).
Note: Parameters other than the required parameters are retained unchanged.
31 / 38
(2) After obtaining necessary values through the above (1), the page will be switched to:
redirect_uri/?code=CODE&state=STATE
After obtaining the value of code, an OpenID can be obtained by accessing to the following URL.
(Calling up by “GET” is acceptable.)
https://api.weixin.qq.com/sns/oauth2/access_token?appid=APPID&secret=SECRET&code=COD
E&grant_type=authorization_code
Request Parameters
Parameter Input Remarks
Required
appid Required A unique identification of WeChat official account. It can be confirmed by signing into the
platform for WeChat Official Account.
secret Required A secret key for each WeChat official account. It can be confirmed by signing into the platform
for WeChat Official Account.
code Required A value of code obtained in the step of (1).
Response Parameters
After sending the correct value, the JSON data such as the below will be responded.
{
"access_token":"ACCESS_TOKEN",
"expires_in":7200,
"refresh_token":"REFRESH_TOKEN",
"openid":"OPENID",
"scope":"SCOPE",
"unionid": "o6_bmasdasdsad6_2sgVt7hMZOPfL"
}
Parameter Remarks
access_token Web page authorization interface access token
expires_in Expiry duration (in seconds) valid for the issued access_token
refresh_token Indicates user refreshes the token
openid User identification ID in WeChat official account. Use as the parameter value of SubOpenID
scope User's authorization scope, comma (,) is used for division.
Unionid Merchants will only receive these parameters after linking their official WeChat account to their
WeChat open platform account.
When error occurs, WeChat returns the following JSON data. For example, an invalid code is used.
{"errcode":40029,"errmsg":"invalid code"}
32 / 38
2-6-2. Execution of settlement in WeChat Official Account
When applying for this feature, you have to provide the domain name and the path to HTML5 payment page.
After getting OpenID, generate JSON format with other parameters (see 2.1 Order Request) and call Order
Request interface (order). If there is no problem with the parameters, you will get the PrepayId.
Open the HTML5 page in the WeChat browser and execute JS call for the settlement. (Data format is JSON)
Note: WeixinJSBridge objects can only be used by WeChat (in-app) browsers.
Code Example
function onBridgeReady(){
WeixinJSBridge.invoke(
'getBrandWCPayRequest',
//JSON parameter string obtained from 2-1 Order Request interface.
function(res) {
if (res.err_msg == "get_brand_wcpay_request：ok" ) { }
//The return of front end will be judged with the above method.
//Note: res.err_msg returns "ok" after successful payment by the user, but it is not absolutely guaranteed.
}
);
}
if (typeof WeixinJSBridge == "undefined") {
if ( document.addEventListener ) {
document.addEventListener('WeixinJSBridgeReady', onBridgeReady, false);
} else if (document.attachEvent) {
document.attachEvent('WeixinJSBridgeReady', onBridgeReady);
document.attachEvent('onWeixinJSBridgeReady', onBridgeReady);
}
} else {
onBridgeReady();
}
Note:
As the result of JS API returns, "get_brand_wcpay_request: ok" is returned only when the WeChat user
has successfully paid. Due to the complexity of exchange information at the front-end,
“get_brand_wcpay_request: cancel” and “get_brand_wcpay_request: fail” should be handled
uniformly, and it is not necessary to distinguish whether the WeChat user voluntarily canceled or resulted in
an error.
33 / 38
2-7 RMB Exchange Rate Inquiry (Deprecated Function)
It can be used only at merchant stores that use WeChat Pay, and WeChat official provides the exchange rate
information. The rates are updated daily at 10:00 am.
* Netstars does not guarantee that the rate matches the rate at the time of the transaction.
Request URL: https://***.*****.**/*******/queryRate
GET Request Parameters

Name Required
Merchant ID MchId String(32) Required Mch0001
Random Character 20151019190813999

Nonce String(32) Required
String
5251C29FCE771B3C3
067A613BCB54E76
NATIVE/JSAPI/MINI
Payment Type TradeType String(8) Required NATIVE
PRO
Confirmed Date SerDate String(8) Required 20151019 yyyyMMdd
Request Example
{
"Sign":"BBF7B0F8011111111111A3F22B149217",
"MchId":"0001000100010001",
"TradeType":"NATIVE",
"SerDate":"20180315"
}
Response Parameters
Name Required
String
5251C29FCE771B3C3
067A613BCB54E76
Refer to the table

Operation Result Result String(32) Required “Operation Result
Codes” below
Operation Result
ResultDesc String(512) -
Description
34 / 38
If the value of Result is “SUCCESS”, the following parameters are included.

Name Required
Confirmed Date/Time RateDate String(32) Required Mch0001

String
Response Example
{
"Sign":"976F24E111F760B1CE29C71E64DFED1D",
"Result":"SUCCESS",
"ResultDesc":"Query Success.",
"RateDate":"20180315",
"Rate":"5920000"
}

Code Description
SUCCESS Success
35 / 38
2-8. Payment Types Inquiry for Merchants
The following are the payment types of StarPay multi-payment available to participating merchants.
Request URL: https://***.*****.**/*******/mchTradeType
Request Parameters
Required
Character String
067A613BCB54E76
Request Example
{
"Sign":"BBF7B0F8011111111111A3F22B149217",
"MchId":"0001000100010001"
}
Response Parameters
Required
Character String
Digital Signature Sign String(32) Required C1FA1590C6C77EFE7
D8555C5C297514E

below
Description
36 / 38

Required
Payment Type MchTradeType String(512) Required If there are multiple payment
types, “_” (underscore)
character is inserted as
separator in between the
payment types
Member Store MchSta String(32) Required ENABLE: In use
Usage Status DISABLED: Not using
Request Example:
{
"Sign":"976F24E111F760B1CE29C71E64DFED1D",
"Result":"SUCCESS",
"ResultDesc":"Query Success.",
"MchTradeType":"JSAPI_NATIVE_CNPAY_LNPAY_ALQR"，
"MchSta":"ENABLE"
}

Code Description
SUCCESS Success
Payment Types (TradeType)

Payment Type Payment Type Description Payment Partial Payment
Name Code Currency Refund Expiry
WeChat Pay JSAPI Payment type for an official account of WeChat CNY Support 60 min
Pay
WeChat Pay NATIVE Payment type for a QR code of PC site of WeChat CNY Support 60 min
Pay
WeChat Pay MINIPRO WeChat Mini Program Payment Type of WeChat CNY Support 60 min
Pay
Alipay ALQR Payment type for a QR code of Alipay CNY Support 60 min
37 / 38
Alipay ALMOB Alipay web payment types CNY Support 60 min
UnionPay UPIMPM UnionPay payment type, which supports EMV CNY Support 60 min
International QR code format
LINE Pay LNPAY Payment type for LINE Pay. It supports payment JPY Support 60 min
by Web or in App
PayPay PAYPAYMPM PayPay payment type (MPM) JPY No 60 min
Rakuten Pay RKTPAY Payment by Rakuten Pay (supports payment on JPY No 60 min
the website)
ChinaPay CNPAY ChinaPay online payment type CNY No 60 min

J-Coin Pay JCOINMPM J-Coin Pay online payment type (MPM) JPY No 1 min
MERPAY MERPAYOM MERPAY online payment types JPY No 20 min
Operation Scenario for Payment Type

Payment Type Payment Type Mobile Terminal EC Website Offline Store /
Code (smartphone, tablet) Vending Machine
App Mobile Official Account / Website QR Dynamic QR

Website Mini Program Display
WeChat Pay JSAPI 〇
NATIVE 〇〇
MINIPRO 〇
Alipay ALQR 〇〇〇〇
ALMOB 〇〇〇〇
It is possible for the
webpage transition
designated by the
store.
UnionPay UPIMPM 〇〇
International
ChinaPay CNPAY 〇〇〇
LINE Pay LNPAY 〇〇〇〇
PayPay PAYPAYMPM 〇〇
Rakuten Pay RKTPAY 〇〇〇〇
J-Coin pay JCOINMPM 〇
MERPAY MERPAYOM 〇〇〇〇
38 / 38

StarPay Settlement MPM&Online - v1.5.4 API Specifications

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

StarPay Settlement MPM&Online - v1.5.4 API Specifications

Uploaded by

Copyright:

Available Formats

StarPay MPM/Online Settlement API Specifications

1. OVERVIEW OF SERVICES ............................................................................................... 4

1-1. Interface Requirements ............................................................................................................................ 4

1-2. Interfaces Overview .................................................................................................................................. 4

1-3. Parameters Specifications ....................................................................................................................... 5

1-4. Digital Signature ........................................................................................................................................ 6

1-5. Settlement Operation Flow....................................................................................................................... 9

2. SERVICES PROVIDED BY THE INTERFACES ............................................................. 14

2-1. Order Request (order) ........................................................................................................................... 14

2-2. Payment Inquiry (payQuery) ................................................................................................................. 19

2-3. Close Order Request (close) ................................................................................................................ 22

2-4. Refund Request (refund) ...................................................................................................................... 24

2-5. Payment Result Notification .................................................................................................................. 27

2-6. Settlement in WeChat Official Account................................................................................................. 31

2-7 RMB Exchange Rate Inquiry (Deprecated Function)............................................................................ 34

2-8. Payment Types Inquiry for Merchants .................................................................................................. 36

1-1. Interface Requirements

Client Environment • Support Server Name Indication (SNI)

1-2. Interfaces Overview

Interface Service Description

1-3. Parameters Specifications

(3) Trading number (or refund number)

(4) Contents of API parameters

1-4. Digital Signature

(1) Digital Signature Generation

When sending and receiving messages:

2. Parameter name or value must not be URL encoded.

4. Lastly, convert the entire MD5 hashed string to uppercase.

Signature Generation Example

stringSignTemp = stringA + "&key=123456"

(2) Generating a random character string

1-5. Settlement Operation Flow

(1) Payment via Scanning

(2) WeChat Pay Official Account Settlement

2. Services Provided by the Interfaces

2-1. Order Request (order)

The validity of the payment reservation lasts for 1 hour.

Request URL: https://***.*****.**/*******/order

Transaction TradeNo String(16) Required 160616203700 A unique value is required.

Additional Attach String(127) - Can be set by the party who is

If the value of Result is “SUCCESS”, the following parameters are included:

Response Example, if the TradeType is “NATIVE”:

Response Example, if the TradeType is “UMIMPM”:

Response Example, if the TradeType is “JSAPI/MINIPRO”:

Operation Result Codes

2-2. Payment Inquiry (payQuery)

Request URL: https://***.*****.**/*******/payQuery

Random Nonce String(32) Required 20151019190813999

Transaction TradeNo String(16) Required The transaction number

Operation Result ResultDesc String(512) Required Query SUCCESS

If the value of Result is “SUCCESS”, the following parameters are included:

Operation Result Codes

Trading Status Code

2-3. Close Order Request (close)

Note: Only unpaid transactions can be closed by the interface.

Request URL: https://***.*****.**/*******/close

Digital Signature Sign String(32) Required 5251C29FCE771B3C

Transaction TradeNo String(16) Required Transaction number

Digital Signature Sign String(32) Required 7326D8E34F6EA840

Operation Result String(32) Required SUCCESS Refer to table “Operation

Operation Result Codes

2-4. Refund Request (refund)

Request URL: https://***.*****.**/*******/refund

Request URL: https://../*******/order

Request URL: https://../*******/payQuery

Request URL: https://../*******/close

Request URL: https://../*******/refund

Request URL: https://../*******/queryRate

Request URL: https://../*******/mchTradeType

LINE Pay LNPAY 〇〇〇〇

Rakuten Pay RKTPAY 〇〇〇〇