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支付,支付二维码和线下扫码支付。

安全支付

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

信用卡快捷支付

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

APP支付

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

支付二维码

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

扫码支付

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

应用场景

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

付款方式 →
应用场景 ↓
支付宝
AliPay
微信支付
WechatPay
银联
UnionPay
PC 浏览器
terminal=ONLINE
标准安全支付 标准安全支付
微信二维码
标准安全支付
信用卡快捷支付
手机浏览器
terminal=WAP
标准安全支付 NA 标准安全支付
信用卡快捷支付
微信浏览器
terminal=WAP
NA 标准安全支付
currency=USD
currency=EUR
currency=JPY
标准安全支付
信用卡快捷支付
In-APP APP支付 APP支付
接入前请先提供AppID
APP支付
微信小程序 NA 微信小程序支付
接入前请先提供小程序AppID
NA
线下商户主扫
扫码支付 扫码支付 扫码支付
仅限美国地区商户
线下商户被扫
展示二维码
固定二维码
展示二维码 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.付款方式

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

IPN通知示例

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

6. 通知URL

接口中callback_urlipn_url 必须是在Internet中可以访问的地址,不能是内网地址(如localhost)或内网IP。

在处理callback和ipn的返回时,需要注意:

7. 终端

Terminal 参数支持ONLINEWAP两种,具体使用规则参见应用场景

sys_reserve = {"vendor_id":"4200000117201806013734875340"}

8. 系统保留域

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

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

签名方法

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

9. 异步通知签名校验

在异步通知返回时,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 ipn_url="http://website.com/ipn" \
-d callback_url="http://website.com/callback"

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

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

请求报文

参数 说明
currency
不为空
订单币种,3位货币代码. 当前NihaoPay接受的币种有:USD 美元, JPY 日元, HKD 港币, GBP 英镑, EUR 欧元 和CAD 加拿大元。
amount
有条件的
订单外币金额,与currency对应。金额为对应货币中的最小单位。详见接口规则
rmb_amount
有条件的
订单人民币金额,使用人民币标价替代外币金额标价。金额单位为分,如金额为100时,表示1.00元人民币。详见接口规则
vendor
不为空
付款方式,客户付款时选择的支付方式,目前支持支付宝 alipay,微信支付 wechatpay和银联 unionpay
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天)

同步返回

安全支付接口同步返回一个HTML页面,商家请展示该页面在浏览器上,页面将自动跳转到支付服务方上的支付页面。

异步返回示例

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 urlIPN 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 reference="jkh25jh1348fd89sg" \
-d ipn_url="http://website.com/ipn"

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

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

请求报文

字段 说明
amount
不为空
订单金额,金额为对应货币中的最小单位。详见接口规则
currency
不为空
订单币种,3位货币代码. 当前NihaoPay接受的币种有:USD 美元, JPY 日元, HKD 港币, GBP 英镑 and EUR 欧元.
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"

请求报文

字段 说明
amount
不为空
订单金额,金额为对应货币中的最小单位。详见接口规则
currency
不为空
订单币种,3位货币代码. 当前NihaoPay接受的币种有:USD 美元, JPY 日元, HKD 港币, GBP 英镑, EUR 欧元 和CAD 加拿大元 .
vendor
不为空
付款方式,客户付款时选择的支付方式,支持支付宝alipay , 微信支付wechatpay 和银联 unionpay
reference
不为空
商户订单号,1-30位的字母,数字和’-‘组合,必须在商户系统中唯一。
ipn_url
不为空
支付通知接收的URL。详见接口规则
description
允许为空
订单描述,可以订单商品信息摘要等,会显示在支付页面和客户付款收据中。
note
允许为空
供商家使用的备注字段,NihaoPay不做处理,在返回时,原数据将返回给商户。

返回示例

{
    "orderInfo": "orderinfo string....."
}

返回报文

字段 说明
orderInfo
string
用于调起渠道方sdk的订单信息,具体使用参见NihaoPay提供的IOS Demo or Android Demo。微信支付的In-app功能需要特殊流程,如果要开通,请联系NihaoPay获取帮助。

微信小程序支付

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

商家在小程序内,请求预下单接口,生成预下单的支付参数,使用小程序的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"

请求报文

字段 说明
amount
不为空
订单金额,金额为对应货币中的最小单位。详见接口规则
currency
不为空
订单币种,3位货币代码. 当前微信小程序接口支持的币种有:USD 美元,JPY 日元,EUR欧元.
reference
不为空
商户订单号,1-30位的字母,数字和’-‘组合,必须在商户系统中唯一。
ipn_url
不为空
支付通知接收的URL。详见接口规则
client_ip
不为空
用户客户端IP
open_id
不为空
用户标识,微信用户在商户小程序内的唯一标识,获取方式请点击这里.
description
允许为空
订单描述,可以订单商品信息摘要等,会显示在支付页面和客户付款收据中。
note
允许为空
供商家使用的备注字段,NihaoPay不做处理,在返回时,原数据将返回给商户。

成功返回示例

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

返回报文

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

信用卡快捷支付

直接消费

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

请求示例

$ curl https://api.nihaopay.com/v1.2/transactions/expresspay \
-H "Authorization: Bearer <TOKEN>" \
-d amount=100 \
-d currency="USD" \
-d card_number="6221558812340000" \
-d card_exp_month=11 \
-d card_exp_year=2017 \
-d card_cvv="123" \
-d client_ip="180.167.25.154"

银联卡快捷支付不需要客户跳转至银联付款页面。在商户端输入信用卡信息,请求ExpressPay API完成扣款,快捷支付仅支持中国发行的银联信用卡。

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

请求报文

字段 说明
currency
不为空
订单币种,3位货币代码. 当前NihaoPay接受的币种有:USD 美元, JPY 日元, HKD 港币, GBP 英镑, EUR 欧元 和CAD 加拿大元。
amount
不为空
订单金额,金额为对应货币中的最小单位。详见接口规则
card_number
不为空
卡号,16位或19号纯数字的卡号.
card_exp_month
不为空
卡片有效期的月份,2位数字,如1月,表示为 01.
card_exp_year
不为空
卡片有效期的年份,4位数字,如2020年.
card_cvv
不为空
卡片验证码,信用卡背面的的3位数字验证码.
client_ip
不为空
客户端IP
description
允许为空
订单描述.
note
允许为空
供商家使用的备注字段,NihaoPay不做处理,在返回时,原数据将返回给商户。
reference
允许为空
商户订单号,1-30位的字母,数字和’-‘组合,必须在商户系统中唯一.

返回示例

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

返回报文

返回一个交易对象。

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

预授权

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

请求示例

$ curl https://api.nihaopay.com/v1.2/transactions/expresspay \
-H "Authorization: Bearer <TOKEN>" \
-d amount=100 \
-d currency="USD" \
-d card_number="6221558812340000" \
-d card_exp_month=11 \
-d card_exp_year=2017 \
-d card_cvv="123" \
-d client_ip="180.167.25.154" \
-d capture="false" 

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

请求报文

字段 说明
amount
Required
订单金额,金额为对应货币中的最小单位。详见接口规则
currency
Required
订单币种,3位货币代码. 当前NihaoPay接受的币种有:USD 美元, JPY 日元, HKD 港币, GBP 英镑, EUR 欧元 和CAD 加拿大元.
card_number
Required
卡号,16位或19号纯数字的卡号.
card_exp_month
不为空
卡片有效期的月份,2位数字,如1月,表示为 01.
card_exp_year
不为空
卡片有效期的年份,4位数字,如2020年.
card_cvv
不为空
卡片验证码,信用卡背面的的3位数字验证码.
client_ip
不为空
客户端IP
capture
不为空
固定值: false
description
允许为空
订单描述.
note
允许为空
供商家使用的备注字段,NihaoPay不做处理,在返回时,原数据将返回给商户。
reference
允许为空
商户订单号,1-30位的字母,数字和’-'组合,必须在商户系统中唯一。

返回示例

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

返回报文

字段 说明
id
string
NihaoPay生成的唯一交易流水号
status
string
交易状态. 包括:支付成功 success, 支付失败failure, 支付中pending, 交易关闭closed
amount
int
订单金额
currency
string
订单币种
captured
bool
false
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}/release

请求示例

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

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

请求报文

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

返回示例

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

返回报文

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

预授权完成

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

请求示例

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

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

请求报文

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

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

返回示例

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

返回报文

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

线下面对面支付

扫码支付

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位货币代码. 当前NihaoPay接受的币种有:USD 美元, JPY 日元, HKD 港币, GBP 英镑, EUR 欧元 和CAD 加拿大元。
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位货币代码. 当前NihaoPay接受的币种有:USD 美元, JPY 日元, HKD 港币, GBP 英镑, EUR 欧元 和CAD 加拿大元。
vendor
不为空
付款方式,客户付款是选择的支付方式,目前支持微信支付wechatpay和支付宝alipay
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位货币代码. 当前NihaoPay接受的币种有:USD 美元, JPY 日元, HKD 港币, GBP 英镑, EUR 欧元 和CAD 加拿大元。
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位货币代码. 当前NihaoPay接受的币种有:USD 美元, JPY 日元, HKD 港币, GBP 英镑, EUR 欧元 和CAD 加拿大元。
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 spilt=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
允许为空
默认:false
是否拆单,true or false 默认为不拆单
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"
}

返回报文

字段 说明
id
string
NihaoPay生成的报关流水号.
status
string
报关状态. 包括:成功 success, 失败failure, 报关中pending.
transaction_id
string
原交易流水号

报关查询接口

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

返回报文

字段 说明
id
string
报关请求ID
transaction_id
string
原支付交易ID
vendor_id
string
原支付交易在渠道方的流水号
status
string
报关状态, 包括:成功 success, 失败failure, 报关中pending.
customs
string
申报海关
customs_amount
string
报关人民币金额,以分为单位
duty_amount
string
关税,以分为单位。部分海关需要上报关税信息
split
string
是否拆单,默认为不拆单
sub_order_id
string
商户子订单号,在拆单情况下,该字段不能为空
product_amount
string
商品金额,以分为单位。在拆单情况下,该字段不能为空
transport_amount
string
物流费用,以分为单位。在拆单情况下,该字段不能为空

退款/查询等接口

申请退款

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"

商户可以对已经付款成功的交易发起全额或者部分退款,每笔交易商户可以发起多次部分退款,但累计退款金额不得大于原交易金额。根据支付方式退款不同,订单退款期限也不同,支付宝付款的交易在90天内可以退款,银联付款成功的交易可在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
是否退款, truefalse
transaction_id
string
原支付交易ID

查询订单状态

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.
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,ExpressPay和Captured的交易会被返回。如果要查看撤销,退款等交易信息,请登录商户交易管理后台(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
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/

请求示例

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

返回满足要求的交易列表,返回交易按照时间倒序排列,按照limit参数要求返回对应的条数,默认返回10条记录。 只有SecurePay,ExpressPay和Captured的交易会被返回。如果要查看撤销,退款等交易信息,请登录商户交易管理后台(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,一天更新一次。

请求示例

$ 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
当前未结算退款金额

申请提现

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

商家请求该接口完成一笔提现申请。

请求示例

$ curl https://api.nihaopay.com/v1.2/withdrawal \
-H "Authorization: Bearer <TOKEN>"  \
-d currency="USD" \
-d full_withdrawal="true"

请求

使用POST方式请求.

字段 说明
currency
不为空
提款币种,与账户币种一致
full_withdrawal
不为空
是否全额提现,即将当前账户的余额全部提出。 true表示全部提现,false时需要指定提现金额
amount
允许为空
提现金额,精确到币种对应的最小单位,当full_withdrawal = false时,该参数不能为空。

返回示例

{
  "id": "20170818112016001805",
  "amount": "1000",
  "status": "success",
  "withdrawal_fee": "0",
  "currency": "USD"
}

返回

字段 说明
id
string
NihaoPay生成的唯一提款交易号.
status
string
交易状态. 包括:提款成功 success
amount
int
提现金额,精确到币种对应的最小单位.
currency
string
提现币种.
withdrawal_fee
int
提现交易产生的手续费,精确到币种对应的最小单位

查询提现历史记录

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请求银联在线支付时,请使用以下测试卡模拟交易。

信用卡一

卡号 6226 3880 0000 0095
校验码 248
有效期 12/2019
手机号 18100000000
短信验证码 111111

信用卡二

卡号 5200 8311 1111 1113
校验码 123
有效期 11/2019
手机号 13552535506
短信验证码 111111

借记卡

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

支付宝测试账号

测试账号

账号 douyufua@alitest.com
验证码 8888
登录密码 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 商户不可用
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更新日志

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