文档简介

API Endpoint

https://api.muskpay.io

MuskPay API 采用通用的REST API风格设计，便于用户集成。端口地址遵循面向对象的命名约定，使用HTTP请求方式（POST，GET）访问。所有的API请求会以规范的json对象返回。所用请求需通过HTTPS方式进行。

所有交易的管理可以在商户交易管理后台(TMS)进行。

为了方便商户快速集成，我们提供了部分样例代码和SDK供参考，可以在GitHub上下载。

如果您在使用我们的API时遇到任何问题，请联系我们的技术支持团队tech_support@nihaopay.com。

English Docs

版本

API Version

/v1.2

我们的产品，服务和API也在不断改进，以更好的适应客户的需求。为帮助客户追踪API变更，我们的API使用版本区分，当前最新的版本是1.2 (v1.2)。要指定版本，只需要将版本号添加到资源命名空间之前。例如，要使用版本1.2，完整的请求路径应该是：https://api.muskpay.io/v1.2/transactions。

认证

请求示例

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

请将示例中的 <TOKEN> 替换成你自己的API Token。

所有的 API 请求必须通过 HTTPS 发送，并提供API Token作为身份验证。您可以在商户交易管理平台(TMS)的设置 -> 证书管理内下载或管理您的API Token.

名称	描述
Authorization 必须	设置`Bearer` 加API Token 作为认证方式

如果您的API Token已泄漏，请在商户管理后台重新生成。一旦您重新生成新的API Token，旧的API Token将立即作废，请及时修改您请求API使用的Token，保证所有接口正常使用。

接口说明

支付模式

信用卡支付

快捷支付是指商户在网站的付款页面收集客户的信用卡等信息，请求API直接完成支付的模式，该模式要求商户的网站需通过PCI认证。

接口规则

1.金额

接口中包含的金额精确到币种的最小单位，参数值中不能带小数点。如1.00美元，在接口请求是应该上送100.

2.币种

MuskPay支持的币种取值列表：

USD:美元

3.商户订单号

商户订单号由商户自己生成，MuskPay要求商户订单号保持唯一性，对于未支付的订单使用原订单号重新发起支付时，要避免重复支付，已支付成功的订单号不能再次发起支付。

4.付款方式

目前MuskPay支持的付款方式包括：

Visa
Master
JCB
Amex
Discover
unionpay

5. 通知URL

接口中callback_url必须是在Internet中可以访问的地址，不能是内网地址(如localhost)或内网IP。在处理callback和ipn的返回时，IPN通知可能比Callback返回先到达

sys_reserve = {"vendor_id":"4200000117201806013734875340"}

6. 系统保留域

sys_reserve 系统保留域，主要是用于返回一些特殊信息，比如付款在支付渠道的支付流水号，用户付款使用的付款银行等信息，当前包含的主要字段有：

key	valye
vendor_id	付款成功后在支付渠道的支付流水号，通常显示在客户的付款凭证上

异步通知

异步返回说明

订单支付成功后，MuskPay会异步返回交易结果到IPN url，请求方式为HTTP POST。请尽可能根据IPN url收到的结果处理商户系统中的订单状态。 MuskPay会在2小时内自动重复多次发送异步通知，直到商户服务器回复“ok”消息在响应中。

针对ipn_url要求如下：

ipn_url 必须是在Internet中可以访问的地址，不能是内网地址(如localhost)或内网IP
IPN通知可能比Callback返回先到达
多次的IPN异步通知，不要重复处理
MuskPay使用POST方式发送IPN通知信息，注意接受参数的处理方式
必须保证异步通知页面(ipn_url)上无任何字符，如空格，HTML标签等，程序执行完成后必须打印输入“ok”(不包括引号)，如果商户反馈给MuskPay的字符不是ok这2个字符，MuskPay服务器会不断重发通知，最多发送8次
一般情况下，MuskPay会在支付成功后的2小时内完成8次通知（通知的间隔频率为：0m,1m,2m,4m,8m,20m,30m）
程序执行完成后，ipn_url页面不能执行页面跳转，否则MuskPay会因收不到正确结果而重发结果通知

异步返回示例

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

异步返回报文

字段	说明
id `string`	MuskPay生成的唯一交易流水号.
status `string`	交易状态. 包括：支付成功 `success`, 支付失败`failure`, 支付中`pending`, 交易关闭`closed`.
currency `string`	订单记账币种.
amount `int`	订单记账金额.
time `string`	交易在MuskPay系统中的完成时间. 例如: `2015-01-01T01:01:00Z`(MuskPay使用的是UTC时区).
reference `string`	商户订单号.
note `string`	商户备注，与请求一致，如果请求是为空，则该字段为 null.
sys_reserve `json`	系统保留字段，返回格式为json字符串，详细用法参见接口规则
verify_sign `string`	返回的签名验证

签名方法

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

异步通知签名校验

在异步通知返回时，MuskPay会对返回信息做MD5签名，商户接受到异步通知后，应该按照签名方法验证返回的信息是否被篡改。签名方法如下：

A. 关键信息对和合作密钥信息对的拼接方法为：

单个对的表示方式为 key=value，如果该key对应的value为空，则不参与签名。
多个对的拼接方式为 key1=value1&key2=&key3=value3。多个对根据key值做升序排序。
合作密钥信息的拼接方式为key1=value1&key2=&key3=value3&MD5(Token)。将Token做MD5之后拼接在字符串的末尾，注意MD5(Token)之后应将字符串全部转化为小写字符。

B. 签名方法

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

注意：

MuskPay使用的字符集是UTF-8，请注意编码格式
MuskPay使用的MD5方法，输出都是小写字符，在签名比较时请忽略大小写。
返回报文中的参数可能由于业务需要会有增改，请根据动态获取的key来参与签名

信用卡支付

直接消费

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

请求示例

$ curl https://api.muskpay.io/v1.2/transactions/cardpay \
-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="订单描述" \
-d note="备注信息" \
-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"

信用卡直接消费不需要客户跳转至MuskPay付款页面。在商户端输入信用卡信息，请求CardPay API完成扣款。

支付成功后，将会生成一个交易对象并以JSON 格式返回。交易对象的ID用来查询，退款或者撤销等。

注意:调用此接口要求商户要有PCI资质

请求报文

字段	说明
reference `不为空`	商户订单号，1-30位的字母，数字和'-'组合，必须在商户系统中唯一.
currency `不为空`	订单币种，3位货币代码. 当前支持的币种参见接口规则
amount `不为空`	订单金额，USD最小交易金额为1美元. 对应货币的最小单位。详见接口规则
card_number `不为空`	卡号，16位或19号纯数字的卡号.
card_exp_month `不为空`	卡片有效期的月份，2位数字，如1月，表示为 `01`.
card_exp_year `不为空`	卡片有效期的年份，4位数字，如2020年.
card_cvv `不为空`	卡片安全代码，信用卡背面的的3位数字验证码.
card_holder `不为空`	持卡人姓名.
phone_number `不为空`	持卡人手机号码.
phone_country_code `不为空`	持卡人手机号国家地区代码 ISO数字代码.
email `不为空`	持卡人联系邮箱.
website `不为空`	交易网址.
client_ip `不为空`	客户端IP.
description `允许为空`	订单描述.
note `允许为空`	供商家使用的备注字段，MuskPay不做处理，在返回时，原数据将返回给商户.
账单地址
billing_address_first_name `不为空`	名字.
billing_address_middle_name `允许为空`	中间名.
billing_address_last_name `不为空`	姓.
billing_address_line1 `不为空`	地址第一行.
billing_address_line2 `允许为空`	地址第二行.
billing_address_city `不为空`	城市.
billing_address_state `不为空`	州/省/直辖市.
billing_address_zip `不为空`	邮政编码.
billing_address_country `不为空`	国家地区代码 ISO-3166-1两位字母代码.
收货地址
shipping_address_first_name `不为空`	名字.
shipping_address_middle_name `允许为空`	中间名.
shipping_address_last_name `不为空`	姓.
shipping_address_line1 `不为空`	地址第一行.
shipping_address_line2 `允许为空`	地址第二行.
shipping_address_city `不为空`	城市.
shipping_address_state `不为空`	州/省/直辖市.
shipping_address_zip `不为空`	邮政编码.
shipping_address_country `不为空`	国家地区代码 ISO-3166-1两位字母代码.

返回示例

{
    "id": "bn2345nb53454kjb",
    "status": "success",
    "amount": 110,
    "currency": "USD",
    "captured": true,
    "time": "2015-01-11T01:01:00Z",
    "reference": "jkh25jh1348fd89sg",
    "note": null
}

返回报文

返回一个交易对象。

字段	说明
id `string`	MuskPay生成的唯一交易流水号
status `string`	交易状态. 包括：支付成功 `success`, 支付失败`failure`, 支付中`pending`, 交易关闭`closed`
amount `int`	订单金额
currency `string`	订单币种
captured `bool`	固定值：`true`
time `string`	交易在MuskPay系统中的完成时间. 例如: `2015-01-01T01:01:00Z`(MuskPay使用的是UTC时区)
reference `string`	商户订单号
note `string`	商户备注，与请求一致，如果请求为空，则返回null

预授权

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

请求示例

$ 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="订单描述" \
-d note="备注信息" \
-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"

请求该方法创建一个预授权交易。预授权交易仅冻结金额，不正式扣款，要完成交易并扣款，请调用预授权完成接口。

注意:调用此接口要求商户要有PCI资质

请求报文

字段	说明
reference `不为空`	商户订单号，1-30位的字母，数字和'-'组合，必须在商户系统中唯一.
currency `不为空`	订单币种，3位货币代码. 当前支持的币种参见接口规则
amount `不为空`	订单金额，USD最小交易金额为1美元. 对应货币的最小单位。详见接口规则
card_number `不为空`	卡号，16位或19号纯数字的卡号.
card_exp_month `不为空`	卡片有效期的月份，2位数字，如1月，表示为 `01`.
card_exp_year `不为空`	卡片有效期的年份，4位数字，如2020年.
card_cvv `不为空`	卡片安全代码，信用卡背面的的3位数字验证码.
card_holder `不为空`	持卡人姓名.
phone_number `不为空`	持卡人手机号码.
phone_country_code `不为空`	持卡人手机号国家地区代码 ISO数字代码.
email `不为空`	持卡人联系邮箱.
website `不为空`	交易网址.
client_ip `不为空`	客户端IP.
description `允许为空`	订单描述.
note `允许为空`	供商家使用的备注字段，MuskPay不做处理，在返回时，原数据将返回给商户.
账单地址
billing_address_first_name `不为空`	名字.
billing_address_middle_name `允许为空`	中间名.
billing_address_last_name `不为空`	姓.
billing_address_line1 `不为空`	地址第一行.
billing_address_line2 `允许为空`	地址第二行.
billing_address_city `不为空`	城市.
billing_address_state `不为空`	州/省/直辖市.
billing_address_zip `不为空`	邮政编码.
billing_address_country `不为空`	国家地区代码 ISO-3166-1两位字母代码.
收货地址
shipping_address_first_name `不为空`	名字.
shipping_address_middle_name `允许为空`	中间名.
shipping_address_last_name `不为空`	姓.
shipping_address_line1 `不为空`	地址第一行.
shipping_address_line2 `允许为空`	地址第二行.
shipping_address_city `不为空`	城市.
shipping_address_state `不为空`	州/省/直辖市.
shipping_address_zip `不为空`	邮政编码.
shipping_address_country `不为空`	国家地区代码 ISO-3166-1两位字母代码.

返回示例

{
    "id": "bn2345nb53454kjb",
    "status": "success",
    "amount": 110,
    "currency": "USD",
    "captured": false,
    "time": "2015-01-11T01:01:00Z",
    "reference": "jkh25jh1348fd89sg",
    "note": null
}

返回报文

字段	说明
id `string`	MuskPay生成的唯一交易流水号
status `string`	交易状态. 包括：支付成功 `success`, 支付失败`failure`, 支付中`pending`, 交易关闭`closed`
amount `int`	订单金额
currency `string`	订单币种
captured `bool`	固定值：`false`
time `string`	交易在MuskPay系统中的完成时间. 例如: `2015-01-01T01:01:00Z`(MuskPay使用的是UTC时区)
reference `string`	商户订单号
note `string`	商户备注，与请求一致，如果请求为空，则返回null

释放预授权

POST
https://api.muskpay.io/v1.2/transactions/{transaction_id}/release

请求示例

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

请求该接口释放一个已经存在的预授权交易。超过30天没有完成或释放的预授权将会自动释放。

请求报文

transaction_id 预授权交易ID作为URL请求参数。

返回示例

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

返回报文

字段	说明
id `string`	释放交易ID.
status `string`	交易状态，包括：成功 `success`, 失败`failure`
released `bool`	预授权是否被释放，`true` 和 `false`
transaction_id `string`	被释放的预授权交易ID

预授权完成

POST
https://api.muskpay.io/v1.2/transactions/{transaction_id}/capture

请求示例

$ curl https://api.muskpay.io/v1.2/transactions/{transaction_id}/capture \
-H "Authorization: Bearer <TOKEN>" \
-d amount=100 \
-d currency="USD"

请求该接口完成已存在的预授权交易的扣款。预授权完成金额不能大于原交易金额。可以在预授权交易发起后的30天内调用预授权完成，超过30天的预授权交易将被自动释放。

请求报文

transaction_id 原预授权交易ID作为URL请求参数

字段	说明
amount `不为空`	预授权完成金额，交易币种对应的最小单位，人民币为分，日元最小单位为元。授权完成金额不能大于原预授权金额的115%。
currency `不为空`	预授权完成币种，与预授权交易币种一致。

返回示例

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

返回报文

字段	说明
id `string`	预授权完成交易ID
status `string`	交易状态，包括：成功 `success`, 失败`failure`
captured `bool`	预授权交易是否被捕获，`true` 和 `false`
transaction_id `string`	原预授权交易ID

网关支付

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

请求示例

$ 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="备注信息"

信用卡网关支付是一个异步的，需要页面跳转的支付方式。商家请求MuskPay API后，同步收到付款页URL，商家需跳转至该页面，在支付页面，客户输入支付信息，完成支付。一旦支付成功，页面将跳转至商家提供的callback URL，MuskPay会在返回callback URL时带上返回参数，需要使用GET方式获取。

由于重定向的性质，以及用户可能在重定向发生之前关闭浏览器，为保证支付结果通知到商户，MuskPay使用server-to-server的实时通知(IPN url)返回交易结果，IPN 结果需要使用POST方式获取。

请求报文

字段	说明
reference `不为空`	商户订单号，1-30位的字母，数字和'-'组合，必须在商户系统中唯一.
currency `不为空`	订单币种，3位货币代码. 当前支持的币种参见接口规则
amount `不为空`	订单金额，USD最小交易金额为1美元. 对应货币的最小单位。详见接口规则
website `不为空`	交易网址.
ipn_url `不为空`	接收支付结果异步通知的URL。详见异步通知
callback_url `不为空`	支付成功后浏览器返回商户网站的URL。
description `允许为空`	订单描述.
note `允许为空`	供商家使用的备注字段，MuskPay不做处理，在返回时，原数据将返回给商户.
client_ip `不为空`	客户端IP.

返回示例

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

返回报文

返回一个交易对象。

字段	说明
redirect_url `string`	在浏览器或者webview中使用此Url将用户重定向到对应的wap或web支付页面.

退款/查询等接口

查询订单状态

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

请求示例

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

使用商户订单号查询订单当前状态。

请求

reference 商户订单号作为URL的请求参数.

返回示例

{
    "id": "bn2345nb53454kjb",
    "status": "success",
    "type": "charge",
    "amount": 1111,
    "currency": "USD",
    "time": "2015-01-01T01:01:01Z",
    "reference": "jkh25jh1348fd89sg",
    "note": "sample note"
}

字段	说明
id `string`	MuskPay生成的唯一交易流水号.
status `string`	交易状态. 包括：支付成功 `success`, 支付失败`failure`, 支付中`pending`, 交易关闭`closed`.
vendor `string`	付款方式. 包括：`Visa`、`Master`、`JCB`、`Amex`、`Discover`、`unionpay`.
vendor_id `string`	付款成功后在支付渠道的支付流水号，通常显示在客户的付款凭证上
amount `int`	订单金额.
currency `string`	订单币种.
time `string`	交易在MuskPay中的完成时间. 例如: `2015-01-01T01:01:00Z`(MuskPay使用的是UTC时区).
reference `string`	商户订单号.
note `string`	商户备注，与请求一直，如果请求是为空，则该字段为 null.

查询交易详情

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

请求示例

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

请求参数为MuskPay返回的唯一交易ID，返回对应ID的交易详情对象。如果要查看撤销，退款等交易信息，请登录商户交易管理后台(TMS)。

请求报文

transaction_id MuskPay唯一的交易ID。

返回示例

{
    "id": "bn2345nb53454kjb",
    "status": "success",
    "type": "charge",
    "amount": 1111,
    "currency": "USD",
    "time": "2015-01-01T01:01:01Z",
    "reference": "jkh25jh1348fd89sg",
    "note": "sample note"

}

返回报文

返回对应ID的交易对象。

字段	说明
id `string`	MuskPay生成的唯一交易流水号
status `string`	交易状态. 包括：支付成功 `success`, 支付失败`failure`, 支付中`pending`, 交易关闭`closed`
type `string`	交易类型，包括：直接消费 `charge`, 预授权`authorization`, 预授权完成`capture`
vendor `string`	付款方式. 包括：`Visa`、`Master`、`JCB`、`Amex`、`Discover`、`unionpay`.
vendor_id `string`	付款成功后在支付渠道的支付流水号，通常显示在客户的付款凭证上
amount `int`	订单金额
currency `string`	订单币种
time `string`	交易在MuskPay系统中的完成时间. 例如: `2015-01-01T01:01:00Z`(MuskPay使用的是UTC时区)
reference `string`	商户订单号
note `string`	商户备注，与请求一致，如果请求为空，则返回null

申请退款

POST
https://api.muskpay.io/v1.2/transactions/{transaction_id}/refund

请求示例

$ curl https://api.muskpay.io/v1.2/transactions/{transaction_id}/refund \
-H "Authorization: Bearer <TOKEN>" \
-d amount=100 \
-d currency="USD"

商户可以对已经付款成功的交易发起全额或者部分退款，每笔交易商户可以发起多次部分退款，但累计退款金额不得大于原交易金额。

请求报文

transaction_id 原支付交易ID作为URL中的参数.

字段	说明
currency `不为空`	退款币种，与原交易币种一致。
amount `有条件的`	退款外币金额，交易币种对应的最小单位，人民币为分，日元最小单位为元。退款金额必须等于或小于原交易金额。
reason `允许为空`	退款原因

返回示例

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

返回报文

字段	说明
id `string`	退款交易流水号
status `string`	退款交易状态，包括：退款成功 `success`, 退款失败`failure`
refunded `bool`	`true`
transaction_id `string`	原支付交易ID

退款结果查询

GET
https://api.muskpay.io/v1.2/transactions/refunds/{transaction_id}/

请求示例

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

请求报文

transaction_id 原支付交易ID作为URL中的参数.

返回示例

{
    "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"
}

返回报文

字段	说明
id `string`	MuskPay生成的唯一支付交易流水号
status `string`	交易状态. 包括：支付成功 `success`, 支付失败`failure`, 支付中`pending`, 交易关闭`closed`
type `string`	交易类型，包括：直接消费 `charge`, 预授权`authorization`, 预授权完成`capture`
amount `int`	订单金额
currency `string`	订单币种
time `string`	交易在MuskPay系统中的完成时间. 例如: `2015-01-01T01:01:00Z`(MuskPay使用的是UTC时区)
reference `string`	商户订单号
note `string`	商户备注，与请求一致，如果请求为空，则返回null
vendor `string`	付款方式. 包括：`Visa`、`Master`、`JCB`、`Amex`、`Discover`、`unionpay`.
vendor_id `string`	付款成功后在支付渠道的支付流水号，通常显示在客户的付款凭证上
refunded_amount `int`	累计退款金额
refunds `list`	退款记录
refund_time `string`	退款发起时间
refund_id `string`	退款交易流水号
refunded_amount `int`	退款金额
status `string`	退款状态

批量查询交易信息

GET
https://api.muskpay.io/v1.2/transactions/

请求示例

$ curl https://api.muskpay.io/v1.2/transactions/?starting_after=2015-01-01T01:01:00Z \
-H "Authorization: Bearer <TOKEN>"

返回满足要求的交易列表，返回交易按照时间倒序排列，按照limit参数要求返回对应的条数，默认返回10条记录。如果要查看撤销，退款等交易信息，请登录商户交易管理后台(TMS).

参数starting_after表示读取该时间点之后的交易；ending_before 表示读取该时间点之前的交易。如果两个参数都有值，表示读取该时间范围内的交易信息，请注意ending_before 必须晚于 starting_after。

请求报文

使用GET方式请求。

字段	说明
limit `允许为空` 默认: 10	每次请求返回的交易笔数，接受的范围是1-100条
starting_after `允许为空`	开始时间，时间格式：yyyy-mm-ddThh:mm:ssZ
ending_before `允许为空`	截止时间，时间格式：yyyy-mm-ddThh:mm:ssZ

返回示例

{
    "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"
        }
    ]
}

返回报文

返回一个交易对象的数组，如果在请求的时间段内没有交易，则返回为空数组。

字段	说明
id `string`	MuskPay生成的唯一交易ID
status `string`	交易状态. 包括：支付成功 `success`, 支付失败`failure`, 支付中`pending`, 交易关闭`closed`
type `string`	交易类型，包括：直接消费 `charge`, 预授权`authorization`, 预授权完成`capture`
amount `int`	订单金额
currency `string`	订单币种
time `string`	交易在MuskPay系统中的完成时间. 例如: `2015-01-01T01:01:00Z`(MuskPay使用的是UTC时区)
reference `string`	商户订单号
note `string`	商户备注，与请求一致，如果请求为空，则返回null

交易下载

GET
https://api.muskpay.io/v1.2/download/transactions

商家可以请求该接口下载历史消费交易。

请求示例

$ curl https://api.muskpay.io/v1.2/download/transactions/?start_date=20170801&end_date=20170805 \
-H "Authorization: Bearer <TOKEN>"

请求报文

使用GET方式请求。注意：开始日期和结束日期间隔最长10天；不能请求当天的交易。

字段	说明
start_date `不为空`	交易的开始日期，格式为YYYYMMDD.
end_date `不为空`	交易的结束日期，格式为YYYYMMDD.

返回报文

如果请求成功，返回带交易记录的csv文件；如果请求失败，返回一个json格式的错误对象。

对账文件下载

GET
https://api.muskpay.io/v1.2/billing

商家需要对交易进行对账，可以通过该接口下载最长10天时间范围内的交易来对账。注意，MuskPay端未支付成功的订单不会出现对账文件中，支付成功后撤销的交易也不出现对账文件中。北京时间23点启动生成前一天23点到当天23点之间的对账单，建议商户0点之后再获取。

请求示例

$ curl https://api.muskpay.io/v1.2/billing/?start_date=20170101&end_date=20170105 \
-H "Authorization: Bearer <TOKEN>"

请求报文

使用GET方式请求。注意：开始日期和结束日期间隔最长10天；不能请求当天的交易。

字段	说明
start_date `不为空`	交易的开始日期，格式为YYYYMMDD.
end_date `不为空`	交易的结束日期，格式为YYYYMMDD.

返回报文

如果请求成功，返回带交易记录的csv文件；如果请求失败，返回一个json格式的错误对象。

账户/提款等

查询账户余额

GET
https://api.muskpay.io/v1.2/accounts

该接口提供查询商家当前账户余额的功能。

请求示例

$ curl https://api.muskpay.io/v1.2/accounts \
-H "Authorization: Bearer <TOKEN>"

请求

使用GET方式请求，无请求参数

返回示例

{
  "accounts": [
    {
      "balance": "100.00",
      "currency": "USD",
      "pending_amount": "12.40",
      "freeze_amount": "0.00"
    }
  ]
}

返回报文

如果请求成功，返回json格式的账户余额对象；如果请求失败，返回一个json格式的错误对象。

字段	说明
currency `string`	账户币种
balance `string`	当前账户余额
pending_amount `string`	当前未结算消费金额
freeze_amount `string`	当前未结算退款金额

查询提现历史记录

GET
https://api.muskpay.io/v1.2/withdrawal/history

返回满足要求的提现交易列表，返回按照时间倒序排列。最多可以查询6个月的提款记录

请求示例

$ curl https://api.muskpay.io/v1.2/withdrawal/history/?start_date=20170101&end_date=20170105 \
-H "Authorization: Bearer <TOKEN>"

请求报文

使用GET方式请求。

字段	说明
start_date `不为空`	开始日期，格式为YYYYMMDD.
end_date `不为空`	结束日期，格式为YYYYMMDD.

返回示例

{
    "withdrawal": [
        {
            "id": "bn2345nb53454kjb",
            "status": "completed",
            "amount": "100.00",
            "currency": "USD",
            "fee": "0.30",
            "fee_currency":"USD",
            "date": "20170101"
        }
    ]
}

返回报文

返回一个提款交易对象的数组，如果在请求的时间段内没有交易，则返回为空数组。

字段	说明
id `string`	MuskPay生成的withdrawal ID
status `string`	提款状态. 包括：处理中 `processing`, 完成`completed`
amount `int`	提款金额
currency `string`	到账币种
fee `string`	提款手续费
fee_currency `string`	手续费扣费币种
date `string`	提款日期，格式：YYYYMMDD

查询提现明细

GET
https://api.muskpay.io/v1.2/withdrawal/detail/{withdrawal_id}

通过withdrawl_id取得相对应的交易金额以及明细

请求示例

$ curl https://api.muskpay.io/v1.2/withdrawal/detail/{withdrawal_id} \
-H "Authorization: Bearer <TOKEN>"

请求报文

withdrawal_id 以申请提款生成的withdrawal ID作为URL请求参数.

返回报文

返回一个CSV文件

测试

测试地址

https://apitest.nihaopay.com

我们的API提供测试环境供商户在集成开发时使用，测试时请使用测试请求地址，例如：https://apitest.nihaopay.com/v1.2/transactions。在您完成集成开发，转入生产环境时，请将请求地址更换为生产环境地址。

在测试环境，我们提供测试卡和测试账户供您模拟交易，真实的银行卡是不能使用的。

如果您还没有测试账号，您可以在NihaoPay网站上申请一个测试账号来进行接入测试。

测试卡

当您通过MuskPay API请求信用卡支付时，请使用以下测试卡模拟交易。

Visa 信用卡 1


Card Number	4012 0000 7777 7777
CVV	997
EXP	12/2025

Visa 信用卡 2


Card Number	4264 2815 6666 6664
CVV	997
EXP	12/2025

Visa 信用卡 3


Card Number	4761 7300 0000 0011
CVV	997
EXP	12/2025

错误码

错误示例

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

当请求API失败，MuskPay会返回一个json格式的错误对象.

MuskPay的错误对象遵循HTTP状态码，2xx 表示请求成功，你将不会看到错误对象。 4xx 表示请求的信息中有错误，可能是请求参数格式不正确，也可能是未经身份验证的请求或未知的请求端点。5xx 表示MuskPay服务器存在内部错误，请与我们的技术支持团队tech_support@nihaopay.com 联系。

错误对象

字段	描述
code `int`	HTTP状态码.
label `string`	MuskPay的错误代码，请提供该字段以便于我们追踪错误信息。
message `string`	错误代码对应的错误描述.

错误码列表

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 MuskPay customer service. 支付方式受限制，请联系MuskPay
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.预授权完成失败，捕获扣款金额不能超过预授权交易金额的115%
402	71	Buyer not exist or buyer account info error 付款人账户不存在或者错误
402	72	Transaction amount is exceed the limit 交易金额超过单笔限额或者超过单日累计总限额
500	81	Merchant config error 商户配置错误，请联系MuskPay
500	82	Merchant unavailable 商户不可用
500	83	QRcode has expired 二维码已过期
500	84	Service is not activated for this account 服务未开通
402	86	Withdrawal amount exceeds account balance 提款金额超过账户余额
402	87	Withdrawal amount less than the minimum withdrawal amount 提款金额小于最小提款金额
402	88	Invalid application, it's only available for manually withdrawal merchant 提款申请仅对手工提款的商户开放
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	98	Vendor error 渠道系统出错，请稍后再试
500	99	System error 系统错误，请联系MuskPay
401	301	Invalid merchant credentials provided 无效的认证信息，或身份验证失败

API更新日志

2024-09-18

增加CardPay

2023-08-23

SecurePay支持返回json格式的数据

2023-08-05

增加分账功能

2022-07-18

增加Alipay A+接口

2020-09-01

更新支持的币种列表
新增银联的海关报关支持

2018-06-01

新增海关清关接口
IPN通知中增加渠道付款流水号

2018-05-17

In-app支持微信支付
扫码支付支持银联境外二维码，仅限美国地区商户

2018-03-15

新增多合一固定收款码接口
新增支付宝收款码接口

2017-11-10

新增微信小程序支付接口

2017-08-21

新增交易下载接口
新增固定二维码接口
新增查询余额接口
新增提现接口
新增提现记录查询接口

2017-05-25

新增线下面对面支付接口
新增In-APP支付接口
IPN通知机制的修改
IPN通知增加签名验证

2017-04-10

更新错误码列表
新增支持人民币标价金额

2017-03-07

新增中文文档
快捷支付接口增加client_ip字段
新增汇率查询接口
新增下载对账单接口

2017-01-01

启用1.2版本