StarPay Settlement CPM POS - v2.0.23 - API Specifications

StarPay
Version 2.0.23
(English)
Netstars Co., Ltd.

StarPay CPM Settlement API Specifications
Table of Contents
1. BUSINESS OVERVIEW .................................................................................................................. 3
1-1. Interface Requirements .............................................................................................................................. 3
1-2. Interfaces Overview.................................................................................................................................... 3
1-3. Parameter Specifications ........................................................................................................................... 4
1-4. Digital Signature ......................................................................................................................................... 5

(1) Generate hash value for digital signature ............................................................................................................5
(2) Generate Random Character String ....................................................................................................................7
(3) Attention to Verification of Digital Signature .........................................................................................................7
1-5. Payment Password Input Rules ................................................................................................................. 8
1-6. Available Payment Types ........................................................................................................................... 9
2. SERVICES PROVIDED BY INTERFACE ..................................................................................... 10
2-1. Sign In（signIn） .................................................................................................................................. 10
2-2. Payment Request（pay） ....................................................................................................................... 14
2-3. Payment Inquiry（payQuery）............................................................................................................... 17
2-4. Cancellation Request（revoke）........................................................................................................... 21
2-5. Refund Request（refund） ................................................................................................................... 23
2-6. Balance and Points Inquiry (balanceQuery) ........................................................................................ 27
2-7. Historical Transaction Inquiry（recordQuery2） ................................................................................. 29
2-8. Service Check（serviceDetect） ...................................................................................................... 34
Page 1 of 35
Change History
No. Version Revision Topic Details Author
No. Date
1 2.0.23 2019/07/20 - - -
2 2.0.24 2020/04/28 All Translation to English based on version Jeremiah Chan
20.0.23 JP and 20.0.24 JP Draft
Page 2 of 35
1. Business Overview
StarPay gateway provides the payment functionalities of multi-payment (QR code/barcode settlement) to the
merchant. The interfaces specified in this document are for POS terminals and various payment terminals including
iOS and Android mobile terminals in Customer-Presented Mode (CPM, also known as B-scan-C Mode).
The customer presents the QR code/barcode, and the merchant scans it with the payment terminal/POS scanner to
initiate the payment process via the provided interfaces.
1-1. Interface Requirements

Subject Content
Data Transmission Protocol HTTPS
Support TLS versions: 1.0, 1.1 and 1.2
❖ TLS 1.2 is recommended
Data Transmission Method HTTP POST
Data Format JSON
Character Code UTF-8
Signature Adopt digital signature and hashing for assurance of data integrity
Signature Creation Concatenate the authorization key with the requesting parameter names and values (of the
interface) and hash it with MD5 for data communication.
❖ Refer to the chapter “1-4 Digital Signature” for the validation method for digital signature.
1-2. Interfaces Overview

Interface Content
1. Sign In
Sign in is required to access various payment services.
(signIn)
2. Payment Request Scan the QR code/barcode presented by the customer and initiate the payment request
(pay) process.
3. Payment Inquiry Initiate an inquiry request for the status of a payment. If the result of the payment response is
(payQuery) USERPAYING, invoke this interface at an interval of 5 seconds to check for the current payment
status. If it has been unsuccessful after 30 seconds, it is recommended to invoke the
Cancellation Request.
❖ WeChat Pay and Alipay may require a 6-digit password when making a payment that
exceeds a certain amount.
4. Cancellation If the customer is required to input the payment password to confirm the payment and it has
Request (revoke) not been input within the given time, Cancellation Request can be invoked from the terminal to
cancel the payment on the server. If the cancellation request has been initiated after the
payment approval, the server will initiate a refund, since the terminal has initiated a
cancellation.
5. Refund Request Refunding a payment has a time constraint, which must be carried out within a specified period
(refund) from the moment of the payment is made. Upon receiving the refund request, the system
processes it based on the refund validations and settings. If you specify a full amount of its
payment for refund, it is processed as a Full Refund. If a refund amount specified is less than
its payment amount, the refund is processed as a Partial Refund.
Page 3 of 35
6. Balance and Points Inquire the balance (points) of the QUO Card Pay owned by the customer.
Inquiry
(balanceQuery)
7. Transaction History You can get the transaction history within the specified period.
Inquiry ❖ Settlement Reconciliation Data is provided separately through other means. Please refrain
(recordQuery2) from using this interface other than retrieving recent transaction data.
8. Service Check Check the service for available payment types and their regular expressions.
(serviceDetect) ❖ This interface has been deprecated and should not be used.
1-3. Parameter Specifications
1. Amount
Amount values in this document do not have decimal points in Japanese Yen.
2. Time
Time values in this document are based on Japan Standard Time (JST).
3. Transaction Number (TradeNo)

A transaction number is generated by the merchant and send it to Netstars server through the API. The
transaction number generated by each terminal must be unique within the same terminal and cannot be
reused. It is recommended to generate the transaction number as a string based on the system time. For
example, “20170206151553”.
The transaction number which has already been paid or cancelled cannot be used again for payment. To
make a new payment, please use a new transaction number.
4. Mch Transaction Number (OutTradeNo)

Mch Transaction Number is a global unique transaction number generated by StarPay server upon successful
payment. This number concatenated with the merchant code, store code, terminal number and transaction
number. For example, TESTMIKI1563P20170206151553
If the transaction number is generated uniquely by each terminal, the Mch Transaction Number generated by
StarPay server is logically unique. In addition, Mch transaction number is applicable to refund operation.
5. Parameter Content
All parameters cannot contain commas (,).
Blank/empty input is allowed as values. For example, Key: "".
Page 4 of 35
6. Terminal ID (DeviceId)
The terminal ID must be set with a unique value accordingly for the StarPay server. Please set it with the serial
number unique for each terminal or concatenation of values such as the company/business name in English,
store code and cashier/checkout/terminal number.
❖ The allowed symbols that can be used for the terminal ID are “! # $ _ - + =”.
❖ Some payment brands (or wallets) may support only alphanumeric characters, and thus it is strongly
recommended to set with alphanumeric value only.
❖ Please consult us if the parameter data length required is longer than 32 characters, as some brands do not
allow value longer than that.
1-4. Digital Signature
(1) Generate hash value for digital signature
Data sent and received from the StarPay server contain digital signature.
See below for the generation method:

When sending and receiving message:
Signature = MD5(API parameter names and values for data transmission &key= Authentication/Secret
Key).toUpperCase()
❖ The above function names could be different based on the programing language used in your platform.
1. Except for the Sign parameter, arrange all parameters must in ascending order limited to ASCII characters.
Example:
param1=value1&param2=param2...&paramN=valueN&key=authentication/secret key.
❖ The authentication key will be provided separately for Signing In (via signIn interface) only.
❖ The secret key is obtained from the response of signIn API and used for invoking other APIs.
2. Empty data (including empty array) is excluded from signature generation.
3. Parameter name and value are not URL encoded.
4. Add the key string to the end of the data string and hash it with MD5.
Page 5 of 35
5. The hashed signature is converted to uppercase.
❖ For verifying the data received from the server, generates the hash value in the same way as
mentioned above for signature comparison. The signature responded by the server does not include the
Sign parameter for hashing as well.
6. Do anticipate that the parameters may increase as the system upgrades. When verifying the return
parameters, the digital signature must be verified for data integrity.
❖ It is recommended to obtain all the parameters from the response message for signature verfication,
instead of verifying only the response parameters defined in the specifications.
Example of Signature Data Creation:

When setting the following parameters for transmission data:
Nonce：flRbiAzyCBdkeTFESgighyaldTOpqaMN
OrderAmount：25000
AuthCode：130123456789012345
7. Concatenate the parameters in ascending order (as in ASCII characters only) in the form of parameter
key=value separated with the & character.
Example:
stringA="AuthCode=130123456789012345&Nonce=flRbiAzyCBdkeTFESgighyaldTOpqaMN
&OrderAmount=25000"
8. Append the authentication key (or secret key) to stringA and hash it shown as below:
stringSignTemp = stringA + "&key=457493358787b2254ce27878a82b"
Sign = MD5(stringSignTemp).toUpperCase()
= "20072236E84EF1B26E80FC355025E4FF"
❖ The Authentication Key shown above is only a sample for signing in, which will be provided separately.
For invoking APIs other than signing in (signIn interface), append the value of the SecretKey
parameter (of the signIn’s response) instead of the Authentication Key.
❖ The programming syntax and function names could be different from your development platform.
Page 6 of 35
9. Finally, generate the JSON format data shown as below:
{
"Nonce":"flRbiAzyCBdkeTFESgighyaldTOpqaMN",
"OrderAmount":"25000",
"AuthCode":"130123456789012345",
"Sign":"20072236E84EF1B26E80FC355025E4FF"
}
(2) Generate Random Character String
Data received and transmitted to our server include random character string as “Nonce”, so that hashed
signature cannot be anticipated with it included. It is recommended to use the randomize function for
generating the random character string based on the programming language.
(3) Attention to Verification of Digital Signature

We recommend that you prioritize the transaction results when having mismatch for signature in order to
respond flexibly to requests for changes in specifications and additions of return parameters for each
settlement brand. It is recommended not to process it as a settlement error even if the signature does not
coincide with payment success or payment while outputting WARNING to the log.
Page 7 of 35
1-5. Payment Password Input Rules

Under certain conditions, the wallet app prompts the customer for a password input before proceeding the payment.
a) If password input is not required:
2.Send
settlement
1.Scan of authorization 3.Payment
settlement code request
authorization Payment Terminal StarPay Payment
code (With StarPay API) Server
Server
5.Return 4.Return
payment payment
result result
User
6.Notify payment result
b) If password input is required:

2.Send
settlement
authorization 3.Payment
code request
1.Scan of
settlement 5.Return payment 4.Return payment
authorization (USERPAYING) StarPay (USERPAYING)
Payment Terminal
code 8.Confirm payment 9.Confirm payment
(With StarPay API)
status Server status Payment
11.Return payment 10.Return Server

result payment result
6.Password input request
User 7.Password input

12.Notify payment result
Page 8 of 35
1-6. Available Payment Types

StarPay supports the following payment types:
Payment Brand Payment Type Partial Refund Remarks
Alipay ALIPAY Yes
d 払い DPAY Yes
(d Payment)
LINE Pay LINEPAY Yes
PayPay PAYPAY No
楽天ペイ RAKUTENPAY No
(Rakuten Pay)
WeChat Pay MICROPAY Yes
銀聯 QR コード UPICPM Yes
(UnionPay QR Code)
au Pay AUPAY No
メルペイ MERPAY No
(MERPAY)
Origami Pay ORIGAMIPAY No
銀行 Pay GINKOPAY No Its BankType has one of the
(Ginko Pay) following values:
ゆうちょ Pay (Yucho Pay): JPPS
はま Pay (Hama Pay): HAMA
YOKA! Pay: FKBK
OKI Pay: BOKI
QUO カード Pay QUOPAY No
(QUO Card Pay)
VIA - Dash SGTDASH No
VIA - Global Pay SGTGLB No
Smart Code SMARTCODE No
J-Coin Pay JCOINPAY No
Amazon Pay AMAZONPAY Yes
JKOPAY JKOPAY Yes
GLN GLNPAY No
Page 9 of 35
2. Services Provided by Interface

Please send the request via HTTP POST method. The server returns results with HTTP response.
2-1. Sign In（signIn）

This interface gets the authentication key for other interfaces. It can also be used for terminal activation by entering the
license number. The authentication key retrieved has an expiry duration of 2 hours. If it expires, a new authentication
key has to be obtained by signing in again. In other words, if the terminal receives the POS_SIGN_ERROR or
POS_NEED_SIGNIN error when invoking other interfaces, invoke this interface again to retrieve a new authentication
key.
Upon receiving the response, verify the data received with a digital signature when signing in, using the Authentication
Key provided exclusively to each API user.
Request URL: https://***.*****.**/mchpos/signIn
Request Parameters
Name Parameter Data Type Required Data Example Remarks
Name Input
Random Character
Nonce String(32) Required WvuGS1KODEP2S4FY
String
41040AFB6D8A5B78A3
Digital Signature Sign String(32) Required
149FEECC0F57F8
❖ Refer to the chapter “1-3
Terminal ID DeviceId String(96) Required STARPAY99990001
Parameter Specifications”.
License number issued to
License Number LicenseNo String(32) Required 123456ABC
each store.
Set the software version of
App Version AppVersion String(16) Required 1.0.1.0 your app and it will be
recorded in StarPay server.
Set the model number of the
Device Model settlement terminal arbitrarily.
DeviceModel String(2048) － Test device model
Number Record it on the StarPay
server.
It can be filled or leave it
empty. If it is empty, the
Terminal Number DeviceNo String(4) － 0010 StarPay server will
automatically generate it a
Numeric range from 0 to 9999.
Page 10 of 35
Request Example
{
"Nonce":"WvuGS1KODEP2S4FY",
"Sign":"41040AFB6D8A5B78A3149FEECC0F57F8",
"AppVersion":"1.0.1.0",
"DeviceId":"STARPAY99990001",
"DeviceModel":"Test device model",
"LicenseNo":"123456"
}
Response Parameters
Name Input
Random Character
Nonce String(32) Required iq9odtum2XT1yoEf
String
C15853E9432DBA8835
760CDF05254606
❖ Refer to the table “Operation

Operation Result Result String(32) Required SUCCESS
Result Codes” below
Operation Result
ResultDesc String(512) Required SUCCESS
Explanation
If the value of Result is SUCCESS, it includes the following parameters:

Name Input
Used for the signature validation
Secret Key SecretKey String(32) Required 20151025112211012
for each merchant
Company/store information to
License Info LicenseInfo String(32) Required NWGenius be displayed on payment
terminal
Terminal number to be displayed
Terminal Number DeviceNo String(4) Required 1563
on payment terminal
Company / shop information to
Receipt Info ReceiptInfo String(32) Required NETSTARS
be displayed on receipt
Product categories of the store
食品|化粧品|その他 issued with the specific license
Array
Product Category Category Required (Food|Cosmetics number.
|Others) Array Item Data Type:
String(4096)
Company Code EntCode String(4) Required TEST 4 Alphabet characters
Store Code ShopCode String(4) Required MIKI 4 Alphabet characters
Page 11 of 35
Request Example
{
"Nonce":"iq9odtum2XT1yoEf",
"Sign":"C15853E9432DBA8835760CDF05254606",
"Category":[
"紳士服洋品",
"婦人服洋品",
"その他衣料品",
"身のまわり品",
"化粧品",
"食堂喫茶",
"家庭用品",
"飲料食品",
"その他"
],
"DeviceNo":"1563",
"EntCode":"TES1",
"LicenseInfo":"NWGenius",
"ReceiptInfo":"NETSTARS",
"Result":"SUCCESS",
"ResultDesc":"SUCCESS",
"SecretKey":"xxxxxxxxxxxxxxxx",
"ShopCode":"MIK2"
}
Operation Result Codes

Code Description
SUCCESS Success
PARAM_ERROR Parameter Error
POS_SIGN_ERROR Digital Signature Error
Prohibited using the payment terminal. It indicates the payment service for this terminal
POS_STATE_ERROR
has been disabled (or suspended) at the backend by the payment gateway administrator.
Page 12 of 35
Do not sign in at a regular interval, but only when receiving an error of POS_SIGN_ERROR or POS_NEED_SIGNIN.
The following is an example of the secret key expires.
a) When the Payment Request (pay) is invoked and the secret key has expired
1.pay
2.Result: POS_SIGN_ERROR
Payment 3.signIn StarPay

Terminal 4.Get Authorization Key Server
5.pay
❖ Same TradeNo & AuthCode as step 1
6.Result: SUCCESS
b) When invoking the Payment Inquiry (payQuery)
1.pay
2.Result: USERPAYING
3.payQuery
4.Result: POS_SIGN_ERROR
Payment StarPay
Terminal 5.signIn
Server
6.Get SecretKey
7.payQuery ❖ Same TradeNo as step 3
8.Result: SUCCESS
Page 13 of 35
2-2. Payment Request（pay）

After reading the QR code or barcode presented by the customer, Payment Request interface is invoked to make the
payment.
Request URL: https://***.*****.**/mchpos/pay
Request Parameters
Name Input
Random
Nonce String(32) Required LAlqm132GIN66tif
Character String
3007BA9369147D294
C0616457FE3AF65
Parameter Specifications”
Set a unique alphanumeric
Transaction value on the same terminal
TradeNo String(15) Required P20170206151553
Number ❖ See the Request Example
below
Categories selected during the
商品カテゴリ payment or item
_Category detailed information to be set on the
Product Details Detail String(256) －
(Product settlement terminal side. This value
Category) is not displayed on the user side.
Set this value arbitrarily.
Payment amount in Japanese
Payment Amount OrderAmount int Required 108
Yen up to 7 digits.
Settlement The settlement authorization
13049562333864774
Authorization AuthCode String(512) Required code read from the QR code on the
8
Code smartphone screen
This indicates which brand of
payment is used at the
terminal. If you do not specify a
payment type, the StarPay server
Payment Type TradeType String(16) － ALIPAY
automatically identifies it and
performs settlement processing.
❖ Refer to the chapter “1-6 Support
Payment Type”
Page 14 of 35
Request Example
{
"Nonce":"LAlqm132GIN66tif",
"Sign":"3007BA9369147D294C0616457FE3AF65",
"AuthCode":"130495623338647748",
"Detail":"商品カテゴリ_Category",
"OrderAmount":108,
"TradeNo":"P20170206151553"
}
Response Parameters
Name Input
Random
Nonce String(32) Required t3YljmmsAhr6pVfO
Character String
22F47A31C2C4DEDFE7DEB
4FD510FC538
Operation Result
ResultDesc String(512) Required
Description
Payment Type TradeType String(16) Required MICROPAY
Available Payment Types”
Balance Balance Long - B20

Name Input
Mch Global unique number
TESTMIKI1563P2017020
Transaction OutTradeNo String(32) Required generated by StarPay server
6151553
Number for the transaction
Transaction Same value as the parameter
Number of request
Payment
Completion TradeTime String(16) Required 20170206151558 yyyyMMddHHmmss
Time
Bank name abbreviation used
Payment Bank BankType String(16) Required CFT
for payment
Payment Equivalent to the request
OrderAmount int Required 180
Amount parameter
Currency Currency String(16) Required JPY
❖ If the value of Result is not SUCCESS, the above parameters may be included, but do not need to be referred.
Page 15 of 35
Response Example
{
"Nonce":"t3YljmmsAhr6pVfO",
"Sign":"22F47A31C2C4DEDFE7DEB4FD510FC538",
"BankType":"CFT",
"Currency":"JPY",
"OrderAmount":108,
"OutTradeNo":"TES1MIK21563P20170206151553",
"Result":"SUCCESS",
"ResultDesc":"支払成功しました。(Payment Succeeded)",
"TradeNo":"P20170206151553",
"TradeTime":"20170206151558",
"TradeType":"MICROPAY"
}
❖ The Balance parameter is set only when the payment type is QUOPAY.

Code Remarks
SUCCESS Success
PARAM_ERROR Parameter error
POS_NEED_SIGNIN Sign in error
POS_SIGN_ERROR Digital signature error
Prohibited using the payment terminal. It indicates the payment service for this terminal has
POS_STATE_ERROR
been disabled (or suspended) at the backend by the payment gateway administrator.
This transaction number has already been used. Please use a new transaction number for
TRADE_NO_USED
the payment.
SYSTEMERROR Communication error, interface error, error from Payment Brand, etc.
The value of the settlement authorization code is invalid, has already expired or has already
AUTHCODEEXPIRE
been used
NOTENOUGH Insufficient Fund
NOTSUPORTCARD The bank card you used is not supported by StarPay payment system
User is paying (including password being input). A payment inqury at every 5 seconds to
USERPAYING
check the transaction status.
Parameter error on the settlement authorization code. Each settlement
AUTH_CODE_ERROR
authentication code can be used only once. Please scan again.
Validation error on the settlement authorization code. The scanned QR code and barcode
AUTH_CODE_INVALID
are not codes available for the target merchant.
ORDERREVERSED（Deleted）取引は既に取り消されています。（Deleted）
PAY_LIMIT It exceeds the payment limit of the merchant store
OTHER_ERROR For other errors, see the description of ResultDesc for details.
Supplementary Explanation:
The POS terminal reads the QR code/barcode and subsequently send the payment request. For payment that does
not require password input, StarPay server immediately returns a success or failure result. For payment that requires
password input, StarPay server returns USERPAYING result during the password input or when the terminal inquires
the payment status. If a network error or terminal timeout has occurred, it is necessary to make a Revoke request from
the POS terminal.
Page 16 of 35
2-3. Payment Inquiry（payQuery）

This interface checks the current payment status. If the result of the payment processing request is USERPAYING, call
this interface once every 5 seconds, and if it is unsuccessful after 30 to 60 seconds, Netstars recommend the
merchant to cancel payment request process.
Example: If the payment amount exceeds the fixed amount, the customer will be prompted to input the password. If
this interface is invoked when the customer is entering the password, it responds back the status of USERPAYING
Also, if the following situation occurs, the merchant can check the actual payment status using this interface:
• When an abnormality occurs in the system or network, and the operation result of the payment request cannot
be received.
• When payment status confirmation is required before invoking the interface of cancellation request.
Request URL: https://***.*****.**/mchpos/payQuery
Request Parameters
Name Input
Random as8xA0fuzz4DsaFM
Character Nonce String(32) Required
String
Digital C5E47C5E7BB7CB5A2A6D
Sign String(32) Required
Signature D5161BAC06F9
STARPAY99990001 ❖ Refer to the chapter “1-3
Terminal ID DeviceId String(96) Required
P20170206151553 Transaction number
Transaction
TradeNo String(15) Required created during the
Number
payment process
Request Example
{
"Nonce":"as8xA0fuzz4DsaFM",
"Sign":"C5E47C5E7BB7CB5A2A6DD5161BAC06F9",
"TradeNo":"P20170206151553"
}
Page 17 of 35
Response Parameters
Name Input
Random
Nonce String(32) Required 1HGien87rDRF6spL
Character String
9F208A3B7B507107F
FE4948C20185693
❖ Refer to the table
Operation Result Result String(32) Required SUCCESS “Operation Result Codes”
below
支払成功しました。
Operation Result
ResultDesc String(512) Required (Payment
Description
Succeeded)

Name Input
Global unique number
Mch Transaction TESTMIKI1563P2017
OutTradeNo String(32) Required generated by StarPay server
Number 0206151553
for the transaction
Transaction Same value as parameter of
Number the request.
Payment
TradeTime String(16) Required 20170206151558 yyyyMMddHHmmss
Completion Time
Transaction
TradeState String(32) Required SUCCESS “Transaction Status Codes”
Status
below
Bank name abbreviation
Payment Bank BankType String(16) Required CFT
code used for payment
Actual payment amount of
Payment Amount OrderAmount int Required 180
the transaction
❖ If the value of Result is not SUCCESS, the above parameters may be included, but do not need to be referred.
Response Example
{
"Nonce":"1HGien87rDRF6spL",
"Sign":"9F208A3B7B507107FFE4948C20185693",
"BankType":"CFT",
"Currency":"JPY",
"OrderAmount":108,
"Result":"SUCCESS",
"ResultDesc":"支払成功しました。(Payment Succeeded)",
Page 18 of 35
"TradeNo":"P20170206151553",
"TradeState":"SUCCESS",
"TradeTime":"20170206151558",
}

Code Description
Success.
Remarks:
For transactions that have already been refunded/canceled after successful payment,
the values of Result and TradeState should be SUCCESS and REFUND/REVOKED
SUCCESS respectively.
For payment transactions which has not been successful and is being cancelled, the
value of Result is REVOKED and its TradeState does not return.
If the user is paying, the value of Result will return USERPAYING and TradeState will
not be returned.
POS_NEED_SIGNIN Sign in error. Sign in again is required.
Prohibited using the payment terminal. It indicates that the payment service for this
POS_STATE_ERROR terminal has been disabled (or suspended) at the backend by the payment gateway
administrator.
SYSTEMERROR Communication error, error occurred at the interface, etc.
ORDERNOTEXIST Transaction number does not exist in the system
Unpaid.
NOTPAY
(Unpaid due to user's cause. E.g. Cancel operation on password entry screen etc.)
Cancel.
REVOKED ❖ Refer to the Supplementary Explanation section at `Operation Result Codes
(SUCCESS) of Chapter 2-2.
User is paying (including password being input).
USERPAYING
❖ It is recommended to inquire every 5 seconds for transaction status.
PAYERROR Payment failures (other causes, password errors, bank errors, etc.)
OTHER_ERROR Other error. For details, please refer to the contents of ResultDesc parameter.
Page 19 of 35
Transaction Status Codes
Code Description
SUCCESS Payment Success
REFUND Successful refund
Unpaid.
NOTPAY
(Unpaid due to user's cause. E.g. Cancel operation on password entry screen etc.)
It has already been canceled.
REVOKED ❖ Refer to the Supplementary Explanation section at `Operation Result Codes
(SUCCESS) of Chapter 2-2.
User is paying (including password being input).
USERPAYING
❖ It is recommended to inquire every 5 seconds for transaction status.
Failure of payment due to other causes (such as when the password is incorrect, the
PAYERROR
bank system returns an error, etc.)
❖ To identify whether the transaction status should be NOTPAY or REVOKED, please implement the conditions as
below.
Example：Condition for the transaction status NOTPAY

if (「Operation Result Code」= “NOTPAY”) OR (「Operation Result Code」= “SUCCESS” AND
「Transaction Status Code」=“NOTPAY”)) {
//NOTPAY process
}
Example：Condition for transaction status REVOKED

If (「Operation Result Code」= “REVOKED”) OR (「Operation Result Code」= “SUCCESS” AND
「Transaction Status Code」=“REVOKED”)) {
//REVOKED process
}
Example：Condition for transaction status USERPAYING

if(「Operation Result Code」= “USERPAYING”) OR (「Operation Result Code」= “SUCCESS” AND
「Transaction Status Code」=“USERPAYING”)) {
//USERPAYING process
}
Page 20 of 35
2-4. Cancellation Request（revoke）

The terminal requests a payment cancellation when it does not receive the response, or due to the server timeout
while processing the payment. If payment transaction that has been successfully paid, the server performs a refund
process since the terminal has initiated a cancellation.
Notes:
• Payments processed within 1 hour can be cancelled typically based on design. For general refund process,
e.g. return of purchases by customer, please make a refund request.
• Alipay payment does not allow cross-day cancellation. The server processes the cancellation as a refund
when it has past the Settlement End-Of-Day (EOD).
• When performing cancellation, if the payment transaction has already been processed as successful payment,
the server generates a cancellation record for the cancellation. If the transaction is an unsuccessful payment,
no cancellation record is being generated for the cancellation.
Request URL: https://***.*****.**/mchpos/revoke
Request Parameters
Name Input
Random s0utbxu80o7WYvGa
Nonce String(32) Required
Character String
C52B29707D1B642A1271
35B632A0F29D
STARPAY99990001 ❖ Refer to chapter “1-3
Transaction P20170206151553 Transaction number created
TradeNo String(15) Required
Number during payment processing
Payment amount in Japanese
Yen. Up to 7 digits.
Payment Required
OrderAmount int 108 ❖ It is mandatory only if the
Amount （❖ ）
payment is paid by LINEPay
and d payment.
Request Example
{
"Nonce":"s0utbxu80o7WYvGa",
"Sign":"C52B29707D1B642A127135B632A0F29D",
"TradeNo":"P20170206151553"
}
Page 21 of 35
Response Parameters
Name Input
Random 6AXM7JoxctqIWHU1
Character Nonce String(32) Required
String
Digital DA023877DDBADDA6518F
Sign String(32) Required
Signature 81D27A5CE0D9
SUCCESS ❖ Refer to the table
Operation
Result String(32) Required “Operation Result Codes”
Result
below
取引のキャンセルが完了
Operation しました。
Result ResultDesc String(512) Required (Cancellation of
Explanation transaction has been
completed.)
Response Example
{
"Nonce":"6AXM7JoxctqIWHU1",
"Sign":"DA023877DDBADDA6518F81D27A5CE0D9",
"Result":"SUCCESS",
"ResultDesc":"取引のキャンセルが完了しました。(Cancellation of transaction has been
completed.)"
}

Code Description
SUCCESS Success
administrator.
SYSTEMERROR Communication error, error occurred at the interface, etc.
Payment transaction number is invalid. The transaction cannot be found for
TRADE_NO_INVALID
cancellation.
REVOKE_EXPIRE Cancellation has exceeded the allowed period
Page 22 of 35
2-5. Refund Request（refund）

Refunding a payment has a time constraint, which must be carried out within a specified period from the moment of
the payment is made. Upon receiving the refund request, the system processes it based on the refund validations and
settings. If you specify a full amount of its payment for refund, it is processed as a Full Refund. If a refund amount
specified is less than its payment amount, the refund is processed as a Partial Refund.
• The default value of the refund expiry is set as non-refundable at the same time (payment time) after the N (*)
days of the payment date, which based on the payment type of the payment transaction. If you have a request
to change the refund deadline, please contact us.
o (*) Number of days of the refund for specific payment type is set by the gateway operator
• The refund request is processed immediately, but the actual process duration of refunding the fund back to the
customer may be different among the payment types.
For the partial refund, it requires to specify the refund amount that does not exceed the payment amount. The
maximum times of partial refunds allowed on a single payment are 10.
Some payment types do not support partial refund (see 1-6. Available Payment Types).
Request URL: https://***.*****.**/mchpos/refund
Request Parameters
Name Input
Random 1Ef2EzfTnbrP30YR
Character String
43646B12A53795B33
7E4570753A0A775
STARPAY99990001 The ID of the terminal which
refund is currently being
Refund Terminal
DeviceId String(96) Required processed.
ID
STARPAY99990001 ID of the terminal which the
Payment
PayDeviceId String(96) - payment was being
Terminal ID
processed
Transaction P20170206152837 Transaction number created
TradeNo String(15) -
Number during payment process.
The priority for this parameter
is higher than the
Mch Tansaction
OutTradeNo String(32) Required combination of
Number
PayDeviceID and
TradeNo.
Page 23 of 35
R20170206152939 Set a value that is unique
and distinct from the
payment transaction number
Refund Number RefundNo String(16) Required for use on the same terminal.
Alphanumeric only
❖ See Request Example
below
1000 Refundable Amount: 1 Yen to
Refund Amount RefundFee int Required
Payment Amount.
❖ The refund process can proceed with either the Mch Transaction Number (OutTradeNo) or the combination of
Payment Terminal ID (PayDeviceID) and Transaction Number (TradeNo). If the server receives the refund request
with OutTradeNo, PayDeviceID, and TradeNo, the OutTradeNo parameter will be processed with priority.
Request Example
{
"Nonce":"1Ef2EzfTnbrP30YR",
"Sign":"43646B12A53795B337E4570753A0A775",
"PayDeviceId":"STARPAY9999-0001",
"RefundNo":"R20170206152939",
"TradeNo":"P20170206152837",
"RefundFee":1000
}
Response Parameters
Name Input
Random Character
Nonce String(32) Required jvxy5z5etyIphuU0
String
EAB99A4DCCFA4B30
C348BC796FC54172
Result Codes”
返金成功しました。
Operation Result
ResultDesc String(512) Required (The refund was
Explanation
successful.)
Page 24 of 35
Name Input
OutTradeNo String(32) TES1MIK21563P2017 Global unique number generated by
Mch Transaction
Required 0206152837 StarPay server for the refund
Number
transaction
Transaction TradeNo String(15) P20170206152837 Transaction number created during
Required
Number payment process
Refund Number RefundNo String(16) Required R20170206152939 Same as the request parameter
Payment Amount OrderAmount int Required 1000 Payment amount in Japanese Yen
Refund Amount RefundAmount int Required 1000 Refund amount in Japanese Yenß
Refund Time RefundTime String(16) Required 20170206152950 yyyyMMddHHmmss
❖ If the value of Result is other than SUCCESS, the above parameters may be included, but do not need to be
referred.
Response Example
{
"Nonce":"jvxy5z5etyIphuU0",
"Sign":"EAB99A4DCCFA4B30C348BC796FC54172",
"OrderAmount":1000,
"RefundAmount":1000,
"RefundNo":"R20170206152939",
"RefundTime":"20170206152950",
"Result":"SUCCESS",
"ResultDesc":"返金成功しました。(The refund was successful.)",
"TradeNo":"P20170206152837",
}

Code Description
SUCCESS Success
administrator.
SYSTEMERROR Communication error, error occurred at interface, etc.
REFUND_NO_USED The transaction has already been refunded or a duplicate refund number was being
used
TRADE_NO_INVALID The transaction number is invalid or does not exist
OUT_TRADE_NO_INVALID Mch transaction number is invalid
REFUND_EXPIRE Cannot refund due to the exceeding the refundable period
OTHER_ERROR Other error. For details, please refer to the contents of ResultDesc parameter.
Page 25 of 35
REFUND_FEE_INVALID The refund amount is invalid, or the refund amount input exceeds its payment amount.
EXCEED_MAX_LIMIT The maximum count of partial refunds has been exceeded.
Page 26 of 35
2-6. Balance and Points Inquiry (balanceQuery)

This interface provides the functionality to get the balance and points of the wallet for the merchant.
Request URL: https://***.*****.**/mchpos/balanceQuery
Request Parameters
Name Input
Random as8xA0fuzz4DsaFM
Character String
C5E47C5E7BB7CB5A2A
6DD5161BAC06F9
STARPAY99990001 ❖ Refer to the chapter “1-3
Settlement 130495623338647748 The value decoded from the
Authorization AuthCode String(512) Required QR code presented by
Code customer
Request Example
{
"Nonce":"as8xA0fuzz4DsaFM",
"Sign":"C5E47C5E7BB7CB5A2A6DD5161BAC06F9",
"AuthCode":"130495623338647748"
}
Response Parameters
Name Input
Random
Nonce String(32) Required 1HGien87rDRF6spL
Character String
9F208A3B7B507107FF
E4948C20185693
Operation Result Result String(32) Required SUCCESS “Operation Result Codes”
below
Operation Result
ResultDesc String(512) Required QuerySuccess
Description
❖ Refer to the table “1-6
Available Payment Types”.
Payment Type TradeType String(16) Required QUOPAY
Currently only support for
QUO Card Pay.
Page 27 of 35
If the Result value is SUCCESS, it includes the following parameters:
Name Parameter Name Data Type Required Data Example Remarks
Input
Available Payment Types”.
Balance Balance Long Required 108
Applicable to QUO Card Pay
only.
❖ If the Result value is other than SUCCESS, the above parameters may be included, but do not need to be referred.
Response Example
{
"Nonce":"1HGien87rDRF6spL",
"Sign":"9F208A3B7B507107FFE4948C20185693",
"Currency":"JPY",
"Balance":108,
"Result":"SUCCESS",
"ResultDesc":"QuerySuccess",
"TradeType":"QUOPAY"
}

Code Description
SUCCESS Success
POS_NEED_SIGNIN Sign in error. Sign-in again is required.
Prohibited using the payment terminal. It indicates the payment service for this terminal
POS_STATE_ERROR
has been disabled (or suspended) at the backend by the payment gateway administrator.
SYSTEMERROR Communication error, interface error, etc.
OTHER_ERROR Other error. For details, refer to the value of ResultDesc parameter.
Page 28 of 35
2-7. Historical Transaction Inquiry（recordQuery2）

You can inquire about the historical transactions by the specifying transaction period or status.
A maximum of 3 months can be specified for the period (with the start and end dates). For example, specify the start
date/time as 12 May 2018 at 06:00:00, and the latest end date/time would 12 August 2018 at 05:59:59. If you specify a
date and time that is longer than that, a parameter error will be returned.
❖ This interface has been deprecated and will be removed in future. Please consult Netstars who has started
to provide this functionality in other means.
Request URL: https://***.*****.**/mchpos/recordQuery2
Request Parameters
Name Input
Random Character
Nonce String(32) Required YM7pVzQzhIYthw7U
String
9B4F114B22EE46E064
A285CBA7E6946A
Terminal ID DeviceId String(96) Required STARPAY-9999-0001
Start Date/Time BeginTime String(16) Required 20170206000000 yyyyMMddHHmmss
End Date/Time EndTime String(16) Required 20170206235959 yyyyMMddHHmmss
Terminal Number DeviceNo String(4) -- 0010
Payment / Refund
Transaction TradeRefundNo String(16) --
Number
SUCCESS: Payment
Transaction State
TradeState String(32) -- SUCCESS REFUND: Refund
(Transaction Type)
Null (Blank)：All
❖ Refer to chapter “1.6 Available
Payment Type TradeType String(16) -- MICROPAY
Payment Types”
Request Example
{
"Nonce":"YM7pVzQzhIYthw7U",
"Sign":"9B4F114B22EE46E064A285CBA7E6946A",
"BeginTime":"20170206000000",
"DeviceId":"STARPAY-9999-0001",
"EndTime":"20170206235959",
}
Page 29 of 35
Response Parameters
Name Input
Random Character
Nonce String(32) Required ekD5tXF2JcV0d6v5
String
BA819960E4DBB0564415
A6DA8A5096A4
❖ Refer to table “Operation
取引照会が完了しました。
Operation Result
ResultDesc String(512) Required (Transaction inquiry
Description
has been completed.)

Name Input
Total Payment TotalCount Int Required 10
Count
Total Payment PayAmount Int Required 50000
Amount (A)
Total Refund RefundAmount Int Required 10000
Amount (B)
Total Amount TotalAmount Int Required 40000 Total Payment – Total Refund
(Balance)
Transaction Records Array Required ❖ Refer to the table
Records “Transaction Record Array”
below
❖ If the value of Result is other than SUCCESS, the above parameters may be included, but do not need to be
referred.
Transaction Record Array:

If the transaction state (TradeState) is SUCCESS, information of the Refund transaction (i,e, RefundOperator)
could be included for payment transaction, in which the payment transaction has been refunded or cancelled/revoked.
Name Parameter Name Data Type Required Data Example Remarks
Input
Mch Transaction Number generated by StarPay
OutTradeNo String(32) Required
Number server
Transaction Transaction number generated
TradeNo String(15) Required
Number during payment request
Payment
TradeTime String(16) Required yyyyMMddHHmmss
Completion Time
取引状態 SUCCESS: Payment
Transaction State
TradeState String(32) Required (Transaction REFUND: Refund
(Transaction Type)
Status) REVOKED: Cancel
❖ Refer to the chapter “1.6
Page 30 of 35
The Bank Abbreviation used in
Payment Bank BankType String(16) Required BOC_DEBIT
payment
Payment Amount in Japanese
Payment Amount OrderAmount Int Required 108
Yen
The terminal ID that made the
payment request
Terminal Number DeviceNo String(4) Required 1563
Store Code ShopCode String(4) Required MIK2 4 Alphanumeric Characters
Company Code EntCode String(4) Required TES1 4 Alphanumeric Characters
It is the category name selected
Product Details Detail String(256) － or the product details set at the
terminal when making payment
If the transaction state is REFUND or REVOKED, it includes the following parameters:

Refund Time RefundTime String(16) Required 20151104203522 yyyyMMddHHmmss
Terminal number of the
refunding terminal.
Refund Terminal
RefundOperator String(32) Required 1563 If it is refunded from web
Info
management system, the value
is prefixed with "WEBM".
Refund Amount RefundFee Int Required
If transaction state is REFUND, it includes the following parameters:

Refund Transaction
RefundNo String(16) Required
Number
Mch Refund
OutRefundNo String(32) Required
Number
Response Example
{
"Nonce":"ekD5tXF2JcV0d6v5",
"Sign":"BA819960E4DBB0564415A6DA8A5096A4",
"PayAmount":216,
"Records":[
{
"BankType":"CFT",
"Currency":"JPY",
"DeviceNo":"1563",
"EntCode":"TES1",
"OrderAmount":108,
"RefundOperator":"1563",
"ShopCode":"MIK2",
Page 31 of 35
"TradeNo":"P20170206151553",
"TradeTime":"20170206151558",
},
{
"BankType":"CFT",
"Currency":"JPY",
"DeviceNo":"1563",
"EntCode":"TES1",
"OrderAmount":108,
"RefundFee":"108",
"RefundTime":"20170206152714",
"ShopCode":"MIK2",
"TradeNo":"P20170206151553",
"TradeState":"REVOKED",
"TradeTime":"20170206151558",
},
{
"BankType":"CFT",
"Currency":"JPY",
"DeviceNo":"1563",
"EntCode":"TES1",
"OrderAmount":108,
"ShopCode":"MIK2",
"TradeNo":"P20170206152837",
"TradeTime":"20170206152907",
},
{
"BankType":"CFT",
"Currency":"JPY",
"DeviceNo":"1563",
"EntCode":"TES1",
"OrderAmount":108,
Page 32 of 35
"OutTradeNo":"TES1MIKI2563P20170206152837",
"RefundNo":"R20170206152939",
"OutRefundNo":"TES1MIK21563R20170206152939",
"RefundFee":"108",
"RefundTime":"20170206152950",
"ShopCode":"MIK2",
"TradeNo":"P20170206152837",
"TradeState":"REFUND",
"TradeTime":"20170206152907",
}
],
"RefundAmount":216,
"Result":"SUCCESS",
"ResultDesc":"取引照会が完了しました。(Transaction inquiry completed.)",
"TotalAmount":0,
"TotalCount":4
}

Code Description
SUCCESS Success
PARAM_ERROR Parameter errors
POS_STATE_ERROR
Page 33 of 35
2-8. Service Check（serviceDetect）

Check the service with available payment types and their regular expressions.
❖ This interface has been deprecated and should not be used.
❖ When reading the QR code, it may not be recognized by the terminal due to the EMV standard composition for the
QR code could be defined differently. Please consult Netstars before use.
Request URL: https://***.*****.**/mchpos/serviceDetect
Request Parameters
Name Parameter Required Required Data Example Remarks
Name Input Input
Random Character
Nonce String(32) Required YM7pVzQzhIYthw7U
String
9B4F114B22EE46E064A28
5CBA7E6946A
Terminal ID DeviceId String(96) Required STARPAY-9999-0001
Request Example
{
"DeviceId":"STARPAY-9999-0001"
}
Response Parameters
Name Input
Random Character
Nonce String(32) Required ekD5tXF2JcV0d6v5
String
BA819960E4DBB0564415A
6DA8A5096A4
サービス確認が完了しまし
Operation Result た。
ResultDesc String(512) Required
Explanation (Service confirmation has
been completed.)
Page 34 of 35
Name Input
Valid Payment PayTypes Array Required Array of PayTypes.
Types ❖ Refer to the table “Item
Parameters of PayTypes Array”
below
Item Parameters of PayTypes Array

Name Input
Payment Type TradeType String(16) Required ALIPAY Refer to the chapter “1.6
Regular Expression Pattern String(128) Required Regular Expression for retrieving
the payment type
Response Example
{
"Result":"SUCCESS",
"ResultDesc":"SUCCESS",
"PayTypes":[
{ "TradeType":"MICROPAY", "Pattern":"^1[0-5](¥d{16}|¥d{15}N)$" },
{ "TradeType":"DPAY", "Pattern":"^71(¥d{20}|¥d{19}D)$" }
]
}

Code Description
SUCCESS Success
POS_STATE_ERROR
SERVICE_ERROR Error encountered such as payment service settings or communication error
Page 35 of 35

StarPay Settlement CPM POS - v2.0.23 - 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 CPM POS - v2.0.23 - API Specifications

Uploaded by

Copyright:

Available Formats

StarPay

Netstars Co., Ltd.

1. BUSINESS OVERVIEW .................................................................................................................. 3

1-1. Interface Requirements .............................................................................................................................. 3

1-2. Interfaces Overview.................................................................................................................................... 3

1-3. Parameter Specifications ........................................................................................................................... 4

1-4. Digital Signature ......................................................................................................................................... 5

1-5. Payment Password Input Rules ................................................................................................................. 8

1-6. Available Payment Types ........................................................................................................................... 9

2. SERVICES PROVIDED BY INTERFACE ..................................................................................... 10

2-1. Sign In（signIn） .................................................................................................................................. 10

2-2. Payment Request（pay） ....................................................................................................................... 14

2-3. Payment Inquiry（payQuery）............................................................................................................... 17

2-4. Cancellation Request（revoke）........................................................................................................... 21

2-5. Refund Request（refund） ................................................................................................................... 23

2-6. Balance and Points Inquiry (balanceQuery) ........................................................................................ 27

2-7. Historical Transaction Inquiry（recordQuery2） ................................................................................. 29

2-8. Service Check（serviceDetect） ...................................................................................................... 34

1-1. Interface Requirements

1-2. Interfaces Overview

1-3. Parameter Specifications

3. Transaction Number (TradeNo)

4. Mch Transaction Number (OutTradeNo)

1-4. Digital Signature

(1) Generate hash value for digital signature

See below for the generation method:

2. Empty data (including empty array) is excluded from signature generation.

3. Parameter name and value are not URL encoded.

Example of Signature Data Creation:

stringSignTemp = stringA + "&key=457493358787b2254ce27878a82b"

(2) Generate Random Character String

(3) Attention to Verification of Digital Signature

1-5. Payment Password Input Rules

a) If password input is not required:

b) If password input is required:

11.Return payment 10.Return Server

User 7.Password input

1-6. Available Payment Types

2. Services Provided by Interface

2-1. Sign In（signIn）

Request URL: https://***.*****.**/mchpos/signIn

❖ Refer to the table “Operation

If the value of Result is SUCCESS, it includes the following parameters:

Operation Result Codes

Payment 3.signIn StarPay

b) When invoking the Payment Inquiry (payQuery)

7.payQuery ❖ Same TradeNo as step 3

2-2. Payment Request（pay）

Request URL: https://***.*****.**/mchpos/pay

If the value of Result is SUCCESS, it includes the following parameters:

Operation Result Codes

2-3. Payment Inquiry（payQuery）

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

If the value of Result is SUCCESS, it includes the following parameters:

Operation Result Codes

Example：Condition for the transaction status NOTPAY

Example：Condition for transaction status REVOKED

Example：Condition for transaction status USERPAYING

2-4. Cancellation Request（revoke）

Request URL: https://***.*****.**/mchpos/revoke

Operation Result Codes

2-5. Refund Request（refund）

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

Request URL: https://../mchpos/signIn

Request URL: https://../mchpos/pay

Request URL: https://../mchpos/payQuery

Request URL: https://../mchpos/revoke

Request URL: https://../mchpos/refund

Request URL: https://../mchpos/balanceQuery

Request URL: https://../mchpos/recordQuery2

Request URL: https://../mchpos/serviceDetect