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, ExpressPay, 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.

ExpressPay

In Expresspay, we require merchants’ websites to have PCI certification. Merchants will collect users’ credit card information and send request to API to finish the order.

In-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.

How to use

AliPay WechatPay UnionPay
PC Browser
terminal=ONLINE
Standard SecurePay Standard SecurePay
Generate QRcode
SecurePay
ExpressPay
Mobile Browser
terminal=WAP
Standard SecurePay NA SecurePay
ExpressPay
Wechat Browser
terminal=WAP
NA Standard SecurePay
currency=USD
currency=EUR
currency=JPY
SecurePay
ExpressPay
In-APP In-APP Payment In-APP Payment
Please contact us for help
In-APP Payment
WeChat Mini-Program NA Mini-Program Payment
Please contact us for help
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
NA

Parameter Description

1.Amount

Amount as a positive integer of the smallest unit of the currency. For Example, $10.50 in USD would be 1050, ¥100 in JPY would be 100.

2.Currency

Currently, NihaoPay accepts currency codes:

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.

IPN 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

6. IPN URL & 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.

When executing the callback and IPN notification, please note:

7.Terminal

Currently, acceptable values are ONLINE and WAP. Please note WAP for WeChat Pay is only available in the live environment (api.nihaopay.com) and does not work in testing (apitest.nihaopay.com).

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 Valye
vendor_id Vendor’s transaction id, usually showed on customer’s payment receipt.

Sign method

verify_sign = MD5(key1=value1&key2=value2&...&keyn=valuen&MD5(TOKEN))

9. 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"

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 currency in 3 character ISO code. Currently, acceptable currency codes are USD, JPY, HKD, GBP, EUR, and CAD.
amount
Conditional
Amount as a positive integer of the smallest 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 smallest 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, 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. 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 Parameters Description.
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). Currently, acceptable values are ONLINE and WAP. Please note WAP for WeChat Pay is only available in the live environment (api.nihaopay.com) - it does not work in testing (apitest.nihaopay.com).
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.

Synchronous 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.

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
Currency in three letter ISO 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 Wechat 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 currency="USD" \
-d reference="jkh25jh1348fd89sg" \
-d ipn_url="http://website.com/ipn"

Merchant’s backend system requests Wechat 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, 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
amount
Required
Amount as an integer of the smallest unit of the currency. See Parameters Description.
currency
Required
The currency in 3 character ISO code. Currently, acceptable currency codes are USD, JPY, HKD and EUR.
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 Parameters Description.
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 smallest unit of the currency. For example, cents in USD.
currency
string
Currency in three letter ISO 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 currency in 3 character ISO code. Currently, acceptable currency codes are USD, JPY, HKD, GBP, EUR and CAD.
amount
Required
Amount as a positive integer of the smallest unit of the currency. If amount is not null, it means the transaction uses foreign currency. 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.
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 Parameters Description.
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

{
    "orderInfo": "order info string...."
}

Response

Property Description
orderInfo
string
Used to call the vendor SDK. For more information, see NihaoPay IOS demo or Andriod demo. If you need WeChatPay In-app, please contact us for help.

WeChat Mini-Program Payment

POST
https://api.nihaopay.com/v1.2/transactions/micropay

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
amount
Required
Amount as a positive integer of the smallest unit of the currency. If amount is not null, it means the transaction uses foreign currency. See Parameters Description.
currency
Required
The currency in 3 character ISO code. Currently, acceptable currencies are USD, JPY and EUR.
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 Parameters Description.
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.

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

ExpressPay

Charge a Credit Card

Definition

POST
https://api.nihaopay.com/v1.2/transactions/expresspay

Request

$ curl https://api.nihaopay.com/v1.2/transactions/expresspay \
-H "Authorization: Bearer <TOKEN>" \
-d amount=100 \
-d currency="USD" \
-d card_number="6221558812340000" \
-d card_exp_month=11 \
-d card_exp_year=2017 \
-d card_cvv="123" \
-d client_ip="180.167.25.154"

To charge a credit card directly on your website without redirecting users to the vendor, you should submit an ExpressPay request. Please note only credit cards are accepted via ExpressPay.

For every successful payment, a Transaction Object will be created and returned in JSON format with an assigned transaction ID. This transaction ID can be used to retrieve details, request cancellations and create refunds.

Request

Property Description
currency
Required
The currency in 3 character ISO code. Currently, acceptable currency codes are USD, JPY, HKD, GBP, EUR and CAD.
amount
Required
Amount as a positive integer of the smallest unit of the currency. See Parameters Description.
card_number
Required
Credit card number. Numeric and up to 16 characters only.
card_exp_month
Required
Card expiration month with leading zero. Acceptable values are 01 through 12.
card_exp_year
Required
Card expiration year in 4 digits.
card_cvv
Required
Card verification value in 3 digits.
client_ip
Required
Customer IP
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.
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. If you do not provide this field, a reference will be generated and given to you.

Response

{
    "id": "bn2345nb53454kjb",
    "status": "success",
    "amount": 110,
    "currency": "USD",
    "captured": true,
    "time": "2015-01-11T01:01:00Z",
    "reference": "jkh25jh1348fd89sg",
    "note": null
}

Response

Returns a transaction object.

Property Description
id
string
Transaction ID.
status
string
Transaction status. Either success, failure, or pending.
amount
int
Amount of the transaction in the smallest unit of the currency. For example, cents in USD.
currency
string
Currency in three letter ISO code.
captured
bool
Whether or not the transaction amount has been captured. true for captured and false for uncaptured or authorization.
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.

Authorize a Credit Card

Definition

POST
https://api.nihaopay.com/v1.2/transactions/expresspay

Request

$ curl https://api.nihaopay.com/v1.2/transactions/expresspay \
-H "Authorization: Bearer <TOKEN>" \
-d amount=100 \
-d currency="USD" \
-d card_number="6221558812340000" \
-d card_exp_month=11 \
-d card_exp_year=2017 \
-d card_cvv="123" \
-d client_ip="180.167.25.154" \
-d capture="false"

Use this method to authorize a credit card payment. To actually charge the funds you will need to follow up with a capture transaction

Request

Property Description
amount
Required
Amount as a positive integer of the smallest unit of the currency. See Parameters Description.
currency
Required
The currency in 3 character ISO code. Currently, acceptable currency codes are USD, JPY, HKD, GBP, EUR and CAD.
card_number
Required
Credit card number. Numeric and up to 16 characters only.
card_exp_month
Required
Card expiration month with leading zero. Acceptable values are 01 through 12.
card_exp_year
Required
Card expiration year in 4 digits.
card_cvv
Required
Card verification value in 3 digits.
client_ip
Required
Customer IP
capture
Required
Boolean. false only.
description
Optional
Default: null
Arbitrary string that you can set to be displayed on the card charge.
note
Optional
Default: null
Arbitrary string as note to self regarding the transaction.
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. If you do not provide this field, a reference will be generated and given to you.

Response

{
    "id": "bn2345nb53454kjb",
    "status": "success",
    "amount": 110,
    "currency": "USD",
    "captured": false,
    "time": "2015-01-11T01:01:00Z",
    "reference": "jkh25jh1348fd89sg",
    "note": null
}

Response

Returns a transaction object.

Property Description
id
string
Transaction ID.
status
string
Transaction status. Either success, failure, or pending.
amount
int
Amount of the transaction in the smallest unit of the currency. For example, cents in USD.
currency
string
Currency in three letter ISO code.
captured
bool
false for authorization.
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.

Release a Previously Authorized

POST
https://api.nihaopay.com/v1.2/transactions/{transaction_id}/release

Request

$ curl https://api.nihaopay.com/v1.2/transactions/{transaction_id}/release \
-H "Authorization: Bearer <TOKEN>"

Release an authorization transaction. Authorizations not captured within 30 days will be automatically released.

Request

transaction_id as URL parameter.

Response

{
    "id": "bn2345nb53454kjb",
    "status": "success",
    "released": true,
    "transaction_id": "bn2345nb53454kjb"
}

Response

Returns a partial transaction object.

Property Description
id
string
Transaction ID.
status
string
Transaction status. Either success, failure, or pending.
released
bool
Whether or not the transaction amount has been successfully released.
transaction_id
string
ID of the transaction that was released.

Capture a Previously Authorized

POST
https://api.nihaopay.com/v1.2/transactions/{transaction_id}/capture

Request

$ curl https://api.nihaopay.com/v1.2/transactions/{transaction_id}/capture \
-H "Authorization: Bearer <TOKEN>" \
-d amount=100 \
-d currency="USD"

Use this method to capture funds for a transaction that was previously authorized. The amount cannot be higher than the original authorized amount.

Authorized not captured within 30 days are automatically released and cannot be re-captured. A new transaction will need to be created.

Request

transaction_id as URL parameter.

Property Description
amount
Required
Amount as an integer of the smallest unit of the currency.
For example, $10.50 in USD would be 1050.
currency
Required
The currency in 3 character ISO code. Currently, acceptable currency codes are USD, JPY, HKD, GBP,CAD and EUR. Currency must match the uncaptured transaction’s currency.

Response

{
    "id": "bn2345nb53454kjb",
    "status": "success",
    "captured": true,
    "transaction_id": "bn2345nb53454kjb"
}

Response

Returns a partial transaction object.

Property Description
id
string
Transaction ID.
status
string
Transaction status. Either success, failure, or pending.
captured
bool
Whether or not the transaction amount has been successfully captured.
transaction_id
string
ID of the transaction that was captured.

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 currency in 3 character ISO code. Currently, acceptable currency codes are USD, JPY, HKD, GBP, EUR and CAD.
amount
Required
Amount as a positive integer of the smallest 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 smallest unit of the currency. For example, cents in USD.
currency
string
Currency in three letter ISO 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 smallest unit of the currency. See Parameters Description.
currency
Required
The currency in 3 character ISO code. Currently, acceptable currency codes are USD, JPY, HKD, GBP and EUR.
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 wechatpay and alipay.
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 Parameters Description.
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 smallest unit of the currency. For example, cents in USD.
currency
string
Currency in three letter ISO 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 currency in 3 character ISO code. Currently, acceptable currency codes are USD, JPY, HKD, GBP, EUR and CAD.
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 Parameters Description.
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 smallest 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 currency in 3 character ISO code. Currently, acceptable currency codes are USD, JPY, HKD, GBP, EUR and CAD.
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 Parameters Description.
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 AliPay and WeChatPay. If you want to use this service for Wechat payments, 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 spilt=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 Conditional
The declaration amount in RMB “fen (cent)”, If the order is splitted, this field cannot be empty.
duty_amount
Int Conditional
Customs duty in RMB “fen (cent)”. Required by some customs
description
String(128) Optional
Customs declaration description
split
Optional
Default: false
Splitting order? true or false. Default: not splitting
sub_order_id
String(64) Conditional
Merchant’s sub order number. If the order is splitted, this field cannot be empty
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) Optional
Certification type. Only supports Chinese Mainland ID for now. Default: ID_CARD
cert_name
String(64) Optional
Name on certificate
cert_no
String(32) Optional
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"
}

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

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"
}

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
string
Same with request
duty_amount
string
Same with request
split
string
Splitting order
sub_order_id
string
Same with request
product_amount
string
Same with request
transport_amount
string
Same with request

Refund/Query/Others

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 currency in 3 character ISO code. Currency must match the original transaction’s currency.
amount
Conditional
Amount to be funded in the smallest 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 smallest 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, failure, or pending.
refunded
bool
Whether or not the transaction amount has been successfully refunded.
transaction_id
string
ID of the transaction that was refunded.

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.
amount
int
Amount of the transaction in the smallest unit of the currency. For example, cents in USD.
currency
string
Currency in three letter ISO 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, ExpressPay, and Captured 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.
amount
int
Amount of the transaction in the smallest unit of the currency. For example, cents in USD.
currency
string
Currency in three letter ISO 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.

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, ExpressPay, and Captured 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 smallest unit of the currency. For example, cents in USD.
currency
string
Currency in three letter ISO 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.

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

Apply withdrawal

POST
https://api.nihaopay.com/v1.2/withdrawal

Request

$ curl https://api.nihaopay.com/v1.2/withdrawal \
-H "Authorization: Bearer <TOKEN>"  \
-d currency="USD" \
-d full_withdrawal="true"

Request

Property Description
currency
Required
Withdrawal currency.
full_withdrawal
Required
Boolean. Is full withdrawal. true full withdrawal,false partial withdrawal.
amount
Optional
Withdrawal amount,when full_withdrawal = false, must set withdrawal amount.

Response

{
  "id": "20170818112016001805",
  "amount": "1000",
  "status": "success",
  "withdrawal_fee": "0",
  "currency": "USD"
}

Response

Property Description
id
string
Withdrawal ID.
status
string
Withdrawal result. Include: success
amount
int
Withdrawal amount
currency
string
Withdrawal currency
withdrawal_fee
int
withdrawal fee.

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

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

Testing API is available only with standard HTTP requests. HTTPS requests will not work.

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

UnionPay 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 6226 3880 0000 0095
CVV 248
EXP 12/2019
Phone # 18100000000
Verification Code 111111

UnionPay Credit Card 2

Card Number 5200 8311 1111 1113
CVV 123
EXP 11/2019
Phone # 13552535506
Verification Code 111111

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 douyufua@alitest.com
Captcha Code 8888
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
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

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