API 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 (further information available in Create a SecurePay transaction section). All API request must be made over HTTPS.
To manage transactions through a web client, please use our Transaction Management System (TMS).
If you have any questions regarding our API or the integration process, please contact our support team: support@nihaopay.com.
Version
API Version
/v1.1
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.1 (v1.1
).
To specify a version, simply add /v1.1
namespace to the base endpoint before the resource namespace.
For example, to use Version 1.1, the full endpoint for the transactions resource would be:
https://api.nihaopay.com/v1.1/transactions
Authentication
Sample Request
$ curl https://api.nihaopay.com/v1.1/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 -> View API Token.
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.
Testing
Testing Endpoint
http://api.test.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:
http://api.test.nihaopay.com/v1.1/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 Cards for you to use to simulate transactions.
To start testing, apply for a test account here
Test Cards and Accounts
When using the Testing environment, bank issued cards and Alipay accounts will not work. We have provided Test Cards and Test Alipay Accounts below for you to use to simulate transactions.
UnionPay Credit Card
Card Number | 6221558812340000 |
CVV | 123 |
EXP | 11/2017 |
Phone # | 1-355-253-5506 |
Verification Code | 111111 |
UnionPay Debit Card
Card Number | 6216261000000000018 |
PIN | 123456 |
Phone # | 1-355-253-5506 |
Verification Code | 111111 |
Alipay Account 1
Account | alipaytest20091@gmail.com |
Captcha Code | 8888 |
Login Password | 111111 |
Payment Password on Cashier Page | 111111 |
Alipay Account 2
Account | sandbox_forex1@gmail.com |
Captcha Code | 8888 |
Login Password | 111111 |
Payment Password on Cashier Page | 111111 |
Alipay Mobile Account
Account | 13122443313 |
ID | 2088102130934287 |
Login Password | 111111 |
Payment Password on Cashier Page | 111111 |
Transactions
Create a SecurePay transaction
Definition
POST
https://api.nihaopay.com/v1.1/transactions/securepay
Request
$ curl https://api.nihaopay.com/v1.1/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"
Response
The API will respond with 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.
POST
id = bn2345nb53454kjb
status = success
amount = 1111
currency = USD
time = 2015-01-01T01:01:00Z
reference = jkh25jh1348fd89sg
note = null
Upon completing the transaction, the API will return asynchronous information to the IPN url and the callback URL. The format will be the same, as key value pairs in a POST format.
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.
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.
Request
Property | Description |
---|---|
amountRequired |
Amount as an integer of the smallest unit in the currency. For example, $10.50 in USD would be 1050. |
currencyRequired |
The currency in 3 character ISO code. Currently, acceptable currency codes are USD and JPY . |
vendorRequired |
Transaction vendor. Currently, acceptable vendors are unionpay , alipay , and wechatpay . |
referenceRequired |
An alphanumeric string up to 30 characters that must be unique to each of your transactions. This allows you to keep track of transactions when data comes back through IPN and Callback URLs. |
ipn_urlRequired |
Instant Payment Notification URL. Called by the API to update you on transaction information. This is where the response goes to. |
callback_urlRequired |
URL the browser will be redirected to upon completing the transaction. |
descriptionOptional Default: null |
Arbitrary string that you can set to be displayed on the card charge. |
noteOptional Default: null |
Arbitrary string as note to self regarding the transaction. |
terminalOptional 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 (api.test.nihaopay.com). |
timeoutOptional Default: 90 |
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 . |
Response
Returns a transaction object as POST fields.
Property | Description |
---|---|
idstring |
Transaction ID. |
statusstring |
Transaction status. Either success , failure , or pending . |
amountint |
Amount of the transaction in the smallest unit of the currency. For example, cents in USD. |
currencystring |
Currency in three letter ISO code. |
timestring |
Timestamp of the transaction in UTC. Ex: 2015-01-01T01:01:00Z is Jan 1, 2015 1:01:00 UTC. |
referencestring |
AlphaNumeric string set in request to correspond transaction ID with your original transaction request. |
notestring |
If set in request, your transaction note to self. Else if not set, this will be null . |
Create an ExpressPay transaction
Definition
POST
https://api.nihaopay.com/v1.1/transactions/expresspay
Request
$ curl https://api.nihaopay.com/v1.1/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"
Response
{
"id": "bn2345nb53454kjb",
"status": "success",
"amount": 110,
"currency": "USD",
"captured": true,
"time": "2015-01-11T01:01:00Z",
"reference": "jkh25jh1348fd89sg",
"note": null
}
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 |
---|---|
amountRequired |
Amount as an integer of the smallest unit in the currency. For example, $10.50 in USD would be 1050. |
currencyRequired |
The currency in 3 character ISO code. Currently, acceptable currency codes are USD and JPY . |
card_numberRequired |
Credit card number. Numeric and up to 16 characters only. |
card_exp_monthRequired |
Card expiration month with leading zero. Acceptable values are 01 through 12 . |
card_exp_yearRequired |
Card expiration year in 4 digits. |
card_cvvRequired |
Card verification value in 3 digits. |
captureOptional Default: true |
Boolean. true will charge the full amount. false will create an authorization in the amount of the transaction to be captured or released at a later time. |
descriptionOptional Default: null |
Arbitrary string that you can set to be displayed on the card charge. |
noteOptional Default: null |
Arbitrary string as note to self regarding the transaction. |
referenceOptional |
An alphaNumeric string up to 30 characters that must be unique to each of your transactions. This allows you to keep track of transactions. If you do not provide this field, a reference will be generated and given to you. |
Response
Returns a transaction object.
Property | Description |
---|---|
idstring |
Transaction ID. |
statusstring |
Transaction status. Either success , failure , or pending . |
amountint |
Amount of the transaction in the smallest unit of the currency. For example, cents in USD. |
currencystring |
Currency in three letter ISO code. |
capturedbool |
Whether or not the transaction amount has been captured. true for captured and false for uncaptured or authorization. |
timestring |
Timestamp of the transaction in UTC. Ex: 2015-01-01T01:01:00Z is Jan 1, 2015 1:01:00 UTC |
referencestring |
A reference number to track each transactions. If you did not provide this, a reference will be generated and returned to you. |
notestring |
If set in request, your transaction note to self. Else if not set, this will be null. |
Capture a transaction
POST
https://api.nihaopay.com/v1.1/transactions/{transaction_id}/capture
Request
$ curl https://api.nihaopay.com/v1.1/transactions/{transaction_id}/capture \
-H "Authorization: Bearer <TOKEN>" \
-d amount=100 \
-d currency="USD"
Response
{
"id": "bn2345nb53454kjb",
"status": "success",
"captured": true,
"transaction_id": "bn2345nb53454kjb"
}
Capture the full or partial amount on an existing and uncaptured authorization. The amount cannot be higher than the original authorized amount.
Authorizations 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 |
---|---|
amountRequired |
Amount as an integer of the smallest unit in the currency. For example, $10.50 in USD would be 1050. |
currencyRequired |
The currency in 3 character ISO code. Currently, acceptable currency codes are USD and JPY . Currency must match the uncaptured transaction’s currency. |
Response
Returns a partial transaction object.
Property | Description |
---|---|
idstring |
Transaction ID. |
statusstring |
Transaction status. Either success , failure , or pending . |
capturedbool |
Whether or not the transaction amount has been successfully captured. |
transaction_idstring |
ID of the transaction that was captured. |
Release a transaction
POST
https://api.nihaopay.com/v1.1/transactions/{transaction_id}/release
Request
$ curl https://api.nihaopay.com/v1.1/transactions/{transaction_id}/release \
-H "Authorization: Bearer <TOKEN>"
Response
{
"id": "bn2345nb53454kjb",
"status": "success",
"released": true,
"transaction_id": "bn2345nb53454kjb"
}
Release an uncaptured transaction. Authorizations not captured within 30 days are automatically released.
Request
transaction_id
as URL parameter.
Response
Returns a partial transaction object.
Property | Description |
---|---|
idstring |
Transaction ID. |
statusstring |
Transaction status. Either success , failure , or pending . |
releasedbool |
Whether or not the transaction amount has been successfully released. |
transaction_idstring |
ID of the transaction that was released. |
Cancel a transaction
Definition
POST
https://api.nihaopay.com/v1.1/transactions/{transaction_id}/cancel
Request
$ curl https://api.nihaopay.com/v1.1/transactions/{transaction_id}/cancel \
-H "Authorization: Bearer <TOKEN>"
Response
{
"id": "bn2345nb53454kjb",
"status": "success",
"cancelled": true,
"transaction_id": "bn2345nb53454kjb"
}
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
Returns a partial transaction object.
Property | Description |
---|---|
idstring |
Transaction ID. |
statusstring |
Transaction status. Either success , failure , or pending . |
cancelledbool |
Whether or not the transaction amount has been successfully cancelled. |
transaction_idstring |
ID of the transaction that was cancelled. |
Look up a transaction
Definition
GET
https://api.nihaopay.com/v1.1/transactions/{transaction_id}
Request
$ curl https://api.nihaopay.com/v1.1/transactions/{transaction_id} \
-H "Authorization: Bearer <TOKEN>"
Response
{
"id": "bn2345nb53454kjb",
"status": "success",
"type": "charge",
"amount": 1111,
"currency": "USD",
"time": "2015-01-01T01:01:01Z",
"reference": "jkh25jh1348fd89sg",
"note": "sample note"
}
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 (UnionPay and AliPay), 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
Returns a transaction object.
Property | Description |
---|---|
idstring |
Transaction ID. |
statusstring |
Transaction status. Either success , failure , or pending . |
typestring |
Transaction type. Either charge , authorization , or capture . |
amountint |
Amount of the transaction in the smallest unit of the currency. For example, cents in USD. |
currencystring |
Currency in three letter ISO code. |
timestring |
Timestamp of the transaction in UTC. Ex: 2015-01-01T01:01:00Z is Jan 1, 2015 1:01:00 UTC. |
referencestring |
AlphaNumeric string set in request to correspond transaction ID with your original transaction request. |
notestring/null |
If set in request, your transaction note to self. Else if not set, this will be null. |
List transactions
Definition
GET
https://api.nihaopay.com/v1.1/transactions/
Request
$ curl https://api.nihaopay.com/v1.1/transactions/?starting_after=2015-01-01T01:01:00Z \
-H "Authorization: Bearer <TOKEN>"
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"
}
]
}
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 |
---|---|
limitOptional Default: 10 |
Number of transactions returned for each request. Limit can range between 1 and 100. |
starting_afterOptional |
Time in UTC format yyyy-mm-ddThh:mm:ssZ. Used to retrieve transactions processed after the specified time. |
ending_beforeOptional |
Time in UTC format yyyy-mm-ddThh:mm:ssZ. Used to retrieve transactions processed before the specified time. |
Response
Returns a transactions array of transaction objects. If no transactions are available, returns an empty array.
Property | Description |
---|---|
idstring |
Transaction ID. |
statusstring |
Transaction status. Either success , failure , or pending . |
typestring |
Transaction type. Either charge , authorization , or capture . |
amountint |
Amount of the transaction in the smallest unit of the currency. For example, cents in USD. |
currencystring |
Currency in three letter ISO code. |
timestring |
Timestamp of the transaction in UTC. Ex: 2015-01-01T01:01:00Z is Jan 1, 2015 1:01:00 UTC. |
referencestring |
AlphaNumeric string set in request to correspond transaction ID with your original transaction request. |
notestring/null |
If set in request, your transaction note to self. Else if not set, this will be null. |
Refunds
Create a Refund
Definition
POST
https://api.nihaopay.com/v1.1/transactions/{transaction_id}/refund
Request
$ curl https://api.nihaopay.com/v1.1/transactions/{transaction_id}/refund \
-H "Authorization: Bearer <TOKEN>" \
-d amount=100 \
-d currency="USD"
Response
{
"id": "bn2345nb53454kjb",
"status": "success",
"refunded": true,
"transaction_id": "jkh25jh1348fd89sg"
}
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 |
---|---|
amountRequired |
Amount to be funded in the smallest unit of the currency. Must be equal to or less than the amount of the original transaction. |
currencyRequired |
The currency in 3 character ISO code. Currently, acceptable currency codes are USD and JPY . Currency must match the original transaction’s currency. |
reasonOptional |
Arbitrary string detailing the reason for refund. |
Response
Returns a refund object.
Property | Description |
---|---|
idstring |
Refund ID. |
statusstring |
Status of the refund. Either success , failure , or pending . |
refundedbool |
Whether or not the transaction amount has been successfully refunded. |
transaction_idstring |
ID of the transaction that was refunded. |
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 |
---|---|
codeint |
HTTP status code. |
labelstring |
Label of the error generated by NihaoPay. Support team may ask for this to help with integration questions. |
messagestring |
A human readable message as to the cause of the encountered error. |