Introduction

API Endpoint

https://api.muskpay.io

Thanks for choosing MuskPay! 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. 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.muskpay.io/v1.2/transactions

Authentication

Sample Request

$ curl https://api.muskpay.io/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

MuskPay supports five payment models: CardPay, SecurePay, In-APP payment, Show QRcode and Scan QRcode.

CardPay

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

The following four payment products can be found in NihaoPay API Documentation

SecurePay

In Securepay, users will be redirected to the payment tunnel and finish rest of payment steps in the official payment page.

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.

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, MuskPay supported currencies:

3.Reference

An alphanumeric string up to 30 characters that must be unique to each of your transactions.

4.Vendor

Currently, MuskPay accepts vendors are:

• Visa
• Master
• JCB
• Amex
• Discover
• unionpay

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

System Reserve

sys_reserve = {"vendor_id":"4200000117201806013734875340"}

8. System Reserved

sys_reserve, MuskPay system reserved, used for return vendor's transaction id or customer's info. Currently, includes:

Instant Payment Notification

Asynchronous Response

After payment completed, MuskPay 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.
• MuskPay returns to ipn_url using the POST method.
• After the program is executed, the IPN page must print “ok” (without quote). If not, MuskPay 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 MuskPay will not recognize an “ok” string; therefore, it would be regarded as an error, and MuskPay system will just keep sending the notification.

Asynchronous Response

id = 20170519103602011338
amount = 2
currency = USD
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, MuskPay 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:

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

CardPay

Charge a Credit Card

Definition

POST
https://api.muskpay.io/v1.2/transactions/cardpay

Request

$ curl https://api.muskpay.io/v1.2/transactions/cardpay \
-d reference="order19852245687" \
-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 card_holder="Tim Smith" \
-d phone_number="123-123-1234" \
-d phone_country_code="1" \
-d email="customer@domain.com" \
-d website="http://mywebsite.com" \
-d client_ip="180.167.25.154" \
-d description="order desc" \
-d note="some tips" \
-d billing_address_first_name="Tim" \
-d billing_address_last_name="Smith" \
-d billing_address_line1="4699 Old Ironsides Dr, Suite 278" \
-d billing_address_city="Santa Clara" \
-d billing_address_state="CA" \
-d billing_address_zip="95054" \
-d billing_address_country="US" \
-d shipping_address_first_name="Tim" \
-d shipping_address_last_name="Smith" \
-d shipping_address_line1="4699 Old Ironsides Dr, Suite 278" \
-d shipping_address_city="Santa Clara" \
-d shipping_address_state="CA" \
-d shipping_address_zip="95054" \
-d shipping_address_country="US" 

To charge a credit card directly on your website without redirecting users to the vendor, you should submit an CardPay request.

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.

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

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.muskpay.io/v1.2/transactions/auth

Request

$ curl https://api.muskpay.io/v1.2/transactions/auth \
-H "Authorization: Bearer <TOKEN>" \
-d reference="order19852245687" \
-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 card_holder="Tim Smith" \
-d phone_number="123-123-1234" \
-d phone_country_code="1" \
-d email="customer@domain.com" \
-d website="http://mywebsite.com" \
-d client_ip="180.167.25.154" \
-d description="order desc" \
-d note="some tips" \
-d billing_address_first_name="Tim" \
-d billing_address_last_name="Smith" \
-d billing_address_line1="4699 Old Ironsides Dr, Suite 278" \
-d billing_address_city="Santa Clara" \
-d billing_address_state="CA" \
-d billing_address_zip="95054" \
-d billing_address_country="US" \
-d shipping_address_first_name="Tim" \
-d shipping_address_last_name="Smith" \
-d shipping_address_line1="4699 Old Ironsides Dr, Suite 278" \
-d shipping_address_city="Santa Clara" \
-d shipping_address_state="CA" \
-d shipping_address_zip="95054" \
-d shipping_address_country="US" 

Use this method to authorize a credit card payment. Now support Visa,Master,JCB,Amex,Discover,unionpay. 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.muskpay.io/v1.2/transactions/{transaction_id}/release

Request

$ curl https://api.muskpay.io/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.muskpay.io/v1.2/transactions/{transaction_id}/capture

Request

$ curl https://api.muskpay.io/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.

Gateway Hosted Payment

POST
https://api.muskpay.io/v1.2/cardpay/checkout

Request

$ curl https://api.muskpay.io/v1.2/transactions/cardpay \
-H "Authorization: Bearer <TOKEN>" \
-d reference="order19852245687" \
-d amount=100 \
-d currency="USD" \
-d website="http://mywebsite.com" \
-d ipn_url="http://website.com/ipn"
-d description="订单描述" \
-d client_ip="180.167.25.154" \
-d note="备注信息" 

Credit card gateway payment is an asynchronous payment method that requires page redirection. After the merchant requests the MuskPay API, it will receive the payment page URL synchronously. The merchant needs to jump to the page. On the payment page, the customer enters the payment information to complete the payment. Once the payment is successful, the page will jump to the callback URL provided by the merchant. MuskPay will return the callback URL with the return parameters, which need to be obtained using the GET method.

Due to the nature of redirection and the possibility that the user closes the browser before the redirection occurs, in order to ensure that the payment result is notified to the merchant, MuskPay uses server-to-server real-time notification (IPN url) to return the transaction result. The IPN result needs to be obtained using the POST method.

Request

Response

{
    "redirect_url": "https://apitest.nihaopay.com/v1.2/cardpay/checkout/20100920042332106649?otp=xxx"
}

Response

Returns a 'JSON' object.

Refund/Query/Others

Retrieve a transaction by reference

Definition

GET
https://api.muskpay.io/v1.2/transactions/merchant/{reference}

Request

$ curl https://api.muskpay.io/v1.2/transactions/merchant/{reference} \
-H "Authorization: Bearer <TOKEN>"

Provide reference that was requested for a transaction in order to retrieve corresponding transaction’s details.

Applicable to 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.muskpay.io/v1.2/transactions/{transaction_id}

Request

$ curl https://api.muskpay.io/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. 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.muskpay.io/v1.2/transactions/{transaction_id}/refund

Request

$ curl https://api.muskpay.io/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.muskpay.io/v1.2/transactions/refunds/{transaction_id}/

Request

$ curl https://api.muskpay.io/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.muskpay.io/v1.2/transactions/

Request

$ curl https://api.muskpay.io/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.

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.

Download transactions

GET
https://api.muskpay.io/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.muskpay.io/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.muskpay.io/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.muskpay.io/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.muskpay.io/v1.2/accounts

Request

$ curl https://api.muskpay.io/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.muskpay.io/v1.2/withdrawal/history

Request

$ curl https://api.muskpay.io/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.muskpay.io/v1.2/withdrawal/detail/{withdrawal_id}

According to the withdrawal_id to get the corresponding data

Request

$ curl https://api.muskpay.io/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.

Visa Credit Card 1

Visa Credit Card 2

Visa Credit Card 3

Errors

Error

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

When an API request fails, MuskPay will return an error object.

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

2024-09-18

• Add CardPay

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