NAV
cURL

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:

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
id
string
Transaction ID.
status
string
Transaction status. In SecurePay scenario, only success.
amount
int
The settlement amount uses foreign currency.
rmb_amount
int
Payment Renminbi Amount. Same with the Request, If the request is null, payment amount will be returned.
currency
string
The 3-letter currency code.
time
string
Timestamp of the transaction in UTC. Ex: 2015-01-01T01:01:00Z is Jan 1, 2015 1:01:00 UTC.
reference
string
AlphaNumeric string set in request to correspond transaction ID with your original transaction request.
note
string
If set in request, your transaction note to self. Else if not set, this will be null.
sys_reserve
json
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 pair and the cooperative key message pair is:

B. Signature method

verify_sign = MD5(key1=value1&key2=&key3=value3...&keyn=value&MD5(Token))

Note:

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
currency
Required
The 3-letter currency code. See Parameters Description for acceptable currencie.
amount
Conditional
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_amount
Conditional
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.
vendor
Required
Transaction vendor. Currently, acceptable vendors are unionpay, alipay, wechatpay and PayPal.
reference
Required
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_url
Required
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_url
Required
URL the browser will be redirected to upon completing the transaction.
description
Optional
Arbitrary string that you can set to be displayed on the card charge.
note
Optional
Arbitrary string as note to self regarding the transaction.
terminal
Optional
Default: ONLINE
Specifies whether payment is submitted on desktop (ONLINE) or mobile (WAP).
timeout
Optional
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_wechat
Optional
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_format
Optional
Default: HTML
Specifies whether the returned data is in (JSON) format or (HTML) format.

JSON

Property Description
url
Optional
Redirect url, when the interface returns url, the caller can directly redirect to this url after getting the url.
form
Optional
form form object, and url are mutually exclusive, when the url does not exist, the form object exists.
form.actionUrl
Required
The action attribute of the form form.
form.method
Required
The method attribute of the form form
form.target
Required
The target attribute of the form form
form.params
Required
The parameters of the form form, in map format, key is the parameter name, and value is the parameter value.

Synchronous Response

  1. 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.
  2. 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
id
string
Transaction ID.
status
string
Transaction status. In SecurePay scenario, only success.
amount
int
The settlement amount uses foreign currency.
rmb_amount
int
Payment Renminbi Amount. Same with the Request, If the request is null, payment amount will be returned.
currency
string
The 3-letter currency code.
time
string
Timestamp of the transaction in UTC. Ex: 2015-01-01T01:01:00Z is Jan 1, 2015 1:01:00 UTC.
reference
string
AlphaNumeric string set in request to correspond transaction ID with your original transaction request.
note
string
If set in request, your transaction note to self. Else if not set, this will be null.
sys_reserve
json
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
currency
Required
The 3-letter currency code. See Parameters Description for acceptable currencie.
amount
Conditional
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_amount
Conditional
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.
vendor
Required
Transaction vendor. Currently, acceptable vendors are unionpay and wechatpay.
reference
Required
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_url
Required
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.
timeout
Optional
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.
description
Optional
Arbitrary string that you can set to be displayed on the card charge.
note
Optional
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_url
string
The string of QR code url.
id
string
Transaction ID.
amount
int
Amount of the transaction in the minor unit of the currency. For example, cents in USD.
currency
string
The 3-letter currency code.
timeout
int
Within the specified minutes, code url will time out. If you did not provide this, default value will be returned to you.
reference
string
AlphaNumeric string set in request to correspond transaction ID with your original transaction request.
time
string
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
currency
Required
The 3-letter currency code. See Parameters Description for acceptable currencie.
amount
Conditional
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_amount
Conditional
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.
reference
Required
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.
vendor
Required
Transaction vendor. Currently, acceptable vendors are alipay,wechatpay and unionpay.
app_id
Conditional
APPID approved by WeChat Open Plarform. Required when vendor = wechatpay
ipn_url
Required
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.
description
Optional
Arbitrary string that you can set to be displayed on the card charge.
note
Optional
Arbitrary string as note to self regarding the transaction.
timeout
Optional
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.
ostype
Required
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
orderInfo
string
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.
redirectUrl
string
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
currency
Required
The 3-letter currency code. See Parameters Description for acceptable currencie.
amount
Conditional
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_amount
Conditional
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.
reference
Required
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_url
Required
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_url
Conditional
URL the browser will be redirected to upon completing the transaction, Required when terminal=ONLINE or terminal=WAP.
description
Optional
Arbitrary string that you can set to be displayed on the card charge.
note
Optional
Arbitrary string as note to self regarding the transaction.
terminal
Optional
Default: ONLINE
Specifies whether payment is submitted on desktop (ONLINE) or mobile (WAP) or mobile application (APP).
timeout
Optional
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.
ostype
Conditional
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
amount
int
Order amount.
timeout
int
Order timeout time(minutes).
currency
string
Order currency.
reference
string
Your transactions id.
id
string
Nihaopay transactions id.
time
string
Order create time.
redirectUrl
string
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.

Mini Program Flow

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
currency
Required
The 3-letter currency code. See Parameters Description for acceptable currencie.
amount
Conditional
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_amount
Conditional
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.
reference
Required
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_id
Required
WeChat Mini-Program APPID.
ipn_url
Required
Instant Payment Notification URL. See Instant Payment Notification.
client_ip
Required
Customer IP
open_id
Required
The openid for a WeChat user that mini programs obtained after a wx.login() call. For get openid in mini programs please see here.
description
Optional
Arbitrary string that you can set to be displayed on the card charge.
note
Optional
Arbitrary string as note to self regarding the transaction.
timeout
Optional
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
timeStamp
string
Time Stamp
nonceStr
string
Random string
wechatPackage
string
Data package include prepay_id=****
signType
string
Signature type, default MD5
paySign
string
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.

Scan QRcode

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
currency
Required
The 3-letter currency code. Currently, acceptable currencies are USD and JPY.
amount
Required
Amount as a positive integer of the minor unit of the currency. See Parameters Description.
vendor
Required
Transaction vendor. Currently, acceptable vendors are alipay , unionpayand wechatpay.
reference
Required
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_code
Required
Identification of Customer's QRcode or barcode.
client_ip
Required
Terminal IP, The IP of Merchant terminal device
description
Optional
Arbitrary string that you can set to be displayed on the card charge.
note
Optional
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
id
string
Transaction ID.
status
string
Transaction status. Either success, failure, or pending.
sys_reserve
string
NihaoPay reserved. json format. If status is success, return verdor's transaction id.
amount
int
Amount of the transaction in the minor unit of the currency. For example, cents in USD.
currency
string
The 3-letter currency code.
time
string
Timestamp of the transaction in UTC. Ex: 2015-01-01T01:01:00Z is Jan 1, 2015 1:01:00 UTC
reference
string
A reference number to track each transactions. If you did not provide this, a reference will be generated and returned to you.
note
string
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.

Show QRcode

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
amount
Required
Amount as an integer of the minor unit of the currency. See Parameters Description.
currency
Required
The 3-letter currency code. Currently, acceptable currencies are USD and JPY.
reference
Required
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.
vendor
Required
Transaction vendor. Currently, acceptable vendors are alipay , unionpayand wechatpay.
ipn_url
Required
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.
timeout
Optional
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.
description
Optional
Arbitrary string that you can set to be displayed on the card charge.
note
Optional
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_url
string
The string of QR code url.
id
string
Transaction ID.
amount
int
Amount of the transaction in the minor unit of the currency. For example, cents in USD.
currency
string
The 3-letter currency code.
timeout
int
Within the specified minutes, code url will time out. If you did not provide this, default value will be returned to you.
reference
string
AlphaNumeric string set in request to correspond transaction ID with your original transaction request.
time
string
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_currency
Required
The 3-letter currency code. Currently, acceptable currencies are USD and JPY.
ipn_url
Optional
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_name
Required
Seller name, Displayed on payment page.
store_name
Required
Store name
store_no
Required
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_name
string
Seller name
store_name
string
Store name
store_no
string
Store number
qrcode_img_url
string
QRcode image url.
qrcode
string
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
amount
Required
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.
vendor
Required
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.
qrcode
Required
QRcode url,It's returned by Create a Static Omni-Channel QrCode.
reference
Optional
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_url
Optional
URL the browser will be redirected to upon completing the transaction.
description
Optional
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_url
string
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_currency
Required
The 3-letter currency code. Currently, acceptable currencies are USD and JPY.
vendor
Required
Only: alipay.
ipn_url
Optional
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_name
Required
Seller name, Displayed on payment page.
store_name
Required
Store name
store_no
Required
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_name
string
Seller name
store_name
string
Store name
store_no
string
Store number
qrcode_img_url
string
QRcode image with AliPay logo
qrcode
string
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:

Response

{
    "id": "20180529084416000000",
    "status": "pending",
    "transaction_id": "20180529073648029764",
    "pay_transaction_id": "2019011122001376840500835544",
    "ver_dept": 2,
    "pay_code": "312226T001",
    "cert_check": "UNCHECKED"
}

Response

Property Description
id
string
Serial number for customs declaration, generated by NihaoPay
status
string
Customs declaration status: success, failure, pending.
transaction_id
string
Transaction ID
pay_transaction_id
string
A unique number assigned by payment provider
ver_dept
int
The organization that verifies the transaction can be: 0-UnionPay,1-NetsUnion,2-Other
pay_code
string
The customs registration number of payment provider.
cert_check
string
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:

WeChatPay's customs registration info:

AliPay's customs registration info:

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_no
Required
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
id
string
Declaration status request ID
transaction_id
string
Original transaction ID
vendor_id
string
Vendor's serial number of original transaction
status
string
Customs declaration status: success, failure, pending.
customs
string
Customs the declaration is sent to
customs_amount
int
Same with request
duty_amount
int
Same with request
split
bool
Splitting order
sub_order_id
string
Same with request
product_amount
int
Same with request
transport_amount
int
Same with request
pay_transaction_id
string
A unique number assigned by payment provider
ver_dept
int
The organization that verifies the transaction can be: 0-UnionPay,1-NetsUnion,2-Other
pay_code
string
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_no
Required
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_no
string
Request order number
id
string
Declaration status request ID
merchant_id
string
NihaoPay Merchant ID
transaction_id
string
Original transaction ID
status
string
Customs declaration status: success, failure, pending.
pay_transaction_id
string
A unique number assigned by payment provider
ver_dept
int
The organization that verifies the transaction can be: 0-UnionPay,1-NetsUnion,2-Other
pay_code
string
The customs registration number of payment provider.
cert_check
string
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
id
string
Transaction ID.
status
string
Transaction status. Either success, failure, or pending.
type
string
Transaction type. Either charge, authorization, or capture.
vendor
string
Payment method. Include: unionpay, alipay, wechatpay or alipayhk.
vendor_id
string
Vendor’s transaction id, usually showed on customer’s payment receipt.
amount
int
Amount of the transaction in the minor unit of the currency. For example, cents in USD.
currency
string
The 3-letter currency code.
time
string
Timestamp of the transaction in UTC. Ex: 2015-01-01T01:01:00Z is Jan 1, 2015 1:01:00 UTC.
reference
string
AlphaNumeric string set in request to correspond transaction ID with your original transaction request.
note
string/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
id
string
Transaction ID.
status
string
Transaction status. Either success, failure, or pending.
type
string
Transaction type. Either charge, authorization, or capture.
vendor
string
Payment method. Include: unionpay, alipay, wechatpay or alipayhk.
vendor_id
string
Vendor’s transaction id, usually showed on customer’s payment receipt.
amount
int
Amount of the transaction in the minor unit of the currency. For example, cents in USD.
currency
string
The 3-letter currency code.
time
string
Timestamp of the transaction in UTC. Ex: 2015-01-01T01:01:00Z is Jan 1, 2015 1:01:00 UTC.
reference
string
AlphaNumeric string set in request to correspond transaction ID with your original transaction request.
note
string/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
currency
Required
The 3-letter currency code. Currency must match the original transaction's currency.
amount
Conditional
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_amount
Conditional
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.
reason
Optional
Arbitrary string detailing the reason for refund.

Response

{
    "id": "bn2345nb53454kjb",
    "status": "success",
    "refunded": true,
    "transaction_id": "jkh25jh1348fd89sg"   
}

Response

Returns a refund object.

Property Description
id
string
Refund ID.
status
string
Status of the refund. Either success, or failure.
refunded
bool
true
transaction_id
string
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
id
string
Transaction ID.
status
string
Transaction status. Either success, failure, pending or closed
type
string
Transaction type. Either charge, authorization, or capture.
amount
int
Amount of the transaction in the minor unit of the currency. For example, cents in USD.
currency
string
Transaction currency.
time
string
Timestamp of the transaction in UTC.
reference
string
Merchant order number.
note
string
If set in request, your transaction note to self. Else if not set, this will be null.
vendor
string
Payment method. Include: unionpay, alipay, wechatpay or alipayhk.
vendor_id
string
Vendor’s transaction id, usually showed on customer’s payment receipt.
refunded_amount
int
Total refunded amount
refunds
list
Refund records
refund_time
string
Refund time
refund_id
string
Refund ID.
refunded_amount
int
refund amount
status
string
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
limit
Optional
Default: 10
Number of transactions returned for each request. Limit can range between 1 and 100.
starting_after
Optional
Time in UTC format yyyy-mm-ddThh:mm:ssZ. Used to retrieve transactions processed after the specified time.
ending_before
Optional
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
id
string
Transaction ID.
status
string
Transaction status. Either success, failure, or pending.
type
string
Transaction type. Either charge, authorization, or capture.
amount
int
Amount of the transaction in the minor unit of the currency. For example, cents in USD.
currency
string
The 3-letter currency code.
time
string
Timestamp of the transaction in UTC. Ex: 2015-01-01T01:01:00Z is Jan 1, 2015 1:01:00 UTC.
reference
string
AlphaNumeric string set in request to correspond transaction ID with your original transaction request.
note
string/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&currency=USD \
-H "Authorization: Bearer <TOKEN>"

Request

Properties as URL GET parameters.

Property Description
rate_date
Required
Rate date, formatted as YYYYMMDD
currency
Required
Foreign currency,acceptable are USD, JPY, HKD, GBP,EUR
vendor
Optional
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_date
string
Rate date, formatted as YYYYMMDD
currency
string
Foreign currency
vendor
string
alipay, wechatpay or unionpay
rate
string
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_date
Required
The start date, formatted as YYYYMMDD
end_date
Required
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_date
Required
The start date, formatted as YYYYMMDD
end_date
Required
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
currency
string
Account currency
balance
string
Currently account balance
pending_amount
string
Currently unsettled purchase amount
freeze_amount
string
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_date
Required
Start date, formatted as YYYYMMDD.
end_date
Required
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
id
string
NihaoPay withdrawal ID
status
string
Withdrawal status. Included processing and completed.
amount
int
Withdrawal amount
currency
string
Withdrawal currency
fee
string
Withdrawal fee
fee_currency
string
Withdrawal fee currency type.
date
string
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
code
int
HTTP status code.
label
string
Label of the error generated by NihaoPay. Support team may ask for this to help with integration questions.
message
string
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

2023-08-05

2022-07-18

2020-09-01

2018-06-01

2018-05-17

2018-03-15

2017-11-10

2017-08-21

2017-05-25

2017-04-10

2017-03-07

2017-01-01