# 支付API ### 请求说明 * 本文档适用于已经在官方申请过渠道号channelId与私钥的合作方 * 合作方要求：提供渠道名称、注册账户 ### 流程图 ![](https://content.gitbook.com/content/CZbt3X4wpzSYqsOt0CQF/blobs/p0qIKRmLUmTHlHNOmwy8/swftpay.png) ![](file:///D:/work/swftcoin/swft-h5/swft-api/images/swftpay.png?lastModify=1554203813) #### 接入流程： ①开发者调用创建支付订单接口，创建支付订单； ②返回支付页面链接，用户进行付款； ③获取支付结果，以下两种方式都可行： ⅰ开发者提供支付完成通知接口，用户完成支付后，我们调用该接口进行通知； ⅱ 开发者调用查询订单状态接口，获取订单支付结果状态。 ### 接口列表 | 请求类型 | 请求方法 | 描述 | 接口示例 | | --------------------- | ---------------------- | ------ | ---- | | POST application/json | api/pay/createPayOrder | 创建支付订单 | 代码示例 | | POST application/json | api/pay/queryPayOrder | 查询订单状态 | 代码示例 | | POST application/json | 由开发者提供 | 支付完成通知 | | #### 创建支付订单 #### api/pay/createPayOrder #### 说明 合作方调用该接口，创建收款订单 #### 请求参数 | 参数名称 | 是否必须 | 数据类型 | 描述 | 默认值 | 取值范围 | | -------------- | ---- | ------ | ------ | --- | ----------------------------- | | channelId | 是 | String | 渠道编号 | | 由我们官方提供，eg：payaaa201903212028 | | channelName | 是 | String | 渠道名称简写 | | 开发者提供给我们，eg：xxMall | | sign | 是 | String | 签名 | | 参见签名生成 | | timestamp | 是 | Long | 时间戳 | | 毫秒时间戳 | | channelOrderId | 否 | String | 渠道订单Id | | 开发者自定义 | | channelUserNo | 否 | String | 渠道用户名 | | 开发者自定义 | | coinCode | 是 | String | 付款币种名称 | | eg：ETH | | amount | 是 | String | 付款金额 | | eg：1 | | remark | 否 | String | 备注 | | 订单备注 | #### 响应参数 ```yaml { "data": { "amount": "2", "channelOrderId": "channelorder001", "channelUserNo": "xxMall_zhangsan", "coinCode": "ETH", "payId": "jpedyB3T", "payUrl": "{host}/swft-v3/PayAPI.html?payID=jpedyB3T", "remark": "zhangsan pay to xxMall" }, "resCode": "800", "resMsg": "成功" } ``` #### data说明 ```yaml { "amount": "付款金额", "channelOrderId": "渠道订单号", "channelUserNo": "渠道用户名", "coinCode": "付款币种", "payId": "支付订单号", "payUrl": "支付页面链接", "remark": "备注" } ``` #### 查询订单状态 #### api/pay/queryPayOrder #### 说明 查询支付订单状态接口 #### 请求参数 | 参数名称 | 是否必须 | 数据类型 | 描述 | 默认值 | 取值范围 | | --------- | ---- | ------ | ------ | --- | --------------------- | | payId | 是 | String | 支付订单Id | | eg : Nlt0OnQP | | channelId | 是 | String | 渠道编号 | | eg：payaaa201903212028 | | sign | 是 | String | 签名 | | 参见签名生成 | | timestamp | 否 | String | 时间戳 | | 毫秒时间戳 | #### 响应参数 ```yaml { "data": { "amount": "2", "channelId": "payaaa201903212028", "channelName": "xxMall", "coinCode": "ETH", "createTime": "2019-03-22 17:11:38", "payId": "XMdqbM8Q", "remark": "zhangsan pay to xxMall", "sign": "DB99639E8B9EC419F88C94355DF1C483ACD420B7366C27CAB8E86A6D7B84CB52", "status": "complete", "timestamp": 1553838107450, "transType": "PAY_IN", "userNo": "5****@qq.com" }, "resCode": "800", "resMsg": "成功" } ``` #### data说明 ```yaml { "amount": "付款金额", "channelOrderId": "渠道订单号", "channelUserNo": "渠道用户名", "coinCode": "付款币种", "createTime": "创建时间", "payId": "支付订单号", "remark": "备注", "sign": "签名", "status": "支付订单状态", "timestamp": 时间戳, "transType": "订单类型", "userNo": "第三方开户账号" } ``` #### 支付完成通知 #### 说明 订单支付完成通知接口 #### 请求参数 | 参数名称 | 是否必须 | 数据类型 | 描述 | 默认值 | 取值范围 | | --------- | ---- | ------ | ------ | --- | --------------------------------------- | | payId | 是 | String | 支付订单号 | | eg: Nlt0OnQP | | status | 是 | String | 支付订单状态 | | 状态: valid-有效，complete-支付完成，invalid-超时无效 | | sign | 是 | String | 签名 | | | | timestamp | 是 | String | 时间戳 | | 毫秒时间戳 | #### 响应参数 ``` { "data": “响应完成”, "resCode": "800", "resMsg": "成功" } ``` #### data说明 ``` { "data": “响应信息”, "resCode": "返回状态码",//800：表示成功，其他表示失败 "resMsg": "返回结果信息" } ``` ### 错误码说明 #### HTTP请求错误码 | 错误码 | 含义 | 说明 | | --- | ------ | -------------- | | 200 | 成功 | | | 403 | 资源不可用 | header头信息错误或不全 | | 404 | 资源未找到 | url错误 | | 405 | 请求方式错误 | GET、POST方式替换 | | 500 | 服务器错误 | 需联系平台客服 | #### 接口返回数据resCode码 | 错误码 | 含义 | 说明 | | ---- | ---------------- | ------------- | | 800 | 成功 | 请求成功 | | 900 | 服务器错误 | 服务器错误 | | 213 | 非法请求 | 签名认证失败 | | 214 | 币种不存在 | 币种不一致 | | 216 | 金额数量不合法 | 付款金额不合法 | | 907 | 必填字段为空 | 参数请求不全 | | 1002 | 订单不存在 | 支付订单未创建或订单号错误 | | 1017 | 第三方渠道未创建账户或账号不存在 | 需要检查是否创建账户 | | 1018 | 第三方渠道账号未配置 | 需要联系官方进行配置 | | 1019 | 第三方渠道号未配置 | 需要联系官方进行配置 | | 1031 | 备注长度超出50个字符 | 备注长度超限 | | 1032 | 第三方渠道支付页面地址未配置 | 需要联系官方进行配置 | ### 生成签名 按照ASCII码的顺序对参数名进行排序，转化为json字符串，使用私钥签名，采用HMAC-SHA256加密方式。 #### 签名生成步骤说明 **第一步：** 设所有发送或者接收到的数据为集合M，将集合M内非空参数值的参数按照参数名ASCII码从小到大排序（字典序)，使用URL键值对的格式（即key1=value1\&key2=value2…）拼接成字符串stringA。 **特别注意以下重要规则：** 1. 参数名ASCII码从小到大排序（字典序)； 2. app\_id，timestamp为必填参数；timestamp为最近五分钟时间戳，超过5分钟失效; 3. 如果参数的值为空不参与签名； 4. 参数名区分大小写； 5. 传送的sign参数不参与签名，将生成的签名与该sign值作校验。 **第二步：** 在stringA最后拼接上key得到stringSignTemp字符串，并对stringSignTemp进行HMAC-SHA256运算，再将得到的字符串所有字符转换为大写，得到sign值signValue。 **伪代码举例** 假设传送的参数如下： channelId: mttest timestamp : 1516320000 body : test ```bash 第一步：对参数按照key=value的格式，并按照参数名ASCII字典序排序如下： stringA="app_id=mttest&body=test×tamp=1516320000"; 第二步：拼接API密钥： stringSignTemp=stringA+"&secret=my_test_secret" sign=hash_hmac("sha256",stringSignTemp,key).toUpperCase()="6A9AE1657590FD6257D693A078E1C3E4BB6BA4DC30B23E0EE2496E54170DACD6" //注：HMAC-SHA256签名方式 ``` **示例代码** ```java @Test public void deductBalance() throws IOException { JTextField field ; String url = "http://localhost:8088/channel/deductBalance"; TreeMap params = Maps.newTreeMap(); params.put("orderId","my_order_id"); params.put("channelId","test91021071617412"); long timestamp = System.currentTimeMillis(); params.put("timestamp",timestamp); String channelSign = getChannelSign(params, secret); params.put("sign",channelSign); System.out.println(url); System.out.println(JSON.toJSONString(params)); String result = HttpUtils.sendRequestBody(url, params); System.out.println(result); } ​ public static String getChannelSign(Map params,String secret) { StringBuilder result = new StringBuilder(); if (params != null) { for (Object key : params.keySet()) { Object value = params.get(key); result.append(key).append("=").append(value).append("&"); } String tempString = result + "secret=" + secret; try { System.out.println(tempString); String sign = EncryptUtils.sha256_HMAC(tempString, secret).toUpperCase(); System.out.println(sign); return sign; } catch (Exception e) { e.printStackTrace(); } } return null; } ``` > 代码中参与加密的参数及顺序为：`channelId=test91021071617412&orderId=my_test_id×tamp=1547987604644&secret=my_secret`