❤
npm
Sign UpSign In

syd-payshangyinda

1.1.2 • Public • Published

商银达支付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

Readme

Keywords

none

Package Sidebar

Install

npm i syd-payshangyinda

Weekly Downloads

1

Version

1.1.2

License

ISC

Unpacked Size

19.9 kB

Total Files

3

Last publish

Collaborators

  • shengxq
Try on RunKit
Report malware