翼支付商户接入规范-条码支付分册V1.4(2).doc

翼支付商户接入规范条形码支付修订历史记录日期版本说明修订2015.06.081.0初稿林健，张善良2015.07.151.1新增2.1下单业务返回码新增2.2查询接口新增2.3退款http接口（含分账）废弃2.5退款ws接口废弃2.6分账退款ws接口新增2.4冲正http接口废弃2.7冲正ws接口刘永富林健韦家驹2015.07.201.2修订及完善查询接口相关文档韦家驹2015.07.211.3下单接口返回值调整。增加HTTP退款和冲正接口的相关文档韦家驹20查询接口增加退款标志，及支付账户号韦家驹目录1.引言71.1编写目的71.2编写原则71.3读者对象71.4需求来源71.5术语定义72.条码支付72.1下单支付72.1.1接口描述72.1.2接口地址82.1.3接口参数82.1.4接口响应92.1.5响应示例102.1.6接口说明102.1.7客户端测试用例112.2查询132.2.1接口描述132.2.2接口地址132.2.3接口参数142.2.4接口响应142.2.5响应示例152.2.6接口说明152.2.7客户端测试用例162.3退款162.3.1接口描述162.3.2接口地址162.3.3接口参数172.3.4接口响应182.3.5响应示例182.3.6接口说明182.3.7客户端测试用例192.4冲正202.4.1接口描述202.4.2接口地址202.4.3接口参数202.4.4接口响应212.4.5响应示例222.4.6接口说明222.4.7客户端测试用例222.5退款【建议使用2.3】232.5.1接口描述232.5.2接口地址232.5.3接口参数242.5.4接口响应242.5.5响应示例242.5.6接口说明252.5.7客户端测试用例252.6分账退款【建议使用2.3】262.6.1接口描述262.6.2接口地址262.6.3接口参数262.6.4接口响应272.6.5响应示例272.6.6接口说明272.6.7客户端测试用例282.7冲正【建议使用2.4】282.7.1接口描述282.7.2接口地址292.7.3接口参数292.7.4接口响应302.7.5响应示例302.7.6接口说明302.7.7客户端测试用例302.8交易结果通知接口312.8.1接口描述312.8.2接口地址312.8.3接口定义322.8.4接口说明333.条码支付交互流程344.权限申请355.响应码说明356.商品信息填写说明431. 引言1.1 编写目的本文档的目的是为翼支付条码产品定义一个标准接口规范，以帮助外部商户更好的接入翼支付网关平台系统。1.2 编写原则根据翼支付系统管理规范，从业务人员的角度对需求的阐述，以及对需求描述的细化程度。此文档将在开发过程随着需求的变更而更改和修订。1.3 读者对象本手册的读者对象默认为:接入翼支付条码产品的商户开发人员。1.4 需求来源产品部门1.5 术语定义2. 条码支付2.1 下单支付2.1.1 接口描述接口名称商户下单支付接口描述商户请求翼支付网关，生成订单且完成支付接口类型HTTPS传输方式Post数据编码Utf-8接口提供者翼支付网关平台接口使用者商户2.1.2 接口地址生产地址/barcode/placeOrder 2.1.3 接口参数属性含义类型长度必填备注merchantId商户号n30M由翼支付网关平台统一分配subMerchantId子商户号ans30O由商户平台自己分配，在做支付时，可以一并发送过来，翼支付网关平台可以负责记录，如没有可以不填写barcode条形码号n30M商户POS扫描用户客户端条形码orderNo订单号an30M由商户平台提供，数字或字母组成orderReqNo订单请求交易流水号an30M由商户平台提供，数字或字母组成channel渠道n5M默认填：05busiType业务类型an5M默认填：0001orderDate订单日期n20M由商户提供，长度14位格式yyyyMMddhhmmssorderAmt订单总金额n10M单位：分订单总金额 = 产品金额+附加金额productAmt产品金额n10M单位：分attachAmt附加金额n10M单位：分goodsName商品名称ans256O商品信息storeId门店号n10M门店号backUrl后台返回地址ans255O商户提供的用于异步接收交易返回结果的后台url，商户可根据需要填写ledgerDetail分账信息ans256O商户需要在结算时进行分账情况，需填写此字段，详情见接口说明attach附加信息ans128O商户附加信息macMAC校验域an256M采用标准的MD5算法，由商户实现2.1.4 接口响应属性含义类型长度必填备注success是否成功booleanMTrue：成功False：失败代表商户下单的成功与失败result调用返回值ans100O当success为true时，result为下单详情，success为false时，result为nullerrorCode错误码ans10O当success为true时，为null，当success为false时，为错误码errorMsg错误描述ans10O当success为true时，为null，当success为false时，为错误描述请求成功success为true时响应结果result为：属性含义类型长度必填备注merchantId商户号n30M由翼支付网关平台统一分配merchantIdorderNo商户总订单号an30M查询到的商户订单号orderNoorderReqNo商户总订单请求流水号an30M查询到的商户请求流水号orderReqNoorderDate预留字段始终为nullourTransNo翼支付交易号an30M翼支付生成的内部流水号（用户支付后生成）transAmt订单金额n10MtransStatus交易状态A：请求（支付中） B：成功（支付成功）C：失败encodeType签名方式n1O1代表MD53代表RSA9代表CA默认为1signsign校验域an30M2.1.5 请求及响应示例请求参数示例：merchantId=043101180050000&subMerchantId=043101180050000&barcode=515665002854886972&orderNo=1433734609560&orderReqNo=14337346095601&orderDate=20150608113649&channel=05&busiType=0001&orderAmt=1&productAmt=1&attachAmt=0&goodsName=%E6%9D%A1%E7%A0%81%E6%94%AF%E4%BB%98&storeId=201231&backUrl=http%3A%2F%2F%3A8030%2FwebBgNotice.action&ledgerDetail=&attach=&mac=3B5E200FD1EF8988693F242438A32475响应参数示例：成功：success:true,result:merchantId:043101180050000,orderNo:1437384365362,orderReqNo:14373843653621,orderDate:null,transStatus:B,transAmt:1,ourTransNo:2015072000000207092286,encodeType:1,sign:E1E4E5141AB332F0F2E2A1EA0DE32120,errorCode:null,errorMsg:null失败：success:false,result:null,errorCode:BE300001,errorMsg:订单MAC域验证失败2.1.6 接口说明1. 商户的商户号由翼支付统一分配，商户需与翼支付的运营人员对接，提供商户资料，申请正式的商户号。2. 商户要保证订单号的唯一性。3. 订单请求流水号不能重复,建议以日期时间（yyyyMMDDhhmmss格式）加一固定长度（不小于6位）流水号组成，如： 20061012132425 + 0000001等。4. 订单流水号和订单号可以相同。（使用翼支付提供的“流程测试”商户时除外，如果相同会提示订单或流水号重复的错误）5. MAC校验，保证了交易信息到翼支付网关平台的完整性，参与MAC运算的字符及其顺序如下：a) 顺序MERCHANTID=123456789&ORDERNO=123456&ORDERREQNO=1234567&ORDERDATE=200603141210&BARCODE=111111&ORDERAMT=1&KEY=123456b) 此处的KEY为商户的数据KEY，可以通过翼支付的统一运行地址生成。此数据KEY对本文档其它接口进行MAC校验时同样适用。/login.jspc) 要求：将上述固定顺序组织的字符串，参数名均为大写，使用标准md5算法进行摘要，然后将摘要果转成16进制字符串，字符串建议使用大写，就是校验域MAC的值，并在提交订单时，将MAC值和订单信息一起提交到翼支付网关翼支付网关平台。d) 需保证MAC校验时中的各个参数，与下单请求时的参数完全一致。6. 商户若需分账，则填写ledgerDetail字段，例如：a) 规则：023101111:4|023102222:3|023103333:1 b) 说明：订单总金额4+3+1=8分,商户023101111分账4分，每组对应关系之间“|”分隔c) 分账权限与一般支付权限不同。商户分账支付的权限需要额外申请，并且在结算时翼支付将形成各个分账商户的对账文件。7. 下单支付接口返回的success值并不是最终支付结果。支付结果在下单成功情况下，result的transStatus字段代表支付结果。8. 返回结果中的翼支付网关流水号ourTransNo，当用户完成支付后才会生成。对于有密支付情况，由于用户未实际支付，返回的流水号为空字符串。商户可在查询接口获得该流水号。9. 接口响应中的sign值是网关根据返回结果进行的前面，保证收到结果的完整性，商户可以根据需要进行验签，目前签名默认为MAC形式，参与MAC运算的字符及其顺序如下：顺序：MERCHANTID=0018888888&ORDERNO=1234567890& ORDERREQNO=20141001&ORDERDATE=null&OURTRANSNO=201508080808&TRANSAMT=10&TRANSSTATUS=B&ENCODETYPE=1&KEY=123456ORDERDATE在下单接口返回时暂未使用，目前始终为null。2.1.7 客户端测试用例注：此用例仅供参考import mons.util.CryptTool;import org.apache.http.Consts;import org.apache.http.HttpEntity;import org.apache.http.HttpStatus;import org.apache.http.NameValuePair;import org.apache.http.client.config.RequestConfig;import org.apache.http.client.entity.UrlEncodedFormEntity;import org.apache.http.client.methods.CloseableHttpResponse;import org.apache.http.client.methods.HttpPost;import org.apache.http.impl.client.CloseableHttpClient;import org.apache.http.impl.client.HttpClients;import org.apache.http.message.BasicNameValuePair;import org.apache.http.util.EntityUtils;import .ssl.SSLContext;import space.QName;import java.security.cert.CertificateException;import java.security.cert.X509Certificate;import java.util.ArrayList;import java.util.HashMap;import java.util.List;import java.util.Map;import org.apache.http.conn.ssl.SSLConnectionSocketFactory;import org.apache.http.conn.ssl.SSLContextBuilder;import org.apache.http.conn.ssl.TrustStrategy;import java.util.ArrayList;import java.util.HashMap;import java.util.List;import java.util.Map;public class TestClient public static void main(String args) throws Exception String merchantId = 043101180050000; String orderNo = 1433734609522; String orderReqNo = 14337346095221; String orderDate = 20150608113649; String barcode = 512582454851204002; String orderAmt = 1; StringBuilder sb = new StringBuilder();/组装mac加密明文串 sb.append(MERCHANTID=).append(merchantId); sb.append(&ORDERNO=).append(orderNo); sb.append(&ORDERREQNO=).append(orderReqNo); sb.append(&ORDERDATE=).append(orderDate); sb.append(&BARCODE=).append(barcode); sb.append(&ORDERAMT=).append(orderAmt); sb.append(&KEY=).append(111);/此处是商户的key String mac = CryptTool.md5Digest(sb.toString();/进行md5加密(商户自己封装MD5加密工具类，此处只提供参考) Map param = new HashMap();/组装请求参数 param.put(merchantId, merchantId); param.put(subMerchantId, merchantId); param.put(barcode, barcode); param.put(orderNo, orderNo); param.put(orderReqNo, orderReqNo); param.put(orderDate, orderDate); param.put(channel, 05); param.put(busiType, 0001); param.put(TransType, B); param.put(orderAmt, orderAmt); param.put(productAmt, 1); param.put(attachAmt, 0); param.put(goodsName, 条码支付); param.put(storeId, 201231); param.put(backUrl, :8030/webBgNotice.action); param.put(ledgerDetail, ); param.put(attach, ); param.put(mac, mac); /创建信任证书 CloseableHttpClient httpClient = createSSLClientDefault(); HttpPost httpPost = null; CloseableHttpResponse response = null; try httpPost = new HttpPost(/barcode/placeOrder); List paramList = new ArrayList(); for (String key : param.keySet() paramList.add(new BasicNameValuePair(key, param.get(key); httpPost.setEntity(new UrlEncodedFormEntity(paramList, Consts.UTF_8); httpPost.setConfig(RequestConfig.custom().setConnectTimeout(30000).setSocketTimeout(30000).build(); response = httpClient.execute(httpPost); HttpEntity entity = response.getEntity(); int statusCode = response.getStatusLine().getStatusCode(); if(HttpStatus.SC_OK = statusCode)/如果响应码是200 System.out.println(EntityUtils.toString(entity); finally if (response != null) response.close(); if (httpPost != null) httpPost.releaseConnection(); httpClient.close(); /创建链接 public static CloseableHttpClient createSSLClientDefault() throws Exception SSLContext sslContext = new SSLContextBuilder().loadTrustMaterial(null, new AllTrustStrategy().build(); SSLConnectionSocketFactory sslSf = new SSLConnectionSocketFactory(sslContext); return HttpClients.custom().setSSLSocketFactory(sslSf).build(); /加载证书 private static class AllTrustStrategy implements TrustStrategy public boolean isTrusted(X509Certificate x509Certificates, String s) throws CertificateException return true; 说明当使用org.apache.http.client之外的第三方类封装HTTP请求时，需要注意1. HTTP请求中的字符串，需要经过URL编码，其中的中文字符使用UTF-8。2. HTTP请求中的Content-Type使用application/x-www-form-urlencoded; charset=UTF-8，请求方法为POST。2.1.8 错误码错误码描述备注BE199999请求参数有误检查HTTP请求相关代码BARCODE_VALIDATE_ERROR条形码验证异常849卡信息解密失败用户信息异常5146查询绑卡信息出错用户信息异常4008绑卡信息不存在用户信息异常-301订单MAC域验证失败-302校验订单出错检查订单金额-304商户未配置此交易权限1001商户未注册1002商户未配置密钥信息检查数据KEY是否申请1003商户未开通银行-3061分账商户不存在-3062分账金额有误-3063分账金额总和不等于订单金额-3064分账商户父商户有误-3065分账信息不允许有两个相同商户BARCODE_STORE_CODE_IS_EMPTY条码门店号不能为空BE999999系统繁忙，请稍后再试 系统原因，联系技术支协查2.2 订单查询2.2.1 接口描述接口名称订单查询接口接口描述为商户提供入口接口类型HTTPS传输方式POST数据编码Utf-8接口提供者翼支付网关平台接口使用者商户业务平台2.2.2 接口地址生产地址/query/queryOrder2.2.3 接口参数属性含义类型长度必填备注merchantId商户号n30M由翼支付网关平台统一分配orderNo订单号an30M由商户平台提供，数字或字母组成orderReqNo订单请求交易流水号an30M由商户平台提供，数字或字母组成orderDate订单日期an20M日期格式：yyyyMMddmacmac校验域an256M默认为0，当加密方式为1时有意义，采用标准的MD5算法，由商户实现2.2.4 接口响应参数含义类型和长度备注success是否查询到订单booleanTrue：成功False：失败result调用返回值ans100当success为true时取此值，result中包含的信息见下表errorCode错误码ans10当success为false时取此值，result为空errorMsg错误描述ans10当success为false时取此值，result为空refundFlag退款标识n10代表为退款，1 已退款2部分退款 3已冲正查询成功success为true时响应结果result(MAP)为：参数含义类型长度必填备注merchantId商户号n30M由翼支付网关平台统一分配orderNo商户总订单号an30M查询到的商户订单号orderReqNo商户总订单请求流水号an30M查询到的商户请求流水号orderDate商户下单时间n20MyyyyMMDDHHmmss查询到的订单实际日期，可能与查询请求日期不同ourTransNo网关平台流水号n30M翼支付生成的内部流水号transAmt交易金额n10M单位：分transStatus交易状态n1MA：请求（支付中） B：成功（支付成功）C：失败G：订单作废encodeType加密方式n1O1代表MD53代表RSA9代表CA默认为1signsign校验域anM验证签名，签名方式根据encodeType决定refundFlag退款标识n1M0代表为退款，1 已退款2部分退款 3已冲正customerID客户支付手机号n11M客户条码消费时的支付手机号，中间4位被隐去，用*代替如180*26872.2.5 请求及响应示例请求示例orderReqNo=20150713093607000001&orderNo=20150713093607&orderDate=20150713&mac=880D9E9DE657E3C351697D3B6CFE5626&merchantId=043101180050000HTTP请求对参数的顺序没有要求，保证参数名称完全一致（包括大小写）。响应示例订单存在success:true,result:merchantId:043101180050000,orderNo:20151026105223,orderReqNo:20151026105223000001,orderDate:20151026105358,transStatus:B,transAmt:1,ourTransNo:2015102600000297670338,encodeType:1,sign:B0C948619CB5895FEABEB39328934144,customerID:180*2687,refundFlag:0,errorCode:null,errorMsg:null订单不存在success:false,result:null,errorCode:BE110062,errorMsg:没有找到符合条件的记录。其它错误success:false,result:null,errorCode:BE199999,errorMsg:订单日期格式有误 接口响应的格式为JSON。2.2.6 接口说明1. MAC校验，保证了交易信息到翼支付网关平台的完整性，参与MAC运算的字符及其顺序如下：a) 顺序：MERCHANTID=0018888888&ORDERNO=1234567890& ORDERREQNO=20141001&ORDERDATE=201507020&KEY=123456b) 要求：将上述固定顺序组织的字符串，参数名均为大写，使用标准md5算法进行摘要，然后将摘要果转成16进制字符串，字符串建议使用大写, 就是校验域MAC的值，并在提交订单时，将MAC值和订单信息一起提交到翼支付网关翼支付网关平台。KEY值为商户的数据KEY。2. 接口响应的success字段标识的是查询过程的结果，并不代表交易的成功和失败。交易的结果当success为true时，取result中的tranStatus字段。字段为A，代表请求状态，表明用户正在输入密码或交易本身在进行中。字段为B时，代表本次交易成功。字段为C时，代表本次交易失败。字段为G时，代表本次交易已被作废。3. 订单请求时，为了加快查询的速度，需给定下单的日期，实际的查询范围，会在给定日期的前一天到给定日期的后一天范围内进行。4. 接口响应中的sign值是网关根据返回结果进行的前面，保证收到结果的完整性，商户可以根据需要进行验签，目前签名默认为MAC形式，参与MAC运算的字符及其顺序如下：顺序：MERCHANTID=0018888888&ORDERNO=1234567890& ORDERREQNO=20141001&ORDERDATE=2015070215000000&OURTRANSNO=201508080808&TRANSAMT=10&TRANSSTATUS=B&ENCODETYPE=1&KEY=1234562.2.7 客户端测试用例import mons.util.CryptTool;import org.apache.http.Consts;import org.apache.http.HttpEntity;import org.apache.http.HttpStatus;import org.apache.http.NameValuePair;import org.apache.http.client.config.RequestConfig;import org.apache.http.client.entity.UrlEncodedFormEntity;import org.apache.http.client.methods.CloseableHttpResponse;import org.apache.http.client.methods.HttpPost;import org.apache.http.impl.client.CloseableHttpClient;import org.apache.http.impl.client.HttpClients;import org.apache.http.message.BasicNameValuePair;import org.apache.http.util.EntityUtils;import java.util.ArrayList;import java.util.HashMap;import java.util.List;import java.util.Map;import .ssl.SSLContext;import space.QName;import java.security.cert.CertificateException;import java.security.cert.X509Certificate;import java.util.ArrayList;import java.util.HashMap;import java.util.List;import java.util.Map;import org.apache.http.conn.ssl.SSLConnectionSocketFactory;import org.apache.http.conn.ssl.SSLContextBuilder;import org.apache.http.conn.ssl.TrustStrategy;public class QueryClient public static void main(String args) throws Exception String merchantId = 043101180050000; String orderNo = 20150713093607; String orderReqNo = 20150713093607000001; String orderDate = 20150713; StringBuilder sb = new StringBuilder();/组装mac加密明文串 sb.append(MERCHANTID=).append(merchantId); sb.append(&ORDERNO=).append(orderNo); sb.append(&ORDERREQNO=).append(orderReqNo); sb.append(&ORDERDATE=).append(orderDate); sb.append(&KEY=).append(111);/此处是商户的key String mac = CryptTool.md5Digest(sb.toString();/进行md5加密(商户自己封装MD5加密工具类，此处只提供参考) Map param = new HashMap();/组装请求参数，参数名大小写敏感 param.put(merchantId, merchantId); param.put(orderNo, orderNo); param.put(orderReqNo, orderReqNo); param.put(orderDate, orderDate); param.put(mac, mac); /创建信任证书 CloseableHttpClient httpClient = createSSLClientDefault(); HttpPost httpPost = null; CloseableHttpResponse response = null; try /发起HTTP的POST请求 httpPost = new HttpPost(/query/queryOrder); List paramList = new ArrayList(); for (String key : param.keySet() paramList.add(new BasicNameValuePair(key, param.get(key); /UTF8+URL编码 httpPost.setEntity(new UrlEncodedFormEntity(paramList, Consts.UTF_8); httpPost.setConfig(RequestConfig.custom().setConnectTimeout(30000).setSocketTimeout(30000).build(); response = httpClient.execute(httpPost); HttpEntity entity = response.getEntity(); int statusCode = response.getStatusLine().getStatusCode(); if (HttpStatus.SC_OK = statusCode)/如果响应码是200 System.out.println(EntityUtils.toString(entity); finally if (response != null) response.close(); if (httpPost != null) httpPost.releaseConnection(); httpClient.close(); public static CloseableHttpClient createSSLClientDefault() throws Exception SSLContext sslContext = new SSLContextBuilder().loadTrustMaterial(null, new AllTrustStrategy().build(); SSLConnectionSocketFactory sslSf = new SSLConnectionSocketFactory(sslContext); return HttpClients.custom().setSSLSocketFactory(sslSf).build(); /加载证书 private static class AllTrustStrategy implements TrustStrategy public boolean isTrusted(X509Certificate x509Certificates, String s) throws CertificateEx