简介面向移动支付开发者的云闪付交易编号转支付数据可运行源码包覆盖苹果与安卓两大移动平台专门解决双端在支付入参格式转换上的差异问题。苹果端采用三重数据加密标准3DES算法完成交易编号到支付数据的转换保障敏感支付信息传递安全安卓端则通过Base64编码方式重组支付数据两种方案均附带在线测试链接和可直接运行的调用示例开发者可按自己的平台对照选用。资源压缩包共3个文件包体仅4KB结构精简。其中网页文件可在浏览器中直接打开用于预览和验证转换效果云端开发环境配置文件便于导入后快速调试版本控制忽略清单帮助过滤本地临时文件方便纳入现有代码库。已有521人浏览学习适合对接周期紧、想快速掌握云闪付联调环节的初中级开发者。通过运行代码可理解交易编号与支付数据之间的字段映射和加密编码规则改动少量参数即可复用省去从零编写转换逻辑和反复排查格式错误的时间。1. 从TN到PayData这套源码解决的究竟是什么问题做跨境电商站点或者接单做收银台改造时最容易卡住的一步不是页面而是支付回调。用户用云闪付App完成付款后你的后端会收到一个TN交易流水号而对接的第三方渠道SDK只认它自己定义的PayData结构。两边字段名不同、签名算法不同、回调时机也不同靠人肉拼接报文既慢又容易出错。这份云闪付TN转PayData可运行源码把从收TN、验签、查单、组装PayData到签名透传的整段链路打包成了一个能直接启动的Spring工程。它适合正在做支付业务开发的工程师也适合接支付类外包源码单的开发者拿到手改配置就能跑起来做二次开发。2. 拆开源码包模块划分、配置项与启动方式2.1 先看包结构别急着改代码一个陌生源码包拿手里我一般先做两件事看目录布局和看配置文件。这类支付适配工程最常见的包结构是下面这个样子四个模块各管一段职责pay-adapter/ ├── src/main/java/com/pay/adapter/ │ ├── facade/ // 接收回调的HTTP接口层 │ ├── service/ // TN→PayData转换核心逻辑 │ ├── channel/ // 第三方渠道SDK适配 │ └── common/ // 签名、HTTP、JSON工具 ├── src/main/resources/ │ ├── application.yml │ └── cert/ // 密钥与平台公钥 └── pom.xmlfacade层做的事情很薄接收HTTP POST请求取出原始报文交给service层不在这里拼任何业务字段。service层是核心TN回调进来之后它要干四件事验签、查单或查本地订单、映射字段、生成签名。channel层做的是渠道适配把组装好的PayData送到上游或者把PayData直接放进同步响应返回给调用方。common层是RSA签名和HTTP调用工具签名工具必须独立成类别和业务代码混在一起否则后面切环境的时候会非常痛苦。为什么要这样拆因为做支付外包接单的时候同一个后端往往要接多个支付渠道。facade保持稳定service做通用转换channel层把每家渠道的差异隔离在独立类里新增渠道时只动channel包不动核心链路。源码包里这种分层方式直接拿来做底座是划算的。2.2 配置文件里最关键的三个参数一打开application.yml先别被一大堆回调地址、密钥路径、超时时间吓住。真正影响链路通断的只有三个点回调接口路径、密钥文件位置、渠道标识请求头。下面是一份简化后的配置模板server: port: 8080 pay: platform: callback-url: /api/pay/notify merchant-id: 603xxxx # 商户号从开发者后台复制 cert: private-key: classpath:cert/merchant_rsa_private.pem # 本端商户私钥 public-key: classpath:cert/platform_rsa_public.pem # 平台公钥用于验签 channel: default-header: PAYADAPTER # 渠道标识缺失时兜底 timeout-ms: 3000 # 调用渠道接口超时注意三处别搞反。private-key指的是自己这端用于签名请求的私钥不是平台给的那把public-key是平台公钥回调过来验签就靠它default-header是第三方渠道要求带的请求头标识空值会导致上游直接返回401。源码包里一般会带application-sandbox.yml和application-prod.yml两套环境文件启动时用--spring.profiles.activesandbox切换密钥路径千万别在全局配置里用绝对路径不然换一台服务器就要改代码。2.3 启动与冒烟测试这套工程是用Maven构建的JDK 1.8及以上就能跑。常规启动方式如下mvn clean package -DskipTests java -jar target/pay-adapter-1.0.0.jar --spring.profiles.activesandbox启动完之后别急着连真实平台先用一条curl做冒烟确认服务能收报文、能返回结构化的回包curl -X POST http://localhost:8080/api/pay/notify \ -H Content-Type: application/json \ -d {\tn\:\202406121030001234567890abcdef\,\orderNo\:\PO202406120001\,\payStatus\:\FINISHED\,\tradeTime\:\20240612103000\,\totalAmount\:\1000\,\sign\:\test-sign\}冒烟通过的判断标准是接口不报5xx响应体里有一个固定的ACK结构code是SUCCESS或FAIL都算正常。这里要泼一盆冷水千万不要以为curl通了业务就通了。真实平台回调的报文里带签名和渠道头冒烟脚本里sign字段是假的所以冒烟只是验证服务存活和基本参数绑定真正的验签、字段映射、渠道推送得等后面章节用真实验证手段来测。3. 核心链路实操从TN回调到PayData返回要过的三道关3.1 第一关收TN先验签再谈业务回调入口要做的事情其实非常少存原始报文、验签、幂等判断、交给转换服务。源码里facade层的控制器大概长这样RestController RequestMapping(/api/pay) public class PayNotifyController { private final TnToPayDataService service; public PayNotifyController(TnToPayDataService service) { this.service service; } PostMapping(/notify) public MapString, String notify(RequestBody String rawBody) { // 1. 先存原始报文排查签名和映射问题时靠它还原现场 log.debug([callback-raw] {}, rawBody); // 2. 验签失败直接返回FAIL让支付平台走重试不要默默吞掉 MapString, String data parseAndVerify(rawBody); if (data null) { return responseOf(FAIL, sign verify failed); } // 3. 幂等检查用 tn orderNo 组合做锁后面避坑章节细讲 boolean duplicated idempotentService.isProcessed( data.get(tn), data.get(orderNo)); if (duplicated) { return responseOf(SUCCESS, duplicated callback); } // 4. 交给转换服务得到 PayData 并透传 PayData payData service.convert(data); return responseOf(SUCCESS, payData.toJson()); } private MapString, String responseOf(String code, String msg) { MapString, String map new HashMap(); map.put(code, code); map.put(message, msg); return map; } private MapString, String parseAndVerify(String rawBody) { // 常见做法先把JSON解析成Map再按平台约定的字段拼接待验签串 // 调用common包里的SignTool做验签失败时打印详细原因 return null; } }逻辑说明控制器只做编排所有转换都下沉到service。验签失败返回FAIL很重要因为支付平台的异步回调有重试机制你返回FAIL它过几分钟会再推一次如果返回SUCCESS平台就认为你收妥了丢单只能人工补。幂等检查放在验签之后、业务处理之前避免重复通知把订单状态覆盖成错误值。参数说明这里的tn是平台回调报文里的交易流水号orderNo是我们自己系统的商户订单号。两个字段在幂等判断时必须组合使用因为某些渠道重发时tn一致但orderNo可能因为网关重试而出现相同值单靠tn做唯一键有隐患。3.2 第二关组装PayData字段映射和签名顺序是命门TN拿到手之后一种是回调报文里已经带全了订单字段可以直接映射另一种是回调里只有tn需要调用支付平台的查询接口把订单详情取回来再组装PayData。源码里两种方式都兼容核心是下面这张字段映射表PayData字段来源字段说明tn回调报文tn原样透传tradeNoorderNo商户订单号payStatuspayStatus渠道FINISHED转成SUCCESSrespCode固定00渠道SDK用它判断成功respMsg回调respMsg失败原因透传payTimetradeTime统一成yyyyMMddHHmmsssettleAmttotalAmount单位是分映射的代码不复杂但有一个坑必须提前说签名用的字符串顺序和字段选取顺序必须严格按渠道SDK的要求来多一个字段、换一次顺序对方验签就挂。下面这段是转换服务里的核心片段public PayData convert(MapString, String raw) { PayData payData new PayData(); payData.setTn(raw.get(tn)); payData.setTradeNo(raw.get(orderNo)); payData.setPayStatus(FINISHED.equals(raw.get(payStatus)) ? SUCCESS : FAIL); payData.setRespCode(00); payData.setPayTime(formatTime(raw.get(tradeTime))); payData.setSettleAmt(String.valueOf(raw.get(totalAmount))); // 签名串顺序必须固定tn tradeNo payStatus respCode settleAmt payTime String toSign String.join(, payData.getTn(), payData.getTradeNo(), payData.getPayStatus(), payData.getRespCode(), payData.getSettleAmt(), payData.getPayTime()); payData.setSign(signTool.sign(toSign)); return payData; }逻辑说明组装PayData本质上是两件事一是字段名映射二是枚举值映射。字段名映射好理解payStatus的FINISHED到SUCCESS属于枚举映射漏掉这一步渠道方拿到的状态永远是未知值。签名顺序我用String.join按固定顺序拼之后要加字段必须同步跟渠道方确认对方的验签串是否也加了该字段。参数说明settleAmt这里我写了String.valueOf因为回调报文里金额有时是数字类型有时已经带了小数建议在format阶段统一乘以100转成整数分。千万别在映射层做四舍五入金额精度问题会在对账的时候爆发属于那种事后查三天才能定位的翻车现场。3.3 第三关返回给渠道SDK兼容同步和异步两种方式PayData组装好之后对接方式分两种。一种是同步返回我们的接口作为被调用方把PayData放进HTTP响应体返回给上游。另一种是异步推送我们作为调用方把PayData POST到渠道配置的回调地址。源码里这两种方式都做了封装异步推送的代码是个重点因为请求头最容易出错public void pushToChannel(PayData payData) { String targetUrl config.getChannelCallbackUrl(); HttpHeaders headers new HttpHeaders(); // 这个头极容易漏第三方渠道要求必须带渠道标识否则直接401 headers.add(x-pay-channel, config.getChannelHeader()); headers.setContentType(MediaType.APPLICATION_JSON); HttpEntityString entity new HttpEntity(payData.toJson(), headers); ResponseEntityString resp restTemplate.postForEntity(targetUrl, entity, String.class); // 对方返回 invalid sign 时先打印你发出的原文 // 再拿对方SDK的待验签串对比大部分情况是字段顺序不一致 log.info([push-channel] response status{}, body{}, resp.getStatusCode(), resp.getBody()); }逻辑说明同步返回的优点是链路短调试方便异步推送的优点是上游不用等你处理完但你需要额外处理渠道方的响应码。第一次接渠道时我通常先走同步返回看链路效果跑通之后再切成异步推送降低排查变量。这里的restTemplate建议单独配置超时时间不要用默认值渠道方接口偶尔慢默认的几十秒超时会让线程池全部占满。参数说明x-pay-channel这个头是渠道用来识别调用方身份的value要和渠道方约定不是一个随意写的字符串。defaultHeader这个兜底值只负责防止空指针真正上线时必须在配置里显式写清楚渠道分配的值。4. 常见问题排查联调时最容易翻车的五个坑这一章的五条记录每一条都是真金白银踩出来的。按照现象、原因、解决的顺序写方便你遇到问题时直接对照定位。4.1 respCode00但验签一直失败现象回包里的交易结果是成功但日志里一直是sign verify failed验签异常堆栈反复出现查了很久都看不出业务字段有什么问题。原因九成情况是密钥环境错位把沙箱平台的公钥配在了生产环境或者反过来还有一成是签名算法不匹配平台开通时用的RSA2代码里默认还在用老RSASHA1和SHA256验签结果当然对不上。解决第一步确认cert.public-key路径指向的确实是当前环境的平台公钥第二步把SignTool里的算法换成平台开通时约定的算法第三步在验签失败日志里打印出待验签串原文拿原文去平台的验签工具在线对比。待验签串原样打印是我后来养成的强制习惯很多所谓玄学问题一打印就现原形。4.2 返回401渠道头缺失现象PayData组装完异步推送给渠道回调地址时秒回401 unauthorized但同一个服务用同步返回方式冒烟一点问题都没有。原因restTemplate发送请求时HttpHeaders里没加x-pay-channel或者channelHeader配置是null导致整个header被HttpHeaders过滤掉。这个坑很隐蔽因为同步返回链路根本不会触发这个header只有切到异步推送才现形。解决在配置类里启动时检查channelHeader是否为空为空直接抛异常拒绝启动同时在拦截器里写一个兜底默认值避免漏配时发出去一个无头的请求。这个兜底值只保证请求能发出去能不能被渠道方认领还是要看真实配置。4.3 空指针timeout字段为null现象测试环境偶尔报NullPointerException出问题位置在service层某个字段映射处重启之后又正常过一天又随机出现。原因回调报文里某些流程不传timeout字段转换层直接用map.get(timeout)然后强转Stringnull被塞进了后续逻辑。解决所有从回调Map取字段的地方统一用getOrDefault兜底别做裸强转String timeout String.valueOf(map.getOrDefault(timeout, 3000));同时转换前必须把原始报文完整存一份到日志或者数据库否则平台没下发还是你没接住永远分不清。我的习惯是回调原始报文至少保留24小时排查对账问题时这就是后悔药。4.4 重复回调导致重复入账现象同一笔订单收到两次回调日志里能看到两个线程几乎同时通过了幂等检查最终订单表里出现两条重复记录。原因幂等判断用的是先查后写存在并发窗口。两个请求同时进来都查到订单未处理然后都往下走业务逻辑。唯一键如果只用了tn渠道重发时tn相同数据库层也没挡住。解决三层兜底一起上。数据库加唯一索引用tn加orderNo做联合唯一应用层用Redis的SETNX做10秒幂等锁业务处理放事务里锁和事务要包住整个处理过程。线上遇到重复回调先看唯一索引存不存在不要急着改业务代码。4.5 切生产环境后第一次回调查不到单现象沙箱环境一切正常切换到生产profile之后第一笔真实订单就返回订单不存在。原因多环境配置文件互相覆盖某个Value注入的常量写在了静态工具类里环境切换时静态变量的值没有刷新导致回调过来后查单接口连的还是沙箱地址。解决环境相关配置全部集中放到bootstrap.yml统一维护启动时打印配置指纹包括私钥后四位、当前环境名、渠道回调地址肉眼核对一遍再放流量进来。工具类一律用构造函数注入配置禁止在静态方法里直接读Value。从那以后我每换一次环境第一件事就是看启动日志里的配置指纹。5. 验证方法用沙箱与日志回放把“可运行”变成“真能跑”5.1 沙箱环境准备账号、密钥与回调地址没有沙箱环境的验证都是自我安慰。接这类支付回调源码包第一步去支付平台的开发者后台开通沙箱商户号拿测试商户号、测试卡、密钥文件。注意沙箱的密钥和正式环境是两套文件名和内容都不一样不要图省事互相覆盖。回调地址是重灾区。沙箱平台要异步回调你的本地服务时不能用localhost或192.168开头的地址平台根本访问不到。常见做法是用内网穿透工具把本地8080端口映射成一个公网URL然后把回调地址填成这个公网URL。每次重启穿透工具公网URL的域名前缀可能变要记得同步改配置。密钥文件放的位置也讲究。按application-sandbox.yml里classpath:cert/的路径放文件名严格一致。我见过有同学把私钥文件放在target目录下mvn clean之后密钥被清掉接口全部报验签失败排查半天才发现是文件没了。5.2 看日志回放三个日志文件分别看什么这套源码比较舒服的一点是日志拆得很清楚排查问题时能快速定位是哪一段出的问题。一般会拆成三个日志文件日志文件核心查看内容判断标准access.log平台回调的原始报文和响应入站请求有响应且非5xxconvert.log字段映射前和映射后的完整数据tn和orderNo都能对上sign.log待签名字符串和验签结果待签串与平台在线工具核对一致为什么要拆开因为支付联调有一个黑色定律问题永远出在你没打日志的那一行。如果全塞在一个log里请求量一上来想找一条回调的完整轨迹要翻半天。拆开后先看access.log确认平台有没有把报文送到再看sign.log确认验签是否通过最后看convert.log确认字段映射是否符合预期。三步下来问题在哪个环节非常清楚。我平时联调时习惯在回调处理的开头和结尾各打一行日志日志里带上tn和orderNo这样用grep这两个字段就能把一条请求的完整生命周期拉出来grep 202406121030001234567890abcdef logs/*.log这条命令能把同一笔订单在接入日志、转换日志、签名日志里的所有痕迹一次性捞出来比在IDE里打断点效率高得多。回调类问题往往是时序问题断点调试会改变时序反而掩盖真相日志回放才是最接近真实的排查方式。5.3 自测脚本模拟一次完整回调在沙箱真实验证之前可以先跑一个本地模拟脚本验证服务逻辑是否完整。下面这个bash脚本模拟了平台回调到本地服务的全过程并检查转换日志里是否出现了对应的处理记录#!/bin/bash # 模拟一次回调验证服务能接收、能转换、能落日志 BASE_URLhttp://localhost:8080/api/pay/notify PAYLOAD{tn:2024TEST0001,orderNo:PO0001,payStatus:FINISHED,tradeTime:20240815120000,totalAmount:1000,sign:test-sign} echo send mock callback curl -s -X POST $BASE_URL \ -H Content-Type: application/json \ -d $PAYLOAD | python3 -m json.tool echo check convert log sleep 2 grep 2024TEST0001 logs/convert.log参数说明sign字段是假的test-sign因为本地冒烟只验证链路不验证真实签名。如果机器上没有python3去掉管道里的python3 -m json.tool直接看原始JSON响应也行。判断通过标准是convert.log里出现了tn为2024TEST0001的记录说明服务已经把报文收到并做了转换处理。这个脚本解决的是“本地到底能不能跑起来”的问题不能替代沙箱真实验证。真实的签名、真实的渠道头、真实的回调时间只有沙箱平台能给你。两者配合使用本地脚本每天回归沙箱环境每周至少完整跑一次真实支付流程。6. 一个收敛技巧把TN转PayData沉淀成通用工具类6.1 抽象出稳定的三步法做多了之后你会发现TN转PayData这件事本质可以收敛成一个纯函数入参是回调原始Map出参是标准化PayData对象。业务代码里不应该到处出现“new PayData然后手动set字段”的写法那样每接一个新渠道就要复制改一遍。源码里这个工具类值得直接拿来用public class TnToPayDataConverter { private static final ListString SIGN_FIELDS List.of( tn, tradeNo, payStatus, respCode, settleAmt, payTime ); public PayData convert(MapString, String raw) { return PayData.builder() .tn(trim(raw.get(tn))) .tradeNo(trim(raw.get(orderNo))) .payStatus(FINISHED.equals(raw.get(payStatus)) ? SUCCESS : FAIL) .respCode(raw.containsKey(respCode) ? raw.get(respCode) : 00) .payTime(formatTime(raw.get(tradeTime))) .settleAmt(toFen(raw.get(totalAmount))) .sign(signWithFixedOrder(SIGN_FIELDS, raw)) .build(); } }逻辑说明入参固定Map出参固定PayData签名顺序用SIGN_FIELDS常量数组定死。以后渠道方要求加字段先确认对方SDK验签串里有没有这个字段如果有往SIGN_FIELDS里加一项同时提供对应的getter方法即可。把转换做成纯函数还有一个额外好处单元测试非常好写给定一张Map断言PayData的每个字段值比启动整个Spring容器做集成测试快一个数量级。6.2 我最终保留下来的两个习惯第一所有密钥文件和配置文件只允许用相对路径环境切换靠profile不靠改代码。第二任何一次内容修改之后上线前必须强制走完沙箱到本地脚本回放的完整流程。当初有一次我调整了payStatus的枚举映射本地冒烟是过的因为测试数据里写死了FINISHED但真实沙箱回调里状态值是PROCESSED漏了这个枚举值导致压测时才暴露。从那以后我每次接这种回调转换类的源码都会先画一张“入参字段到PayData字段再到签名串顺序”的三列映射表确认每一个枚举值都有对应处理再动手改业务。这份源码包的价值就在于此它把最容易出错的那段链路做成了可运行、可替换、可扩展的底座省掉的不只是联调时间还有那些事后想起来都后怕的对账事故。希望帮到你。本文还有配套的精品资源点击获取
