API开发文档简介
本文阅读对象：使用 SMPAY 商户自服务系统的技术架构师、研发工程师、系统运维工程师。通过本文档，商户可了解 SMPAY 接入的技术、接入的产品业务、接入的流程、接入规范等信息，以便于商户顺利完成接入工作。
接入网关
请登录商户中心，API管理 开发文档中 查看网关地址和API对接参数。
统一下单接口
提交方式：POST
地址： 接入网关/Pay_Index.html
| 参数名称 |
参数含义 |
是否必填 |
参与签名 | 参数说明 |
| pay_memberid |
商户号 |
是 |
是 |
平台分配商户号 |
| pay_orderid |
订单号 |
是 |
是 |
上送订单号唯一, 字符长度20 |
| pay_applydate |
提交时间 |
是 |
是 |
时间格式：2016-12-26 18:18:18 |
| pay_bankcode |
渠道编码 |
是 |
是 |
在商户中心查询 |
| pay_notifyurl |
服务端通知 |
是 |
是 |
服务端返回地址.（POST返回数据） |
| pay_callbackurl |
页面跳转通知 |
是 |
是 |
页面跳转返回地址（POST返回数据） |
| pay_amount |
订单金额 |
是 |
是 |
单位：PHP |
| pay_md5sign |
MD5签名 |
是 |
否 |
请查看签名算法 |
| pay_productname |
商品名称 |
是 |
否 |
|
| pay_productnum |
商户品数量 |
否 |
否 |
|
| pay_productdesc |
商品描述 |
否 |
否 |
|
| pay_producturl |
商户链接地址 |
否 |
否 |
|
返回值
| 参数名称 |
参数含义 |
是否必填 |
参与签名 |
参数说明 |
| status |
状态 |
是 |
是 |
success:请求成功，error：请求失败 |
| orderid |
订单号 |
是 |
是 |
平台生成的订单号 |
| auto_pay_url |
支付收银台URL |
是 |
是 |
跳转到支付收银台的URL地址（需要再次点击确认支付） |
| pay_page_url |
直接支付页面URL |
是 |
是 |
跳转到直接支付页面的URL地址 |
注意事项：
1. 支付信息会保存在Redis中，有效期为5分钟
2. 支付页面URL需要在有效期内使用，过期后需要重新下单
异步通知
提交方式：POST
接收到服务器点对点通讯时，在页面输出"OK"（ 没有双引号，OK 两个字母大写 ) ，否则会重复5次发送点对点通知.
| 参数名称 |
参数含义 |
是否必填 |
参与签名 | 参数说明 |
| memberid |
商户编号 |
是 |
是 |
平台分配商户号 |
| orderid |
订单号 |
是 |
是 |
上送订单号唯一, 字符长度20 |
| amount |
订单金额 |
是 |
是 |
|
| transaction_id |
交易流水号 |
是 |
是 |
|
| datetime |
交易时间 |
是 |
是 |
|
| returncode |
交易状态 |
是 |
是 |
00表示成功，其它表示失败 |
| attach |
扩展返回 |
否 |
是 |
商户附加数据返回 |
| sign |
MD5签名 |
是 |
否 |
|
订单查询接口
提交方式：POST
地址： 接入网关/Pay_Trade_query.html
| 参数名称 |
参数含义 |
是否必填 |
参与签名 | 参数说明 |
| pay_memberid |
商户编号 |
是 |
是 |
|
| pay_orderid |
商户订单号 |
是 |
是 |
|
| pay_md5sign |
MD5签名 |
是 |
是 |
|
返回值
| 参数名称 |
参数含义 |
是否必填 |
参与签名 |
参数说明 |
| status |
状态 |
是 |
是 |
success：请求成功（不代表业务成功），error：请求失败 |
| msg |
状态描述 |
是 |
是 |
状态说明信息 |
| mchid |
商户号 |
是 |
是 |
status=success时返回 |
| out_trade_id |
商户订单号 |
是 |
是 |
商户提交的订单号 |
| pay_orderid |
平台订单号 |
是 |
是 |
平台生成的订单号 |
| amount |
订单金额 |
是 |
是 |
单位：PHP |
| pay_status |
订单状态 |
是 |
是 |
0：未支付，1：已支付未通知，2：已支付已通知 |
| pay_successdate |
支付成功时间 |
是 |
是 |
订单支付成功的时间戳 |
| sign |
MD5签名 |
是 |
否 |
签名验证 |
注意事项：
1. 订单状态说明：
- 0：未支付
- 1：已支付未通知
- 2：已支付已通知
2. 支付成功时间(pay_successdate)仅在订单支付成功后返回
代付提交接口
提交方式：POST
提交地址：网关地址+/Payment_Dfpay_add.html
| 参数名称 |
参数含义 |
是否必填 |
参与签名 |
参数说明 |
| mchid |
商户编号 |
是 |
是 |
平台分配商户号 |
| out_trade_no |
商户订单号 |
是 |
是 |
保证唯一值 |
| money |
订单金额 |
是 |
是 |
单位：PHP |
| paytype |
支付类型 |
是 |
是 |
Gcash/Maya/Bank，用于确定支付渠道 |
| paywallet |
钱包类型 |
是 |
是 |
Gcash/Maya/Gcash原生/QRPH，用于确定具体钱包类型 |
| bankname |
开户行名称 |
是 |
是 |
具体银行名称 |
| subbranch |
支行名称 |
是 |
是 |
|
| accountname |
开户名 |
是 |
是 |
|
| cardnumber |
银行卡号/手机号 |
是 |
是 |
如果是银行卡支付填写银行卡号，如果是电子钱包支付填写手机号 |
| province |
省份 |
是 |
是 |
|
| city |
城市 |
是 |
是 |
|
| extends |
附加字段 |
否 |
是 |
扩展字段，需要先转JSON再Base64 |
| notifyurl |
异步通知地址 |
否 |
是 |
代付结果异步通知地址 |
| sign |
MD5签名 |
是 |
否 |
|
注：extends字段具体需要上送哪些字段以及字段的含义，对接时请咨询平台方，如果不需要扩展字段则不传。不为空时，格式：先转化为JSON，接着进行Base64加密
例如：扩展字段为phone和idno，extends[phone]=13800138000，extends[idno]=111111111111111111。首先将extends转化为JSON格式得到{"phone":"13800138000","idno":"111111111111111111"}，然后将此JSON字符串进行base64加密得到eyJwaG9uZSI6IjEzODAwMTM4MDAwIiwiaWRubyI6IjExMTExMTExMTExMTExMTExMSJ9，最终得到extends=eyJwaG9uZSI6IjEzODAwMTM4MDAwIiwiaWRubyI6IjExMTExMTExMTExMTExMTExMSJ9。
返回值
| 参数名称 |
参数含义 |
是否必填 |
参与签名 |
参数说明 |
| status |
状态 |
是 |
是 |
成功:success 失败：error（不代表业务成功） |
| msg |
状态描述 |
是 |
是 |
|
| transaction_id |
平台流水号 |
是 |
是 |
成功时返回 |
代付异步通知
通知方式：POST
通知地址：商户提交的notifyurl地址
| 参数名称 |
参数含义 |
是否必填 |
参与签名 |
参数说明 |
| mchid |
商户编号 |
是 |
是 |
平台分配商户号 |
| out_trade_no |
商户订单号 |
是 |
是 |
商户提交的订单号 |
| transaction_id |
平台流水号 |
是 |
是 |
平台生成的流水号 |
| amount |
订单金额 |
是 |
是 |
单位：PHP |
| status |
订单状态 |
是 |
是 |
1：成功，2：失败，3：处理中 |
| msg |
状态描述 |
是 |
是 |
订单状态说明 |
| sign |
MD5签名 |
是 |
否 |
签名验证 |
注意事项：
1. 异步通知可能会多次发送，商户需要做幂等处理
2. 商户收到通知后，需要返回字符串"success"（不包含引号），否则平台会重复发送通知
3. 签名验证方式与提交接口相同，参与签名的参数包括：mchid、out_trade_no、transaction_id、amount、status、msg
代付查询接口
提交方式：POST
提交地址：网关地址+/Payment_Dfpay_query.html
| 参数名称 |
参数含义 |
是否必填 |
参与签名 | 参数说明 |
| out_trade_no |
商户订单号 |
是 |
是 |
|
| mchid |
商户号 |
是 |
是 |
|
| pay_md5sign |
签名 |
是 |
否 |
|
返回值
| 参数名称 |
参数含义 |
是否必填 |
参与签名 |
参数说明 |
| status |
状态 |
是 |
是 |
success：请求成功（不代表业务成功），error：请求失败 |
| msg |
状态描述 |
是 |
是 |
状态说明信息 |
| mchid |
商户号 |
是 |
是 |
status=success时返回 |
| out_trade_no |
商户订单号 |
是 |
是 |
status=success时返回 |
| amount |
金额 |
是 |
是 |
status=success时返回 |
| transaction_id |
平台流水号 |
是 |
是 |
status=success时返回 |
| refCode |
业务状态 |
是 |
是 |
status=success时返回 |
| refMsg |
业务描述 |
是 |
是 |
status=success时返回 |
| success_time |
成功时间 |
是 |
是 |
status=success，refCode=1时返回 |
| sign |
MD5签名 |
是 |
否 |
签名验证 |
refCode返回值
| 返回值 |
含义 |
| 1 |
成功 |
| 2 |
失败 |
| 3 |
处理中 |
| 4 |
待处理 |
| 5 |
审核驳回 |
| 6 |
待审核 |
| 7 |
交易不存在 |
| 8 |
未知状态 |
注：当status=success和refCode=1同时成立时才表示转账成功
签名算法
签名生成的通用步骤如下：
第一步，设所有发送或者接收到的数据为集合M，将集合M内非空参数值的参数按照参数名ASCII码从小到大排序（字典序），使用URL键值对的格式（即key1=value1&key2=value2…）拼接成字符串。
第二步，在stringA最后拼接上应用key得到stringSignTemp字符串，并对stringSignTemp进行MD5运算，再将得到的字符串所有字符转换为大写，得到sign值signValue。
stringSignTemp="pay_amount=pay_amount&pay_applydate=pay_applydate&pay_bankcode=pay_bankcode&pay_callbackurl=pay_callbackurl&pay_memberid=pay_memberid&pay_notifyurl=pay_notifyurl&pay_orderid=pay_orderid&key=key"
sign=MD5(stringSignTemp).toUpperCase()
账户余额查询接口
提交方式：POST
接口地址：网关地址+/Payment_Dfpay_balance.html
| 参数名称 |
参数含义 |
是否必填 |
参与签名 |
参数说明 |
| mchid |
商户编号 |
是 |
是 |
平台分配商户号 |
| pay_md5sign |
MD5签名 |
是 |
否 |
签名验证 |
返回值
| 参数名称 |
参数含义 |
是否必填 |
参与签名 |
参数说明 |
| status |
状态 |
是 |
是 |
success:请求成功，error：请求失败 |
| msg |
状态描述 |
是 |
是 |
状态说明信息 |
| mchid |
商户号 |
是 |
是 |
status=success时返回 |
| data |
钱包列表 |
是 |
是 |
status=success时返回，包含用户所有钱包的余额信息 |
data字段说明
| 参数名称 |
参数含义 |
是否必填 |
参与签名 |
参数说明 |
| walletname |
钱包名称 |
是 |
是 |
钱包类型，如：Gcash、Maya等 |
| available_balance |
可用余额 |
是 |
是 |
单位：PHP |
| frozen_balance |
冻结余额 |
是 |
是 |
单位：PHP |
注意事项：
1. 接口返回的余额单位为PHP
2. 可用余额(available_balance)表示可以立即使用的金额
3. 冻结余额(frozen_balance)表示暂时无法使用的金额
渠道编码
请登录商户中心，API管理 通道费率中 查看所属应用的支付通道编码。
