简介面向微信支付服务商与特约商户进件业务开发者的 PHP 接口示例包围绕特约商户进件、查询等核心接口提供可运行的 demo适合熟悉微信支付 v3 接口但需要快速入门的后端工程师。压缩包内共 3 个文件含 2 个 PHP 源码文件和 1 个证书存放说明 txt代码体量精简8KB 的体积便于直接对比接口调用与参数组装逻辑。作者为全部关键流程添加了中文注释清晰标注了 API 证书存放位置、进件请求与结果查询的调用顺序省去翻阅官方文档的时间。目前已有 1458 人学习下载对于正在对接小微商户或特约商户进件服务的开发者而言是一份可直接参考的轻量示例。1. 特约商户进件API不跑通 demo商户入驻功能根本不敢上线给一个支付系统接「商户入驻」功能头一件事就是找收单机构要进件接口文档和配套 demo。特约商户进件API 是收单机构对外开放的一组 HTTP 接口负责提交商户资料、查询进件进度、接收审核结果demo 则是把这组接口调通的最小示例通常会覆盖进件提交、进件查询、回调验签三块。它的价值在于你不需要先啃完支付行业的字段规范和风控要求照着 demo 把请求发出去、把状态查回来就能确认联调环境通不通、签名对没对上。我会按实际对接这类接口的经验把接口形态、报文设计、签名规则、状态机和踩坑点一次讲清适合正在接进件 API 的支付后端、外包开发者和独立开发者。2. 进件接口的报文设计字段分组、状态机与同步/异步之争接进件接口之前先看文档里两样东西一个是入参字段清单一个是状态流转说明。这两个看懂了demo 里每个字段为什么存在、响应里的 status 怎么消费就都有依据了。很多新手上来就抄 demo 改参数结果字段含义不理解驳回以后改都不知道从哪改起。2.1 一张进件请求表主体、经营、结算、影像四组字段不同收单机构的进件字段不完全一样但核心就四组。我一般建议拿到文档后先按这个分组把字段归类遇到没见过的字段先丢进对应组里理解起来快很多。分组典型字段说明商户主体merchant_name、license_no、license_type、legal_person、legal_id_card企业名称、营业执照号、法人身份证用于实名和工商校验经营信息mcc、store_name、store_address、contact_phone、industry_type经营类目直接影响费率风控不能乱填结算信息settle_account_name、settle_account_no、settle_bank、settle_branch对公账户或法人银行卡审核通过后用于结算打款影像资料license_pic、legal_id_card_pic_front、legal_id_card_pic_back、store_photo通常走图片上传接口拿到 URL再拼进进件请求字段层面的注意点先说三个最容易错的。第一license_no 不是只填统一社会信用代码的纯数字很多机构要求带括号和字母原样传比如「91330106MA2XXXXX(1/1)」多一位少一位都会校验不过。第二mcc 这个类目码直接决定费率档位和风控策略填错可能在审核环节被驳回商户侧报「经营类目与实际经营范围不符」。第三结算账户名和企业名不一致时部分机构允许填法人个人账户但要额外传一个 settle_account_type 字段声明不声明会被当成「非法结算账户」直接退回。demo 里看到的字段数量比生产少这是正常的。收单机构给的 demo 通常只保留必填字段可选项比如门店照片、门头照、特殊资质文件在注释里标注。你往生产环境迁移时把这些可选项按商户类型补上就行不用一开始就全部传完。另外务必确认字段的值域license_type 有的机构收「UNIFIED_SOCIAL_CODE」有的收「1」这个枚举对不上后面所有校验都白搭。2.2 进件状态不是只有成功失败六状态流转与操作权限进件接口返回里的 status 字段新手最容易理解成「提交成功就是成功」。实际上「受理成功」离「进件成功」还隔着一次审核甚至隔着一次打款验证。以我接过的几套进件接口为例状态通常有这几档状态值含义你能做什么0已受理等待审核什么都不做等回调或查询1审核中资料复核不能修改只能查2已开通商户号生效可以接交易接口3审核驳回查 refute_reason改资料后换新单号重提4待补充资料可用修改接口补传材料5已注销/关闭不可逆需要重新进件这里有个关键点状态 3 和状态 4 在业务上差别很大。状态 4 是机构允许你「在原有进件单上补资料」通常有专门的补充接口或者把原单号再提交一次状态 3 是整单驳回你要么改资料换新 request_no 重走流程要么走人工申诉。demo 里往往只写了提交和查询没写补充资料的分支但生产环境里这块出问题最多。另一个容易忽略的是状态之间的「可操作边界」。比如状态 2 之后要改结算账户走的是「结算账户变更接口」而不是重新进件状态 5 之后原来的商户号不能复用必须重新进件生成新商户号。这些行为不是 demo 能覆盖的文档状态说明里会写联调前先读一遍。我的习惯是把状态表和可操作动作整理成一张内部映射表写代码时按表分支避免临场猜。2.3 为什么进件必须走异步人工审核、小额打款与风控黑名单进件接口提交后响应里通常只有一个 request_no、一个状态 0没有商户号。这是异步审核决定的机构要做的不是立刻发商户号而是跑一串校验。第一道是机器校验工商数据比对、法人身份证核验、银行卡四要素验证秒级到分钟级。第二道是人工复核有些机构对大额结算或特定类目比如黄金珠宝、二手奢侈品要人工看资料半小时到一天都可能。第三道是小额打款验证机构给结算账户打一分钱或几分钱要求你回填金额确认账户归属这个流程天然就是异步的。第四道是风控黑名单法人、企业、手机号、IP 都会过一遍黑名单库命中就直接驳回。所以你在设计调用方的时候不要把「进件接口返回成功」当成「商户可以开始收款」。正确的时序是提交进件 → 得到 request_no → 开启轮询或等回调 → 状态变成 2 拿到 merchant_no → 才能去调交易接口。demo 里进件和查询是两个独立接口也是因为这个——进件是「受理」查询是「追踪」两者合在一起才是完整流程。异步的特性还意味着你的数据库里要预留 created_at、updated_at、last_query_at 这类时间字段排查「为什么一直审核中」时全靠它们判断卡在哪个环节。3. 用 Python 跑通进件 demo签名、提交与响应解析文档看完进入动手阶段。大多数收单机构提供 Java、PHP、Python 几种示例我习惯先用 Python 把流程跑通因为 requests 写起来最短排查问题时改参数也快。这一章给出一套能直接改用的进件 demo 脚本并解释每个参数的作用和顺序要求。3.1 签名先生成还是先加密顺序错了接口必挂进件接口最大的玄学在签名。几乎所有进件接口都需要签名防篡改也防伪造形式一般是把请求参数按字典序排序拼成 kvkv再拼接密钥做摘要。拿到 demo 后先确认签名算法是 MD5 还是 HMAC-SHA256这两者的拼法不同混用必挂。更重要的坑是顺序如果请求里有身份证、银行卡这类敏感字段必须先对明文做加密一般是 RSA 公钥加密再用「加密后的密文」参与签名。顺序反过来机构那边解完密发现和签名对不上直接报验签失败。这个顺序错误在联调里出现频率非常高我放到避坑章单独讲。另一个顺序细节是参与签名的参数集合空字符串和 null 要不要参与排序数组参数怎么序列化摘要结果要不要转大写各家有各家的规矩。demo 的签名函数一般是对的你迁移到生产时最常翻车的是自己重写了签名函数把「排除空值」这一步漏了。3.2 一个可直接改用的进件请求脚本以下用 Python requests 写进件提交签名函数独立出来方便在查询、回调里复用import hashlib import json import time import requests APP_ID your_app_id APP_SECRET your_app_secret BASE_URL https://openapi.example.com def make_sign(params: dict, secret: str) - str: 生成 MD5 签名过滤空值 - 按 key 排序 - 拼接 - 加密钥 - 摘要转大写. # 注意排除空值和 sign 自身不然签名永远对不上 items [ (k, params[k]) for k in sorted(params) if params[k] not in (, None) and k ! sign ] raw .join(f{k}{v} for k, v in items) raw key secret return hashlib.md5(raw.encode(utf-8)).hexdigest().upper() def encrypt_rsa(plaintext: str) - str: RSA 公钥加密机构文档会给出填充方式PKCS1 或 OAEP. # 生产环境从机构下发的证书文件加载公钥不要用这段占位逻辑 return ENCRYPTED: plaintext[::-1] def merchant_submit(): # request_no 是幂等键和后续查询的依据不要用时间戳当单号 params { app_id: APP_ID, request_no: M20240101001, merchant_name: 杭州某某餐饮有限公司, license_no: 91330106MA2XXXXXX(1/1), license_type: UNIFIED_SOCIAL_CODE, legal_person: 张三, contact_phone: 13800000000, mcc: 5812, store_name: 某某餐饮西湖店, store_address: 杭州市西湖区某路 1 号, settle_account_name: 杭州某某餐饮有限公司, settle_bank: 招商银行杭州分行, timestamp: str(int(time.time())), } # 敏感字段先加密密文再参与签名 params[legal_id_card] encrypt_rsa(330100199001010011) params[settle_account_no] encrypt_rsa(6222001234567890) # 最后加签名 params[sign] make_sign(params, APP_SECRET) resp requests.post( BASE_URL /v1/merchant/submit, jsonparams, timeout10, headers{Content-Type: application/json; charsetutf-8}, ) print(resp.status_code) print(resp.text) if __name__ __main__: merchant_submit()这段代码的逻辑分三层。第一层是 make_sign 函数它决定整个请求能不能过验签过滤空值和 sign 本身按 key 排序拼接最后加 key密钥算 MD5 再转大写。第二层是参数组装request_no、license_no 这类字段格式在注释里标了别照抄成同一份。第三层是加密位置——legal_id_card 和 settle_account_no 必须先加密密文再进 params 参与签名。参数说明再补几点。app_id 是机构分配的调用方标识对应一套密钥request_no 是每次进件唯一的业务单号重复提交同一单号会被幂等拒绝mcc 填的是商户经营范围类目要和营业执照经营范围对得上timestamp 用秒级时间戳部分机构要求请求时间与服务器时间误差在 5 分钟内超出会报请求过期。timeout 参数建议不小于 10 秒进件接口内部要跑工商核验偶尔响应会到 5 秒以上设太短容易误判超时然后重复提交。3.3 响应码解读0 是受理不是成功进件接口的响应一般长这样{ code: 0, msg: success, data: { request_no: M20240101001, status: 0 } }code 是 0 只代表「请求被受理」不代表「进件成功」。data.status 才是进件流程的当前状态按 2.2 的状态表理解。如果 code 非 0常见几类是参数校验失败缺字段、格式错、商户已存在同一营业执照已被进件、图片资源不存在影像上传接口返回的 URL 失效、签名错误。前两类直接修字段重提图片问题回上传接口查返回。响应里另一个值得关注的是 trace_id 或 request_id 之类的标识。排查问题时把 trace_id 连同 request_no 一起提供给机构技术支持对方能在服务端日志里定位到你的请求。demo 里一般只打印了响应体建议顺手把完整响应存一份日志后面联调会省很多时间。还有一点返回的 data 里如果带 merchant_no那说明这张单子已经审核通过过你的代码要支持「先查后改」的场景别一收到就覆盖本地状态。提示进件请求的日志里不要打印明文身份证和银行卡。真出问题需要排查时把敏感字段掩码后输出否则日志文件本身就是泄密面。4. 进件查询与审核回调两条状态追踪路径的配合进件提交之后业务系统靠两条路径感知状态变化主动查询和被动回调。这两条路径不是二选一而是配合关系。这一章把两边的 demo 和参数讲清楚包括轮询间隔怎么设、回调怎么验签回 ack。4.1 查询接口 demo轮询间隔、超时与频控查询接口是进件 API 里除了提交之外最常用的接口参数比提交少很多核心就是 request_no 加签名。下面是一个带轮询的查询脚本import time import requests APP_ID your_app_id APP_SECRET your_app_secret BASE_URL https://openapi.example.com def query_merchant(request_no: str) - dict: 单次查询进件状态. params { app_id: APP_ID, request_no: request_no, timestamp: str(int(time.time())), } params[sign] make_sign(params, APP_SECRET) resp requests.post(BASE_URL /v1/merchant/query, jsonparams, timeout10) resp.raise_for_status() return resp.json() def poll_status( request_no: str, max_attempts: int 30, interval: int 60, ) - dict: 轮询进件状态直到终态开通/驳回或超时. for attempt in range(1, max_attempts 1): data query_merchant(request_no) code data.get(code) status data.get(data, {}).get(status) if code 0 and status in (2, 3): return data if status 4: # 待补充资料业务上要转人工不要继续空转 return data print(f[{attempt}/{max_attempts}] status{status}, sleep {interval}s) time.sleep(interval) raise TimeoutError(f轮询超时: {request_no}) if __name__ __main__: result poll_status(M20240101001) print(result)轮询参数里interval 用 60 秒起步别短于 30 秒。进件审核本来就要 5 分钟到数小时轮询太频繁触发机构频控反而得不偿失。max_attempts 按业务容忍度设我的经验是 30 次乘 60 秒等于 30 分钟能覆盖大多数审核周期还没出结果转人工查或者放到后台任务继续追。这里有两个设计要点。第一不要用 while True 无界轮询必须在代码里给 max_attempts 和总时长设置上限避免跑飞的循环消耗接口配额。第二考虑加一点退避抖动每次 sleep 的间隔在 60 秒基础上加 0-5 秒随机值多个商户同时进件时能分散请求压力。机构侧通常有调用量配额限制高峰期 10 个商户一起进件退避策略能明显降低 429 报错概率。查询接口的形态也有差异有的机构用 POST /query有的走 RESTful 风格用 GET /merchant/{request_no}demo 里给的哪种就用哪种参数拼法和超时设置要按对应风格调。4.2 回调通知验签、ack 应答与幂等处理审核结果出来后机构除了让你查还会向配置的 notify_url 推送回调。回调报文结构各家类似核心字段有 request_no、status、merchant_no、notify_time。回调处理有两个硬性要求先验签再回 ack。from flask import Flask, request, jsonify app Flask(__name__) app.post(/notify/merchant) def merchant_notify(): payload request.get_json(forceTrue) sign payload.pop(sign, ) calc_sign make_sign(payload, APP_SECRET) if calc_sign ! sign: # 验签失败记录来源 IP 和原始报文不要返回 ack # 否则机构会认为投递成功你再也收不到这条通知 return jsonify({code: 1, msg: verify fail}), 400 request_no payload.get(request_no) status payload.get(status) # 业务处理更新本地商户状态注意幂等同一回调可能重发 # 建议先按 request_no status 查本地是否已处理已处理直接 ack # 处理成功再回 ack return jsonify({code: 0, msg: ack})回调这块最容易踩的坑有三处。一是验签必须使用原始报文如果机构送来的是表单格式或带嵌套的 JSON要按文档重新组织参与签名的参数集不能直接对整个 payload 做字符串签名。二是 ack 只能回一次机构把「收到 ack」当成投递成功你处理完业务再回 ack、处理失败不回 ack机构会按失败重发——所以 ack 前必须先保证业务处理成功或者把耗时的操作放到异步队列先快速回 ack 再慢慢处理。三是处理逻辑要幂等机构的重发机制可能把同一条回调推两三次本地要按 request_no status 去重否则同一个商户会被重复开通。去重最简单的方式是给进件表加一个唯一索引比如 uk_request_status第二次插入直接命中冲突。这样即使漏写了显式判断数据库也能挡住。4.3 查询和回调怎么选业务场景决定主备关系实际生产里查询和回调的关系是「回调为主、查询兜底」。回调及时商户体验好但回调可能丢网络问题、回调地址配错、服务重启窗口期所以必须保留定时查询做补偿。如果机构同时提供两种方式我会这样设计场景用哪个原因用户在前端等待进件结果回调 WebSocket 推送用户体验要求秒级反馈批量导入老商户查询接口批量轮询回调风暴会打垮回调服务回调地址临时不可用查询接口补拉恢复后先查一遍增量商户投诉「已提交但没开通」先查状态再定位避免拿过期的本地状态回复用户还有一个容易被忽略的点查询接口返回的 status 和回调里的 status 字段口径要核对。有的机构查询返回的是进件状态回调里带的是商户状态两个字段值含义不同直接混用会导致业务逻辑判断错误。联调时特意让两种情况同时发生确认两边字段取值一致再上线生产。5. 进件 API 的五个典型翻车现场现象、原因与处置这一章把我在对接进件 API 过程中遇到的高频问题整理成五条每条按现象、原因、解决三个步骤写。这些问题在 demo 阶段不一定暴露但上了生产环境会在某个时刻咬你一口提前处理好能省掉大半血泪。5.1 重复进件同一个商户出现在两套商户号里现象商户系统里同一营业执照出现两条进件记录机构侧下发两个不同商户号后续结算对账时两边数据对不上另一种表现是第二次提交直接返回「商户已存在」但本地没保存第一次的 request_no连关联查询都没法做。原因调用方没有做幂等。进件请求在超时后重试时业务单号用了时间戳而不是唯一业务单号或者前端重复点击提交按钮后端没有按同一个维度去重。进件接口本身一般有幂等控制但幂等的依据是 request_no只要这个号每次重新生成防重复就失效。解决进件请求必须携带唯一 request_no同一业务单号只允许提交一次生成规则建议用「日期 商户外部编号 随机数」提交前先用查询接口按营业执照号查一遍存量商户命中就直接返回已有商户号不要盲目再提一单。5.2 验签失败空值字段和参数类型是重灾区现象接口返回 code 非 0msg 是「sign verify failed」或「签名错误」。联调环境里报这个错的比例非常高而且往往不是一次能解决。有时候进件接口第一次调用就报有时候是先受理成功回调验签又失败两种报错对应的排查路径完全不同。原因签名函数把空字符串字段算进去了而请求报文里没带这个字段或者数值类型的参数在拼签名的过程中被转成了「123.0」这种浮点格式或者中文参数在签名前被转成了不同的字符集服务端按 UTF-8 验签对不上。解决签名函数严格按 demo 来过滤空值和 null数值参数统一先转成字符串再排序中文参数用 UTF-8 编码后参与摘要。改完签名函数后一定用文档里的「签名验证示例」跑一遍确认能对得出结果再联调这一步能过滤掉大半签名问题。5.3 敏感字段加密明文传身份证直接被拒绝现象提交进件时传了明文身份证号和银行卡号接口返回「敏感信息必须加密」或者加密后提交机构侧解密出来是一串乱码只能看到商户名称是对的但证件号全花了。原因加密方式不匹配机构要求 RSA/ECB/PKCS1 填充你按 OAEP 填的或者公钥加载错了拿测试环境公钥去加密生产请求或者加密完没有转 BASE64直接传了二进制串HTTP 传输过程中被截断。解决先看文档的「敏感信息加密」章节确认填充方式和编码规则。加密后的密文先放进 params再参与签名顺序按 3.1 的要求。上线前用机构提供的测试公钥在测试环境各跑一遍确认能解密再切生产密钥不要把测试公钥带到生产。5.4 进件驳回后重提原报文直接重发会一直卡审核现象商户资料被驳回后把原报文原封不动重新提交接口显示受理成功但过一段时间又收到同样的驳回或者直接报了「重复进件」连审核都进不去。原因驳回说明原有资料有硬伤比如营业执照号和法人身份证不匹配、经营范围与 mcc 不符、结算账户名称不一致。原报文没改重提只是重新走一遍同样的校验结果自然一样。有些机构还会把同一主体的多次驳回记录累积影响后续进件的风控评分。解决驳回后先调查询接口读 refute_reason 字段按驳回原因逐项修资料并且换一个新的 request_no 重新进件。如果机构支持「待补充资料」状态下的补件接口优先走补件而不是重新提交一单。给商户的回执里也把驳回原因转成白话别直接甩原始错误码。5.5 回调收不到商户开通了系统里还是「审核中」现象商户已经开通并开始收款但业务系统状态还停留在审核中前端一直显示「处理中」。用户来问为什么不能收款排查半天才发现回调没有送达商户号也没存进本地表。原因回调地址配置成了内网地址或测试域名机构侧无法访问或者回调处理逻辑里业务异常ack 迟迟不回机构侧判定投递失败后放弃重试或者回调报文里没带 request_no服务端无法关联到本地进件单消息进来也不知道该更新哪一行。解决回调地址必须用公网可达的 HTTPS 地址并加入机构白名单ack 返回要快业务处理放到异步任务里先回 ack 再处理重复投递靠 request_no status 去重不依赖机构「只推一次」的保证。最后统一用定时查询做兜底超过 N 分钟没状态变化就主动查一次把漏掉的回调补回来。这五条里重复进件和验签失败占了我实际联调中七成以上的报错。剩下三成分布在加密、驳回重提和回调丢失上。但它们的共性是错误信息都有了只是你没有按顺序排查。我建议排查时先确认参数格式再验签最后查网络和回调地址按这个顺序能最快定位。6. 把 demo 锻成生产工具联调自检和上线前的最后几步拿到 demo 只是起步把它变成能上生产的功能还需要一套自检。我在每次联调结束、准备切生产之前都会按这个清单过一遍。先跑测试商户。机构联调环境一般提供固定的测试参数包括测试营业执照号、测试身份证、测试银行卡。把 demo 里的参数换成测试参数跑通「提交进件 → 查询状态 → 等回调」全流程确认三个接口的请求和响应都被日志记录下来。再故意构造一次签名错误、重复 request_no看机构的错误码是否和文档一致这一步能验证你的异常处理分支真的在工作。第二步是核对状态口径。用同一条进件单同时观察查询接口返回和回调推送的 status确认两个字段取值一致。不一致就以文档为准并在代码里显式兼容。这步做完后面排查「查询说开通、回调说驳回」这类矛盾时能省掉一晚上的抓头时间。然后是敏感信息检查。把代码里所有打印语句过一遍身份证、银行卡、签名密钥一律不进日志实在要打印用掩码函数处理后输出。RSA 公钥不要硬编码在源码里放到配置中心或环境变量。签名密钥同理一旦泄露机构侧可以整把 key 封掉影响所有在用商户。最后是切生产环境的操作顺序先在测试环境把 app_id、密钥、证书都换成生产参数跑通一次进件再切生产地址用最小量的真实商户试进件观察审核周期和回调延迟确认稳定后再把轮询间隔调回来接上对账任务。不要一上来就跑一批 500 个商户的批量导入回调还没配好就把机构侧通知队列打爆的事我见过不止一次。我自己的习惯是在每个接口函数入口写一行 request_no 和 trace_id 的日志出任何问题都能沿着单号把整条链路串起来。这个习惯在很多次凌晨排查里救过我。进件 API 的门槛不在接口本身而在你要不要把这些边界都磨掉——愿你少踩几个我踩过的坑希望帮到你。本文还有配套的精品资源点击获取