Introduction
API Endpoint
https://api.nihaopay.com
Thanks for choosing NihaoPay! Our REST API uses common conventions and practices to make integration easily. Endpoint URLs follow resource-oriented naming conventions and can be accessed by using HTTP verbs such as GET
and POST
. Response will be in JSON
format(except out SecurePay product). All API requests must be made over HTTPS.
To manage transactions through a web client, please use our online Transaction Management System (TMS).
For quick integration, we also provide Sample Codes, SDKs, and Plugins on GitHub.
If you have any questions regarding our API or the integration process, please contact our Technical support team.
Version
API Version
/v1.2
As with all of our products and services, our API is constantly being improved to better suit our customers’ needs. To help our customers track changes, we include versions in our API. We are currently on Version 1.2 (v1.2
).
To specify a version, simply add /v1.2
namespace to the base endpoint before the resource namespace.
For example, to use Version 1.2, the full endpoint for the transactions resource would be:
https://api.nihaopay.com/v1.2/transactions
Authentication
Sample Request
$ curl https://api.nihaopay.com/v1.2/transactions \
-H "Authorization: Bearer <TOKEN>"
Replace <TOKEN> with your bearer token generated in the TMS. See Authentication for more information.
Each request must be made over HTTPS and authenticated using your merchant credentials. Authentication is handled through the Authorization header with a Bearer token.
You can view your bearer token in TMS by logging in and going to Settings -> Certificate.
Header | Description |
---|---|
Authorization Required |
Set authentication type as Bearer with a token obtained from the TMS. |
If you believe either your merchant ID, secret key, or bearer token have been compromised, please regenerate your secret key in the TMS. Once you have a new secret key, a bearer token will be automatically regenerated. Please allow 15 minutes for the new bearer token to propagate through the system.
API Description
Payment Mode
NihaoPay supports five payment models: SecurePay, CardPay, In-APP payment, Show QRcode and Scan QRcode.
SecurePay
In Securepay, users will be redirected to the payment tunnel and finish rest of payment steps in the official payment page.
APP Payment
In-APP Payment will ask merchants to call the selected payment model while users are checking out.
Show QRcode
Our API will return a QRcode URL containing information merchant requested. Merchants will be able to show this URL on mobiles or PC web browsers, thereby enabling users to scan the QR code and pay.
Scan QRcode
In the Scan QRcode, merchants are able to sacn user's QRcode to finish the transaction.
For the following products, please refer to MuskPay API Documentation
CardPay
In CardPay, we require merchants' websites to have PCI certification. Merchants will collect users' credit card information and send request to API to finish the order.
How to use
AliPay | WechatPay | UnionPay | |
---|---|---|---|
PC Browser terminal=ONLINE |
Standard SecurePay | Standard SecurePay Generate QRcode |
SecurePay CardPay |
Mobile Browser terminal=WAP |
Standard SecurePay | Wechat H5 payment Please contact BD to enable this feature |
SecurePay CardPay |
Wechat Browser terminal=WAP |
NA | Standard SecurePay |
SecurePay CardPay |
In-APP | In-APP Payment | In-APP Payment | In-APP Payment |
WeChat Mini-Program | NA | Mini-Program Payment | NA |
In-Store Have Scanner |
Scan QRcode | Scan QRcode | Scan QRcode U.S. merchants only |
In-Store | Show QRcode Static QRcode |
Show QRcode Static QRcode |
Show QRcode U.S. merchants only |
Parameters Description
1.Amount
Amount as a positive integer of the minor unit of the currency. For Example, $10.50 in USD would be 1050, ¥100 in JPY would be 100.
2.Currency
Currently, NihaoPay supported currencies:
Currency | Currency Code | Minor unit |
---|---|---|
US Dollar | USD | 2 |
Japanese Yen | JPY | 0 |
Hong Kong Dollar | HKD | 2 |
Euro | EUR | 2 |
Canadian Dollar | CAD | 2 |
Pound Sterling | GBP | 2 |
Singapore Dollar | SGD | 2 |
Australian Dollar | AUD | 2 |
3. RMB Amount
Use this parameter to replace amount
if merchants wish to price their product in RMB. NihaoPay will return an amount in merchant’s settlement currency when payment is successful.
Request | Response | Description |
---|---|---|
rmb_amount=10000 currency=USD |
rmb_amount=10000 amount=1441 currency=USD |
Order amount is 100.00 Chinese Yuan Settlement amount is 14.41 US Dollars |
amount=10000 currency=USD |
amount=10000 currency=USD |
Order amount and Settlement amount are 100.00 US Dollars |
4.Reference
An alphanumeric string up to 30 characters that must be unique to each of your transactions.
5.Vendor
Currently, NihaoPay accepts three vendors are unionpay
, alipay
, and wechatpay
.
6. Callback URL
callback_url
and ipn_url
must be accessible on the Internet and can't be intranet address (for example localhost
) or intranet IP.
7.Terminal
Currently, acceptable values are ONLINE
and WAP
.
System Reserve
sys_reserve = {"vendor_id":"4200000117201806013734875340"}
8. System Reserved
sys_reserve, NihaoPay system reserved, used for return vendor's transaction id or customer's info. Currently, includes:
Key | Value |
---|---|
vendor_id | Vendor's transaction id, usually showed on customer's payment receipt. |
Instant Payment Notification
Asynchronous Response
After payment completed, NihaoPay will return a transaction object to ipn_url
using the POST
method.
Whenever possible, transaction data should be recorded from the IPN URL instead of the callback URL.
When executing the IPN notification, please note:
ipn_url
must be accessible on the Internet and can't be intranet address (for examplelocalhost
) or intranet IP- The IPN notification may arrive ahead of browser callback.
- The duplicated IPN notifications.
- NihaoPay returns to
ipn_url
using thePOST
method. - After the program is executed, the IPN page must print “ok” (without quote). If not, NihaoPay server will keep re-sending notification.
- Generally, there will be 8 notifications within 2 hours (Frequency: 0m,1m,2m,4m,8m,20m,30m).
- After the program is executed, there should not be any redirecting operation on the page, for NihaoPay will not recognize an “ok” string; therefore, it would be regarded as an error, and NihaoPay system will just keep sending the notification.
Asynchronous Response
id = 20170519103602011338
amount = 2
currency = USD
rmb_amount = 12
reference = 20170519103456437807
sys_reserve = {"vendor_id":"4200000117201806013734875340"}
status = success
time = 2017-05-19T10:36:32Z
note = null
verify_sign = 46072c81e3c6140d6bc92655196b247f
Asynchronous Response message
Property | Description |
---|---|
idstring |
Transaction ID. |
statusstring |
Transaction status. In SecurePay scenario, only success . |
amountint |
The settlement amount uses foreign currency. |
rmb_amountint |
Payment Renminbi Amount. Same with the Request, If the request is null, payment amount will be returned. |
currencystring |
The 3-letter currency code. |
timestring |
Timestamp of the transaction in UTC. Ex: 2015-01-01T01:01:00Z is Jan 1, 2015 1:01:00 UTC. |
referencestring |
AlphaNumeric string set in request to correspond transaction ID with your original transaction request. |
notestring |
If set in request, your transaction note to self. Else if not set, this will be null . |
sys_reservejson |
NihaoPay system reservation, it's json string, See Parameters Description. |
verify_sign string |
Signature value. |
Sign method
verify_sign = MD5(key1=value1&key2=value2&...&keyn=valuen&MD5(TOKEN))
Verify signature
When the asynchronous notification returns, NihaoPay will do the MD5 signature on the return message. After the merchant receives asynchronous notification, it will verify that the returned information is tampered with by the signature method.
Signature method:
A. The connection method between the critical message
- The indication method for a single
pair is key = value. If the value corresponding to the key is null, not include the key. - The connection method for multiple
pairs is key1=value1&key2=&key3=value3. Sort pairs in the signature in an ascending order in accordance with key values. - The connection method of cooperative key messages is key1=value1&key2=&key3=value3&MD5(Token), The token, after MD5 calculation, is connected to the end of the
pair.
B. Signature method
verify_sign = MD5(key1=value1&key2=&key3=value3...&keyn=value&MD5(Token))
Note:
- NihaoPay uses UTF-8 as charset.
- Parameters without a value can be excluded from sign;
- The MD5's output is lowercase when comparing signatures, please ignore case.
SecurePay
Create a Standard SecurePay
Definition
POST
https://api.nihaopay.com/v1.2/transactions/securepay
Request
$ curl https://api.nihaopay.com/v1.2/transactions/securepay \
-H "Authorization: Bearer <TOKEN>" \
-d rmb_amount=100 \
-d currency="USD" \
-d vendor="alipay" \
-d reference="20171023191505118594" \
-d ipn_url="https://demo.nihaopay.com/ipn" \
-d callback_url="https://demo.nihaopay.com/callback"
$ curl https://api.nihaopay.com/v1.2/transactions/securepay \
-H "Authorization: Bearer <TOKEN>" \
-d rmb_amount=100 \
-d currency="USD" \
-d vendor="wechatpay" \
-d reference="20171023191505118594" \
-d ipn_url="https://demo.nihaopay.com/ipn" \
-d inWechat="false" \
-d callback_url="https://demo.nihaopay.com/callback"
json response example 1
{
"url": "https://openapi.alipay.com/gateway.do?app_id=2019031263534265"
}
json response example 2
{
"form": {
"actionUrl": "https://www.nihaopay.com/",
"method": "POST",
"target": "_self",
"params": {
"bizType": "000201",
"backUrl": "https://bgw.nihaopay.com/payBackResp/44e4af32d6494c71aaafe2eaf6c05910",
"orderId": "u20230827102153QvCEZp",
"txnSubType": "01"
}"
}
}
SecurePay transactions will redirect users to the vendor’s payment page, where users can enter payment information. Upon successful transaction, users will be redirected to the callback URL. These redirects are accomplished through the use of a JavaScript enabled form.
Due to the nature of redirects and users being able to close their browsers before the redirect can happen, an instant payment notification (IPN) URL is used to provide transaction data.
A reference string is also required to keep track of transactions as the Transaction object will not respond directly to the request but rather in the asynchronous call to your IPN URL. When you receive the Transaction object, you will need to match the reference against your records in order to determine which transaction IDs correspond to which requests.
Request
Property | Description |
---|---|
currencyRequired |
The 3-letter currency code. See Parameters Description for acceptable currencie. |
amountConditional |
Amount as a positive integer of the minor unit of the currency. If amount is not null, it means the transaction uses foreign currency. See Parameters Description. |
rmb_amountConditional |
Amount as a positive integer of the minor unit of the currency. Use this parameter to replace amount if merchant wish to price their product in RMB. If amount is used, rmb_amount should not be set. They are mutual exclusive. See Parameters Description. |
vendorRequired |
Transaction vendor. Currently, acceptable vendors are unionpay , alipay , wechatpay and PayPal . |
referenceRequired |
An alphanumeric string up to 30 characters that must be unique to each of your transactions. This allows you to keep track of transactions when data comes back through IPN and Callback URLs. See Parameters Description. |
ipn_urlRequired |
Instant Payment Notification URL. Called by the API to update you on transaction information. This is where the response goes to. See Instant Payment Notification. |
callback_urlRequired |
URL the browser will be redirected to upon completing the transaction. |
descriptionOptional |
Arbitrary string that you can set to be displayed on the card charge. |
noteOptional |
Arbitrary string as note to self regarding the transaction. |
terminalOptional Default: ONLINE |
Specifies whether payment is submitted on desktop (ONLINE ) or mobile (WAP ). |
timeoutOptional Default: 120 |
Specifies amount of minutes card holders have before payment page times out. Once the page times out without a successful payment, the transaction is automatically closed. Acceptable values are 1 - 1440 . |
in_wechatOptional |
When the current payment scenario is WeChat built-in browser, pass true , otherwise pass false and it is valid only when vendor=wechatpay . when in_wechat=false ,if you have enabled WeChat H5 payment,use WeChat H5 payment otherwise downgrade For scanning code,use JSAPI to pay when in_wechat=true . |
response_formatOptional Default: HTML |
Specifies whether the returned data is in (JSON ) format or (HTML ) format. |
JSON
Property | Description |
---|---|
urlOptional |
Redirect url, when the interface returns url, the caller can directly redirect to this url after getting the url. |
formOptional |
form form object, and url are mutually exclusive, when the url does not exist, the form object exists. |
form.actionUrlRequired |
The action attribute of the form form. |
form.methodRequired |
The method attribute of the form form |
form.targetRequired |
The target attribute of the form form |
form.paramsRequired |
The parameters of the form form, in map format, key is the parameter name, and value is the parameter value. |
Synchronous Response
- HTML format response >The API returns a synchronous message to the merchant. The message is a form that should be displayed in the browser. The form will submit automatically to the vendor's payment portal, redirecting the user to complete the transaction.
- Response in JSON format >The returned json data returns a form object or url (not both). If the url is returned, the caller can directly redirect to this url after getting the url. If the return is a form object, the caller needs to use the fields in the form object to construct a form form by itself, and write the form form to In the current webpage request, the page will jump to the payment page after submission.
Asynchronous Response
id = 20170519103602011338
amount = 2
currency = USD
rmb_amount = 12
reference = 20170519103456437807
sys_reserve = {"vendor_id":"4200000117201806013734875340"}
status = success
time = 2017-05-19T10:36:32Z
note = null
verify_sign = 46072c81e3c6140d6bc92655196b247f
Asynchronous Response
After the successful completion of a securepay, API will return a transaction object to callback_url
using the GET
method, returns to ipn_url
using the POST
method.
Transaction IDs can be used to retrieve details, request cancellations, and create refunds.
Whenever possible, transaction data should be recorded from the IPN URL instead of the callback URL.
Property | Description |
---|---|
idstring |
Transaction ID. |
statusstring |
Transaction status. In SecurePay scenario, only success . |
amountint |
The settlement amount uses foreign currency. |
rmb_amountint |
Payment Renminbi Amount. Same with the Request, If the request is null, payment amount will be returned. |
currencystring |
The 3-letter currency code. |
timestring |
Timestamp of the transaction in UTC. Ex: 2015-01-01T01:01:00Z is Jan 1, 2015 1:01:00 UTC. |
referencestring |
AlphaNumeric string set in request to correspond transaction ID with your original transaction request. |
notestring |
If set in request, your transaction note to self. Else if not set, this will be null . |
sys_reservejson |
NihaoPay system reservation, it's json string, See Parameters Description. |
verify_sign string |
Signature value. |
Generate a Payment QRcode
Definition
POST
https://api.nihaopay.com/v1.2/transactions/qrcode
Request
$ curl https://api.nihaopay.com/v1.2/transactions/qrcode \
-H "Authorization: Bearer <TOKEN>" \
-d amount=100 \
-d vendor="wechatpay" \
-d currency="USD" \
-d reference="jkh25jh1348fd89sg" \
-d ipn_url="http://website.com/ipn"
Merchant's backend system requests payment QRcode API in order to generate an advance transaction and gets code_url. Merchant's backend creates a QR Code based on code_url
which can be displayed on website or printed on the checkout bill. The cardholder opens "Scan" in WeChat or UnionPay QuickPass, scans the QR Code, enters his or her payment password and completes the transaction.
Upon transaction completion, the API will return asynchronous message to the IPN URL. Merchant can request Look up a transaction if no message is received.
The asynchronous message returned to IPN URL is the same with SecurePay.
Request
Property | Description |
---|---|
currencyRequired |
The 3-letter currency code. See Parameters Description for acceptable currencie. |
amountConditional |
Amount as a positive integer of the minor unit of the currency. If amount is not null, it means the transaction uses foreign currency. See Parameters Description. |
rmb_amountConditional |
Amount as a positive integer of the minor unit of the currency. Use this parameter to replace amount if merchant wish to price their product in RMB. If amount is used, rmb_amount should not be set. They are mutual exclusive. See Parameters Description. |
vendorRequired |
Transaction vendor. Currently, acceptable vendors are unionpay and wechatpay . |
referenceRequired |
An alphanumeric string up to 30 characters that must be unique to each of your transactions. This allows you to keep track of transactions when data comes back through IPN and Callback URLs. |
ipn_urlRequired |
Instant Payment Notification URL. Called by the API to update you on transaction information. This is where the response goes to. See Instant Payment Notification. |
timeoutOptional Default: 120 |
Specifies amount of minutes card holders have before payment page times out. Once the page times out without a successful payment, the transaction is automatically cancelled. Acceptable values are 1 - 1440 . |
descriptionOptional |
Arbitrary string that you can set to be displayed on the card charge. |
noteOptional |
Arbitrary string as note to self regarding the transaction. |
Response
{
"id": "20160829075820003759",
"code_url": "weixin://wxpay/bizpayurl?pr=1dVyJZF",
"timeout": 90,
"amount": 100,
"currency": "USD",
"reference": "jkh25jh1348fd89sg",
"time": "2017-05-19T09:38:28Z"
}
Response
Returns a QRcode object.
Property | Description |
---|---|
code_urlstring |
The string of QR code url. |
idstring |
Transaction ID. |
amountint |
Amount of the transaction in the minor unit of the currency. For example, cents in USD. |
currencystring |
The 3-letter currency code. |
timeoutint |
Within the specified minutes, code url will time out. If you did not provide this, default value will be returned to you. |
referencestring |
AlphaNumeric string set in request to correspond transaction ID with your original transaction request. |
timestring |
Timestamp of the transaction in UTC. Ex: 2015-01-01T01:01:00Z is Jan 1, 2015 1:01:00 UTC. |
In-App Payment
Definition
POST
https://api.nihaopay.com/v1.2/transactions/apppay
Request
$ curl https://api.nihaopay.com/v1.2/transactions/apppay \
-H "Authorization: Bearer <TOKEN>" \
-d amount=100 \
-d currency="USD" \
-d vendor="alipay" \
-d reference="alipay20170503000300" \
-d ipn_url="http://website.com/ipn"
For more information about In-App payment, see NihaoPay IOS demo or Andriod demo
Request
Property | Description |
---|---|
currencyRequired |
The 3-letter currency code. See Parameters Description for acceptable currencie. |
amountConditional |
Amount as a positive integer of the minor unit of the currency. If amount is not null, it means the transaction uses foreign currency. See Parameters Description. |
rmb_amountConditional |
Amount as a positive integer of the minor unit of the currency. Use this parameter to replace amount if merchant wish to price their product in RMB. If amount is used, rmb_amount should not be set. They are mutual exclusive. See Parameters Description. |
referenceRequired |
An alphanumeric string up to 30 characters that must be unique to each of your transactions. This allows you to keep track of transactions when data comes back through IPN and Callback URLs. |
vendorRequired |
Transaction vendor. Currently, acceptable vendors are alipay ,wechatpay and unionpay . |
app_idConditional |
APPID approved by WeChat Open Plarform. Required when vendor = wechatpay |
ipn_urlRequired |
Instant Payment Notification URL. Called by the API to update you on transaction information. This is where the response goes to. See Instant Payment Notification. |
descriptionOptional |
Arbitrary string that you can set to be displayed on the card charge. |
noteOptional |
Arbitrary string as note to self regarding the transaction. |
timeoutOptional Default: 120 |
Specifies amount of minutes card holders have before payment page times out. Once the page times out without a successful payment, the transaction is automatically cancelled. Acceptable values are 1 - 1440 . |
ostypeRequired |
Specifies whether the payment page should be displayed on an Android phone (ANDROID ) or an iphone (IOS ). |
Response
{
"orderInfo": "orderinfo string.....",
"redirectUrl": "https://wallet.com/xxx?xxx=xx....."
}
Response
At the same time, only one of orderInfo and redirectUrl will be returned, and orderInfo is used first.
Property | Description |
---|---|
orderInfostring |
Used to call the vendor SDK if not empty,. For more information, see NihaoPay IOS demo or Andriod demo. If you need WeChatPay In-app, please contact us for help. |
redirectUrlstring |
The payment URL that redirects users to a WAP or Web page in the browser or in the WebView,see NihaoPay IOS demo or Andriod demo. |
Alipay A+
Wallet Support: AlipayHK,GCASH,DANA,KaKaoPay,TNG,TrueMoney
Definition
POST
https://api.nihaopay.com/v1.2/transactions/aplus
Request
$ curl https://api.nihaopay.com/v1.2/transactions/aplus \
-H "Authorization: Bearer <TOKEN>" \
-d amount=100 \
-d currency="USD" \
-d reference="alipay20170503000300" \
-d ipn_url="http://website.com/ipn" \
-d callback_url="http://website.com/callback"
Property | Description |
---|---|
currencyRequired |
The 3-letter currency code. See Parameters Description for acceptable currencie. |
amountConditional |
Amount as a positive integer of the minor unit of the currency. If amount is not null, it means the transaction uses foreign currency. See Parameters Description. |
rmb_amountConditional |
Amount as a positive integer of the minor unit of the currency. Use this parameter to replace amount if merchant wish to price their product in RMB. If amount is used, rmb_amount should not be set. They are mutual exclusive. See Parameters Description. |
referenceRequired |
An alphanumeric string up to 30 characters that must be unique to each of your transactions. This allows you to keep track of transactions when data comes back through IPN and Callback URLs. See Parameters Description. |
ipn_urlRequired |
Instant Payment Notification URL. Called by the API to update you on transaction information. This is where the response goes to. See Instant Payment Notification. |
callback_urlConditional |
URL the browser will be redirected to upon completing the transaction, Required when terminal=ONLINE or terminal=WAP . |
descriptionOptional |
Arbitrary string that you can set to be displayed on the card charge. |
noteOptional |
Arbitrary string as note to self regarding the transaction. |
terminalOptional Default: ONLINE |
Specifies whether payment is submitted on desktop (ONLINE ) or mobile (WAP ) or mobile application (APP ). |
timeoutOptional Default: 10 |
Order timeout time, after NihaoPay receives the order request, if the customer fails to pay within the time specified by timeout (minutes), the order will be closed 1 - 10 . |
ostypeConditional |
Specifies whether the payment page should be displayed on an Android phone (ANDROID ) or an iphone (IOS ), Required when terminal=WAP or terminal=APP . |
Response
{
"amount": 10,
"timeout": 10,
"currency": "USD",
"reference": "1657808342862",
"id": "20220714221903000379",
"time": "2022-07-14T22:19:03Z",
"redirectUrl": "https://alipay.com/connect.html?code=281666040098ZTL79hJiG7"
}
Response
Property | Description |
---|---|
amountint |
Order amount. |
timeoutint |
Order timeout time(minutes). |
currencystring |
Order currency. |
referencestring |
Your transactions id. |
idstring |
Nihaopay transactions id. |
timestring |
Order create time. |
redirectUrlstring |
The payment URL that redirects users to a WAP or Web page in the browser. |
WeChat Mini-Program Payment
POST
https://api.nihaopay.com/v1.2/transactions/micropay
Please send the WeChat Mini-program APPID to our support team before development.
Merchant can ask prePay request at the mini-program, and use the function wx.requestpayment() to call WeChatPay if the variable of request is generated successfully. NihaoPay will send IPN announcement to the IPN_url of merchant as long as the order has been placed successfully. Following figures illustrates the development process.
Request
$ curl https://api.nihaopay.com/v1.2/transactions/micropay \
-H "Authorization: Bearer <TOKEN>" \
-d amount=100 \
-d currency="USD" \
-d reference="wechatpay20171109000300" \
-d ipn_url="http://website.com/ipn" \
-d open_id="oSC6Tw7--mfjTCpIr-72rWloA8TU" \
-d client_ip="180.167.25.154"
Request
Property | Description |
---|---|
currencyRequired |
The 3-letter currency code. See Parameters Description for acceptable currencie. |
amountConditional |
Amount as a positive integer of the minor unit of the currency. If amount is not null, it means the transaction uses foreign currency. See Parameters Description. |
rmb_amountConditional |
Amount as a positive integer of the minor unit of the currency. Use this parameter to replace amount if merchant wish to price their product in RMB. If amount is used, rmb_amount should not be set. They are mutual exclusive. See Parameters Description. |
referenceRequired |
An alphanumeric string up to 30 characters that must be unique to each of your transactions. This allows you to keep track of transactions when data comes back through IPN and Callback URLs. |
app_idRequired |
WeChat Mini-Program APPID. |
ipn_urlRequired |
Instant Payment Notification URL. See Instant Payment Notification. |
client_ipRequired |
Customer IP |
open_idRequired |
The openid for a WeChat user that mini programs obtained after a wx.login() call. For get openid in mini programs please see here. |
descriptionOptional |
Arbitrary string that you can set to be displayed on the card charge. |
noteOptional |
Arbitrary string as note to self regarding the transaction. |
timeoutOptional Default: 120 |
Specifies amount of minutes card holders have before payment page times out. Once the page times out without a successful payment, the transaction is automatically cancelled. Acceptable values are 1 - 1440 . |
Success response
{
"timeStamp": "1510341967363",
"nonceStr": "a611bda03d544b9f941393c48c2e517f",
"wechatPackage": "prepay_id=wx201711110326070ccf2a7f060678638664",
"signType": "MD5",
"paySign": "09E5BE5B9D93080E3B7DD05C8F41049E"
}
Response
Property | Description |
---|---|
timeStampstring |
Time Stamp |
nonceStrstring |
Random string |
wechatPackagestring |
Data package include prepay_id=**** |
signTypestring |
Signature type, default MD5 |
paySignstring |
Signature |
CardPay
For credit card pay, please refer to MuskPay API Documentation
In-Store Payment
Scan QRcode
Face-to-face merchant may scan the QRcode or Barcode on customer's phone to get paid for an order instead of having the customer to pay by cash or card. Merchant can use scanning guns, mobile devices with app or mPOS terminals with camera for scanning.
The figure illustrates the work flow of the Scan QRcode payment solution.
POST
https://api.nihaopay.com/v1.2/transactions/scanqrcode
Request
$ curl https://api.nihaopay.com/v1.2/transactions/scanqrcode \
-H "Authorization: Bearer <TOKEN>" \
-d amount=100 \
-d currency="USD" \
-d vendor="alipay" \
-d reference="alipay201705030002" \
-d buyer_identity_code="288463639882104202" \
-d client_ip="184.167.25.158" \
-d note="alipay" \
-d description="Scan AliPay QrCode"
Request
Property | Description |
---|---|
currencyRequired |
The 3-letter currency code. Currently, acceptable currencies are USD and JPY . |
amountRequired |
Amount as a positive integer of the minor unit of the currency. See Parameters Description. |
vendorRequired |
Transaction vendor. Currently, acceptable vendors are alipay , unionpay and wechatpay . |
referenceRequired |
An alphanumeric string up to 30 characters that must be unique to each of your transactions. This allows you to keep track of transactions when data comes back through IPN and Callback URLs. See Parameters Description. |
buyer_identity_codeRequired |
Identification of Customer's QRcode or barcode. |
client_ipRequired |
Terminal IP, The IP of Merchant terminal device |
descriptionOptional |
Arbitrary string that you can set to be displayed on the card charge. |
noteOptional |
Arbitrary string as note to self regarding the transaction. |
Response
{
"amount": 12,
"id": "20170519093105011337",
"time": "2017-05-19T09:31:05Z",
"status": "success",
"sys_reserve": "{'vendor_id':'2018031421001004970502155891'}",
"note": "123456789",
"reference": "alipay201705030004",
"currency": "USD"
}
Response
Returns a transaction object.
Property | Description |
---|---|
idstring |
Transaction ID. |
statusstring |
Transaction status. Either success , failure , or pending . |
sys_reservestring |
NihaoPay reserved. json format. If status is success, return verdor's transaction id. |
amountint |
Amount of the transaction in the minor unit of the currency. For example, cents in USD. |
currencystring |
The 3-letter currency code. |
timestring |
Timestamp of the transaction in UTC. Ex: 2015-01-01T01:01:00Z is Jan 1, 2015 1:01:00 UTC |
referencestring |
A reference number to track each transactions. If you did not provide this, a reference will be generated and returned to you. |
notestring |
If set in request, your transaction note to self. Else if not set, this will be null. |
Show QRcode
Merchant's backend system request show QRcode API in order to generate an advance transaction and gets code_url. Merchant's backend creates a QR Code based on code_url
and show on wetsite or other devices. The customer scans the QR Code, enters their payment password and completes the transaction.
Upon completing the transaction, the API will return asynchronous message to the IPN url. Merchant can request Look up a transaction if no message is received.
The figure illustrates the work flow of the Show QRcode payment solution.
The asynchronous message return to IPN URL is same with SecurePay.
POST
https://api.nihaopay.com/v1.2/transactions/showqrcode
Request
$ curl https://api.nihaopay.com/v1.2/transactions/showqrcode \
-H "Authorization: Bearer <TOKEN>" \
-d amount=100 \
-d currency="USD" \
-d vendor="alipay" \
-d reference="jkh25jh1348fd89sg" \
-d ipn_url="http://website.com/ipn"
Request
Property | Description |
---|---|
amountRequired |
Amount as an integer of the minor unit of the currency. See Parameters Description. |
currencyRequired |
The 3-letter currency code. Currently, acceptable currencies are USD and JPY . |
referenceRequired |
An alphanumeric string up to 30 characters that must be unique to each of your transactions. This allows you to keep track of transactions when data comes back through IPN and Callback URLs. |
vendorRequired |
Transaction vendor. Currently, acceptable vendors are alipay , unionpay and wechatpay . |
ipn_urlRequired |
Instant Payment Notification URL. Called by the API to update you on transaction information. This is where the response goes to. See Instant Payment Notification. |
timeoutOptional Default: 120 |
Specifies amount of minutes card holders have before payment page times out. Once the page times out without a successful payment, the transaction is automatically cancelled. Acceptable values are 1 - 1440 . |
descriptionOptional |
Arbitrary string that you can set to be displayed on the card charge. |
noteOptional |
Arbitrary string as note to self regarding the transaction. |
Response
{
"code_url": "https://qr.alipay.com/bax02617gyevjsjqxgoz2038",
"id": "20170519093828105112",
"timeout": 120,
"currency": "USD",
"amount": 100,
"reference": "20170427-137-0011",
"time": "2017-05-19T09:38:28Z"
}
Response
Returns a QRcode object.
Property | Description |
---|---|
code_urlstring |
The string of QR code url. |
idstring |
Transaction ID. |
amountint |
Amount of the transaction in the minor unit of the currency. For example, cents in USD. |
currencystring |
The 3-letter currency code. |
timeoutint |
Within the specified minutes, code url will time out. If you did not provide this, default value will be returned to you. |
referencestring |
AlphaNumeric string set in request to correspond transaction ID with your original transaction request. |
timestring |
Timestamp of the transaction in UTC. Ex: 2015-01-01T01:01:00Z is Jan 1, 2015 1:01:00 UTC |
Static Omni-Channel QRcode
Create a Static Omni-Channel QRcode
POST
https://api.nihaopay.com/v1.2/merchantqrcode
The payment solution is making use of a static QR code to represent the account of a merchant. In this solution, the customer needs to scan and the input the amount to complete the payment of transaction.
Merchant requests static QRcode API in order to generate a static QRcode. Merchant creates a QR Code based on qrcode
, then prints and posts the QRcode image in merchant's store. The customer scans the QRcode, enters payment amount and completes the transaction on his or her phone.
Upon transaction completion, the API will return an asynchronous message to the IPN url.
The asynchronous message return to IPN URL is the same with SecurePay.
Request
$ curl https://api.nihaopay.com/v1.2/merchantqrcode \
-H "Authorization: Bearer <TOKEN>" \
-d ipn_url="http://website.com/ipn" \
-d trade_currency="USD" \
-d seller_name="NihaoPay" \
-d store_name="LA Branch" \
-d store_no="B001"
Request
Property | Description |
---|---|
trade_currencyRequired |
The 3-letter currency code. Currently, acceptable currencies are USD and JPY . |
ipn_urlOptional |
Instant Payment Notification URL. Called by the API to update you on transaction information. This is where the response goes to. See Instant Payment Notification. |
seller_nameRequired |
Seller name, Displayed on payment page. |
store_nameRequired |
Store name |
store_noRequired |
Store number |
Response
{
"seller_name": "NihaoPay",
"store_name": "LA Branch",
"store_no": "B001",
"qrcode_img_url": "https://apitest.nihaopay.com/merqrcode/9b2487be23a3434b9eb62870fcb73680",
"qrcode": "https://apitest.nihaopay.com/topayment/9b2487be23a3434b9eb62870fcb73680"
}
Response
Property | Description |
---|---|
seller_namestring |
Seller name |
store_namestring |
Store name |
store_nostring |
Store number |
qrcode_img_urlstring |
QRcode image url. |
qrcodestring |
QRcode url. |
Static QRcode Payment
POST
https://api.nihaopay.com/v1.2/transactions/staticqrcode
NihaoPay provides standard payment page for Omni-channel QRcode. In order for merhcants to display their brands on payment page, NihaoPay supports the merchant build H5 payment page corresponding to the QRcode. When customer confirms payment, the following payment interface will wake up WechatPay or AliPay wallet.
Request
$ curl https://api.nihaopay.com/v1.2/transactions/staticqrcode \
-H "Authorization: Bearer <TOKEN>" \
-d amount=100 \
-d vendor="alipay" \
-d reference="201705030002" \
-d qrcode="https://apitest.nihaopay.com/topayment/9b2487be23a3434b9eb62870fcb73680" \
-d callback_url="https://nihaopay.com" \
-d description="static QrCode"
Request
Property | Description |
---|---|
amountRequired |
Amount as a positive integer of the minor unit of the currency. If amount is not null, it means the transaction uses foreign currency. See Parameters Description. |
vendorRequired |
The payment method is determined based on the APP used by the customer to scan the QR code. If WeChat APP, it's wechatpay ,If AliPay wallet,it's alipay . |
qrcodeRequired |
QRcode url,It's returned by Create a Static Omni-Channel QrCode . |
referenceOptional |
An alphanumeric string up to 30 characters that must be unique to each of your transactions. This allows you to keep track of transactions when data comes back through IPN and Callback URLs. See Parameters Description. |
callbacl_urlOptional |
URL the browser will be redirected to upon completing the transaction. |
descriptionOptional |
Arbitrary string that you can set to be displayed on the card charge. |
Response
{
"redirect_url": "https://wxcode.nihaopay.com/wechatpay/openid?txnId=20180314095142025479"
}
Response
When request is successful, the interface will return a page redirect url, redirecting page to this address, and automatically wakes up the payment function by APP.
Property | Description |
---|---|
redirect_urlstring |
redirect url. |
Static AliPay QRcode
POST
https://api.nihaopay.com/v1.2/merchantqrcode
The payment solution makes use of a static QR code to represent the account of a merchant. In this solution, the customer needs to scan and then input the amount to complete the payment of transaction.
Merchant's requests static QRcode API in order to generate a static QRcode. Merchant creates a QR Code based on qrcode
, then prints and posts the QRcode image in merchant's store. The customer scans the QRcode use AliPay APP, enters payment amount and completes the transaction on his or her phone.
Upon transaction completion, the API will return an asynchronous message to the IPN url.
The asynchronous message returned to IPN URL is same with SecurePay.
Request
$ curl https://api.nihaopay.com/v1.2/merchantqrcode \
-H "Authorization: Bearer <TOKEN>" \
-d ipn_url="http://website.com/ipn" \
-d trade_currency="USD" \
-d seller_name="NihaoPay" \
-d store_name="LA Branch" \
-d store_no="B001"
Request
Property | Description |
---|---|
trade_currencyRequired |
The 3-letter currency code. Currently, acceptable currencies are USD and JPY . |
vendorRequired |
Only: alipay . |
ipn_urlOptional |
Instant Payment Notification URL. Called by the API to update you on transaction information. This is where the response goes to. See Instant Payment Notification. |
seller_nameRequired |
Seller name, Displayed on payment page. |
store_nameRequired |
Store name |
store_noRequired |
Store number |
Response
{
"seller_name": "NihaoPay",
"store_name": "LA Branch",
"store_no": "B001",
"qrcode_img_url": "https://mobilecodec.alipay.com/show.htm?code=ocx09459xspxxdajnvzik3d",
"qrcode": "https://qr.alipay.com/ocx09459xspxxdajnvzik3d"
}
Response
Property | Description |
---|---|
seller_namestring |
Seller name |
store_namestring |
Store name |
store_nostring |
Store number |
qrcode_img_urlstring |
QRcode image with AliPay logo |
qrcodestring |
QRcode url. |
Customs Declaration
Customs declaration is needed for products shipped directly to China from international merchants.
Declaration API
Customs declaration service currenly supports orders paid with UnionPay, AliPay and WeChatPay. If you want to use this service for WeChatPay, please contact us first for technical support.
POST
https://api.nihaopay.com/v1.2/customs/declaration/{transaction_id}
Request
$ curl https://api.nihaopay.com/v1.2/customs/declaration/20180529073648029764 \
-H "Authorization: Bearer <TOKEN>" \
-d request_no=20180529073648029702 \
-d customs=ningbo \
-d merchant_customs_code=440316T004 \
-d merchant_customs_name=财付通支付科技有限公司 \
-d customs_amount=1284 \
-d split=true \
-d product_amount=1284 \
-d transport_amount=0 \
-d sub_order_id=20180529073648029701
Request
Property | Description |
---|---|
request_no String(36) Required |
Request order number |
customs String(64) Required |
Customs to send declaration to |
merchant_customs_code String(32) Required |
The merchant customs recordation number |
merchant_customs_name String(64) Required |
The merchant customs recordation name |
customs_amount Int Required |
The declaration amount in RMB "fen (cent)", If the order is splitted, this field cannot be empty. |
duty_amount Int Optional |
Customs duty in RMB "fen (cent)". Required by some customs |
split bool Required Default: true |
Splitting order? Default: true |
sub_order_id String(64) Required |
Merchant's sub order number. |
product_amount Int Conditional |
Product's value in RMB "fen(cent)". If the order is splitted, this field cannot be empty |
transport_amount Int Conditional |
Shipping cost. If the order is splitted, this field cannot be empty |
cert_type String(16) Required |
Certification type. Only supports Chinese Mainland ID for now. Default: ID_CARD |
cert_name String(64) Required |
Name on certificate |
cert_no String(32) Required |
Chinese mainland ID number (please captalize the trailling X) |
Request parameter desciption
You can declare through the following customs:
- ZONGSHU:General Administration of Customs
- BEIJING:Beijing Customs
- HANGZHOU:Hangzhou Customs
- NINGBO:Ningbo Customs
- GUANGZHOU:Guangzhou Customs
- GUANGZHOU_HUANGPU:Guangzhou Huangpu Customs
- SHENZHEN:Shenzhen Customs
- NANSHA:Nansha Guo Jian
- ZHENGZHOU:Zhenzhou Customs(Henan bonded logistics center)
- XINZHENG:Xinzheng comprehensive free trade zone (Airport)
- CHONGQING:Chongqing Customs
- SHANGHAI:Shanghai Customs
- XIAN:Xi'an Customs
- TIANJING:Tianjin Customs
- XIAMEN: Xiamen Customs
Response
{
"id": "20180529084416000000",
"status": "pending",
"transaction_id": "20180529073648029764",
"pay_transaction_id": "2019011122001376840500835544",
"ver_dept": 2,
"pay_code": "312226T001",
"cert_check": "UNCHECKED"
}
Response
Property | Description |
---|---|
idstring |
Serial number for customs declaration, generated by NihaoPay |
statusstring |
Customs declaration status: success , failure , pending . |
transaction_idstring |
Transaction ID |
pay_transaction_idstring |
A unique number assigned by payment provider |
ver_deptint |
The organization that verifies the transaction can be: 0-UnionPay,1-NetsUnion,2-Other |
pay_codestring |
The customs registration number of payment provider. |
cert_checkstring |
Verification result of the purchaser and payer identity information. SAME - Identity information is matched; DIFFERENT - Identity information is not matched; UNCHECKED - Unchecked or no purchaser identification information provided. |
Customs code
UnionPay's customs registration info:
- Customs Name:中国银联股份有限公司
- Customs code:312228034U
WeChatPay's customs registration info:
- Customs Name:财付通支付科技有限公司
- Customs Code:4403169D3W
AliPay's customs registration info:
- Customs Name:支付宝(中国)网络技术有限公司
Customs | Customs Code |
---|---|
ZONGSHU | 31222699S7 |
SHANGHAI | 31222699S7 |
NINGBO | 31222699S7 |
ZHENGZHOU | 31222699S7 |
XINZHENG | P460400005 |
HANGZHOU | ZF14021901 |
GUANGZHOU | C000010000416158 |
TIANJIN | Q12150016000019 |
Declaration query
GET
https://api.nihaopay.com/v1.2/customs/{request_no}
Request
$ curl https://api.nihaopay.com/v1.2/customs/20180529073648029702 \
-H "Authorization: Bearer <TOKEN>"
Request
Property | Description |
---|---|
request_noRequired |
Request order number |
Response
{
"id": "20180529084416000000",
"request_no": "20180529073648029702",
"status": "pending",
"vendor_id": "4200000112201805292728213273",
"customs": "NINGBO",
"split": true,
"customs_amount": 1284,
"product_amount": 1284,
"transport_amount": 0,
"transaction_id": "20180529073648029764",
"sub_order_id": "20180529073648029701",
"pay_transaction_id": "2019011122001376840500835544",
"ver_dept": 2,
"pay_code": "312226T001"
}
Response
Property | Description |
---|---|
idstring |
Declaration status request ID |
transaction_idstring |
Original transaction ID |
vendor_idstring |
Vendor's serial number of original transaction |
statusstring |
Customs declaration status: success , failure , pending . |
customsstring |
Customs the declaration is sent to |
customs_amountint |
Same with request |
duty_amountint |
Same with request |
splitbool |
Splitting order |
sub_order_idstring |
Same with request |
product_amountint |
Same with request |
transport_amountint |
Same with request |
pay_transaction_idstring |
A unique number assigned by payment provider |
ver_deptint |
The organization that verifies the transaction can be: 0-UnionPay,1-NetsUnion,2-Other |
pay_codestring |
The customs registration number of payment provider. |
Redeclaration
POST
https://api.nihaopay.com/v1.2/customs/redeclaration/{request_no}
Request
$ curl https://api.nihaopay.com/v1.2/customs/redeclaration/20210810150833001421 \
-H "Authorization: Bearer <TOKEN>"
Request
Property | Description |
---|---|
request_noRequired |
Request order number |
Response
{
"transaction_id": "20210810150833001421",
"cert_check": "DIFFERENT",
"ver_dept": 3,
"request_no": "20210810150833001421",
"pay_code": "31222699S7",
"pay_transaction_id": "2021081011082640020055578",
"merchant_id": "M001100001",
"id": "20210810150935000155",
"status": "success"
}
Response
Property | Description |
---|---|
request_nostring |
Request order number |
idstring |
Declaration status request ID |
merchant_idstring |
NihaoPay Merchant ID |
transaction_idstring |
Original transaction ID |
statusstring |
Customs declaration status: success , failure , pending . |
pay_transaction_idstring |
A unique number assigned by payment provider |
ver_deptint |
The organization that verifies the transaction can be: 0-UnionPay,1-NetsUnion,2-Other |
pay_codestring |
The customs registration number of payment provider. |
cert_checkstring |
Verification result of the purchaser and payer identity information. SAME - Identity information is matched; DIFFERENT - Identity information is not matched; UNCHECKED - Unchecked or no purchaser identification information provided. |
Error code for Customs Declaration
code | label | message |
---|---|---|
400 | 31 | Transaction reference number must be unique. Please re-submit. |
402 | 61 | Transaction not found. |
500 | 81 | Merchant config error |
500 | 82 | Merchant unavailable |
400 | 90 | The field not valid. |
500 | 91 | Signature error |
500 | 92 | The {0} field is required. |
500 | 96 | Timeout |
500 | 97 | Inner error |
500 | 98 | Vendor error |
500 | 99 | System error |
401 | 301 | Invalid merchant credentials provided |
402 | 100 | Transaction retransmission fail, Please try it after 5 minutes. |
402 | 101 | Customs not supported. |
402 | 102 | Customs infomation changed. |
402 | 103 | Certification not correct. |
402 | 104 | Split amount not correct. |
402 | 105 | Can not be modified as it is on declaration. |
402 | 106 | Same customs declare once. |
402 | 107 | Your request has been submitted, please confirm that it has taken effect. |
402 | 108 | The original customs does not exist |
402 | 109 | The declaration is not allowed for refunded orders |
Refund/Query/Others
Retrieve a SecurePay
Definition
GET
https://api.nihaopay.com/v1.2/transactions/merchant/{reference}
Request
$ curl https://api.nihaopay.com/v1.2/transactions/merchant/{reference} \
-H "Authorization: Bearer <TOKEN>"
Provide reference that was requested for a SecurePay transactions in order to retrieve corresponding transaction’s details.
Applicable to SecurePay transactions that do not receive asynchronous notifications
Request
reference
as URL parameter.
Response
{
"id": "bn2345nb53454kjb",
"status": "success",
"type": "charge",
"amount": 1111,
"currency": "USD",
"time": "2015-01-01T01:01:01Z",
"reference": "jkh25jh1348fd89sg",
"note": "sample note"
}
Response
Returns a transaction object.
Property | Description |
---|---|
idstring |
Transaction ID. |
statusstring |
Transaction status. Either success , failure , or pending . |
typestring |
Transaction type. Either charge , authorization , or capture . |
vendorstring |
Payment method. Include: unionpay , alipay , wechatpay or alipayhk . |
vendor_idstring |
Vendor’s transaction id, usually showed on customer’s payment receipt. |
amountint |
Amount of the transaction in the minor unit of the currency. For example, cents in USD. |
currencystring |
The 3-letter currency code. |
timestring |
Timestamp of the transaction in UTC. Ex: 2015-01-01T01:01:00Z is Jan 1, 2015 1:01:00 UTC. |
referencestring |
AlphaNumeric string set in request to correspond transaction ID with your original transaction request. |
notestring/null |
If set in request, your transaction note to self. Else if not set, this will be null. |
Look up a transaction
Definition
GET
https://api.nihaopay.com/v1.2/transactions/{transaction_id}
Request
$ curl https://api.nihaopay.com/v1.2/transactions/{transaction_id} \
-H "Authorization: Bearer <TOKEN>"
Returns details of a previously created transaction.
Provide a unique transaction ID that was returned from a previous response in order to retrieve corresponding transaction’s details. Only SecurePay transaction details can be found through this endpoint. For details on Released, Cancelled, and Refunded transactions, please use TMS.
Request
transaction_id
as URL parameter.
Response
{
"id": "bn2345nb53454kjb",
"status": "success",
"type": "charge",
"amount": 1111,
"currency": "USD",
"time": "2015-01-01T01:01:01Z",
"reference": "jkh25jh1348fd89sg",
"note": "sample note"
}
Response
Returns a transaction object.
Property | Description |
---|---|
idstring |
Transaction ID. |
statusstring |
Transaction status. Either success , failure , or pending . |
typestring |
Transaction type. Either charge , authorization , or capture . |
vendorstring |
Payment method. Include: unionpay , alipay , wechatpay or alipayhk . |
vendor_idstring |
Vendor’s transaction id, usually showed on customer’s payment receipt. |
amountint |
Amount of the transaction in the minor unit of the currency. For example, cents in USD. |
currencystring |
The 3-letter currency code. |
timestring |
Timestamp of the transaction in UTC. Ex: 2015-01-01T01:01:00Z is Jan 1, 2015 1:01:00 UTC. |
referencestring |
AlphaNumeric string set in request to correspond transaction ID with your original transaction request. |
notestring/null |
If set in request, your transaction note to self. Else if not set, this will be null. |
Refund a transaction
Definition
POST
https://api.nihaopay.com/v1.2/transactions/{transaction_id}/refund
Request
$ curl https://api.nihaopay.com/v1.2/transactions/{transaction_id}/refund \
-H "Authorization: Bearer <TOKEN>" \
-d amount=100 \
-d currency="USD"
To issue a full or partial refund, you must create a Refund Object based on an existing transaction.
Full refunds can only be created once per transaction by specifying amount as the full amount of the transaction. Partial refunds can be created multiple times untill total refund amount reaches amount of the Transaction.
You cannot refund more than the amount of the original transaction.
Request
transaction_id
as URL Parameter.
Property | Description |
---|---|
currencyRequired |
The 3-letter currency code. Currency must match the original transaction's currency. |
amountConditional |
Amount to be funded in the minor unit of the currency. Must be equal to or less than the amount of the original transaction. |
rmb_amountConditional |
If original transaction Amount as a positive integer of the minor unit of the currency. Use this parameter to replace amount if merchant wish to price their product in RMB. If amount is used, rmb_amount should not be set. They are mutual exclusive. See Parameters Description. |
reasonOptional |
Arbitrary string detailing the reason for refund. |
Response
{
"id": "bn2345nb53454kjb",
"status": "success",
"refunded": true,
"transaction_id": "jkh25jh1348fd89sg"
}
Response
Returns a refund object.
Property | Description |
---|---|
idstring |
Refund ID. |
statusstring |
Status of the refund. Either success , or failure . |
refundedbool |
true |
transaction_idstring |
ID of the transaction that was refunded. |
Refund Query
GET
https://api.nihaopay.com/v1.2/transactions/refunds/{transaction_id}/
Request
$ curl https://api.nihaopay.com/v1.2/transactions/refunds/{transaction_id}/ \
-H "Authorization: Bearer <TOKEN>"
Request
transaction_id
Original transaction ID as URL parameter.
Response
{
"note": null,
"amount": 2,
"type": "charge",
"refunded_amount": 2,
"refunds": [
{
"refund_time": "2021-11-29T05:42:33Z",
"refund_id": "20211129054233008405",
"refunded_amount": 1,
"status": "success"
},
{
"refund_time": "2021-11-29T05:41:55Z",
"refund_id": "20211129054155008404",
"refunded_amount": 1,
"status": "success"
}
],
"reference": "20211129134105329326",
"vendor": "unionpay",
"vendor_id": "512111291341178330258",
"currency": "USD",
"id": "20211129054117043676",
"time": "2021-11-29T05:41:17Z",
"status": "success"
}
Response
Property | Description |
---|---|
idstring |
Transaction ID. |
statusstring |
Transaction status. Either success , failure , pending or closed |
typestring |
Transaction type. Either charge , authorization , or capture . |
amountint |
Amount of the transaction in the minor unit of the currency. For example, cents in USD. |
currencystring |
Transaction currency. |
timestring |
Timestamp of the transaction in UTC. |
referencestring |
Merchant order number. |
notestring |
If set in request, your transaction note to self. Else if not set, this will be null. |
vendorstring |
Payment method. Include: unionpay , alipay , wechatpay or alipayhk . |
vendor_idstring |
Vendor’s transaction id, usually showed on customer’s payment receipt. |
refunded_amountint |
Total refunded amount |
refundslist |
Refund records |
refund_timestring |
Refund time |
refund_idstring |
Refund ID. |
refunded_amountint |
refund amount |
statusstring |
Refund status.Either success or failure |
List transactions
Definition
GET
https://api.nihaopay.com/v1.2/transactions/
Request
$ curl https://api.nihaopay.com/v1.2/transactions/?starting_after=2015-01-01T01:01:00Z \
-H "Authorization: Bearer <TOKEN>"
Returns a list of previously created transactions. Transactions are returned with the most recent transactions appearing first. By default, only 10 transactions are returned at a time. This can be adjusted by providing a limit
argument.
Only SecurePay transactions can be returned. For details on Released, Cancelled, and Refunded transactions, please use TMS.
By providing starting_after
argument, you can retrieve transactions that were processed after the specified time.
By providing ending_before
argument, you can retrieve transactions that were processed before the specified time.
By providing both, starting_after
and ending_before
arguments, you can retrieve transactions that were processed within the specified range.
Request
Properties as URL GET parameters.
Property | Description |
---|---|
limitOptional Default: 10 |
Number of transactions returned for each request. Limit can range between 1 and 100. |
starting_afterOptional |
Time in UTC format yyyy-mm-ddThh:mm:ssZ. Used to retrieve transactions processed after the specified time. |
ending_beforeOptional |
Time in UTC format yyyy-mm-ddThh:mm:ssZ. Used to retrieve transactions processed before the specified time. |
Response
{
"transactions": [
{
"id": "bn2345nb53454kjb",
"status": "success",
"type": "charge",
"amount": 1111,
"currency": "USD",
"time": "2015-01-01T01:05:0Z",
"reference": "jkh25jh1348fd89sg",
"note": "sample note"
},
{
"id": "16zfmK2eZvKYlo2C6X3",
"status": "success",
"type": "authorization",
"amount": 1111,
"currency": "USD",
"time": "2015-01-01T01:01:01Z",
"reference": "6LJDMbC6Ybqlt7fd",
"note": "sample note"
}
]
}
Response
Returns a transactions array of transaction objects. If no transactions are available, returns an empty array.
Property | Description |
---|---|
idstring |
Transaction ID. |
statusstring |
Transaction status. Either success , failure , or pending . |
typestring |
Transaction type. Either charge , authorization , or capture . |
amountint |
Amount of the transaction in the minor unit of the currency. For example, cents in USD. |
currencystring |
The 3-letter currency code. |
timestring |
Timestamp of the transaction in UTC. Ex: 2015-01-01T01:01:00Z is Jan 1, 2015 1:01:00 UTC. |
referencestring |
AlphaNumeric string set in request to correspond transaction ID with your original transaction request. |
notestring/null |
If set in request, your transaction note to self. Else if not set, this will be null. |
Query exchange rate
GET
https://api.nihaopay.com/v1.2/exchangerate
Exchange rate updates 10:30am China Standard Time(UTC+8), once a day (Frequency limit: 1 time per minute, it is recommended to query only once a day).
Response
$ curl https://api.nihaopay.com/v1.2/exchangerate/?rate_date=20170308¤cy=USD \
-H "Authorization: Bearer <TOKEN>"
Request
Properties as URL GET parameters.
Property | Description |
---|---|
rate_dateRequired |
Rate date, formatted as YYYYMMDD |
currencyRequired |
Foreign currency,acceptable are USD , JPY , HKD , GBP ,EUR |
vendorOptional |
Vendor, acceptable are alipay , wechatpay , unionpay |
Response
{
"rates": [
{
"rate_date": "20170308",
"currency": "usd",
"vendor": "unionpay",
"rate": "6.948700"
},
{
"rate_date": "20170308",
"currency": "usd",
"vendor": "alipay",
"rate": "6.921791"
},
{
"rate_date": "20170308",
"currency": "usd",
"vendor": "wechatpay",
"rate": "6.921911"
}
]
}
Response
Returns exchange rate list.
Property | Description |
---|---|
rate_datestring |
Rate date, formatted as YYYYMMDD |
currencystring |
Foreign currency |
vendorstring |
alipay , wechatpay or unionpay |
ratestring |
Foreign currency to Renminbi(RMB) exchange rate |
Download transactions
GET
https://api.nihaopay.com/v1.2/download/transactions
This interface enables the merchants to download the transaction list in a specific time span to reconcile transactions.
Request
$ curl https://api.nihaopay.com/v1.2/download/transactions/?start_date=20170101&end_date=20170105 \
-H "Authorization: Bearer <TOKEN>"
Request
Properties as URL GET parameters.
Note: The starting and end dates should be within a 10-day interval.
Property | Description |
---|---|
start_dateRequired |
The start date, formatted as YYYYMMDD |
end_dateRequired |
The end date , formatted as YYYYMMDD |
Response
Currently the interface only supports .CSV file to be downloaded.
Download billing file
GET
https://api.nihaopay.com/v1.2/billing
This interface enables the merchants to download the transaction list in a specific time span to reconcile the transactions.
Closed, failed or cancelled transactions do not appear in the download file.
Request
$ curl https://api.nihaopay.com/v1.2/billing/?start_date=20170101&end_date=20170105 \
-H "Authorization: Bearer <TOKEN>"
Request
Properties as URL GET parameters.
Note: The starting and end dates should be within a 10-day interval.
Property | Description |
---|---|
start_dateRequired |
The start date, formatted as YYYYMMDD |
end_dateRequired |
The end date , formatted as YYYYMMDD |
Response
Currently the interface only supports .CSV file to be downloaded.
Account / Withdrawal
Inquiry account balance
GET
https://api.nihaopay.com/v1.2/accounts
Request
$ curl https://api.nihaopay.com/v1.2/accounts \
-H "Authorization: Bearer <TOKEN>"
Request
Properties as URL GET parameters.
Response
{
"accounts": [
{
"balance": "100.00",
"currency": "USD",
"pending_amount": "12.40",
"freeze_amount": "0.00"
}
]
}
Response
Returns merchant account object.
Property | Description |
---|---|
currencystring |
Account currency |
balancestring |
Currently account balance |
pending_amountstring |
Currently unsettled purchase amount |
freeze_amountstring |
Currently unsettled refund amount |
Inquiry withdrawal history
GET
https://api.nihaopay.com/v1.2/withdrawal/history
Request
$ curl https://api.nihaopay.com/v1.2/withdrawal/history/?start_date=20170101&end_date=20170105 \
-H "Authorization: Bearer <TOKEN>"
Request
Properties as URL GET parameters.
Property | Description |
---|---|
start_dateRequired |
Start date, formatted as YYYYMMDD. |
end_dateRequired |
End date, formatted as YYYYMMDD. |
Response
{
"withdrawal": [
{
"id": "bn2345nb53454kjb",
"status": "completed",
"amount": "100.00",
"currency": "USD",
"fee": "0.30",
"fee_currency":"USD",
"date": "20170101"
}
]
}
Response
Return an array of withdrawal object. If no transactions are available, returns an empty array.
Property | Description |
---|---|
idstring |
NihaoPay withdrawal ID |
statusstring |
Withdrawal status. Included processing and completed . |
amountint |
Withdrawal amount |
currencystring |
Withdrawal currency |
feestring |
Withdrawal fee |
fee_currencystring |
Withdrawal fee currency type. |
datestring |
Withdrawal date, formatted as YYYYMMDD |
Withdrawal Details
GET
https://api.nihaopay.com/v1.2/withdrawal/detail/{withdrawal_id}
According to the withdrawal_id to get the corresponding data
Request
$ curl https://api.nihaopay.com/v1.2/withdrawal/detail/{withdrawal_id} \
-H "Authorization: Bearer <TOKEN>"
Request
withdrawal_id
: ID generated by 'Apply Withdrawal' request, and send this ID as parameter.
Resonse
Convert return data to a CSV file which conclude all the data.
Testing
Testing Endpoint
https://apitest.nihaopay.com
We have two environments for our API: Testing and Production. These two environments and their endpoints are identical, with the exception that no real money is transferred in the Testing environment. You can use the Testing endpoints as substitutes for the Production endpoints during integration.
For example, transactions in the Testing environment would be:
https://apitest.nihaopay.com/v1.2/transactions
To access the TMS for transactions processed in the testing environment, please use the Testing TMS.
While using the Testing environment, bank issued cards cannot be used. We provide test credentials for you to use to simulate transactions.
To start testing, apply for a test account here
Test Cards
While using the Testing environment, bank issued cards will not work. We provide Test Cards below for you to use to simulate transactions.
UnionPay Credit Card 1
Card Number | 6250 9470 0000 0014 |
CVV | 123 |
EXP | 12/2033 |
Phone # | 852-11112222 |
Verification Code | 111111 |
Visa Credit Card (For Test Approval)
Card Number | 4111 1111 1111 1111 |
CVV | 123 |
EXP | 12/2023 |
Visa Credit Card (For Test Wrong expiration)
Card Number | 4387 7511 1111 1046 |
CVV | 123 |
EXP | 12/2023 |
Mastercard Credit Card (For Test Approval)
Card Number | 5454 5454 5454 5454 |
CVV | 123 |
EXP | 12/2023 |
Mastercard Credit Card (For Test Wrong expiration)
Card Number | 5442 9811 1111 1049 |
CVV | 123 |
EXP | 12/2023 |
UnionPay Debit Card
Card Number | 6226 0900 0000 0048 |
PIN | 123456 |
Phone # | 1810000000 |
Verification Code | 111111 |
Alipay Test Accounts
We provide Alipay Test Accounts below for you to use to simulate transactions.
AliPay Test Account
Account | forex_1701852082070@alitest.com |
Login Password | 111111 |
Payment Password on Cashier Page | 111111 |
WechatPay Test Info
We do not provide Wechat Test accounts; however, you may use your real Wechat account to simulate transactions. If the payment is successful, please call Refund to get your money back.
Errors
Error
{
"code": 409,
"label": "64",
"message": "Refund or capture currency does not match the original transaction currency."
}
When an API request fails, NihaoPay will return an error object.
NihaoPay errors follow conventional HTTP status codes. A 2xx
code indicates request success; therefore, you will not see any of these codes in the error object. A 4xx
code indicates an error in the information provided. These could be anything from a malformed request, an unauthenticated request, or an unknown endpoint. A 5xx
code indicates NihaoPay’s internal server error.
There are certain features that are not yet available but are documented in this API Reference. Requesting those features from the API will result in a 501
error.
Feel free to contact our tech support team at tech_support@nihaopay.com if you encounter errors.
Error Object
Property | Description |
---|---|
codeint |
HTTP status code. |
labelstring |
Label of the error generated by NihaoPay. Support team may ask for this to help with integration questions. |
messagestring |
A human readable message as to the cause of the encountered error. |
Error List
code | label | message |
---|---|---|
200 | 00 | Success |
402 | 01 | Transaction failed. Please try again. |
402 | 02 | Cardholder input an incorrect card number. |
402 | 03 | Cardholder\'s issuing bank prevented the transaction. |
402 | 06 | Customer input an expired card number. |
402 | 11 | Customer has insufficient funds available. |
402 | 14 | Cardholder input an incorrect expiration date. |
402 | 15 | Cardholder authentication failed. Please verify cardholder\'s information. |
402 | 21 | Cardholder authentication failed. Please verify cardholder\'s information. |
402 | 22 | Card state is incorrect. |
402 | 30 | The amount exceeds transaction limit placed. |
400 | 31 | Transaction reference number must be unique. Please re-submit. |
400 | 32 | This payment channel is restricted. Please contact NihaoPay customer service. |
409 | 33 | Transaction failed. Information submitted in a repeat transaction must match the original attempted transaction exactly. |
402 | 36 | Transaction exceeds the cardholder\'s credit limit. |
429 | 39 | Too many transactions attempts by cardholder. |
402 | 56 | Cardholder\'s chosen payment card is not supported in this Gateway. |
402 | 57 | Cardholder has not activated online payments with their issuing bank. |
404 | 59 | Failed. Transaction have refund or chargeback. |
404 | 60 | Transaction has been cleared, please request refund. |
402 | 61 | Transaction not found. |
402 | 62 | Transaction is not within the acceptance time range. |
402 | 63 | The original transaction failed. You cannot refund, cancel, capture, or release an unsuccessful transaction. |
409 | 64 | Refund or capture currency does not match the original transaction currency. |
409 | 65 | Transaction has previously been cancelled. |
409 | 66 | Failed to refund transaction. Transaction has previously been fully refunded. |
402 | 67 | Failed to refund transaction. Refund amount exceeds original transaction amount or remaining transaction balance . |
402 | 68 | Failed to capture transaction. Transaction has previously been released. |
402 | 69 | Failed to capture transaction. Transaction has previously been captured. |
402 | 70 | Failed to capture transaction. Capture amount exceeds authorization amount. |
402 | 71 | Buyer not exist or buyer account info error |
402 | 72 | Transaction amount is exceed the limit |
500 | 81 | Merchant config error |
500 | 82 | Merchant unavailable |
500 | 83 | QRcode has expired |
500 | 84 | Service is not activated for this account |
402 | 86 | Withdrawal amount exceeds account balance |
402 | 87 | Withdrawal amount less than the minimum withdrawal amount |
402 | 88 | Invalid application, it's only available for manually withdrawal merchant |
400 | 90 | The field not valid. |
500 | 91 | Signature error |
500 | 92 | The {0} field is required. |
404 | 93 | The Exchange rate not found. |
500 | 96 | Timeout |
500 | 97 | Inner error |
500 | 98 | Vendor error |
500 | 99 | System error |
401 | 301 | Invalid merchant credentials provided |
API Change Log
2023-08-23
- SecurePay supports returning data in json format
2023-08-05
- Add Profit Sharing Interface ProfitSharing
2022-07-18
- Add interface Alipay A+
2020-09-01
- Update currencies list
- Support UnionPay customs declaration
2018-06-01
- Add customs declaration
- Add vendor's transaction in IPN
2018-05-17
- In-App payment support WeChatPay.
- Scan QRcode support UnionPay QRcode, U.S. merchants only.
2018-03-15
- Add interface
Static Omni-Channel QRcode
- Add interface
Static AliPay QRcode
2017-11-10
- Add interface
WeChat Mini-program payment
2017-08-21
- Add interface
Download transactions
- Add interface
Static QRcode
- Add interface
Inquiry account balance
- Add interface
Apply withdrawal
- Add interface
Inquiry withdrawal history
2017-05-25
- Add In-Store Payment API
- Add In-App Payment API
- Add verify signature in IPN notification
- Change IPN notification frequency
2017-04-10
- Update Error list
- Add parameter
rmb_amount
in SecurePay and ExpressPay request field list.
2017-03-07
- Add Chinese document
- Add parameter
client_ip
in ExpressPay request field list - Add interface
Query Exchange Rate
- Add interface
Download Billing
2017-01-01
- Upgrade to
v1.2