- auto-gen TOC: {:toc}
商户接入都能印共同体支付，调用API必须遵循以下规则：
| 规则 | 说明 |
|---|---|
| 传输方式 | 为保证交易安全性，采用HTTPS传输 |
| 提交方式 | 采用POST方法提交 |
| 数据格式 | 提交和返回数据都为JSON格式 |
| 字符编码 | 统一采用UTF-8字符编码 |
| 签名算法 | MD5 |
| 签名要求 | 请求和接收数据均需要校验签名 |
签名生成的通用步骤如下： 第一步，设所有发送或者接收到的数据为集合M，将集合M内非空参数值的参数按照参数名ASCII码从小到大排序（字典序），使用URL键值对的格式（即key1=value1&key2=value2…）拼接成字符串stringA。 特别注意以下重要规则：
- 参数名ASCII码从小到大排序（字典序）；
- 如果参数的值为空不参与签名；
- 参数名区分大小写；
- 验证调用返回或都能印主动通知签名时，传送的sign参数不参与签名，将生成的签名与该sign值作校验。
- 都能印接口可能增加字段，验证签名时必须支持增加的扩展字段
第二步，在stringA最后拼接上key得到stringSignTemp字符串，并对stringSignTemp进行MD5运算，再将得到的字符串所有字符转换为大写，得到sign值signValue。 举例： 假设传送的参数如下：
mchId： 10000100
body： test
nonceStr： ibuaiVcKdpRxkhJA
第一步：对参数按照key=value的格式，并按照参数名ASCII字典序排序如下：
stringA="body=test&mchId=10000100&nonceStr=ibuaiVcKdpRxkhJA";
第二步：拼接API密钥：
stringSignTemp=stringA+"&key=192006250b4c09247ec02edce69f6a2d" //注：key为商户平台设置的密钥key
sign=MD5(stringSignTemp).toUpperCase()="9A0A8659F005D6984697E2CA0A9CF3B7" //注：MD5签名方式
最终得到最终发送的数据：
{
"appid": "wxd930ea5d5a258f4f",
"mch_id": "10000100",
"device_info": "1000",
"body": "test",
"nonce_str": "ibuaiVcKdpRxkhJA",
"sign": "9A0A8659F005D6984697E2CA0A9CF3B7"
}
都能印支付API接口协议中包含字段nonceStr，主要保证签名不可预测。我们推荐生成随机数算法如下：调用随机数函数生成，将得到的值转换为字符串。
商户通过该接口进行交易的创建下单
https://www.dounengyin.net/apis/pay/dny/unifiedorder
| 参数 | 类型 | 必填 | 描述 | 示例值 |
|---|---|---|---|---|
| mchId | String(32) | 是 | 都能印共同体分配的商户号 | 182xxxx1439 |
| mchTradeNo | String(32) | 是 | 商户系统内部订单号，要求32个字符内，只能是数字、大小写字母且在同一个商户号下唯一 | OB20180521000001 |
| amount | Int | 是 | 订单总金额，单位为分 | 8888 |
| channelId | String(16) | 是 | 支付渠道类型，暂时固定为dny | dny |
| currencyCode | String(16) | 是 | 支付货币代码，都能印支持多种余额消费方式，常用为都能印余额，代码为tyy，其他代码可在线询问客服人员 | tyy |
| clientIp | String(16) | 否 | 支付提交用户端ip | 123.12.12.123 |
| device | String(16) | 否 | 终端设备号 | 自定义参数，可以为终端设备号 |
| subject | String(32) | 是 | 商品标题 | 商品简单描述 |
| body | String(128) | 否 | 商品描述 | 商品详细描述 |
| attach | String(128) | 否 | 附加数据，在支付通知中原样返回，可作为自定义参数使用 | 都能印共同体 |
| timeStart | String(14) | 否 | 订单生成时间，格式为yyyyMMddHHmmss，如2009年12月25日9点10分10秒表示为20091225091010 | 20091225091010 |
| timeExpire | String(14) | 否 | 订单失效时间，格式为yyyyMMddHHmmss，如2009年12月27日9点10分10秒表示为20091227091010 | 20091227091010 |
| notifyUrl | String(256) | 是 | 异步接收微信支付结果通知的回调地址，通知url必须为外网可访问的url，不能携带参数 | http://www.xxx.com/pay/notify.html |
| nonceStr | String(32) | 是 | 随机字符串，长度要求在32位以内 | 5K8264ILTKCH16CQ2502SI8ZNMTM67VS |
| sign_type | String(32) | 否 | 签名类型，为MD5 | MD5 |
| sign | String(32) | 是 | 通过签名算法计算得出的签名值 | C380BEC2BFD727A4B6845133519F3AD6 |
| 变量名 | 描述 | 示例值 |
|---|---|---|
| return_code | 返回状态码，此字段是通信标识，非交易标识，交易是否成功需要查看result_code来判断 | SUCCESS/FAIL |
| return_msg | 返回信息，如非空，为错误原因 签名失败 参数格式校验错误 |
参数中缺少mchId |
以下字段在return_code为SUCCESS返回
| 变量名 | 描述 | 示例值 |
|---|---|---|
| err_code | 错误代码 | 00001 |
| err_code_des | 错误代码描述 | 交易单已存在 |
| mch_id | 商户号 | 182xxxx1439 |
| pay_url | 支付链接网址 | https://www.dounengyin.net/pay.html |
| code_url | 暂不使用(支付二维码地址) | |
| nonce_str | 随机字符串，调用接口原样返回 | 5K8264ILTKCH16CQ2502SI8ZNMTM67VS |
| sign_type | 签名类型，为MD5 | MD5 |
| sign | 签名 | C380BEC2BFD727A4B6845133519F3AD6 |
| 错误代码 | 描述 | 原因 | 解决方案 |
|---|---|---|---|
| 00001 | 交易单已存在 | 同一笔交易不能多次提交 | 请核实商户订单号是否重复提交 |
| 00002 | 交易单已支付 | 商户订单已支付，无需重复操作 | 商户订单已支付，无需更多操作 |
| 00003 | 交易单已关闭 | 当前订单已关闭，无法支付 | 当前订单已关闭，请重新下单 |
| 00004 | 交易单已完成 | 当前订单已完成，无法支付 | 当前订单已完成(代表支付已经完成异步通知)，请重新下单 |
| 00005 | 服务加密错误 | 通知开发商 |
以下情况需要调用关单接口：商户订单支付失败需要生成新单号重新发起支付，要对原订单号调用关单，避免重复支付；系统下单后，用户支付超时，系统退出不再受理，避免用户继续，请调用关单接口。
https://www.dounengyin.net/apis/pay/dny/closeorder
| 参数 | 类型 | 必填 | 描述 | 示例值 |
|---|---|---|---|---|
| mch_id | String(32) | 是 | 都能印共同体分配的商户号 | 182xxxx1439 |
| out_trade_no | String(32) | 是 | 商户系统内部订单号，要求32个字符内，只能是数字、大小写字母且在同一个商户号下唯一 | OB20180521000001 |
| channel_id | String(16) | 是 | 支付渠道类型，暂时固定为dny | dny |
| nonce_str | String(32) | 是 | 随机字符串，长度要求在32位以内 | 5K8264ILTKCH16CQ2502SI8ZNMTM67VS |
| sign_type | String(32) | 否 | 签名类型，为MD5 | MD5 |
| sign | String(32) | 是 | 通过签名算法计算得出的签名值 | C380BEC2BFD727A4B6845133519F3AD6 |
| 变量名 | 描述 | 示例值 |
|---|---|---|
| return_code | 返回状态码，此字段是通信标识，非交易标识，交易是否成功需要查看result_code来判断 | SUCCESS/FAIL |
| return_msg | 返回信息，如非空，为错误原因 签名失败 参数格式校验错误 |
参数中缺少mchId |
以下字段在return_code为SUCCESS返回
| 变量名 | 描述 | 示例值 |
|---|---|---|
| err_code | 错误代码 | 00001 |
| err_code_des | 错误代码描述 | 交易单已存在 |
| mch_id | 商户号 | 182xxxx1439 |
| nonce_str | 随机字符串，调用接口原样返回 | 5K8264ILTKCH16CQ2502SI8ZNMTM67VS |
| sign_type | 签名类型，为MD5 | MD5 |
| sign | 签名 | C380BEC2BFD727A4B6845133519F3AD6 |
| 错误代码 | 描述 | 原因 | 解决方案 |
|---|---|---|---|
| 00001 | 交易单已支付 | 商户订单已支付，不能发起关单 | 订单已支付，不能发起关单，请当作已支付的正常交易 |
| 00002 | 交易单已关闭 | 当前订单已关闭，无法重复关闭 | 订单已关闭，无需继续调用 |
| 00003 | 交易单已退款 | 当前订单已退款，无法关闭 | 当前订单已已退款，无需继续调用 |
| 00005 | 交易单正在关闭过程中 | 交易单正在关闭过程中 |
当交易发生之后一段时间内，由于买家或者卖家的原因需要退款时，卖家可以通过退款接口将支付款退还给买家，都能印共同体将在收到退款请求并且验证成功之后，按照退款规则将支付款按原路退到买家帐号上
https://www.dounengyin.net/apis/pay/dny/refund
| 参数 | 类型 | 必填 | 描述 | 示例值 |
|---|---|---|---|---|
| mch_id | String(32) | 是 | 都能印共同体分配的商户号 | 182xxxx1439 |
| out_trade_no | String(32) | 是 | 商户系统内部订单号，要求32个字符内，只能是数字、大小写字母且在同一个商户号下唯一 | OB20180521000001 |
| out_refund_no | String(32) | 是 | 商户系统内部退款单号，要求32个字符内，只能是数字、大小写字母且在同一个商户号下唯一 | OB20180521000001 |
| refund_fee | Int | 是 | 退款金额，单位为分 | 8888 |
| channel_id | String(16) | 是 | 支付渠道类型，暂时固定为dny | dny |
| nonce_str | String(32) | 是 | 随机字符串，长度要求在32位以内 | 5K8264ILTKCH16CQ2502SI8ZNMTM67VS |
| sign_type | String(32) | 否 | 签名类型，为MD5 | MD5 |
| sign | String(32) | 是 | 通过签名算法计算得出的签名值 | C380BEC2BFD727A4B6845133519F3AD6 |
| 变量名 | 描述 | 示例值 |
|---|---|---|
| return_code | 返回状态码，此字段是通信标识，非交易标识，交易是否成功需要查看result_code来判断 | SUCCESS/FAIL |
| return_msg | 返回信息，如非空，为错误原因 签名失败 参数格式校验错误 |
参数中缺少mchId |
以下字段在return_code为SUCCESS返回
| 变量名 | 描述 | 示例值 |
|---|---|---|
| err_code | 错误代码 | 00001 |
| err_code_des | 错误代码描述 | 交易单已存在 |
| mch_id | 商户号 | 182xxxx1439 |
| nonce_str | 随机字符串，调用接口原样返回 | 5K8264ILTKCH16CQ2502SI8ZNMTM67VS |
| transaction_id | 都能印共同体订单号 | 1217752501201407033233368018 |
| out_trade_no | 商户订单号 | 1217752501201407033233368018 |
| out_refund_no | 商户退款单号 | 121775250 |
| sign_type | 签名类型，为MD5 | MD5 |
| sign | 签名 | C380BEC2BFD727A4B6845133519F3AD6 |
| 错误代码 | 描述 | 原因 | 解决方案 |
|---|---|---|---|
| 00001 | 交易单未支付，不能发起退款 | 交易单未支付，不能发起退款 | 交易单未支付，不能发起退款 |
| 00002 | 交易单已关闭 | 当前订单已关闭，不能发起退款 | 订单已关闭，无需继续调用 |
| 00003 | 申请退款失败，退款金额超出 | 申请退款失败，退款金额超出 | 申请退款失败，退款金额超出原交易单总金额 |
| 00005 | 余额不足 | 商户可用退款余额不足 | 此状态代表退款申请失败，商户可根据具体的错误提示做相应的处理。 |
| 00006 | 交易单正在退款过程中 | 交易单正在退款过程中 | |
| 00007 | 交易单不存在 | 交易单不存在 |
支付完成后，都能印会把相关支付结果和用户信息发送给商户，商户需要接收处理，并返回应答。
对后台通知交互时，如果都能印收到商户的应答不是成功或超时，都能印信认为通知失败，都能印会通过一定的策略定期重新发起通知，尽可能提高通知的成功率，但都能印不保证通知最终能成功。 （通知频率为15/15/30/180/，单位：秒）
注意：同样的通知可能会多次发送给商户系统。商户系统必须能够正确处理重复的通知。 推荐的做法是，当收到通知进行处理时，首先检查对应业务数据的状态，判断该通知是否已经处理过，如果没有处理过再进行处理，如果处理过直接返回结果成功。在对业务数据进行状态检查和处理之前，要采用数据锁进行并发控制，以避免函数重入造成的数据混乱。
特别提醒：商户系统对于支付结果通知的内容一定要做签名验证,并校验返回的订单金额是否与商户侧的订单金额一致，防止数据泄漏导致出现“假通知”，造成资金损失。
该链接是通过【统一下单API】中提交的参数notifyUrl设置，如果链接无法访问，商户将无法接收到微信通知。
通知url必须为直接可访问的url，不能携带参数。示例：notifyUrl：“http://www.xxx.com/pay/notify.html”
| 参数 | 类型 | 必填 | 描述 | 示例值 |
|---|---|---|---|---|
| mchId | String(32) | 是 | 都能印共同体分配的商户号 | 182xxxx1439 |
| transactionId | String(32) | 是 | 都能印共同体订单号 | 1217752501201407033233368018 |
| mchOrderNo | String(32) | 是 | 商户系统内部订单号 | |
| amount | Int | 是 | 订单总金额，单位为分 | 8888 |
| channelId | String(16) | 是 | 支付渠道类型，暂时固定为dny | dny |
| attach | String(128) | 否 | 附加数据，在支付通知中原样返回，可作为自定义参数使用 | 都能印共同体 |
| payUser | String(16) | 是 | 支付人 | xxx |
| result_code | String(16) | 是 | 状态码 | SUCCESS |
| sign_type | String(32) | 否 | 签名类型，为MD5 | MD5 |
| sign | String(32) | 是 | 通过签名算法计算得出的签名值 | C380BEC2BFD727A4B6845133519F3AD6 |
{
"amount": "11000",
"attach": "2018032954",
"channelId": "dny",
"mchId": "hslhys",
"mchOrderNo": "CO20180329541527561027826",
"payUser": "测试--测试",
"result_code": "SUCCESS",
"sign": "446A324F538241FDF7F1AC73DBEDE300",
"sign_type": "MD5",
"transactionId": "20180529103026487013100001702200"
}