商银达支付API接口文档

标签： 商银达支付

一、对接前的准备

1. 申请接入资格

要对接商银达支付,需要先申请APPID和SECRET。请联系负责对接的商务，沟通洽谈，根据各自的需求选择合适的入网方式和支付接入方式，并建立合作关系。

2. 商户入网

目前商银达支付商户入网只能通过商银达支付代理商APP进行入网,如果需要通过API入网,请与商务联系!

二、对接流程

1. 激活码在代理商APP中【终端列表】中生成
2. 激活过程只需要激活一次,返回的sn和key要做记录,以后的API通讯中,使用sn和key来计算签名

st=>start: Start
op=>operation: 代理商APP中生成激活码
cond=>condition: 激活?
c1=>operation: 记录终端sn和key
c2=>operation: 支付/查询/预下单/退款/关闭
e=>end
yes=>激活成功

st->op->cond
cond(yes)->c1->c2->e
cond(no)->op

三、签名机制

接入域名(api_domain)：https://payapi.ydcxt.com/api/v1

注：Web API接口是https协议，当发起请求时，会要求检查证书，在发起请求时规避ssl的证书检查或者 携带证书请求**

1.需要使用APPID和SECRET进行签名的接口

• 签名接口

2.需要使用终端SN和KEY进行签名的接口

• 支付接口
• 预下单接口
• 查询接口
• 退款接口
• 取消接口

签名算法:

如果要正常使用各接口，需要按照以下方式去进行签名验证:

• 支付平台所有的API仅支持JSON格式的请求调用，请务必在HTTP请求头中加入Content-Type: application/json。
• 所有请求的body都需采用UTF-8编码，所有响应也会采用相同编码。
• 支付平台所有的API调用都需要签名验证。
• 采用应用层签名机制。将HTTP请求body部分的UTF-8编码字节流视为被签名的内容，不关心主体的格式。
• 所有返回数据的类型都是 字符串。
• 接口中所有涉及金额的地方都以 分 为单位。
• 签名序列号(sn)和签名值(sign)放在json中，在接入服务中统一校验。

假设APPID和SECRET信息如下

• appid:8888
• secret:88888888888888888888888888888888

{
	"cmd": "激活",
	"app_id": "8888",
	"code": "12345678",
	"device_id": "111111",
}

1. 将请求参数中除sign外的多个键值对，根据键按照字典序排序，并按照"key1=value1&key2=value2..."的格式拼成一个字符串,【数据为空,不参与签名】 app_id=8888&cmd=激活&code=12345678&device_id=111111
2. 将secret拼接在1中排序后的字符串后面得到待签名字符串,【终端key也使用&secret=terminal_key进行连接】 app_id=8888&cmd=激活&code=12345678&device_id=111111&secret=88888888888888888888888888888888
3. 使用sha1算法加密待加密字符串并转为小写即为sign c2397a5f4c38778addba2ea722711dad2b0f4713
4. 将sign添加到请求参数中

{
	"cmd": "激活",
	"app_id": "8888",
	"code": "12345678",
	"device_id": "111111",
	"sign": "c2397a5f4c38778addba2ea722711dad2b0f4713",
}

四、接口列表

1. 激活接口

使用激活码换取终端SN和KEY 激活接口使用APPID和SECRECT校验签名 其它接口使用终端SN和KEY校验签名

接口地址: https://payapi.ydcxt.com/api/v1

请求参数: 字段名 |类型 |必填 |说明 -- |:--: |:--: |-- cmd |string |Y |"激活"或"activate" app_id |string |Y |app id，从服务商平台获取 code |string |Y |激活码内容 device_id |string(128)|Y |设备唯一身份ID client_sn |string(50) |N |第三方终端号，必须保证在app id下唯一 name |string(128)|N |终端名 os_info |string(45) |N |当前系统信息，如: Android5.0 sdk_version |string(45) |N |SDK版本

返回参数 字段名 |类型 |必填 |说明 -- |:--: |--: |-- cmd |string |Y |"激活"或"activate" result |string |Y |成功,错误,异常 error |string |N |错误或异常时显示错误描述 terminal_sn |string |Y |终端号 terminal_key |string |Y |终端密钥 merchant_sn |string |Y |商户编号 merchant_name |string |N |商户名称 logourl |string |N |商户logo的url store_sn |string |Y |门店编号 store_name |string |N |门店名称

2. 支付接口

B2C接口,顾客出示付款码,使用扫码器识别得到付款码,通过支付接口提交完成支付。

★★★支付接口返回不代表肯定支付成功 顾客出示付款码付款时,可能需要输入密码,造成接口调用等待时间过长,支付接口会先暂时返回DOING(此时不代表支付成功),支付完成后,支付平台通过回调接口通知支付结果。支付客户端也可以通过查询接口多次循环支付结果。（循环间隔2s以上）

st=>start: Start
op=>operation: 调用支付接口
cond=>condition: 返回最终结果?
c1=>operation: 支付成功/失败
c2=>operation: 支付结果未知
c3=>condition: 查询支付结果
e=>end
yes=>激活成功

st->op->cond
cond(no,left)->c2->c3
cond(yes)->c1
c3(yes)->e
c3(no)->c2

请求参数: 字段名 |类型 |必填 |说明 -- |:--: |:--: |-- cmd |string |Y |"支付"或"pay" terminal_sn |String(32) |Y |激活接口中获取的支付平台终端SN client_sn |String(32) |Y |商户订单编号,必须在商户系统内唯一 total_amount|String(10) |Y |支付金额,单位分 dynamic_id |string(32) |Y |付款码 subject |string(64) |N |显示在支付页面上的商品名称 operator |string(32) |N |操作员工 description |string(256)|N |支付商品描述 reflect |string(64) |N |反射参数,回调接口中原样返回 notify_url |string(128)|N |回调网址,用于接收支付结果

返回参数 字段名 |类型 |必填 |说明 -- |:--: |--: |-- cmd |string |Y |"支付"或"pay" result |string |Y |成功,错误,异常 error |string |N |错误或异常时显示错误描述 ||| order_status |string |Y |支付结果,SUCCESS/FAIL/DOING/CLOSE order_message |string |N |支付失败是的描述 ||| terminal_sn |string |Y |终端sn client_sn |string |Y |商户订单编号,必须在商户系统内唯一 sn |string |N |支付平台订单号(支付成功页面上显示的条码) ||| payway |string |N |支付客户端类型(微信/支付宝) sub_payway |string |N |支付方式(刷卡/扫码) openid |string |N |微信平台opein subOpenId |string |N |微信平台opein total_amount |string |N |支付金额 net_amount |string |N |实收金额(扣除手续费的金额) productFee |string |N |手续费 reflect |string |N |反射参数 channel_finish_time|string|N |支付成功时间

3. 查询接口

接口地址: https://payapi.ydcxt.com/api/v1

请求参数: 字段名 |类型 |必填 |说明 -- |:--: |:--: |-- cmd |string |Y |"查询"或"query" terminal_sn |String(32) |Y |激活接口中获取的支付平台终端SN client_sn |String(32) |N |商户订单编号,必须在商户系统内唯一 sn |String(32) |N |支付平台订单号(支付成功页面上显示的条码)

client_sn和sn二选一,不能同时为空

返回参数 字段名 |类型 |必填 |说明 -- |:--: |--: |-- cmd |string |Y |"查询"或"query" result |string |Y |成功,错误,异常 error |string |N |错误或异常时显示错误描述 ||| order_status |string |Y |订单状态,SUCCESS/FAIL/DOING/CLOSE order_message |string |N |订单状态的描述 ||| terminal_sn |string |Y |终端sn client_sn |string |Y |商户订单编号,必须在商户系统内唯一 sn |string |N |支付平台订单号(支付成功页面上显示的条码) ||| payway |string |N |支付客户端类型(微信/支付宝) sub_payway |string |N |支付方式(刷卡/扫码) openid |string |N |微信平台opein subOpenId |string |N |微信平台opein ||| total_amount |string |N |支付金额 net_amount |string |N |实收金额(扣除手续费的金额) productFee |string |N |手续费 channel_finish_time|string|N |支付成功时间

4. 退款接口

接口地址: https://payapi.ydcxt.com/api/v1

★★★退款返回说明 退款返回DOING代表支付通道已经接收到退款请求,但退款并未到账。退款返回SUCCESS时代表钱已经退回到账。比如微信支付通过银行卡扣款，退款时微信收到退款请求，状态为DOING，一般银行24小时内退款到账，退款到账后再查询退款状态即为SUCCESS

请求参数: 字段名 |类型 |必填 |说明 -- |:--: |:--: |-- cmd |string |Y |"退款"或"refund" terminal_sn |String(32) |Y |激活接口中获取的支付平台终端SN client_tsn |string |Y |退款订单编号,必须在商户系统内唯一 client_sn |String(32) |N |商户订单编号,必须在商户系统内唯一 sn |String(32) |N |支付平台订单号(支付成功页面上显示的条码) refund_amount |string |N |退款金额,不传退全款

client_sn和sn二选一,不能同时为空

返回参数 字段名 |类型 |必填 |说明 -- |:--: |--: |-- cmd |string |Y |"退款"或"refund" result |string |Y |成功,错误,异常 error |string |N |错误或异常时显示错误描述 order_status |string |Y |订单状态,SUCCESS/FAIL/DOING/CLOSE order_message |string |N |订单状态的描述 ||| terminal_sn |string |Y |终端sn client_sn |string |Y |商户订单编号,必须在商户系统内唯一 client_tsn |string |Y |退款订单编号,必须在商户系统内唯一 sn |string |N |支付平台订单号(支付成功页面上显示的条码) ||| refund_amount |string |N |退款金额

5. 退款查询接口

接口地址: https://payapi.ydcxt.com/api/v1

请求参数: 字段名 |类型 |必填 |说明 -- |:--: |:--: |-- cmd |string |Y |"退款查询"或"refundQuery" terminal_sn |String(32) |Y |激活接口中获取的支付平台终端SN client_tsn |string |Y |退款订单编号,必须在商户系统内唯一 client_sn |String(32) |N |商户订单编号,必须在商户系统内唯一 sn |String(32) |N |支付平台订单号(支付成功页面上显示的条码)

client_sn和sn二选一,不能同时为空

返回参数 字段名 |类型 |必填 |说明 -- |:--: |--: |-- cmd |string |Y |"退款查询"或"refundQuery" result |string |Y |成功,错误,异常 error |string |N |错误或异常时显示错误描述 order_status |string |Y |支付结果,SUCCESS/FAIL/DOING/CLOSE order_message |string |N |订单状态描述 ||| terminal_sn |string |Y |终端sn client_sn |string |Y |商户订单编号,必须在商户系统内唯一 client_tsn |string |Y |退款订单编号,必须在商户系统内唯一 sn |string |N |支付平台订单号(支付成功页面上显示的条码) ||| refund_amount |string |N |退款金额

6. 关闭支付接口

接口地址: https://payapi.ydcxt.com/api/v1

请求参数: 字段名 |类型 |必填 |说明 -- |:--: |:--: |-- cmd |string |Y |"关闭"或"close" terminal_sn |String(32) |Y |激活接口中获取的支付平台终端SN client_sn |String(32) |N |商户订单编号,必须在商户系统内唯一 sn |String(32) |N |支付平台订单号(支付成功页面上显示的条码)

client_sn和sn二选一,不能同时为空

返回参数 字段名 |类型 |必填 |说明 -- |:--: |--: |-- cmd |string |Y |"支付"或"pay" result |string |Y |成功,错误,异常 error |string |N |错误或异常时显示错误描述 order_message |string |N |支付失败是的描述 ||| terminal_sn |string |Y |终端sn client_sn |string |Y |商户订单编号,必须在商户系统内唯一 sn |string |N |支付平台订单号(支付成功页面上显示的条码)

7. 预下单接口

使用场景： C2B付款,生成二维码有顾客扫码完成支付 公众号支付/小程序支付

请求参数: 字段名 |类型 |必填 |说明 -- |:--: |:--: |-- cmd |string |Y |"预下单"或"prepay" terminal_sn |String(32) |Y |激活接口中获取的支付平台终端SN client_sn |String(32) |Y |商户订单编号,必须在商户系统内唯一 total_amount|String(10) |Y |支付金额,单位分 subject |string(64) |N |显示在支付页面上的商品名称 operator |string(32) |N |操作员工 description |string(256)|N |支付商品描述 reflect |string(64) |N |反射参数,回调接口中原样返回 notify_url |string(128)|N |回调网址,用于接收支付结果

返回参数 字段名 |类型 |必填 |说明 -- |:--: |--: |-- cmd |string |Y |"预下单"或"prepay" result |string |Y |成功,错误,异常 error |string |N |错误或异常时显示错误描述

五、SDK

目前提供了一下语言的SDK

nodejs SDK

npm install syd-payshangyinda -S

C sharp