cURL

Introduction

API Endpoint

https://api.nihaopay.com

Thanks for using NihaoPay! Our REST API uses common conventions and practices to make integration easy. Endpoint URLs follow resource-oriented naming conventions and are accessed using HTTP verbs such as GET and POST. The API expects arguments in two ways, URL parameters for GET, and POST fields for POST. The response will be returned as JSON, with the exception of our SecurePay product. All API request must be made over HTTPS.

To manage transactions through a web client, please use our Transaction Management System (TMS).

For your quickly intergration, we provide Sample Codes, SDKs, and Plugins on GitHub.

If you have any questions regarding our API or the integration process, please contact our support team: support@nihaopay.com.

中文文档

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 are including 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 the 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.

How to use

AliPay WechatPay UnionPay
PC Browser
terminal=ONLINE
Standard SecurePay Standard SecurePay
Generate QRcode
Standard SecurePay
ExpressPay
Mobile Browser
terminal=WAP
Standard SecurePay Standard SecurePay
Generate QRcode
Standard SecurePay
ExpressPay
Wechat Browser
terminal=WAP
NA Standard SecurePay
currency=USD
Standard SecurePay
ExpressPay
In-APP In-APP Payment
SDK on GitHub
NA In-APP Payment
SDK on GitHub
In-Store Show QRcode Show QRcode NA
In-Store
Have Scanner
Scan QRcode NA NA

Parameters Description

1.Amount

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

2.Currency

Currently, NihaoPay acceptable currency codes are:

3. RMB Amount

Use this parameter to replace amount if merchants wish to price their product in RMB. NihaoPay will return with the settlement amount when payment 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 acceptable vendors are unionpay, alipay, and wechatpay.

Asynchronous Response

id = bn2345nb53454kjb
status = success
amount = 1111
currency = USD
time = 2015-01-01T01:01:00Z
reference = jkh25jh1348fd89sg
note = null
verify_sign = 46072c81e3c6140d6bc92655196b247f

6. IPN URl & Callback URL

callback_url and ipn_url must be accessible on the Internet, can’t be intranet address (such as localhost) or intranet IP.

When execute 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 live environment (api.nihaopay.com) - it does not work in testing (apitest.nihaopay.com).

Sign method

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

8. Verify signature

When the asynchronous notification returns, NihaoPay will do the MD5 signature on the return message. After the merchant receives the asynchronous notification, it should 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 amount=100 \
-d currency="USD" \
-d vendor="unionpay" \
-d reference="jkh25jh1348fd89sg" \
-d ipn_url="http://website.com/ipn" \
-d callback_url="http://website.com/callback"

SecurePay transactions redirect users to the vendor’s payment page, where users can enter payment information. Upon successful completion, users are 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
Required
Amount as a positive integer of the smallest unit in the currency. See Parameters Desctiption.
rmb_amount
Required
Amount as a positive integer of the smallest unit in the currency. See Parameters Desctiption.
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 Desctiption.
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 Desctiption.
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 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 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 = bn2345nb53454kjb
status = success
amount = 1111
currency = USD
time = 2015-01-01T01:01:00Z
reference = jkh25jh1348fd89sg
note = null
verify_sign = 46072c81e3c6140d6bc92655196b247f

Asynchronous Response

After the successful completion of a securepay, API returns 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
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
If set in request, your transaction note to self. Else if not set, this will be null.
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 request 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 and show on wetsite or printed on the checkout bill. The cardholder opens “Scan QR Code” in WeChat, 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 asynchronous message return to IPN URL is same with SecurePay.

Request

Property Description
amount
Required
Amount as an integer of the smallest unit in the currency. See Parameters Desctiption.
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, only acceptable vendor is wechatpay.
ipn_url
Required
Instant Payment Notification URL. Called by the API to update you on transaction information. This is where the response goes to. See Parameters Desctiption.
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
Transaction ID.
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.

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
amount
Required
Amount as an integer of the smallest unit in the currency. See Parameters Desctiption.
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, only acceptable vendor is 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 Desctiption.
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

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 can submit an ExpressPay request. Please note, only credit cards are accepted via ExpressPay.

For every successful payment, a Transaction Object is 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 in the currency. See Parameters Desctiption.
rmb_amount
Required
Amount as a positive integer of the smallest unit in the currency. See Parameters Desctiption.
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 in the currency. See Parameters Desctiption.
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 are 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 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 in 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 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

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"

Face to face merchant may scan the QRcode or Barcode on customer’s phone to pay for an order instead of having to pay by cash or card. Merchant can use laser gun, a mobile device with app or mPOS terminal with camera for scanning.

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

Scan 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 in the currency. See Parameters Desctiption.
vendor
Required
Transaction vendor. Currently, acceptable vendors are 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 Desctiption.
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",
  "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.
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

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"

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 depicts the work flow of the Show QRcode payment solution.

Show QRcode

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

Request

Property Description
amount
Required
Amount as an integer of the smallest unit in the currency. See Parameters Desctiption.
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 Desctiption.
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
Transaction ID.
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

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.

Used for 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.

Cancel a transaction

Definition

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

Request

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

Transactions can only be canceled before the daily settlement deadline - 3:00PM UTC/GMT.

Each transaction can only be cancelled once. Transactions cannot be cancelled if a partial or full refund on the transaction has already been issued.

Request

transaction_id as URL parameter.

Response

{
    "id": "bn2345nb53454kjb",
    "status": "success",
    "cancelled": 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.
cancelled
bool
Whether or not the transaction amount has been successfully cancelled.
transaction_id
string
ID of the transaction that was cancelled.

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 the full amount of the transaction. Partial refunds can be created multiple times up to the amount of the Transaction.

You cannot refund more than the amount of the original transaction.

Request

transaction_id as URL Parameter.

Property Description
amount
Required
Amount to be funded in the smallest unit of the currency.
Must be equal to or less than the amount of the original transaction.
currency
Required
The currency in 3 character ISO code. Currently, acceptable currency codes are USD and JPY. Currency must match the original transaction’s currency.
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.

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 navigate to the 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 navigate to the 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.

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

Query Exchange Rate

GET
https://api.nihaopay.com/v1.2/exchangerate

To get the exchange rate, merchants can call this API.

Exchange rate updates 10:30am China Time, 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

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 monetary value is transacted 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.

When using the Testing environment, bank issued cards cannot be used. We have provided test credentials for you to use to simulate transactions.

To start testing, apply for a test account here

UnionPay Test Cards

When using the Testing environment, bank issued cards will not work. We have provided 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 1

Card Number 6216 2610 0000 0000 018
PIN 123456
Phone # 13552535506
Verification Code 111111

UnionPay Debit Card 2

Card Number 6226 0900 0000 0048
PIN 123456
Phone # 1810000000
Verification Code 111111

Alipay Test Accounts

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

Alipay Account 1

Account douyufua@alitest.com
Captcha Code 8888
Login Password 111111
Payment Password on Cashier Page 111111

Alipay Account 2

Account alipaytest20091@gmail.com
Captcha Code 8888
Login Password 111111
Payment Password on Cashier Page 111111

WechatPay Test Info

We do not provide Wechat Test accounts, you can use your real Wechat account to simulate transactions. If the payment is successful, please call Cancel or Refund to get youe money back.

Errors

Error

{
    "code": 409,
    "label": "64",
    "message": "Refund or capture currency does not match the original transaction currency."
}

When API requests fail, 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 support team at 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
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 97 Vendor error
500 99 System error
401 301 Invalid merchant credentials provided

API Change Log

2017-05-25

2017-04-10

2017-03-07

2017-01-01