上个月接了个第三方支付对接的活，对方文档写得跟天书似的，我硬着头皮上了。结果呢？上线当天晚上11点，老板在群里艾特我：“支付回调怎么没反应？” 我手机差点扔出去。
这玩意儿我搞了3天，踩了13个坑，今天全记下来。谁再对接API，直接对着这个清单查，能省一半时间。
先说第一个坑：接口文档里写的“必须参数”少了一个字段。
对方文档写着必传字段是app_id、timestamp、sign、biz_content。我按这个拼好签名发过去，返回“签名验证失败”。查了2小时，最后在对方技术群里翻到一个历史消息，说“字段排序要排除sign本身，但必须包含nonce_str”。文档里压根没提nonce_str。
后来我写了个脚本，每次对接新API，先把文档里的必传字段全部列出来，再跟对方mock接口返回的报错信息做diff。少一个字段就补一个，直到完全不报错为止。
第二个坑：签名算法文档写的是MD5，实际是MD5+盐。
文档里写“使用MD5对拼接字符串进行加密”。我老老实实MD5，死活通不过。去问对方技术支持，对方回了句“哦，我们盐是固定的，在控制台里可以看，默认是空字符串”。空字符串？那你写什么MD5，直接写“对字符串做MD5，盐为空”不行吗？
从那以后，我所有签名生成都先跑一遍对方SDK的demo，抓包看生成的sign长什么样，再跟自己算的比对。比对不过，直接问。
第三个坑：回调通知的IP白名单没配。
这个最蠢。回调地址配好了，对方说“我们已经收到回调了，但你们服务器没收到”。我查了nginx日志，干干净净。后来发现对方回调服务器的IP段会变，而我只配了一个IP。最后把对方官网公布的IP段全部加进去，再加个动态更新脚本，每周拉一次。
第四个坑：接口超时时间设太短。
默认超时是5秒，对方接口偶尔要处理复杂业务逻辑，响应时间能飙到8秒。结果一堆请求超时重试，对方那边出现重复订单。最后我把超时时间改成15秒，重试机制加了个去重逻辑。每次重试前先查一次订单状态，如果已经成功了就不再发。
第五个坑：JSON序列化字段顺序不一致。
这个坑得细说。我用Go的json.Marshal，对方用Java的Jackson。Go默认按字段定义顺序输出，Jackson默认按字母序。结果签名字段拼接出来的字符串顺序不一样，签名就永远对不上。
解决方案：用map[string]interface{}接收对方JSON，自己定义排序规则，按字母序排好再拼字符串算签名。或者直接用对方提供的SDK，别自己造轮子。
第六个坑：时间戳格式。
对方文档写“timestamp格式为yyyy-MM-dd HH:mm:ss”，我传了“2025-03-15 14:30:00”，对方返回“时间戳格式错误”。后来发现对方解析时要求时区必须是UTC+8，而且秒数必须补零。我传的14:30:00没问题啊？结果是对方代码里有个bug，对两位数的小时数做了特殊处理，20点以后就报错。最后我直接传时间戳毫秒数，绕过去了。
第七个坑：回调通知的幂等性没做好。
对方回调通知会重试3次，每次间隔5秒。我没做幂等，第一次处理成功了，第二次又来，又处理了一次，生成了两条重复记录。后来加了个请求唯一ID，每次处理前先去redis查一下这个ID是否处理过。处理过就直接返回成功。
第八个坑：接口返回的HTTP状态码含义跟标准不一样。
对方接口返回200表示成功，但有一次返回了200，body里却写着“code:50001, msg:系统繁忙”。我按HTTP 200处理了，结果业务没成功，用户那边显示支付失败，钱却扣了。最后我改成只认body里的业务状态码，HTTP状态码只做连接层面的判断。
第九个坑：签名密钥轮换没通知。
对方说密钥有效期90天，到期前7天会发邮件通知。结果我那个对接邮箱是公司公共邮箱，没人看。密钥到期那天，所有请求全部失败。最后我写了个定时任务，每天凌晨检查密钥有效期，如果小于30天就报警。同时跟对方确认了密钥轮换的API接口，实现自动换密钥。
第十个坑：接口字段名大小写敏感。
对方文档写“userName”，我传了“username”。对方返回“字段不存在”。我查了3小时，最后发现是大小写问题。从那以后，所有字段名都严格按照文档来，用代码生成工具自动生成结构体，手写容易写错。
第十一个坑：分页接口的游标设计。
对方分页用游标，文档写“cursor传上一页返回的next_cursor”。我第一页没传cursor，正常返回。第二页传了上一页的next_cursor，结果返回的数据跟第一页一样。后来发现对方游标设计是按ID排序的，但ID不是单调递增的，导致游标定位不准。最后我改成按时间排序，用时间戳做游标。
第十二个坑：接口文档版本跟实际版本不一致。
对方文档版本是v2.1，实际接口是v2.0。有些字段v2.0不支持，我传了就报错。最后我每次对接都先请求一个最简单的接口，确认版本号跟文档一致。不一致就问。
第十三个坑：没有做全链路日志。
这个最致命。出问题的时候，我只有服务器日志，没有请求链路ID。对方问我“你那笔订单的traceId是什么”，我翻半天找不到。后来所有请求都加一个requestId，传给对方，对方也在日志里记。出问题直接拿requestId去两边查。
总结一下，对接API最核心的就是三件事：签名、幂等、日志。签名错了全完蛋，幂等没做好数据乱，日志不全查不了。
我现在所有对接项目都建一个checklist，每次对接完手动过一遍。这13个坑，我花了3天才填完。你花10分钟看完，能省3天。
对了，最后说一句：千万别信文档。文档是理想，代码是现实。拿demo跑通再动手，比看文档省心十倍。
📎 延伸阅读
看完这篇，如果你想：
- 直接拿工具 → 回复”13“，我把跨境获客工具包发给你
- 系统学习 → 点击菜单”AI训练营”，从0开始跑通AI变现