乐收银API文档

乐收银

蛋蛋宝/乐收银是湖南五谷兄弟网络科技有旗下金融解决方案的产品之一

乐收银API接口

API 采用 REST 风格设计。所有接口请求地址都是可预期的以及面向资源的。使用规范的 HTTP 响应代码来表示请求结果的正确或错误信息。使用 HTTP 内置的特性，如 HTTP Authentication 和 HTTP 请求方法让接口易于理解。所有的 API 请求都会以规范友好的 JSON 对象格式返回（包括错误信息）。

官方 SDK

待补充提供多语言多平台的官方服务端和客户端 SDK。

认证

错误

所有的交易返回 http 状态均为 200，相关错误信息在 code、message 中；

错误码

错误码	描述
invalid_request_error	非法请求

接口介绍

功能介绍
通过接口为用户提供各类支付平台
接入方式
接口通过 HTTP 请求接收 JSON 数据，返回的结果也为 JSON 格式

统一响应参数

响应参数

字段是否必选字段类型字段说明

code 是 String 错误码

message 是 String 错误信息

result 是 Boolean 返回结果

data 是 String 业务参数

注:以下支付，查询，退款，撤销，关闭订单的响应参数为统一响应参数中的业务参数，封装在data中。

字段	是否必选	字段类型	字段说明
`code`	是	String	错误码
`message`	是	String	错误信息
`result`	是	Boolean	返回结果
`data`	是	String	业务参数

支付

请求地址：https://pay.dandanpay.com/transaction/unify/charge/pay

请求参数

字段	是否必选	字段类型	字段说明
`app_id`	是	String	app_id, 由系统统一分配
`merchant_code`	是	String	商户号
`out_trade_no`	是	String	商户订单号
`channel`	否	String	支付渠道,详细参考支付渠道 channel属性值
`product`	是	String	支付产品,详细参考支付产品 product属性值
`client_ip`	是	String	客户端调用的 IP
`amount`	是	int	支付金额，单位分
`subject`	是	String	订单标题，该参数最长 32 个 Unicode
`body`	是	String	商品描述信息，该参数最长为 128 个 Unicode 字符
`description`	是	String	订单附加说明，最多 255 个 Unicode 字符
`extra`	否	String	特定渠道发起交易时需要的额外参数，以及部分渠道支付成功返回的额外参数，详细参考支付渠道 extra 参数说明。
`notify_url`	是	String	交易的通知地址
`sign_type`	是	String	签名类型
`sign`	是	String	签名值

响应参数

字段	是否必选	字段类型	字段说明
`id`	是	String	通知支付平台流水号
`out_trade_no`	是	String	商户订单号
`credential`	是	String	调用支付的凭证
`third_trade_no`	是	String	第三方流水号，不长于 32 位
`failure_code`	是	String	业务参数 code
`failure_msg`	是	String	业务结果描述
`sign_type`	是	String	签名类型
`sign`	是	String	签名值
`qr_code`	是	String	当前预下单请求生成的二维码码串，可以用二维码生成工具根据该码串值生成对应的二维码，扫码支付时必有值
`prepay_id`	是	String	预支付 ID 标识
`pay_info`	否	String	预留字段

订单查询

请求地址：https://pay.dandanpay.com/transaction/unify/charge/query

请求参数

字段	是否必选	字段类型	字段说明
`app_id`	是	String	app_id, 由系统统一分配
`merchant_code`	是	String	商户号
`out_trade_no`	是	String	商户订单号,d
`third_trade_no`	否	String	第三方支付订单号
`client_ip`	是	String	客户端调用的 IP
`extra`	否	String	特定渠道时需要的额外参数，详细参考支付渠道 extra 参数说明。
`sign_type`	是	String	签名类型
`sign`	是	String	签名值

响应参数

字段	是否必选	字段类型	字段说明
`id`	是	String	通知支付平台流水号
`out_trade_no`	是	String	商户订单号
`trade_state`	是	String	交易状态
`trade_state_desc`	是	String	交易状态描述
`failure_code`	是	String	业务参数 code
`failure_msg`	是	String	业务结果描述
`sign_type`	是	String	签名类型
`sign`	是	String	签名值

退款

请求地址：https://pay.dandanpay.com/transaction/unify/charge/refund

请求参数

字段	是否必选	字段类型	字段说明
`app_id`	是	String	app_id, 由系统统一分配
`out_trade_no`	是	String	商户订单号（原交易订单号）
`third_trade_no`	否	String	第三方支付流水号
`out_refund_no`	是	String	商户订单号（退款订单号）
`total_fee`	是	String	交易金额，单位分
`refund_fee`	是	String	退款金额，单位分
`subject`	是	String	商品标题
`body`	是	String	商品描述信息
`description`	是	String	订单附加说明
`extra`	否	String	特定渠道时需要的额外参数，详细参考支付渠道 extra 参数说明。
`notify_url`	否	String	通知地址，预留字段
`sign_type`	是	String	签名类型
`sign`	是	String	签名值

响应参数

字段	是否必选	字段类型	字段说明
`refund_fee`	是	String	退款金额，单位元
`out_trade_no`	是	String	商户订单号（原订单号）
`out_refund_no`	是	String	商户订单号（退款订单号）
`trade_state`	是	String	交易状态
`trade_state_desc`	是	String	交易状态描述
`failure_code`	是	String	业务参数 code
`failure_msg`	是	String	业务结果描述
`sign_type`	是	String	签名类型
`sign`	是	String	签名值

撤销

请求地址：https://pay.dandanpay.com/transaction/unify/charge/cancel

请求参数

字段	是否必选	字段类型	字段说明
`app_id`	是	String	app_id, 由系统统一分配
`out_trade_no`	是	String	商户订单号（原交易订单号）
`third_trade_no`	否	String	第三方支付流水号
`out_cancel_no`	是	String	商户订单号（撤销订单号）
`subject`	是	String	商品标题
`body`	是	String	商品描述信息
`description`	是	String	订单附加说明
`extra`	否	String	特定渠道时需要的额外参数，详细参考支付渠道 extra 参数说明。
`sign_type`	是	String	签名类型
`sign`	是	String	签名值

响应参数

字段	是否必选	字段类型	字段说明
`out_trade_no`	是	String	商户订单号
`trade_state`	是	String	交易状态
`trade_state_desc`	是	String	交易状态描述
`failure_code`	是	String	业务参数 code
`failure_msg`	是	String	业务结果描述
`sign_type`	是	String	签名类型
`sign`	是	String	签名值

关闭订单

请求地址：https://pay.dandanpay.com/transaction/unify/charge/close

请求参数

字段	是否必选	字段类型	字段说明
`app_id`	是	String	app_id, 由系统统一分配
`out_trade_no`	是	String	商户订单号（原交易订单号）
`merchant_code`	是	String	商户号
`subject`	否	String	商品标题
`body`	否	String	商品描述信息
`description`	否	String	订单附加说明
`extra`	否	String	特定渠道时需要的额外参数，详细参考支付渠道 extra 参数说明。
`sign_type`	是	String	签名类型
`sign`	是	String	签名值

响应参数

字段	是否必选	字段类型	字段说明
`out_trade_no`	是	String	商户订单号
`trade_state`	是	String	交易状态
`trade_state_desc`	是	String	交易状态描述
`failure_code`	是	String	业务参数 code
`failure_msg`	是	String	业务结果描述
`sign_type`	是	String	签名类型
`sign`	是	String	签名值

订单通知

通知参数

注：通知参数不需要加入统一响应参数data中，只需要直接接收以下参数

字段	是否必选	字段类型	字段说明
`out_trade_no`	是	String	商户订单号，商户自行生成的唯一订单标识
`created`	是	String	订单生成时间
`third_trade_no`	否	String	第三方流水号
`state`	是	String	订单状态
`merchant_code`	是	String	商户编号
`update_time`	是	String	订单支付时间
`amount`	是	String	支付金额,单位元
`sign_type`	是	String	签名类型
`sign`	是	String	签名值

返回参数

处理成功，返回SUCCESS，不分大小写，以字符串的形式返回
处理失败，返回任意字符串，平台认为通知失败，平台会通过一定的策略间接性重新发起通知，尽可能提高通知的成功率，但不保证通知最终能成功。

订单状态详情

下面为支付状态 state 和其对应的订单状态详情。

state	详情
`00`	支付成功
`01`	支付失败
`03`	部分退款
`04`	全部退款
`05`	退款中
`06`	已撤销
`09`	待支付
`98`	已关闭
`99`	支付超时

支付产品属性值

下面为支付产品 product 属性值和其对应的支付产品名称。

product 属性值	支付产品名称
`WECHAT_APP`	微信 App 支付
`WECHAT_OFFICE_ACCOUNT`	微信公众号支付
`WECHAT_H5`	微信 H5 支付
`WECHAT_DYNAMIC_SCAN_CODE`	微信扫码支付
`WECHAT_SWIPING_CARD`	微信刷卡支付
`WECHAT_LITE`	微信小程序支付
`ALIPAY_DYNAMIC_SCAN_CODE`	支付宝扫码支付
`ALIPAY_BAR_CODE`	支付宝条码支付
`ALIPAY_FIXED_QRCODE`	支付宝固定二维码支付

支付渠道属性值

下面为支付渠道 channel 属性值和其对应的支付渠道名称。

channel 属性值	支付渠道名称
`WECHAT`	微信支付
`SPDB`	浦发支付
`HKB`	汉口支付
`SWIFTPASS`	威富通支付
`WHFXYUN`	快捷支付

支付渠道 extra 参数说明

特定渠道发起交易时需要的额外参数，以及部分渠道支付成功返回的额外参数。bfb ，cp_b2b 渠道不需要 extra 参数

普通服务商微信小程序支付
普通服务商微信公众号支付

extra 参数参数说明

sub_open_id 支付时，获取到的用户 openId

sub_app_id 商户在微信配置的 app_id

extra 参数	参数说明
`sub_open_id`	支付时，获取到的用户 openId
`sub_app_id`	商户在微信配置的 app_id

汉口微信动态扫码支付
汉口微信公众号支付
汉口微信小程序支付
汉口微信App支付
汉口微信H5支付
汉口支付公众号支付
汉口支付宝动态扫码支付

extra 参数	参数说明
`version`	版本号，V4.1.2.1.1，非必填
`device_type`	终端类型，非必填
`device_info`	终端设备号(门店号或收银设备ID)，注意：PC网页或公众号内支付请传"WEB"，非必填
`attach`	附加数据，在查询API和支付通知中原样返回，该字段主要用于商户携带订单的自定义数据，非必填
`goods_tag`	订单优惠标记，非必填
`limit_pay`	指定支付方式，no_credit--指定不能使用信用卡支付，非必填
`time_start`	订单生成时间，格式为yyyyMMddHHmmss，如2009年12月25日9点10分10秒表示为20091225091010。时区为GMT+8 beijing。该时间取自商户服务器。注：订单生成时间与超时时间需要同时传入才会生效。非必填
`time_expire`	订单失效时间，格式为yyyyMMddHHmmss，如2009年12月27日9点10分10秒表示为20091227091010。时区为GMT+8 beijing。该时间取自商户服务器。注：订单生成时间与超时时间需要同时传入才会生效。非必填，建议最短失效时间为1分钟
`openid`	微信用户关注商家公众号的openid，公众号支付，小程序时支付必填
`wx_appid`	当发起公众号支付时，值是微信公众平台基本配置中的AppID(应用ID)；当发起小程序支付时，值是对应小程序的AppID，公众号支付，小程序支付时必填
`product_id`	商品ID ，动态扫码支付时必填
`scene_info`	H5支付必填，网站应用{"h5_info": //h5支付固定传"h5_info" {"type": "", //场景类型"wap_url": "",//WAP网站URL地址"wap_name": "" //WAP 网站名}}

汉口微信刷卡支付
汉口支付宝条码支付

extra 参数	参数说明
`version`	版本号，V4.1.2.1.1，非必填
`device_info`	终端设备号(门店号或收银设备ID)，注意：PC网页或公众号内支付请传"WEB"，非必填
`attach`	附加数据，在查询API和支付通知中原样返回，该字段主要用于商户携带订单的自定义数据，非必填
`goods_tag`	订单优惠标记，非必填
`limit_pay`	指定支付方式，no_credit--指定不能使用信用卡支付，非必填
`auth_code`	微信或支付宝支付码对应的授权码，必填
`scene`	支付场景(支付宝支付才有，默认条码支付)，bar_code条码支付，wave_code声波支付

浦发支付宝条码支付
浦发微信刷卡支付
浦发微信公众号支付
浦发支付宝固定二维码支付

extra 参数参数说明

auth_code 授权码，微信刷卡支付，支付宝条码支付必填

buyer_id 付款人 ID，微信公众号支付，支付宝固定二维码支付必填

extra 参数	参数说明
`auth_code`	授权码，微信刷卡支付，支付宝条码支付必填
`buyer_id`	付款人 ID，微信公众号支付，支付宝固定二维码支付必填

快捷支付
快捷支付确认
快捷支付查询

extra 参数参数说明

merCode 商户号，必填

bingdingCardSeq 绑卡序列号，支付查询时不填，其他情况必填

verifiyCode 短信验证码，支付确认时必填

extra 参数	参数说明
`merCode`	商户号，必填
`bingdingCardSeq`	绑卡序列号，支付查询时不填，其他情况必填
`verifiyCode`	短信验证码，支付确认时必填

威富通微信小程序
威富通微信公众号支付
威富通支付宝公众号支付
威富通微信 H5 支付

extra 参数	参数说明
`sub_app_id`	当发起公众号支付时，值是微信公众平台基本配置中的 AppID(应用 ID)；当发起小程序支付时，值是对应小程序的 AppID，微信小程序支付和微信公众号支付必填
`sub_open_id`	微信用户关注商家公众号的 openid，微信小程序支付和微信公众号支付必填
`time_start`	订单生成时间，格式为yyyyMMddHHmmss，如2009年12月25日9点10分10秒表示为20091225091010。时区为GMT+8 beijing。该时间取自商户服务器。注：订单生成时间与超时时间需要同时传入才会生效。不是必填
`time_expire`	订单失效时间，格式为yyyyMMddHHmmss，如2009年12月27日9点10分10秒表示为20091227091010。时区为GMT+8 beijing。该时间取自商户服务器。注：订单生成时间与超时时间需要同时传入才会生效。不是必填，建议最短失效时间为1分钟
`buyer_logon_id`	买家支付宝账号，支付宝公众号支付必填
`device_info`	如果是用于苹果 app 应用里值为 iOS_SDK；如果是用于安卓 app 应用里值为 AND_SDK；如果是用于手机网站，值为 iOS_WAP 或 AND_WAP 均可，微信H5支付必填
`mch_app_name`	如果是用于苹果或安卓 app 应用中，传分别对应在 AppStore 和安卓分发市场中的应用名（如：王者荣耀）如果是用于手机网站，传对应的网站名(如：京东官网)，微信H5支付必填
`mch_app_id`	如果是用于苹果或安卓 app 应用中，苹果传 IOS 应用唯一标识(如：com.tencent.wzryIOS)安卓传包名(如：com.tencent.tmgp.sgame)如果是用于手机网站，传网站首页 URL 地址,必须保证公网能正常访问(如：https://m.jd.com)，微信H5支付必填

签名规范

  目前支持MD5签名：MD5 是一种摘要生成算法，通过在签名原始串后加上商户通信密钥的内容，进行MD5运算，形成的摘要字符串即为签名结果。为了方便比较，签名结果统一转换为大写字符。  

  sign签名计算公式：  
  sign = Md5(原字符串&key=密钥).toUpperCase  
  
  签名生成的通用步骤如下：
  第一步，设所有发送或者接收到的数据为集合M，将集合M内非空参数值的参数按照参数名ASCII码从小到大排序（字典序），使用URL键值对的格式（即key1=value1&key2=value2…）拼接成字符串stringA。
  特别注意以下重要规则：
  1 参数名ASCII码从小到大排序（字典序）；
  2 如果参数的值为空不参与签名；
  3 参数名区分大小写；
  4 验证调用返回或微信主动通知签名时，传送的sign参数不参与签名，将生成的签名与该sign值作校验；
  5 接口可能增加字段，验证签名时必须支持增加的扩展字段。
  第二步，在stringA最后拼接上key得到stringSignTemp字符串，并对stringSignTemp进行MD5运算，再将得到的字符串所有字符转换为大写，得到sign值signValue。
  如：
  假设传送的参数如下：
  app_id：969037206616276993
  merchant_code：1010174934854402049
  out_trade_no：
  channel:SWIFTPASS_WECHAT_NATIVE
  product:WECHAT_DYNAMIC_SCAN_CODE
  client_ip:218.76.8.29
  amount:1
  body：test
  description：test
  subject：test
  notify_url：http://127.0.0.1/notify/wechat
  sign_type：MD5  

  我们推荐生成随机数算法如下：调用随机数函数生成，将得到的值转换为字符串。
  1：对参数按照key=value的格式，并按照参数名ASCII字典序排序如下：
  stringA= amount=1&app_id=969037206616276993&body=test&channel=SWIFTPASS_WECHAT_NATIVE&client_ip=218.76.8.29&description=test&merchant_code=1010174934854402049&notify_url=http://127.0.0.1/notify/wechat&out_trade_no=1027805986871574528&product=WECHAT_DYNAMIC_SCAN_CODE&sign_type=MD5&subject=test&
  2：拼接API密钥(假设MD5key = 6C7C97D68C7DB148DE678B4F5827D2F0)：
  stringSignTemp= amount=1&app_id=969037206616276993&body=test&channel=SWIFTPASS_WECHAT_NATIVE&client_ip=218.76.8.29&description=test&merchant_code=1010174934854402049&notify_url=http://127.0.0.1/notify/wechat&out_trade_no=1027805986871574528&product=WECHAT_DYNAMIC_SCAN_CODE&sign_type=MD5&subject=test&key=6C7C97D68C7DB148DE678B4F5827D2F0  

  sign=MD5(stringSignTemp).toUpperCase()="C3D0BB2D39C1274C89B332F2B5739CA4"；

乐收银

 乐收银API接口

认证

错误

错误码

接口介绍

统一响应参数

注:以下支付，查询，退款，撤销，关闭订单的响应参数为统一响应参数中的业务参数，封装在data中。

支付

订单查询

退款

撤销

关闭订单

订单通知

注：通知参数不需要加入统一响应参数data中，只需要直接接收以下参数

订单状态详情

支付产品属性值

支付渠道属性值

支付渠道 extra 参数说明

签名规范

乐收银API接口