文档简介

API Endpoint

https://api.nihaopay.com

NihaoPay API 采用通用的REST API风格设计，便于用户集成。端口地址遵循面向对象的命名约定，使用HTTP请求方式（POST，GET）访问。所有的API请求会以规范的json对象返回（SecurePay接口除外）。所用请求需通过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.nihaopay.com/v1.2/transactions。

认证

请求示例

$ curl https://api.nihaopay.com/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，保证所有接口正常使用。

接口说明

支付模式

NihaoPay提供在五种支付模式，分别是安全支付，信用卡快捷支付，In-APP支付，支付二维码和线下扫码支付。

安全支付

安全支付是指客户付款时页面跳转到付款渠道方，并在付款渠道方的支付页面完成订单支付的模式。

APP支付

APP支付是商户通过在移动端应用APP中集成SDK调起支付宝或者银联支付模块完成付款的模式。

支付二维码

支付二维码是指API返回商户一个包含二维码URL的对象，商户将二维码URL图像化展示在网页或者终端设备上，用户打开微信或者支付宝扫描二维码完成支付的模式。

扫码支付

扫码支付是商家使用带摄像头或者其他扫码功能的终端扫描用户展示的二维码，并完成扣款。

以下产品请参考MuskPay API Documentation

卡支付(CardPay)

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

应用场景

在不同的应用场景中，根据付款方式的不同，支付模式的应用参见下表：

付款方式 → 应用场景 ↓	支付宝 AliPay	微信支付 WechatPay	银联 UnionPay
PC 浏览器 `terminal=ONLINE`	标准安全支付	标准安全支付微信二维码	标准安全支付信用卡支付
手机浏览器 `terminal=WAP`	标准安全支付	微信H5支付请联系BD开启	标准安全支付信用卡支付
微信浏览器 `terminal=WAP`	NA	标准安全支付	标准安全支付信用卡支付
In-APP	APP支付	APP支付接入前请先提供AppID	APP支付
微信小程序	NA	微信小程序支付接入前请先提供小程序AppID	NA
线下商户主扫	扫码支付	扫码支付	扫码支付仅限美国地区商户
线下商户被扫	展示二维码固定二维码	展示二维码固定二维码	展示二维码仅限美国地区商户

接口规则

1.金额

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

2.币种

NihaoPay支持的币种取值列表：

USD:美元
JPY:日元
GBP:英镑
EUR:欧元
HKD:港币
CAD:加拿大元
SGD:新加坡元
AUD:澳大利亚元

3.人民币金额

针对商户标价为人民币的订单，可以使用rmb_amount这个参数来替换amount， NihaoPay根据付款渠道方提供的当前汇率将人民币金额转化对应的外币金额，并在支付成功后返回转换后的外币金额。

请求	返回	说明
`rmb_amount=10000` `currency=USD`	`rmb_amount=10000` `amount=1441` `currency=USD`	订单金额为100元人民币，记账金额为14.41美元
`amount=10000` `currency=USD`	`amount=10000` `currency=USD`	订单金额为100美元

4.商户订单号

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

5.付款方式

目前NihaoPay支持的付款方式包括： alipay:支付宝 wechatpay:微信支付 unionpay:银联

6. 通知URL

接口中callback_url必须是在Internet中可以访问的地址，不能是内网地址(如localhost)或内网IP。在处理callback和ipn的返回时，IPN通知可能比Callback返回先到达。
默认仅支付成功会跳转callback_url,如果商户希望其他状态也跳转，请在callback_url上增加参数accept，如callback_url?accept=pending,failure表示支付失败或者支付取消跳转callback_url。

7. 终端

Terminal 参数支持ONLINE 和WAP两种，具体使用规则参见应用场景。

sys_reserve = {"vendor_id":"4200000117201806013734875340"}

8. 系统保留域

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

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

异步通知

异步返回说明

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

针对ipn_url要求如下：

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

异步返回示例

id = 20170519103602011338
amount = 2
currency = USD
rmb_amount = 12
reference = 20170519103456437807
sys_reserve = {"vendor_id":"4200000117201806013734875340"}
status = success
time = 2017-05-19T10:36:32Z
note = null
verify_sign = 46072c81e3c6140d6bc92655196b247f

异步返回报文

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

签名方法

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

异步通知签名校验

在异步通知返回时，NihaoPay会对返回信息做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))

注意：

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

安全支付

标准安全支付

POST
https://api.nihaopay.com/v1.2/transactions/securepay

请求示例

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

$ 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 inWechat="false" \
-d callback_url="http://website.com/callback"

json响应示例1

{
    "url": "https://openapi.alipay.com/gateway.do?app_id=2019031263534265"
}

json响应示例2

{
    "form": {
        "actionUrl": "https://www.nihaopay.com/",
        "method": "POST",
        "target": "_self",
        "params": {
            "bizType": "000201",
            "backUrl": "https://bgw.nihaopay.com/payBackResp/44e4af32d6494c71aaafe2eaf6c05910",
            "orderId": "u20230827102153QvCEZp",
            "txnSubType": "01"
        }
    }
}

安全支付是一个异步的，需要页面跳转的支付方式。商家请求NihaoPay API后，同步收到一个HTML页面，商家需将该页面写入到当前的网页请求中，该页面会自动跳转到支付服务商的页面，在支付页面，客户输入支付信息，完成支付。一旦支付完成，页面将跳转至商家提供的callback URL，NihaoPay会在返回callback URL时带上返回参数，需要使用GET方式获取。

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

请求报文

参数	说明
currency `不为空`	币种，3位货币代码. 当前支持的币种参见接口规则
amount `有条件的`	订单外币金额，与currency对应。金额为对应货币中的最小单位。详见接口规则
rmb_amount `有条件的`	订单人民币金额，使用人民币标价替代外币金额标价。金额单位为分，如金额为100时，表示1.00元人民币。详见接口规则
vendor `不为空`	付款方式，客户付款时选择的支付方式，目前支持支付宝 `alipay`，微信支付 `wechatpay`，银联 `unionpay`和`PayPal`。
reference `不为空`	商户订单号，1-30位的字母，数字和'-'组合，必须在商户系统中唯一。详见接口规则
ipn_url `不为空`	接收支付结果异步通知的URL。详见异步通知
callback_url `不为空`	支付完成后浏览器返回商户网站的URL。
description `允许为空`	订单描述，可以订单商品信息摘要等，会显示在支付页面和客户付款收据中。
note `允许为空`	供商家使用的备注字段，NihaoPay不做处理，在返回时，原数据将返回给商户。
terminal `允许为空` 默认： ONLINE	指定支付页面是在PC(`ONLINE`) 上显示，还是手机浏览器mobile (`WAP`)上显示。
timeout `允许为空` 默认: 120	订单超时时间，在NihaoPay接受到订单请求后，如果在timeout（分钟）指定的时间内，客户未付款的，订单将会被关闭。接受的范围为`1 - 1440(1天)`。
in_wechat `允许为空`	当前支付场景是微信内置浏览器时传`true`否则传`false`且仅当vendor=`wechatpay`时有效，当in_wechat=`false`时如果您开通了微信H5支付则使用微信H5支付否则降级为扫码支付,当in_wechat=`true`时使用JSAPI支付。
response_format `允许为空` 默认: HTML	指定返回的数据是(`JSON`) 格式，还是 (`HTML`)格式。

JSON 响应报文字段说明

参数	说明
url `有条件的`	重定向url,当接口返回的是url时,调用者拿到url后直接重定向到此url即可
form `有条件的`	form表单对象,和url互斥,当url不存在时则form对象存在
form.actionUrl `不为空`	form表单的action属性
form.method `不为空`	form表单的method属性
form.target `不为空`	form表单的target属性
form.params `不为空`	form表单的参数，map格式，key为参数名，value为参数值。

同步返回

HTML格式响应 >安全支付接口同步返回一个HTML页面，商家请展示该页面在浏览器上，页面将自动跳转到支付服务方上的支付页面。
JSON格式响应 >返回的json数据返回一个form对象或者url(不会同时存在)。如果返回的是url则调用者拿到url后直接重定向到此url即可,如果返回的是form对象则需要调用者使用form对象内的字段自行构造一个form表单,并将form表单写入到当前的网页请求中,提交后该页面会跳转到支付页面。

异步返回示例

id = 20170519103602011338
amount = 2
currency = USD
rmb_amount = 12
reference = 20170519103456437807
sys_reserve = {"vendor_id":"4200000117201806013734875340"}
status = success
time = 2017-05-19T10:36:32Z
note = null
verify_sign = 46072c81e3c6140d6bc92655196b247f

异步返回报文

订单支付成功后，NihaoPay会返回交易结果到商户的callback url和IPN url。在最新版本中使用GET方式返回给callback url，使用POST方式返回给IPN url。请尽可能根据IPN url收到的结果处理商户系统中的订单状态。

NihaoPay会在2小时内自动重复多次发送异步通知，直到商户服务器回复“ok”消息在响应中。

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

获取付款二维码

POST
https://api.nihaopay.com/v1.2/transactions/qrcode

请求示例

$ curl https://api.nihaopay.com/v1.2/transactions/qrcode \
-H "Authorization: Bearer <TOKEN>" \
-d amount=100 \
-d currency="USD" \
-d vendor="wechatpay" \
-d reference="jkh25jh1348fd89sg" \
-d ipn_url="http://website.com/ipn"

商户请求该接口获得一个包含二维码URL的json对象，将URL使用二维码生成软件生成一个图片格式的二维码展示在商户的网站上，客户打开微信或者云闪付，使用”扫一扫"扫描二维码，并完成支付。一旦客户付款成功，NihaoPay将发送异步通知到商户的IPN URL。商户也可以请求查询接口，获取订单的支付结果。

IPN异步通知信息与安全支付的返回机制一样

请求报文

字段	说明
currency `不为空`	订单币种，3位货币代码. 当前支持的币种参见接口规则
amount `有条件的`	订单外币金额，与currency对应。金额为对应货币中的最小单位。详见接口规则
rmb_amount `有条件的`	订单人民币金额，使用人民币标价替代外币金额标价。金额单位为分，如金额为100时，表示1.00元人民币。详见接口规则
vendor `不为空`	付款方式，客户付款时选择的支付方式，目前支持微信支付 `wechatpay`和银联云闪付 `unionpay`。
reference `不为空`	商户订单号，1-30位的字母，数字和’-‘组合，必须在商户系统中唯一。
ipn_url `不为空`	支付通知接收的URL。详见异步通知
timeout `允许为空` 默认：120	订单超时时间，在NihaoPay接受到订单请求后，如果在timeout（分钟）指定的时间内，客户未付款的，订单将会被关闭。接受的范围为1 - 1440(1天)。
description `允许为空`	订单描述，可以订单商品信息摘要等，会显示在支付页面和客户付款收据中。
note `允许为空`	供商家使用的备注字段，NihaoPay不做处理，在返回时，原数据将返回给商户。

返回示例

{
    "id": "20160829075820003759",
    "code_url": "weixin://wxpay/bizpayurl?pr=1dVyJZF",
    "timeout": 90,
    "amount": 100,
    "currency": "USD",
    "reference": "jkh25jh1348fd89sg",
    "time": "2017-10-10T06:35:12Z"
}

返回报文

字段	说明
code_url `string`	二维码URL
id `string`	NihaoPay生成的唯一交易ID
amount `int`	订单金额。
currency `string`	订单币种
timeout `int`	二维码的有效时间（分钟），超过该时间，二维码将失效。
reference `string`	商户订单号
time `string`	交易在NihaoPay系统中的完成时间. 例如: `2015-01-01T01:01:00Z`(NihaoPay使用的是UTC时区).

In-App支付

POST
https://api.nihaopay.com/v1.2/transactions/apppay

请求示例

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

请求报文

字段	说明
currency `不为空`	订单币种，3位货币代码. 当前支持的币种参见接口规则
amount `有条件的`	订单外币金额，与currency对应。金额为对应货币中的最小单位。详见接口规则
rmb_amount `有条件的`	订单人民币金额，使用人民币标价替代外币金额标价。金额单位为分，如金额为100时，表示1.00元人民币。详见接口规则
vendor `不为空`	付款方式，客户付款时选择的支付方式，支持支付宝`alipay` , 微信支付`wechatpay` 和银联 `unionpay`。
app_id `允许为空`	APP在微信开放平台审核通过的APPID。当vendor=wechatpay时，不能为空。
reference `不为空`	商户订单号，1-30位的字母，数字和’-‘组合，必须在商户系统中唯一。
ipn_url `不为空`	支付通知接收的URL。详见异步通知
description `允许为空`	订单描述，可以订单商品信息摘要等，会显示在支付页面和客户付款收据中。
note `允许为空`	供商家使用的备注字段，NihaoPay不做处理，在返回时，原数据将返回给商户。
timeout `允许为空` 默认: 120	订单超时时间，在NihaoPay接受到订单请求后，如果在timeout（分钟）指定的时间内，客户未付款的，订单将会被关闭。接受的范围为`1 - 1440(1天)`。
ostype `不为空`	指定支付页面是在Android手机(`ANDROID`) 上显示，还是iphone手机 (`IOS`)上显示。

返回示例

{
    "orderInfo": "orderinfo string.....",
    "redirectUrl": "https://wallet.com/xxx?xxx=xx....."
}

返回报文

同一时间 orderInfo 和 redirectUrl 只有一个会返回, 优先使用orderInfo

字段	说明
orderInfo `string`	用于调起渠道方sdk的订单信息，具体使用参见NihaoPay提供的IOS Demo or Android Demo。微信支付的In-app功能需要特殊流程，如果要开通，请联系NihaoPay获取帮助。
redirectUrl `string`	在浏览器或者webview中使用此Url将用户重定向到对应的wap或web支付页面，具体使用参见NihaoPay提供的IOS Demo or Android Demo。

支付宝 A+

支持钱包: AlipayHK，GCASH，DANA，KaKaoPay，TNG，TrueMoney

POST
https://api.nihaopay.com/v1.2/transactions/aplus

请求示例

$ curl https://api.nihaopay.com/v1.2/transactions/aplus \
-H "Authorization: Bearer <TOKEN>" \
-d amount=100 \
-d currency="USD" \
-d reference="alipay20170503000300" \
-d ipn_url="http://website.com/ipn" \
-d callback_url="http://website.com/callback"

请求报文

字段	说明
currency `不为空`	订单币种，3位货币代码. 当前支持的币种参见接口规则
amount `有条件的`	订单外币金额，与currency对应。金额为对应货币中的最小单位。详见接口规则
rmb_amount `有条件的`	订单人民币金额，使用人民币标价替代外币金额标价。金额单位为分，如金额为100时，表示1.00元人民币。详见接口规则
reference `不为空`	商户订单号，1-30位的字母，数字和’-‘组合，必须在商户系统中唯一。
ipn_url `不为空`	支付通知接收的URL。详见异步通知
callback_url `有条件的`	Terminal=`ONLINE` 或 terminal=`WAP` 时必须, 支付完成后浏览器返回商户网站的URL。
description `允许为空`	订单描述，可以订单商品信息摘要等，会显示在支付页面和客户付款收据中。
note `允许为空`	供商家使用的备注字段，NihaoPay不做处理，在返回时，原数据将返回给商户。
timeout `允许为空` 默认: 10	订单超时时间，在NihaoPay接受到订单请求后，如果在timeout（分钟）指定的时间内，客户未付款的，订单将会被关闭。接受的范围为`1 - 10`。
terminal `允许为空` 默认： ONLINE	指定支付页面是在PC(`ONLINE`) 上显示，应用程序(`APP`)，还是手机浏览器mobile (`WAP`)上显示。
ostype `有条件的`	指定支付页面是在Android手机(`ANDROID`) 上显示，还是iphone手机 (`IOS`)上显示，terminal=`WAP` 或 terminal=`APP` 时必须。

返回示例

{
    "amount": 100,
    "timeout": 10,
    "currency": "USD",
    "reference": "1657808342862",
    "id": "20220714221903000379",
    "time": "2022-07-14T22:19:03Z",
    "redirectUrl": "https://alipay.com/connect.html?code=281666040098ZTL79hJiG7"
}

返回报文

字段	说明
amount `int`	订单金额，与currency对应，金额为对应货币中的最小单位。
timeout `int`	超时时间，单位分钟。
currency `string`	订单币种，3位货币代码。
reference `string`	商户订单号。
id `string`	nihaopay 订单号。
time `string`	下单时间。
redirectUrl `string`	支付重定向Url，建议使用新窗口打开。

微信小程序支付

POST
https://api.nihaopay.com/v1.2/transactions/micropay

在对接小程序支付API之前，需要先将商家通过微信认证的海外小程序对应的AppID和主体名称发送给支持团队配置后才可以使用。

商家在小程序内，请求预下单接口，生成预下单的支付参数，使用小程序的wx.requestpayment()唤醒微信支付。在订单支付完成后，NihaoPay会发送IPN通知到商户的IPN_url。开发步骤见下图

Mini Program Flow

请求示例

$ curl https://api.nihaopay.com/v1.2/transactions/micropay \
-H "Authorization: Bearer <TOKEN>" \
-d amount=100 \
-d currency="USD" \
-d reference="wechatpay20171109000300" \
-d ipn_url="http://website.com/ipn" \
-d open_id="oSC6Tw7--mfjTCpIr-72rWloA8TU" \
-d client_ip="180.167.25.154"

请求报文

字段	说明
currency `不为空`	订单币种，3位货币代码. 当前支持的币种参见接口规则
amount `有条件的`	订单外币金额，与currency对应。金额为对应货币中的最小单位。详见接口规则
rmb_amount `有条件的`	订单人民币金额，使用人民币标价替代外币金额标价。金额单位为分，如金额为100时，表示1.00元人民币。详见接口规则
reference `不为空`	商户订单号，1-30位的字母，数字和’-‘组合，必须在商户系统中唯一。
app_id `不为空`	微信小程序对应的APPID。
ipn_url `不为空`	支付通知接收的URL。详见异步通知
client_ip `不为空`	用户客户端IP
open_id `不为空`	用户标识，微信用户在商户小程序内的唯一标识，获取方式请点击这里.
description `允许为空`	订单描述，可以订单商品信息摘要等，会显示在支付页面和客户付款收据中。
note `允许为空`	供商家使用的备注字段，NihaoPay不做处理，在返回时，原数据将返回给商户。
timeout `允许为空` 默认: 120	订单超时时间，在NihaoPay接受到订单请求后，如果在timeout（分钟）指定的时间内，客户未付款的，订单将会被关闭。接受的范围为`1 - 1440(1天)`。

成功返回示例

{
    "timeStamp": "1510341967363",
    "nonceStr": "a611bda03d544b9f941393c48c2e517f",
    "wechatPackage": "prepay_id=wx201711110326070ccf2a7f060678638664",
    "signType": "MD5",
    "paySign": "09E5BE5B9D93080E3B7DD05C8F41049E"
}

返回报文

字段	说明
timeStamp `string`	时间戳
nonceStr `string`	随机字符串
wechatPackage `string`	prepay_id等信息
signType `string`	微信的签名类型
paySign `string`	签名

卡支付

信用卡支付，请参考MuskPay API 文档

线下面对面支付

扫码支付

Scan QRcode

POST
https://api.nihaopay.com/v1.2/transactions/scanqrcode

请求示例

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

请求报文

参数	说明
currency `不为空`	订单币种，3位货币代码. 扫码支付支持的币种有：`USD` 美元和 `JPY` 日元。
amount `不为空`	订单金额，金额为对应货币中的最小单位。详见接口规则
vendor `不为空`	付款方式，客户付款时选择的支付方式，目前支持支付宝 `alipay`,微信支付`wechatpay`和银联`unionpay`。
reference `不为空`	商户订单号，1-30位的字母，数字和'-'组合，必须在商户系统中唯一。详见接口规则
buyer_identity_code `不为空`	客户付款二维码或者条形码的信息
client_ip `不为空`	终端IP，调用API的终端设备的IP
description `允许为空`	订单描述，可以订单商品信息摘要等，会显示在支付页面和客户付款收据中。
note `允许为空`	供商家使用的备注字段，NihaoPay不做处理，在返回时，原数据将返回给商户。

返回示例

{
  "amount": 12,
  "id": "20170519093105011337",
  "time": "2017-05-19T09:31:05Z",
  "status": "success",
  "note": "123456789",
  "sys_reserve": "{'vendor_id':'2018031421001004970502155891'}",
  "reference": "alipay201705030004",
  "currency": "USD"
}

返回报文

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

展示交易二维码

POST
https://api.nihaopay.com/v1.2/transactions/showqrcode

商户请求该接口获得一个包含二维码URL的json对象，将URL使用二维码生成软件生成一个图片格式的二维码展示在商户的收款终端上，客户打开微信或者支付宝，使用”扫一扫"扫描二维码，并完成支付。一旦客户付款成功，NihaoPay将发送异步通知到商户的IPN URL。商户也可以请求查询接口，获取订单的支付结果。

Show QRcode

请求示例

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

请求报文

字段	说明
amount `不为空`	订单金额，金额为对应货币中的最小单位。详见接口规则
currency `不为空`	订单币种，3位货币代码. 该产品支持的币种有：`USD` 美元和 `JPY` 日元。
vendor `不为空`	付款方式，客户付款是选择的支付方式，目前支持支付宝 `alipay`,微信支付`wechatpay`和银联`unionpay`。
reference `不为空`	商户订单号，1-30位的字母，数字和’-‘组合，必须在商户系统中唯一。
ipn_url `不为空`	支付通知接收的URL。详见异步通知
timeout `允许为空` 默认：120	订单超时时间，在NihaoPay接受到订单请求后，如果在timeout（分钟）指定的时间内，客户未付款的，订单将会被关闭。接受的范围为1 - 1440(1天)。
description `允许为空`	订单描述，可以订单商品信息摘要等，会显示在支付页面和客户付款收据中。
note `允许为空`	供商家使用的备注字段，NihaoPay不做处理，在返回时，原数据将返回给商户。

返回示例

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

返回报文

字段	说明
code_url `string`	二维码URL
id `string`	NihaoPay生成的唯一交易ID
amount `int`	订单金额。
currency `string`	订单币种
timeout `int`	二维码的有效时间（分钟），超过该时间，二维码将失效。
reference `string`	商户订单号
time `string`	交易在NihaoPay系统中的时间. 例如: `2015-01-01T01:01:00Z`(NihaoPay使用的是UTC时区).

多合一固定收款码

生成固定收款码

POST
https://api.nihaopay.com/v1.2/merchantqrcode

商户请求该接口获得一个包含NihaoPay固定收款码URL的json对象，将URL使用二维码生成软件生成一个图片格式的二维码，打印后张贴在商户的店铺中。客户打开支付宝或微信，使用”扫一扫"扫描二维码，在显示的页面中输入消费金额，确认后完成支付。商户通过NihaoPay商户后台查询客户付款记录。

请求示例

$ curl https://api.nihaopay.com/v1.2/merchantqrcode \
-H "Authorization: Bearer <TOKEN>" \
-d ipn_url="http://website.com/ipn" \
-d trade_currency="USD" \
-d seller_name="NihaoPay" \
-d store_name="LA Branch" \
-d store_no="B001"

请求报文

字段	说明
trade_currency `不为空`	订单币种，3位货币代码. 该产品支持的币种有：`USD` 美元和 `JPY` 日元。
ipn_url `允许为空`	支付通知接收的URL。详见异步通知
seller_name `不为空`	商家名称，用于显示在扫描二维码后的收银页面上
store_name `不为空`	分店名称
store_no `不为空`	分店编号

返回示例

{
  "seller_name": "NihaoPay",
  "store_name": "LA Branch",
  "store_no": "B001",
  "qrcode_img_url": "https://apitest.nihaopay.com/merqrcode/9b2487be23a3434b9eb62870fcb73680",
  "qrcode": "https://apitest.nihaopay.com/topayment/9b2487be23a3434b9eb62870fcb73680"
}

返回报文

字段	说明
seller_name `string`	商家名称
store_name `string`	分店名称
store_no `string`	分店编号
qrcode_img_url `string`	二维码图片地址
qrcode `string`	二维码Url

固定收款码支付

POST
https://api.nihaopay.com/v1.2/transactions/staticqrcode

多合一的固定收款码，NihaoPay是提供标准收银页面的。为方便服务商或商户在收银页面中展现自己的品牌标识，NihaoPay支持商家自己构建二维码对应的H5收银页面，该页面确认支付时，调用如下接口唤醒微信或支付宝的付款。

请求示例

$ curl https://api.nihaopay.com/v1.2/transactions/staticqrcode \
-H "Authorization: Bearer <TOKEN>" \
-d amount=100 \
-d vendor="alipay" \
-d reference="201705030002" \
-d qrcode="https://apitest.nihaopay.com/topayment/9b2487be23a3434b9eb62870fcb73680" \
-d callback_url="https://nihaopay.com" \
-d description="static QrCode"

请求报文

参数	说明
amount `不为空`	订单金额，金额为对应货币中的最小单位。详见接口规则
vendor `不为空`	付款方式，根据客户扫描二维码使用的APP决定，如果用微信扫码，该参数为`wechatpay`，如果用支付宝钱包扫码，该参数为`alipay`。
qrcode `不为空`	收款码url。该参数为创建收款码接口的返回字段`qrcode`
reference `允许为空`	商户订单号，1-30位的字母，数字和'-'组合，必须在商户系统中唯一。详见接口规则
callbacl_url `允许为空`	支付完成后浏览器返回商户网站的URL。
description `允许为空`	订单描述，可以订单商品信息摘要等，会显示在支付页面和客户付款收据中。

返回示例

{
  "redirect_url": "https://wxcode.nihaopay.com/wechatpay/openid?txnId=20180314095142025479"
}

返回报文

当请求无误时，接口返回一个页面跳转url, 商家需要页面重定向到该地址，由APP自动唤醒支付功能。

字段	说明
redirect_url `string`	页面跳转地址。

支付宝收款码

POST
https://api.nihaopay.com/v1.2/merchantqrcode

商户请求该接口获得一个包含支付宝静态二维码URL的json对象，将URL使用二维码生成软件生成一个图片格式的二维码,打印后张贴在商户的店铺中。客户打开支付宝，使用”扫一扫"扫描二维码，在显示的页面中输入消费金额，确认后完成支付。一旦客户付款成功，NihaoPay将发送异步通知到商户的IPN URL。商户也可以登录商户后台查询客户付款记录。

请求示例

$ curl https://api.nihaopay.com/v1.2/merchantqrcode \
-H "Authorization: Bearer <TOKEN>" \
-d vendor="alipay" \
-d ipn_url="http://website.com/ipn" \
-d trade_currency="USD" \
-d seller_name="NihaoPay" \
-d store_name="LA Branch" \
-d store_no="B001"

请求报文

字段	说明
trade_currency `不为空`	订单币种，3位货币代码. 该产品支持的币种有：`USD` 美元和 `JPY` 日元。
vendor `不为空`	固定值：`alipay`。
ipn_url `允许为空`	支付通知接收的URL。详见异步通知
seller_name `不为空`	商家名称，用于显示在扫描二维码后的付款页面上
store_name `不为空`	分店名称
store_no `不为空`	分店编号

返回示例

{
  "seller_name": "NihaoPay",
  "store_name": "LA Branch",
  "store_no": "B001",
  "qrcode_img_url": "https://mobilecodec.alipay.com/show.htm?code=ocx09459xspxxdajnvzik3d",
  "qrcode": "https://qr.alipay.com/ocx09459xspxxdajnvzik3d"
}

返回报文

字段	说明
seller_name `string`	商家名称
store_name `string`	分店名称
store_no `string`	分店编号
qrcode_img_url `string`	带支付宝logo的二维码图片地址
qrcode `string`	二维码Url

报关

报关产品是为跨境电商行业商户提供直邮中国业务场景下支付单海关申报的服务。

报关接口

目前支持使用银联，支付宝和微信付款的订单做海关申报，如果开通微信支付的商户，需要使用报关产品前请先将海关备案号和海关备案名称邮件发送至业务支持团队，避免出现报关失败的问题。

身份信息校验申报规则：

身份信息校验不管是否一致，微信或支付宝都以系统登记的支付人信息推送海关
商户重推上传新的用户身份信息，渠道会重新校验

POST
https://api.nihaopay.com/v1.2/customs/declaration/{transaction_id}

请求示例

$ curl https://api.nihaopay.com/v1.2/customs/declaration/20180529073648029764 \
-H "Authorization: Bearer <TOKEN>" \
-d request_no=20180529073648029702 \
-d customs=ningbo \
-d merchant_customs_code=440316T004 \
-d merchant_customs_name=财付通支付科技有限公司 \
-d customs_amount=1284 \
-d split=true \
-d product_amount=1284 \
-d transport_amount=0 \
-d sub_order_id=20180529073648029701

请求报文

参数	说明
request_no String(36) `不为空`	请求订单号
customs String(64) `不为空`	申报海关
merchant_customs_code String(32) `不为空`	商户海关备案号
merchant_customs_name String(64) `不为空`	商户海关备案名称
customs_amount Int `不为空`	报关人民币金额，以分为单位
duty_amount Int `允许为空`	关税，以分为单位。部分海关需要上报关税信息
description String(128) `允许为空`	报关信息描述
split bool `不为空`	是否拆单，默认为`true`
sub_order_id String(64) `不为空`	商户子订单号，用于在海关系统中匹配物流单和订单信息
product_amount Int `有条件的`	商品金额，以分为单位。在拆单情况下，该字段不能为空
transport_amount Int `有条件的`	物流费用，以分为单位。在拆单情况下，该字段不能为空
cert_type String(16) `不为空`	订购人证件类型，目前只支持大陆身份证，默认固定值`ID_CARD`
cert_name String(64) `不为空`	订购人姓名，如张三
cert_no String(32) `不为空`	用户大陆身份证号，尾号为X的，请用大写字母X。

请求参数说明

支持的申报海关包括：

ZONGSHU：海关总署
BEIJING：北京海关
HANGZHOU：杭州海关
NINGBO：宁波海关
GUANGZHOU：广州海关
GUANGZHOU_HUANGPU：广州黄埔国检
SHENZHEN：深圳海关
NANSHA：南沙国检
ZHENGZHOU：河南保税物流中心
XINZHENG：新郑综合保税区
CHONGQING：重庆海关
SHANGHAI：上海海关
XIAN：西安海关
TIANJING：天津海关
XIAMEN：厦门海关

返回示例

{
    "id": "20180529084416000000",
    "status": "pending",
    "transaction_id": "20180529073648029764",
    "pay_transaction_id": "2019011122001376840500835544",
    "ver_dept": 2,
    "pay_code": "312226T001",
     "cert_check": "UNCHECKED"
}

返回报文

字段	说明
id `string`	NihaoPay生成的报关流水号.
status `string`	报关状态. 包括：成功 `success`, 失败`failure`, 报关中`pending`.
transaction_id `string`	原交易流水号.
pay_transaction_id `string`	支付流水号，来自支付机构，如微信或者支付宝的交易交易流水号，供商户海关报备使用
ver_dept `int`	核验机构，包括 0-银联，1-网联，2-其他
pay_code `string`	支付企业的海关注册登记编号
cert_check `string`	订购人和支付人身份信息校验结果，`UNCHECKED`:商户未上传订购人身份信息,`SAME`:商户上传的订购人身份信息与支付人身份信息一致,`DIFFERENT`:商户上传的订购人身份信息与支付人身份信息不一致

支付企业海关注册编号

银联付款的订单对应的支付企业海关信息如下：

备案名称：中国银联股份有限公司
备案编号：312228034U

微信付款的订单对应的支付企业海关信息如下：

备案名称：财付通支付科技有限公司
备案编号：4403169D3W

支付宝付款的订单对应的支付企业海关信息如下：

备案名称：支付宝(中国)网络技术有限公司

海关	支付宝备案号
总署	31222699S7
上海海关	31222699S7
宁波海关	31222699S7
河南保税物流中心	31222699S7
新郑综合保税区	P460400005
杭州海关	ZF14021901
广州海关	C000010000416158
天津海关	Q12150016000019

报关查询接口

GET
https://api.nihaopay.com/v1.2/customs/{request_no}

请求示例

$ curl https://api.nihaopay.com/v1.2/customs/20180529073648029702 \
-H "Authorization: Bearer <TOKEN>"

请求报文

字段	说明
request_no `不为空`	需要查询的报关请求单号

返回示例

{
    "id": "20180529084416000000",
    "request_no": "20180529073648029702",
    "status": "pending",
    "vendor_id": "4200000112201805292728213273",
    "customs": "NINGBO",
    "split": true,
    "customs_amount": 1284,
    "product_amount": 1284,
    "transport_amount": 0,
    "transaction_id": "20180529073648029764",
    "sub_order_id": "20180529073648029701",
    "pay_transaction_id": "2019011122001376840500835544",
    "ver_dept": 2,
    "pay_code": "312226T001"
}

返回报文

字段	说明
id `string`	报关请求ID
transaction_id `string`	原支付交易ID
vendor_id `string`	原支付交易在渠道方的流水号
status `string`	报关状态，包括：成功 `success`, 失败`failure`, 报关中`pending`.
customs `string`	申报海关
customs_amount `int`	报关人民币金额，以分为单位
duty_amount `int`	关税，以分为单位。部分海关需要上报关税信息
split `bool`	是否拆单，默认为不拆单
sub_order_id `string`	商户子订单号，在拆单情况下，该字段不能为空
product_amount `int`	商品金额，以分为单位。在拆单情况下，该字段不能为空
transport_amount `int`	物流费用，以分为单位。在拆单情况下，该字段不能为空
pay_transaction_id `string`	支付流水号，来自支付机构，如微信或者支付宝的交易交易流水号，供商户海关报备使用
ver_dept `int`	核验机构，包括 0-银联，1-网联，2-其他
pay_code `string`	支付企业的海关注册登记编号

报关重推接口

POST
https://api.nihaopay.com/v1.2/customs/redeclaration/{request_no}

请求示例

$ curl https://api.nihaopay.com/v1.2/customs/redeclaration/20210810150833001421 \
-H "Authorization: Bearer <TOKEN>"

请求报文

字段	说明
request_no `不为空`	需要重推的报关请求单号

返回示例

{
    "transaction_id": "20210810150833001421",
    "cert_check": "DIFFERENT",
    "ver_dept": 3,
    "request_no": "20210810150833001421",
    "pay_code": "31222699S7",
    "pay_transaction_id": "2021081011082640020055578",
    "merchant_id": "M001100001",
    "id": "20210810150935000155",
    "status": "success"
}

返回报文

字段	说明
request_no `string`	原报关请求订单号
id `string`	NihaoPay生成的报关流水号.
merchant_id `string`	NihaoPay的商户号
status `string`	报关状态. 包括：成功 `success`, 失败`failure`, 报关中`pending`.
transaction_id `string`	原交易流水号.
pay_transaction_id `string`	支付流水号，来自支付机构，如微信或者支付宝的交易交易流水号，供商户海关报备使用
ver_dept `int`	核验机构，包括 0-银联，1-网联，2-其他
pay_code `string`	支付企业的海关注册登记编号
cert_check `string`	订购人和支付人身份信息校验结果，`UNCHECKED`:商户未上传订购人身份信息,`SAME`:商户上传的订购人身份信息与支付人身份信息一致,`DIFFERENT`:商户上传的订购人身份信息与支付人身份信息不一致

报关接口错误码列表

code	label	message
400	31	Transaction reference number must be unique. Please re-submit.商户订单号不能重复，请更换订单号后重新提交
402	61	Transaction not found.交易未找到
500	81	Merchant config error 商户配置错误，请联系NihaoPay
500	82	Merchant unavailable 商户不可用
400	90	The field not valid. 请求参数格式不正确
500	91	Signature error 签名错误
500	92	The {0} field is required.请求字段不能为空
500	96	Timeout 请求超时
500	97	Inner error 内部错误
500	98	Vendor error 渠道系统出错，请稍后再试
500	99	System error 系统错误，请联系NihaoPay
401	301	Invalid merchant credentials provided 无效的认证信息，或身份验证失败
402	100	Transaction retransmission fail, Please try it after 5 minutes. 交易重传失败
402	101	Customs not supported. 报关不支持
402	102	Customs infomation changed. 报关信息篡改
402	103	Certification not correct. 认证不正确
402	104	Split amount not correct. 拆分金额不正确
402	105	Can not be modified as it is on declaration. 报关时无法修改
402	106	Same customs declare once. 同一个海关申报一次
402	107	Your request has been submitted, please confirm that it has taken effect. 您的请求已提交，请确认已生效
402	108	The original customs does not exist 原报关订单不存在
402	109	The declaration is not allowed for refunded orders. 已退款订单不能申报

代扣

代扣功能描述

和用户完成签约后即可直接从用户签约钱包完成扣款.

代扣规则

同一个合约同一个用户只能签约一次, 重复签约会返回签约失败
签约后商户和用户都可以解约
扣款后全额退款不会返还周期内剩余扣款次数
代扣目前仅支持微信支付
当前微信代扣限制
- 单笔限额：100元(CNY)
- 每日限额：100元(CNY)
- 单月限额：100元(CNY)
- 单日限次：1次
- 单月限次：2次

代扣接口

1.代扣签约

请求参数说明

参数名	是否必须	类型	说明	示例值
appId	否	string	应用ID,如果开通了多个为了区分则必传	wx123567
agreementId	是	string	签约协议ID，微信场景即`plan_id`	202301010001
username	是	string(32)	签约用户的名称，用于页面展示,不需要对值进行URL编码，参数值不支持UTF8非3字节编码的字符	张三
vendor	是	string(16)	支付渠道，如：`wechatpay`（微信支付）	wechatpay
currency	是	string(3)	货币代码，如：`USD`（美元）	USD
notifyUrl	是	string	异步通知URL，用于接收签约结果通知	https://api.example.com/notify
returnUrl	否	string	同步返回URL，(`H5`,`JSAPI`时必须)用户签约完成后跳转的URL	https://api.example.com/return
userId	否	string	用户标识，(`JSAPI`,`MINI_APP`时必须),vendor=wechatpay时填充openid	oSC6Tw6SrhMMzMguby9cCqVzOo
platform	是	string	平台类型，如：`WEB`/`H5`（网页）、`APP`（移动应用）、`MINI_APP`(小程序)、`JSAPI`(微信公众号)	WEB
clientIp	否	string	客户端IP地址(`H5`时必须)，用于风控校验	127.0.0.1
reference	是	string(64)	商户唯一标识号，用于标识本次签约请求	202301010001
remark	否	string	备注信息，用于记录本次签约的附加信息	测试签约

响应参数说明

参数名	是否必须	类型	说明	示例值
code	是	string	返回码，`00`表示成功，其他表示失败	00
label	是	string	返回码标签，用于标识返回码类型	00
message	是	string	返回信息，描述操作结果	success
agreementId	是	string	签约协议ID，微信场景即`plan_id`	202301010001
contractNo	是	string	合约编号，nihaopay合约唯一标识	202301010001
signId	是	string	签约URL，APP/小程序返回signId，WEB/H5返回signUrl	202501111159364508440
signUrl	是	string	签约ID，APP/小程序返回signId，WEB/H5返回signUrl	https://api.example.com/sign

请求示例 场景1：WEB签约

curl --location 'https://api.nihaopay.com/v1.2/contract/sign' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <TOKEN>' \
--data '{
    "appId": "your appId",
    "agreementId": "your agreementId",
    "usersame": "your customer name",
    "vendor": "wechatpay",
    "currency": "USD",
    "notifyUrl": "https://YOUR_HOST/notify",
    "returnUrl": "https://YOUR_HOST/callback",
    "platform": "WEB",
    "clientIp": "127.0.0.1",
    "reference":"your unique reference",
    "remark": "remark",
    "userId": "your_user_id"
}'

请求失败响应示例

{
    "code": "01",
    "label": "01",
    "message": "failed"
}

请求成功响应示例 场景1：APP/小程序

{
    "code": "00",
    "label": "00",
    "message": "success",
    "agreementId": "your agreementId",
    "contractNo": "our contractNo",
    "signId": "xxxxxxxx"
}

场景2：JSAPI/WEB/H5

{
    "code": "00",
    "label": "00",
    "message": "success",
    "agreementId": "your agreementId",
    "contractNo": "our contractNo",
    "signUrl": "https://api.mch.weixin.qq.com/global/papay/contracts/login?os_session_id=xxx#wechat_pay"
}

2.代扣解约

请求参数说明

参数	是否必须	类型	说明
agreementId	`可选`	string	签约协议ID，微信场景即plan_id
reference	`可选`	string(64)	商户唯一标识符
reason	`必须`	string	解约原因
contractNo	`可选`	string	合约编号,nihaopay合约唯一标识,reference+agreementId 和 contractNo 不能同时为空

响应参数说明

参数	是否必须	类型	说明
code	`不为空`	string	返回码，00表示成功
label	`不为空`	string	返回码标签
message	`不为空`	string	返回信息
contractId	`不为空`	string	合约ID
contractNo	`不为空`	string	合约编号,nihaopay合约唯一标识
reference	`不为空`	string	商户唯一标识号

请求示例 使用agreementId + reference

curl --location 'https://api.nihaopay.com/v1.2/contract/terminate' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <TOKEN>' \
--data '{
    "agreementId": "your agreementId",
    "reference": "your unique reference",
    "reason": "your terminate reason"
}'

使用contractNo

curl --location 'https://api.nihaopay.com/v1.2/contract/terminate' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <TOKEN>' \
--data '{
    "contractNo": "d649252400014ea7a8a890704cc600d6",
    "reason": "your terminate reason"
}'

成功响应示例

{
    "code": "00",
    "label": "00",
    "message": "success",
    "contractId": "contract id",
    "contractNo": "our contract number",
    "reference": "your unique reference"
}

失败响应示例

{
    "code": "01",
    "label": "01",
    "message": "failed"
}

3.代扣合约查询

请求参数说明

参数	是否必须	类型	说明
agreementId	`可选`	string	签约协议ID，微信场景即`plan_id`
reference	`可选`	string(64)	商户唯一标识符
contractNo	`可选`	string	合约编号,nihaopay合约唯一标识,reference+agreementId 和 contractNo 不能同时为空

响应参数说明

参数	是否必须	类型	说明
code	`不为空`	string	返回码，00表示成功
label	`不为空`	string	返回码标签
message	`不为空`	string	返回信息
contractId	`不为空`	string	合约ID
contractNo	`不为空`	string	合约编号,nihaopay合约唯一标识
contractStatus	`不为空`	string	合约状态，`Signed`(已签约)、`Terminated`(已解约),`Processing`(待签约),`FAIL`(签约失败)
signedTime	`可能为空`	string	签约时间
terminateTime	`可能为空`	string	解约时间
terminateMode	`可能为空`	string	解约模式，`USER`(用户主动解约)、`MERCHANT`(商户解约)、`PLATFORM`(商户解约平台解约)

请求示例 场景: agreementId + reference

curl --location 'https://api.nihaopay.com/v1.2/contract/query' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <TOKEN>' \
--data '{
    "agreementId": "your agreementId",
    "reference": "your unique reference"
}'

场景: contractNo

curl --location 'https://api.nihaopay.com/v1.2/contract/query' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <TOKEN>' \
--data '{
    "contractNo": "d649252400014ea7a8a890704cc600d6"
}'

返回示例

{
    "code": "00",
    "label": "00",
    "message": "success",
    "contractId": "contract id",
    "contractNo": "our contract number",
    "contractStatus": "Signed/Terminated",
    "signedTime": "2025-01-15 19:15:14",
    "terminateTime": "2025-01-15 19:15:14",
    "terminateMode": "USER/MERCHANT/PLATFORM",
}

4.发起扣款

请求参数说明

参数	是否必须	类型	说明
amount	`不为空`	string	扣款金额
currency	`不为空`	string(3)	货币代码，如USD
note	`可选`	string	订单备注
description	`不为空`	string	扣款描述信息(用户端能看到的扣款内容)
ipn_url	`不为空`	string	异步通知URL
reference	`不为空`	string(64)	商户唯一标识符
vendor	`不为空`	string(16)	支付渠道，如wechatpay
contract_id	`不为空`	string	合约ID,可以从签约回调中的通知获得,也可以主动调用query查询得到

响应参数说明

参数	是否必须	类型	说明
status	`不为空`	string	交易状态，可能值: `success`/`failure`
reference	`不为空`	string	商户订单号
currency	`不为空`	string(3)	交易货币，如 USD
amount	`不为空`	decimal	交易金额
rmb_amount	`不为空`	decimal	人民币金额
id	`不为空`	string	交易流水号
note	`允许为空`	string	订单备注
time	`不为空`	string	交易时间，UTC格式
message	`不为空`	string	交易结果描述

请求示例

curl --location 'https://api.nihaopay.com/v1.2/transactions/autodebit' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <TOKEN>' \
--data '{
    "amount": "1",
    "currency": "USD",
    "note": "your order note",
    "description": "<your debit description>",
    "ipn_url": "<your ipn url>",
    "reference": "<your unique reference>",
    "vendor": "wechatpay",
    "contract_id": "<your contract id>"
}'

成功返回示例

{
    "status": "success",
    "reference": "<your unique reference>",
    "currency": "USD",
    "amount": 1,
    "rmb_amount": 0,
    "id": "20250111220054100012",
    "note": "autodebit test",
    "time": "2025-01-11T22:00:54Z",
    "message": ""
}

错误返回示例

{
    "status": "failure",
    "reference": "<your unique reference>",
    "currency": "USD",
    "amount": 1,
    "rmb_amount": 0,
    "id": "20250111220054100012",
    "note": "autodebit test",
    "time": "2025-01-11T22:00:54Z",
    "message": "用户账户支付已达上限"
}

签约状态异步通知

通知参数说明

参数	是否必须	类型	说明
agreementId	`不为空`	string	签约协议ID，微信场景即`plan_id`
userId	`不为空`	string	用户ID,微信场景即`open_id`
contractId	`不为空`	string	合约ID,发起扣款时需要
contractNo	`不为空`	string	合约编号,nihaopay合约唯一标识
reference	`不为空`	string	商户唯一标识符
contractStatus	`不为空`	string	状态:`Signed`(已签约)、`Terminated`(已解约),`Processing`(待签约),`FAIL`(签约失败)
signedAt	`可能为空`	string	签约时间,签约通知时必须
terminateAt	`可能为空`	string	解约时间,解约通知时必须
terminateMode	`可能为空`	string	解约模式,解约通知时必须，`USER`(用户主动解约)、`MERCHANT`(商户解约)、`PLATFORM`(商户解约平台解约)

签约通知示例

curl -X POST ${YOUR_NOTIFY_URL} \
--header 'Content-Type: application/json' \
--header 'Signature: ${signature}' \
--data '{
    "agreementId": "your agreementId",
    "userId": "contract user id",
    "contractId": "contract id",
    "contractNo": "our contract number",
    "reference": "your unique reference",
    "contractStatus": "Signed/Terminated",
    "signedAt": "yyyy-MM-dd'T'HH:mm:ss.SSSZZZ",
    "terminateAt": "yyyy-MM-dd'T'HH:mm:ss.SSSZZZ",
    "terminateMode": "USER/MERCHANT/PLATFORM",
}'

签约通知签名

signature = MD5(body + '&' + MD5(token))

回调通知重试机制

最多通知7次
通知的间隔频率为：0m,1m,2m,4m,8m,20m,30m

分账

分账功能描述

分账功能是指将支付订单款项中的一部分金额支付给多个收款方的功能。

分账规则

同一币种的全局分账仅能存在一个,且随时可以取消.
对支付订单的分账可以执行多次,但累计的分账金额和费用总和不能超过原支付订单结算金额.
对支付订单发起的分账订单状态初始为待分账状态,每天北京时间 23:00 开始陆续执行,分账成功后状态变更为成功,分账失败后状态变更为失败.
待分账状态的分账订单可以直接取消,不能对待分账状态的分账订单发起撤销分账.
分账订单状态为成功的分账订单不能取消,可以对成功的分账订单发起撤销分账.
撤销分账可以全量取消也可以执行多次部分撤销,但累计撤销金额和费用总和不能超过原分账订单结算金额.
由于分账会产生手续费,因此无论是分账或者是撤销分账的累计总金额都不能超过原支付订单或分账订单扣除手续费后的金额,或许你可能需要设置为手续费从源账户扣除.
商户仅能对自己的支付订单进行分账.
平台型商户能够对所属的所有商户的支付订单发起分账.
分账的最大次数限制请联系 BD 进行咨询.

分账的实际效果说明

前置条件

支付订单 100 美元,平台收取手续费 2 美元,商户 A 实际结算到手 98 美元.
商户 A 发起分账,分账比例为 10%到商户 B,手续费 2%
支付手续费费率 2%,分账手续费费率 2%

场景 1 手续费从交易中扣除

账户	分账金额	手续费	到手金额
商户 A	-9.8	0.00	-9.8
商户 B	9.8	0.196	9.604

场景 2 手续费从源账户扣除

账户	分账金额	手续费	到手金额
商户 A	-9.8	0.196	-9.996
商户 B	9.8	0.00	9.80

撤销分账的实际效果说明

前置条件

支付订单 100 美元,平台收取手续费 2 美元,商户 A 实际结算到手 98 美元.
商户 A 发起分账,分账比例为 10%到商户 B,手续费 2%.
商户 A 发起撤销分账,注意原分账订单有可能因为扣除手续费,导致不能原金额撤销
支付手续费费率 2%,分账手续费费率 2%,撤销分账手续费费率 2%

场景 1 手续费从交易中扣除

账户	分账金额	手续费	到手金额
商户 A	-9.8	0.00	-9.8
商户 B	9.8	0.196	9.604
商户 A	9.604	0.19208	9.41192
商户 B	-9.604	0.00	-9.604

场景 2 手续费从源账户扣除

账户	分账金额	手续费	到手金额
商户 A	-9.8	0.196	-9.996
商户 B	9.8	0.00	9.80
商户 A	9.8	0.00	9.8
商户 B	-9.8	0.196	-9.996

固定金额分账金额说明

JPY,KRW,VND 等常见货币的最小单位是元,当 currency 是这些货币时,splitValue 的单位是元,例如 splitValue=1000,即分账 1000 元.
USD,CNY 等常见货币的最小单位是分,当 currency 是这些货币时,splitValue 的单位是分,例如 splitValue=1023,即分账 10.23 元.

参数说明

参数	是否必须	类型	说明
reference	`不为空`	string(240)	分账发起方单号,分账配置唯一性判断依据
sharingType	`不为空`	int	0:分账,2:撤销分账
splitMethod	`有条件`	int	0: 百分比分账, 1:固定金额分账
splitValue	`有条件`	int	当 splitMethod=0 时为分账百分比,精度万分之一,例如传 1023 即为 10.23% 当 splitMethod=1 时为实际分账金额(货币的最小单位)币种规则
targetMerCode	`有条件`	string(11)	分账的收款方商户
sourceMerCode	`可选`	string(11)	分账的资金来源商户,不传则为当前商户
currency	`有条件`	string(3)	币种, 例如 USD,CNY 等,全局分账时必须
relationTxnId	`有条件`	string(21)	要分账的支付订单 id, nihaopay 的 transactionId, 不传时是全局分账配置,生产环境请谨慎配置
remark	`可选`	string(128)	备注, 在查看订单详情时会出现在订单描述的位置
feeFrom	`可选`	int	0:手续费从交易中扣除 1:手续费从源账户扣除默认 0
baseFrom	`可选`	int	撤销分账时如果指定按百分比的基准金额 0: 原支付订单的结算金额 1: 原分账订单的结算金额 2: 原支付订单的订单金额默认 0
originConfId	`有条件`	string(21)	取消分账时原分账配置 id
notifyUrl	`可选`	string(240)	分账结果回调通知地址,失败或成功都会通知,数据格式

分账接口

postman 配置下载

场景:发起全局按比例分账

curl --location 'https://api.nihaopay.com/v1.2/sharing/apply' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <TOKEN>' \
--data '{
    "sharingType": 0,
    "splitMethod": 0,
    "splitValue": 10,
    "reference": "20211111153109001472",
    "targetMerCode": "M001000001",
    "currency": "USD",
    "remark": "test remark",
    "notifyUrl": "https://www.nihaopay.com/sharing/notify"
}'

场景:对指定订单发起按比例分账

curl --location 'https://api.nihaopay.com/v1.2/sharing/apply' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <TOKEN>' \
--data '{
    "relationTxnId": "20211111153109001472",
    "sharingType": 0,
    "splitMethod": 0,
    "splitValue": 1000,
    "targetMerCode": "M001000001",
    "reference": "20211111153109001472",
    "remark": "test remark",
    "notifyUrl": "https://www.nihaopay.com/sharing/notify"
    "currency": "USD"
}'

场景:对指定订单发起固定金额分账

curl --location 'https://api.nihaopay.com/v1.2/sharing/apply' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <TOKEN>' \
--data '{
    "relationTxnId": "20211111153109001472",
    "sharingType": 0,
    "splitMethod": 1,
    "splitValue": 100,
    "targetMerCode": "M001000001",
    "reference": "20211111153109001472",
    "remark": "test remark",
    "notifyUrl": "https://www.nihaopay.com/sharing/notify"
    "currency": "USD"
}'

场景:对分账订单发起部分撤销分账

curl --location 'https://api.nihaopay.com/v1.2/sharing/apply' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <TOKEN>' \
--data '{
    "relationTxnId": "20211111153109001472",
    "sharingType": 2,
    "splitMethod": 0,
    "splitValue": 10,
    "reference": "20211111153109001472",
    "remark": "test remark",
    "notifyUrl": "https://www.nihaopay.com/sharing/notify",
    "originConfId": "20211111153109001472",
}'

场景:对分账订单发起全量撤销分账

curl --location 'https://api.nihaopay.com/v1.2/sharing/apply' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <TOKEN>' \
--data '{
    "relationTxnId": "20211111153109001472",
    "sharingType": 2,
    "reference": "20211111153109001472",
    "remark": "test remark",
    "notifyUrl": "https://www.nihaopay.com/sharing/notify",
    "originConfId": "20211111153109001472",
}'

分账发起成功响应

{
  "confId": "20230804021118097285"
}

分账发起失败响应

{
  "code": 400,
  "label": "N/A",
  "message": "sharing conf already exists"
}

查询当前分账配置

查询所有分账配置

curl --location 'https://apitest.nihaopay.com/v1.2/sharing/query' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <TOKEN>' \
--data '{}'

查询指定支付订单的分账配置

curl --location 'https://apitest.nihaopay.com/v1.2/sharing/query' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <TOKEN>' \
--data '{
    "relationTxnId": "20230804021118097285"
}'

分账配置成功响应

{
  "relationTxnId": "20230804021118097285",
  "sharingConfItems": [
    {
      "confId": "20230804021822097288",
      "reference": "9200",
      "originConfId": "",
      "relationTxnId": "20230804021118097285",
      "sourceMerCode": "M001000001",
      "targetMerCode": "M001000002",
      "sharingType": 0,
      "splitMethod": 0,
      "splitValue": 22,
      "currency": "USD",
      "txnStatus": "SUCCESS",
      "failReason": "",
      "feeFrom": 0,
      "baseFrom": 0,
      "remark": "test",
      "notifyUrl": "https://www.nihaopay.com/sharing/notify"
    }
  ]
}

分账配置失败响应

{
  "relationTxnId": "",
  "sharingConfItems": []
}

查询当前分账执行结果

请求示例

curl --location 'https://apitest.nihaopay.com/v1.2/sharing/detail' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <TOKEN>' \
--data '{
    "relationTxnId": "20230804021118097285",
    "confId": "20230804021822097288"
}'

成功响应示例

{
  "id": 37,
  "initMerCode": "M001000003",
  "sourceMerCode": "M001000001",
  "targetMerCode": "M001000002",
  "clearBatchId": "20230804022158056882",
  "clearBatchDate": 1691107200000,
  "sharingType": 0,
  "splitMethod": 0,
  "splitValue": 22,
  "sharingAmount": 0.29,
  "serviceFee": 0.01,
  "sharingCurrency": "USD",
  "relationTxnId": "20230804021118097285",
  "relationTxnNetSettlementAmount": 130.75,
  "sharingConfId": "20230804021822097288",
  "originSharingConfId": "",
  "reference": "9200",
  "isGlobalSharing": 0,
  "feeFrom": 0,
  "baseFrom": 0,
  "sharingStatus": 1,
  "notifyUrl": "https://nihaopay.com/sharing/notify",
  "notifyStatus": 1,
  "failReason": "",
  "createAt": 1691115721000
}

失败响应示例

{
  "code": 400,
  "label": "N/A",
  "message": "sharing history not exist"
}

取消分账

请求

curl --location 'https://apitest.nihaopay.com/v1.2/sharing/cancel' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <TOKEN>' \
--data '{
    "confId": "20230719002724096890"
}'

成功响应

{
  "confId": "20230719002724096890",
  "reason": "",
  "txnStatus": "SUCCESS"
}

失败响应

{
  "confId": "20230719002724096890",
  "reason": "sharing config not exist",
  "txnStatus": "FAIL"
}

分账回调

分账成功回调

{
  "sharingStatus": "SUCCESS",
  "sourceMerCode": "M001100001",
  "sharingConfId": "20230803211516007112",
  "targetSharingTxnAmount": 499,
  "txnType": "SHARE_PROFIT",
  "targetMerCode": "M086100129",
  "baseAmount": 2496,
  "reference": "TEST_20230803211516007112",
  "targetServiceFee": 10,
  "relationTxnId": "20230803211516007111",
  "rate": {
    "minAmount": 0,
    "percentage": 2,
    "txnCurrency": "USD",
    "refundReturn": 0,
    "fixedAmount": 0,
    "maxAmount": 0
  },
  "sourceSharingTxnAmount": -499,
  "txnCurrency": "USD",
  "sourceServiceFee": 0
}

分账失败回调

{
  "sharingStatus": "FAIL",
  "sourceMerCode": "M001100001",
  "sharingConfId": "20230803211516007112",
  "txnType": "SHARE_PROFIT",
  "targetMerCode": "M086100129",
  "reference": "TEST_20230803211516007112",
  "relationTxnId": "20230803211516007111",
  "failReason": "balance not enough"
}

退款/查询等接口

查询订单状态

GET
https://api.nihaopay.com/v1.2/transactions/merchant/{reference}

请求示例

$ curl https://api.nihaopay.com/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`	NihaoPay生成的唯一交易流水号.
status `string`	交易状态. 包括：支付成功 `success`, 支付失败`failure`, 支付中`pending`, 交易关闭`closed`.
vendor `string`	付款方式. 包括：银联 `unionpay`, 支付宝`alipay`, 微信支付`wechatpay`, 支付宝香港钱包`alipayhk`.
vendor_id `string`	付款成功后在支付渠道的支付流水号，通常显示在客户的付款凭证上
amount `int`	订单金额.
currency `string`	订单币种.
time `string`	交易在NihaoPay中的完成时间. 例如: `2015-01-01T01:01:00Z`(NihaoPay使用的是UTC时区).
reference `string`	商户订单号.
note `string`	商户备注，与请求一直，如果请求是为空，则该字段为 null.

查询交易详情

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

请求示例

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

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

请求报文

transaction_id NihaoPay唯一的交易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`	NihaoPay生成的唯一交易流水号
status `string`	交易状态. 包括：支付成功 `success`, 支付失败`failure`, 支付中`pending`, 交易关闭`closed`
type `string`	交易类型，包括：直接消费 `charge`, 预授权`authorization`, 预授权完成`capture`
vendor `string`	付款方式. 包括：银联 `unionpay`, 支付宝`alipay`, 微信支付`wechatpay`, 支付宝香港钱包`alipayhk`.
vendor_id `string`	付款成功后在支付渠道的支付流水号，通常显示在客户的付款凭证上
amount `int`	订单金额
currency `string`	订单币种
time `string`	交易在NihaoPay系统中的完成时间. 例如: `2015-01-01T01:01:00Z`(NihaoPay使用的是UTC时区)
reference `string`	商户订单号
note `string`	商户备注，与请求一致，如果请求为空，则返回null

申请退款

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

请求示例

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

商户可以对已经付款成功的交易发起全额或者部分退款，每笔交易商户可以发起多次部分退款，但累计退款金额不得大于原交易金额。根据支付方式不同，订单退款期限也不同，银联付款成功的交易可在180天内退款，支付宝和微信付款成功的交易可在1年内发起退款。

请求报文

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

字段	说明
currency `不为空`	退款币种，与原交易币种一致。
amount `有条件的`	退款外币金额，交易币种对应的最小单位，人民币为分，日元最小单位为元。退款金额必须等于或小于原交易金额。
rmb_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.nihaopay.com/v1.2/transactions/refunds/{transaction_id}/

请求示例

$ curl https://api.nihaopay.com/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`	NihaoPay生成的唯一支付交易流水号
status `string`	交易状态. 包括：支付成功 `success`, 支付失败`failure`, 支付中`pending`, 交易关闭`closed`
type `string`	交易类型，包括：直接消费 `charge`, 预授权`authorization`, 预授权完成`capture`
amount `int`	订单金额
currency `string`	订单币种
time `string`	交易在NihaoPay系统中的完成时间. 例如: `2015-01-01T01:01:00Z`(NihaoPay使用的是UTC时区)
reference `string`	商户订单号
note `string`	商户备注，与请求一致，如果请求为空，则返回null
vendor `string`	付款方式. 包括：银联 `unionpay`, 支付宝`alipay`, 微信支付`wechatpay`, 支付宝香港钱包`alipayhk`.
vendor_id `string`	付款成功后在支付渠道的支付流水号，通常显示在客户的付款凭证上
refunded_amount `int`	累计退款金额
refunds `list`	退款记录
refund_time `string`	退款发起时间
refund_id `string`	退款交易流水号
refunded_amount `int`	退款金额
status `string`	退款状态

批量查询交易信息

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

请求示例

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

返回满足要求的交易列表，返回交易按照时间倒序排列，按照limit参数要求返回对应的条数，默认返回10条记录。只有SecurePay的交易会被返回。如果要查看撤销，退款等交易信息，请登录商户交易管理后台(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`	NihaoPay生成的唯一交易ID
status `string`	交易状态. 包括：支付成功 `success`, 支付失败`failure`, 支付中`pending`, 交易关闭`closed`
type `string`	交易类型，包括：直接消费 `charge`, 预授权`authorization`, 预授权完成`capture`
amount `int`	订单金额
currency `string`	订单币种
time `string`	交易在NihaoPay系统中的完成时间. 例如: `2015-01-01T01:01:00Z`(NihaoPay使用的是UTC时区)
reference `string`	商户订单号
note `string`	商户备注，与请求一致，如果请求为空，则返回null

汇率查询接口

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

如果商户网站的商品以外币标价，可以使用这个接口来查询当前支付渠道方的参考汇率。一般情况下，汇率更新时间为北京时间上午10:30，一天更新一次(频率限制: 每分钟1次,建议每天仅查询一次即可)。

请求示例

$ curl https://api.nihaopay.com/v1.2/exchangerate/?rate_date=20170308&currency=USD \
-H "Authorization: Bearer <TOKEN>"

请求报文

使用GET方式请求，如果不指定vendor参数，默认返回所有渠道的汇率。

字段	说明
rate_date `不为空`	要查询的汇率日期，格式为YYYYMMDD
currency `不为空`	外币币种，当前NihaoPay接受的币种有：`USD` 美元, `JPY` 日元, `HKD` 港币, `GBP` 英镑 and `EUR` 欧元
vendor `允许为空`	渠道方，目前支付宝 `alipay`，微信支付 `wechatpay`和银联 `unionpay`使用的汇率不一致，您可以指定该参数查询某一渠道的汇率。

返回示例

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

返回报文

如果请求成功，返回一个json格式的汇率列表。

字段	说明
rate_date `string`	汇率日期，格式为YYYYMMDD
currency `string`	外币币种
vendor `string`	支付宝 `alipay`，微信支付 `wechatpay` 或银联 `unionpay`
rate `string`	外币币种兑换人民币的汇率

交易下载

GET
https://api.nihaopay.com/v1.2/download/transactions

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

请求示例

$ curl https://api.nihaopay.com/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.nihaopay.com/v1.2/billing

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

请求示例

$ curl https://api.nihaopay.com/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.nihaopay.com/v1.2/accounts

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

请求示例

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

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

请求示例

$ curl https://api.nihaopay.com/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`	NihaoPay生成的withdrawal ID
status `string`	提款状态. 包括：处理中 `processing`, 完成`completed`
amount `int`	提款金额
currency `string`	到账币种
fee `string`	提款手续费
fee_currency `string`	手续费扣费币种
date `string`	提款日期，格式：YYYYMMDD

查询提现明细

GET
https://api.nihaopay.com/v1.2/withdrawal/detail/{withdrawal_id}

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

请求示例

$ curl https://api.nihaopay.com/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网站上申请一个测试账号来进行接入测试。

测试卡

当您通过NihaoPay API请求银联在线支付时，请使用以下测试卡模拟交易。

银联信用卡一


卡号	6250 9470 0000 0014
校验码	123
有效期	12/2033
手机号	852-11112222
短信验证码	111111

借记卡


卡号	6226 0900 0000 0048
密码	123456
手机号	1810000000
短信验证码	111111

支付宝测试账号

测试账号


账号	forex_1701852082070@alitest.com
登录密码	111111
支付密码	111111

微信支付测试信息

我们不提供微信的测试账号，您可以使用您自己的微信账号进行支付测试。一旦您支付成功造成扣款，您可以请求退款或撤销接口将已扣款资金退回至元账户，我们也会在每个月的1号将前一个月在测试环境下支付成功的微信交易全部退款.

错误码

错误示例

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

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

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

错误对象

字段	描述
code `int`	HTTP状态码.
label `string`	NihaoPay的错误代码，请提供该字段以便于我们追踪错误信息。
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 NihaoPay customer service. 支付方式受限制，请联系NihaoPay
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 商户配置错误，请联系NihaoPay
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 系统错误，请联系NihaoPay
401	301	Invalid merchant credentials provided 无效的认证信息，或身份验证失败

API更新日志

2025-01-16

新增微信代扣支付

2024-09-18

新增信用卡支付

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