NAV
cURL

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
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 and JPY.
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.
ipn_url
Required
Instant Payment Notification URL. Called by the API to update you on transaction information. This is where the response goes to.
callback_url
Required
URL the browser will be redirected to upon completing the transaction.
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.
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 (api.test.nihaopay.com).
timeout
Optional
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
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
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.

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
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 and JPY.
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.
capture
Optional
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.
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

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.

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
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 and JPY. Currency must match the uncaptured transaction’s currency.

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.

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

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

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

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.

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

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.

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.