NAV
cURL

文档简介

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支持的币种取值列表：

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.订单商品信息

form 请求参数示例

items[0][name]=T-Shirt&items[0][unitAmount]=500&items[0][quantity]=1&items[1][name]=Hat&items[1][unitAmount]=500&items[1][quantity]=2

items 是一个数组，每个元素代表一个商品。数组中的每个元素包含以下字段：

字段名称 描述
items 商品信息列表，包含一个或多个商品对象。
items[n].name
不为空		 商品名称。
items[n].unitAmount
不为空		 商品单价信息，与订单currency对应。金额为对应货币中的最小单位。详见接口规则。
items[n].quantity
不为空		 商品数量。

商品总金额应等于订单总金额:

amount = (items[0].unitAmount * items[0].quantity + items[1].unitAmount * items[1].quantity + ...)

6.付款方式

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

7. 通知URL

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

8. 终端

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

sys_reserve = {"vendor_id":"4200000117201806013734875340"}

9. 系统保留域

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

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

异步通知

异步返回说明

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

针对ipn_url要求如下：

异步返回示例

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. 关键信息对和合作密钥信息对的拼接方法为：

B. 签名方法

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

注意：

安全支付

标准安全支付

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 items[0].name="T-Shirt Test" \
-d items[0].unitAmount=100 \
-d items[0].quantity=1 \
-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 items[0].name="T-Shirt Test" \
-d items[0].unitAmount=100 \
-d items[0].quantity=1 \
-d ipn_url="http://website.com/ipn" \
-d in_wechat="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位的字母，数字和'-'组合，必须在商户系统中唯一。详见接口规则
items
允许为空		 订单商品列表，详见接口规则。
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即可
orderId
有条件的		 PayPal Order Id，用于商户使用PayPal Javascript SDK创建订单参考代码。
form
有条件的		 form表单对象,和url互斥,当url不存在时则form对象存在
form.actionUrl
不为空		 form表单的action属性
form.method
不为空		 form表单的method属性
form.target
不为空		 form表单的target属性
form.params
不为空		 form表单的参数，map格式，key为参数名，value为参数值。

同步返回

  1. HTML格式响应 >安全支付接口同步返回一个HTML页面，商家请展示该页面在浏览器上，页面将自动跳转到支付服务方上的支付页面。
  2. 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位的字母，数字和’-‘组合，必须在商户系统中唯一。
items
允许为空		 订单商品列表，详见接口规则。
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位的字母，数字和’-‘组合，必须在商户系统中唯一。
items
允许为空		 订单商品列表，详见接口规则。
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位的字母，数字和’-‘组合，必须在商户系统中唯一。
items
允许为空		 订单商品列表，详见接口规则。
ipn_url
不为空		 支付通知接收的URL。详见异步通知
callback_url
有条件的		 Terminal=ONLINE 或 terminal=WAP 时必须, 支付完成后浏览器返回商户网站的URL。
description
允许为空		 订单描述，可以订单商品信息摘要等，会显示在支付页面和客户付款收据中。
note
允许为空		 供商家使用的备注字段，NihaoPay不做处理，在返回时，原数据将返回给商户。
timeout
允许为空
默认: 10		 订单超时时间，在NihaoPay接受到订单请求后，如果在timeout（分钟）指定的时间内，客户未付款的，订单将会被关闭。接受的范围为1 - 10。
terminal
允许为空
默认： ONLINE		 指定支付页面是在PC(ONLINE) 上显示，应用程序(APP)，小程序(MICRO)，还是手机浏览器mobile (WAP)上显示。
ostype
有条件的		 指定支付页面是在Android手机(ANDROID) 上显示，还是iphone手机 (IOS)上显示，terminal=WAP 或 terminal=APP或 terminal=MICRO 时必须。
wallet
允许为空		 默认：CONNECT_WALLET,可选值ALIPAY_CN,ALIPAY_HK,TRUEMONEY,TNG,GCASH,DANA,KAKAOPAY，CONNECT_WALLET时展示所有可用钱包,由支付者自行选择。

返回示例

{
    "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位的字母，数字和’-‘组合，必须在商户系统中唯一。
items
允许为空		 订单商品列表，详见接口规则。
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位的字母，数字和'-'组合，必须在商户系统中唯一。详见接口规则
items
允许为空		 订单商品列表，详见接口规则。
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位的字母，数字和’-‘组合，必须在商户系统中唯一。
items
允许为空		 订单商品列表，详见接口规则。
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位的字母，数字和'-'组合，必须在商户系统中唯一。详见接口规则
items
允许为空		 订单商品列表，详见接口规则。
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。

请求参数说明

支持的申报海关包括：

返回示例

{
    "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:商户上传的订购人身份信息与支付人身份信息不一致

支付企业海关注册编号

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

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

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

海关 支付宝备案号
总署 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. 已退款订单不能申报

代扣

代扣功能描述

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

代扣规则

  1. 同一个合约同一个用户只能签约一次, 重复签约会返回签约失败
  2. 签约后商户和用户都可以解约
  3. 扣款后全额退款不会返还周期内剩余扣款次数
  4. 代扣目前仅支持微信支付
  5. 当前微信代扣限制
    • 单笔限额：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))

回调通知重试机制

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

分账

分账功能描述

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

分账规则

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

分账的实际效果说明

前置条件

  1. 支付订单 100 美元,平台收取手续费 2 美元,商户 A 实际结算到手 98 美元.
  2. 商户 A 发起分账,分账比例为 10%到商户 B,手续费 2%
  3. 支付手续费费率 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

撤销分账的实际效果说明

前置条件

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

固定金额分账金额说明

  1. JPY,KRW,VND 等常见货币的最小单位是元,当 currency 是这些货币时,splitValue 的单位是元,例如 splitValue=1000,即分账 1000 元.
  2. 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/refund/{transaction_id}

请求示例

$ curl https://api.nihaopay.com/v1.2/transactions/refund/{transaction_id} \
-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号将前一个月在测试环境下支付成功的微信交易全部退款.

PayPal测试账号

测试账号
账号 sb-s47aho8657191@personal.example.com
登录密码 J^Fby/5@

错误码

错误示例

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

2023-08-05

2022-07-18

2020-09-01

2018-06-01

2018-05-17

2018-03-15

2017-11-10

2017-08-21

2017-05-25

2017-04-10

2017-03-07

2017-01-01

cURL