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.

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.

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

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:

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.

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:

Instant Payment Notification

Synchronous Response

After payment completed, NihaoPay will return a transaction object to ipn_url using the POST method. Whenever possible, transaction data should be recorded from the IPN URL instead of the callback URL.

When executing the IPN notification, please note:

• ipn_url must be accessible on the Internet and can't be intranet address (for example localhost) or intranet IP
• The IPN notification may arrive ahead of browser callback.
• The duplicated IPN notifications.
• NihaoPay returns to ipn_url using the POST method.
• After the program is executed, the IPN page must print “ok” (without quote). If not, NihaoPay server will keep re-sending notification.
• Generally, there will be 8 notifications within 2 hours (Frequency: 0m,1m,2m,4m,8m,20m,30m).
• After the program is executed, there should not be any redirecting operation on the page, for NihaoPay will not recognize an “ok” string; therefore, it would be regarded as an error, and NihaoPay system will just keep sending the notification.

Asynchronous Response

id = 20170519103602011338
amount = 2
currency = USD
rmb_amount = 12
reference = 20170519103456437807
sys_reserve = {"vendor_id":"4200000117201806013734875340"}
status = success
time = 2017-05-19T10:36:32Z
note = null
verify_sign = 46072c81e3c6140d6bc92655196b247f

Asynchronous Response message

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:

• The indication method for a single pair is key = value. If the value corresponding to the key is null, not include the key.
• The connection method for multiple pairs is key1=value1&key2=&key3=value3. Sort pairs in the signature in an ascending order in accordance with key values.
• The connection method of cooperative key messages is key1=value1&key2=&key3=value3&MD5(Token), The token, after MD5 calculation, is connected to the end of the pair.

B. Signature method

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

Note:

• NihaoPay uses UTF-8 as charset.
• Parameters without a value can be excluded from sign;
• The MD5's output is lowercase when comparing signatures, please ignore case.

SecurePay

Create a Standard SecurePay

Definition

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

Request

$ curl https://api.nihaopay.com/v1.2/transactions/securepay \
-H "Authorization: Bearer <TOKEN>" \
-d rmb_amount=100 \
-d currency="USD" \
-d vendor="alipay" \
-d reference="20171023191505118594" \
-d ipn_url="https://demo.nihaopay.com/ipn" \
-d callback_url="https://demo.nihaopay.com/callback"

$ curl https://api.nihaopay.com/v1.2/transactions/securepay \
-H "Authorization: Bearer <TOKEN>" \
-d rmb_amount=100 \
-d currency="USD" \
-d vendor="wechatpay" \
-d reference="20171023191505118594" \
-d ipn_url="https://demo.nihaopay.com/ipn" \
-d inWechat="false" \
-d callback_url="https://demo.nihaopay.com/callback"

json response example 1 json { "url": "https://openapi.alipay.com/gateway.do?app_id=2019031263534265" }

json response example 2 json { "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

JSON

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.

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

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.

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

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.

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"

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

WeChat Mini-Program Payment

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

Please send the WeChat Mini-program APPID to our support team before development.

Merchant can ask prePay request at the mini-program, and use the function wx.requestpayment() to call WeChatPay if the variable of request is generated successfully. NihaoPay will send IPN announcement to the IPN_url of merchant as long as the order has been placed successfully. Following figures illustrates the development process.

Request

$ curl https://api.nihaopay.com/v1.2/transactions/micropay \
-H "Authorization: Bearer <TOKEN>" \
-d amount=100 \
-d currency="USD" \
-d reference="wechatpay20171109000300" \
-d ipn_url="http://website.com/ipn" \
-d open_id="oSC6Tw7--mfjTCpIr-72rWloA8TU" \
-d client_ip="180.167.25.154"

Request

Success response

{
    "timeStamp": "1510341967363",
    "nonceStr": "a611bda03d544b9f941393c48c2e517f",
    "wechatPackage": "prepay_id=wx201711110326070ccf2a7f060678638664",
    "signType": "MD5",
    "paySign": "09E5BE5B9D93080E3B7DD05C8F41049E"
}

Response

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" \
-d note="some tips" \
-d capture="true"

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

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.

Authorize a Credit Card

Definition

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

Request

$ curl https://api.nihaopay.com/v1.2/transactions/auth \
-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. Now support UnionPay,Amex,Visa,Master,JCB,Discover,Diners. To actually charge the funds you will need to follow up with a capture transaction

Note: Calling this interface requires merchants to have PCI qualifications.

Request

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.

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.

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.

Response

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

Response

Returns a partial transaction object.

In-Store Payment

Scan QRcode

Face-to-face merchant may scan the QRcode or Barcode on customer's phone to get paid for an order instead of having the customer to pay by cash or card. Merchant can use scanning guns, mobile devices with app or mPOS terminals with camera for scanning.

The figure illustrates the work flow of the Scan QRcode payment solution.

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

Request

$ curl https://api.nihaopay.com/v1.2/transactions/scanqrcode \
-H "Authorization: Bearer <TOKEN>" \
-d amount=100 \
-d currency="USD" \
-d vendor="alipay" \
-d reference="alipay201705030002" \
-d buyer_identity_code="288463639882104202" \
-d client_ip="184.167.25.158" \
-d note="alipay" \
-d description="Scan AliPay QrCode"

Request

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.

Show QRcode

Merchant's backend system request show QRcode API in order to generate an advance transaction and gets code_url. Merchant's backend creates a QR Code based on code_url and show on wetsite or other devices. The customer scans the QR Code, enters their payment password and completes the transaction.

Upon completing the transaction, the API will return asynchronous message to the IPN url. Merchant can request Look up a transaction if no message is received.

The figure illustrates the work flow of the Show QRcode payment solution.

The asynchronous message return to IPN URL is same with SecurePay.

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

Request

$ curl https://api.nihaopay.com/v1.2/transactions/showqrcode \
-H "Authorization: Bearer <TOKEN>" \
-d amount=100 \
-d currency="USD" \
-d vendor="alipay" \
-d reference="jkh25jh1348fd89sg" \
-d ipn_url="http://website.com/ipn"

Request

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.

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

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

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

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.

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

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

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

Request parameter desciption

You can declare through the following customs:

• ZONGSHU：General Administration of Customs
• BEIJING：Beijing Customs
• HANGZHOU：Hangzhou Customs
• NINGBO：Ningbo Customs
• GUANGZHOU：Guangzhou Customs
• GUANGZHOU_HUANGPU：Guangzhou Huangpu Customs
• SHENZHEN：Shenzhen Customs
• NANSHA：Nansha Guo Jian
• ZHENGZHOU：Zhenzhou Customs(Henan bonded logistics center)
• XINZHENG：Xinzheng comprehensive free trade zone (Airport)
• CHONGQING：Chongqing Customs
• SHANGHAI：Shanghai Customs
• XIAN：Xi'an Customs
• TIANJING：Tianjin Customs
• XIAMEN: Xiamen Customs

Response

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

Response

Customs code

UnionPay's customs registration info：

• Customs Name：中国银联股份有限公司
• Customs code：312228034U

WeChatPay's customs registration info：

• Customs Name：财付通支付科技有限公司
• Customs Code：4403169D3W

AliPay's customs registration info：

• Customs Name：支付宝(中国)网络技术有限公司

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

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

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

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

Error code for Customs Declaration

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.

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.

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.

Response

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

Response

Returns a refund object.

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

Visa Credit Card (For Test Approval)

Visa Credit Card (For Test Wrong expiration)

Mastercard Credit Card (For Test Approval)

Mastercard Credit Card (For Test Wrong expiration)

UnionPay Debit Card

Alipay Test Accounts

We provide Alipay Test Accounts below for you to use to simulate transactions.

AliPay Test Account

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

Error List

API Change Log

2023-08-23

• SecurePay supports returning data in json format

2023-08-05

• Add Profit Sharing Interface ProfitSharing

2022-07-18

• Add interface Alipay A+

2020-09-01

• Update currencies list
• Support UnionPay customs declaration

2018-06-01

• Add customs declaration
• Add vendor's transaction in IPN

2018-05-17

• In-App payment support WeChatPay.
• Scan QRcode support UnionPay QRcode, U.S. merchants only.

2018-03-15

• Add interface Static Omni-Channel QRcode
• Add interface Static AliPay QRcode

2017-11-10

• Add interface WeChat Mini-program payment

2017-08-21

• Add interface Download transactions
• Add interface Static QRcode
• Add interface Inquiry account balance
• Add interface Apply withdrawal
• Add interface Inquiry withdrawal history

2017-05-25

• Add In-Store Payment API
• Add In-App Payment API
• Add verify signature in IPN notification
• Change IPN notification frequency

2017-04-10

• Update Error list
• Add parameter rmb_amount in SecurePay and ExpressPay request field list.

2017-03-07

• Add Chinese document
• Add parameter client_ip in ExpressPay request field list
• Add interface Query Exchange Rate
• Add interface Download Billing

2017-01-01

• Upgrade to v1.2