从0到1：支付宝当面付PHP集成全流程实操
第一步：开放平台接口申请与环境准备
在动手写代码前，你得先在支付宝开放平台（https://open.alipay.com{rel=”nofollow”}）完成开发者认证和应用创建。这里有个很多人会忽略的细节：应用类型一定要选“自研应用”，如果选了“第三方应用”，后续调用支付接口时会提示“权限不足”——去年那个奶茶店朋友就是一开始选错了类型，白白浪费了一天时间重新申请。认证通过后，在“应用详情”页找到“当面付”功能，点击“添加能力”，支付宝会要求你填写经营场景（比如“线下门店收银”），提交后通常1-3个工作日会审核通过，记得每天登录后台看看进度，别干等着。
接口申请下来后，得准备开发环境。PHP版本 用7.3及以上（支付宝SDK对PHP8.0+兼容性更好），服务器需要支持HTTPS（支付回调必须用HTTPS，这是硬性要求）。我通常会推荐用Composer安装官方SDK：composer require alipay/easysdk，比手动下载SDK包方便多了，而且能自动处理依赖。安装完成后，先别急着写业务代码，一定要先配置密钥——这里是第一个高频坑点：支付宝支持RSA2和SM2两种加密方式，推荐用RSA2（密钥长度2048位），很多人图省事用1024位的RSA，结果支付时直接报错“不支持的签名算法”。生成密钥可以用支付宝官方的密钥生成工具（https://opendocs.alipay.com/common/02kipl{rel=”nofollow”}），生成后把公钥上传到开放平台，私钥保存到服务器的config目录，记得设置权限为600（只有服务器能读取，避免泄露）。
第二步：核心功能代码实现（附可复用示例）
接下来就是写代码了，我把整个流程拆成“创建订单→生成支付二维码→处理支付结果”三个核心环节，每个环节都给你标好关键代码和逻辑。
创建订单
时，你需要调用支付宝的alipay.trade.precreate接口（扫码支付）或alipay.trade.pay接口（条码支付）。这里以最常用的扫码支付为例，关键是参数组装：必须包含out_trade_no（商户订单号，自己生成，唯一）、total_amount（订单金额，单位元，保留两位小数）、subject（订单标题）、store_id（门店号，选填但 填，方便后续对账）。之前帮一个便利店客户集成时，他们的开发员漏传了timeout_express（订单超时时间），结果用户扫了码没付钱，订单一直挂着，后来在代码里加上"timeout_express" => "30m"（30分钟超时），就解决了这个问题。 生成支付二维码其实是调用接口后，用返回的qr_code参数生成图片。这里推荐用PHP的GD库或Imagick扩展，代码示例可以这样写：“拿到接口返回的qr_code字符串后，你可以用QRcode::png($qr_code, 'qrcode.png', QR_ECLEVEL_L, 6);生成图片（需要先安装phpqrcode库），记得把图片路径存到数据库，方便后续用户查询订单时展示。”不过要注意，生成的二维码最好加上 logo（比如店铺Logo），但别太大，否则扫码识别率会下降——我一般把logo大小控制在二维码尺寸的1/5以内。 处理支付结果分两种：同步回调和异步通知。同步回调（return_url）是用户支付成功后跳转的页面，主要给用户看；异步通知（notify_url）才是给服务器确认支付状态的关键，支付宝会在用户支付成功后主动调用这个地址。这里有个90%的人会踩的坑：异步通知必须返回“success”字符串，而且不能加任何HTML标签或空格，否则支付宝会认为通知失败，一直重复发送。之前有个客户在notify_url页面加了echo "支付成功";，结果支付宝一直重试，服务器日志都满了，后来改成echo "success";才解决。 异步通知的验签也很重要，你需要用支付宝公钥对通知参数进行验签，确保是支付宝发来的真实请求，代码里可以用SDK的aopclient->rsaCheckV1()方法，具体可以参考支付宝官方文档的验签步骤（https://opendocs.alipay.com/open/203/105286{rel=”nofollow”}）。
避坑指南：10+典型问题的诊断与解决
集成过程中遇到报错别慌，大部分问题都有固定的解决套路。我整理了过去两年帮客户解决的10+个高频问题，每个问题都告诉你“怎么看报错信息→可能的原因→一步步排查”，照着做基本能解决90%的麻烦。
问题1：签名验证失败（invalid-signature）
这是最常见的问题，没有之一。你先看报错信息里有没有“sign check fail”，有的话先检查这三点：①参数是不是按字母顺序排序了（支付宝要求参数名ASCII码从小到大排序，比如app_id要在biz_content前面）；②有没有漏传参数（特别是app_id和timestamp，后者格式必须是yyyy-MM-dd HH:mm:ss）；③私钥是不是对应应用的（很多人有多个应用，结果拿错了私钥文件）。去年帮一个电商客户排查时，发现他们把seller_id写成了sellerId（驼峰式），支付宝接口只认下划线命名，改过来后马上就好了。
问题2：异步通知（notify_url）收不到
遇到这个问题，你先在服务器日志里搜一下有没有支付宝的请求记录。如果没有，可能是：①notify_url不是HTTPS（支付宝从2017年起就要求回调地址必须是HTTPS）；②服务器防火墙拦截了支付宝的IP（支付宝的服务器IP段可以在https://opendocs.alipay.com/common/02km9f{rel=”nofollow”}查到，需要把这些IP加入白名单）；③URL里有参数（比如notify_url?type=1），支付宝不支持带参数的回调地址。如果日志里有请求但返回500错误，那就是你代码里有bug， 先在notify_url页面写个简单的file_put_contents('notify.log', print_r($_POST, true));，看看能不能收到参数，再逐步排查逻辑。
问题3：退款接口调用失败（insufficient-isv-permission）
如果你调用alipay.trade.refund接口时提示“权限不足”，先去支付宝开放平台的“接口权限”页面看看，是不是没申请退款权限——当面付默认开通支付权限，但退款需要单独申请。 退款金额不能大于订单金额，而且只能退一次全额或多次部分退款（累计不能超过订单金额）。之前有个客户想给一笔100元的订单退101元，结果接口直接报错，调整金额后就好了。
除了这些，还有“订单不存在”（检查out_trade_no是不是和创建订单时一致）、“重复提交订单”（确保out_trade_no唯一）等问题，你可以在开发时准备一个“问题排查清单”，遇到报错时按清单一步步检查，比盲目百度效率高多了。
最后想对你说，支付集成确实细节多，但只要跟着流程走，遇到问题时先看官方文档（支付宝开发者文档真的写得很详细），再结合代码日志排查，基本都能解决。如果你按文章里的步骤试了，遇到新的问题，欢迎在评论区告诉我，咱们一起看看怎么解决~
异步通知收不到简直是支付集成里的“老大难”问题，我去年帮一个连锁便利店调试系统时，就遇到过客户付了钱但后台没记录的情况，最后发现是三个小细节没做好。你先别急着改代码，按这个顺序排查，基本能定位问题。第一步你得先看协议——支付宝从2017年起就要求所有回调地址必须是HTTPS，这不是“ ”是“硬性规定”，如果你的notify_url还是HTTP，哪怕代码写得再对也收不到通知。之前有个客户不信邪，非说自己HTTP能收到测试环境的通知，结果上线后正式环境直接“罢工”，后来换成HTTPS当天就好了。
接着检查服务器防火墙，这是最容易被忽略的点。支付宝的通知请求是从他们的服务器发过来的，如果你服务器的安全组或防火墙没开放对应的IP段，请求根本到不了你的代码层。你可以去支付宝开放平台的IP白名单文档里查最新的服务器IP段（https://opendocs.alipay.com/common/02km9f{rel=”nofollow”}），把这些IP全部加入白名单，特别是中小型服务器厂商，默认规则可能会拦截陌生IP。对了，URL本身也别带参数，比如写成“notify_url?orderType=1”这种形式，支付宝会直接忽略带参数的地址，我见过有开发者为了区分订单类型加了参数，结果调试三天才发现是这个原因。
如果前面两步都没问题，就该看看服务器到底有没有收到请求了。你可以在notify_url对应的PHP文件最开头加一行日志代码，比如“file_put_contents(‘alipay_notify.log’, date(‘Y-m-d H:i:s’).’ ‘.print_r($_POST, true).”n”, FILE_APPEND);”，这样每次有请求进来，就能在日志文件里看到具体参数。去年那个便利店客户就是通过日志发现，支付宝其实发了通知，但服务器返回了500错误——后来查代码才知道，他在验签前就调用了一个未定义的函数，导致脚本中断。最后还有个关键细节：验签通过后，一定要用echo输出纯文本的“success”，不能加任何HTML标签、空格或换行，甚至连“success！”都不行，支付宝只认纯小写的“success”字符串，少一个字母都会判定通知失败，然后每隔1分钟重试一次，直到24小时后停止。
个人开发者可以申请支付宝当面付接口吗？
不可以。支付宝当面付接口目前仅对企业或个体工商户开放，个人开发者无法申请。在申请时需提供营业执照、经营场景说明等材料，完成企业实名认证后才能开通接口权限。如果是个人项目需要测试，可先使用支付宝沙箱环境（https://open.alipay.com/platform/appDaily.htm?tab=info）进行模拟开发，沙箱环境支持个人账号调试。
RSA和RSA2密钥有什么区别，应该选哪个？
RSA和RSA2是两种不同的签名算法，主要区别在安全性和兼容性：RSA密钥长度通常为1024位，安全性较低；RSA2密钥长度为2048位，是支付宝推荐的签名方式，安全性更高且接口兼容性更好。集成时 优先选择RSA2，若使用RSA可能会因“签名算法不支持”导致调用失败。可通过支付宝官方密钥生成工具直接生成RSA2密钥（https://opendocs.alipay.com/common/02kipl），生成后需将公钥上传至开放平台并保存私钥用于代码签名。
异步通知（notify_url）接收不到时，如何排查？
可按以下步骤排查：①确认notify_url是否为HTTPS协议（支付宝要求回调地址必须是HTTPS）；②检查服务器防火墙是否拦截支付宝IP段（可在https://opendocs.alipay.com/common/02km9f查询支付宝官方IP，将其加入白名单）；③查看URL是否包含参数（如“notify_url?type=1”，支付宝不支持带参数的回调地址）；④在notify_url页面添加日志记录（如“file_put_contents(‘notify.log’, print_r($_POST, true));”），确认是否有请求进入服务器；⑤检查代码是否返回“success”字符串（需纯文本，不可包含HTML标签或空格，否则支付宝会重复发送通知）。
当面付订单的超时时间可以自定义吗？最长支持多久？
可以自定义。通过调用支付接口时的“timeout_express”参数设置，格式为“XXm”（分钟）或“XXh”（小时），例如“30m”表示30分钟超时。支付宝当面付订单超时时间范围为1分钟-15天（即1m-15d），需根据实际业务场景设置， 线下零售场景设置30分钟-2小时（避免用户长时间未支付导致库存锁定），自助售货机等无人场景可缩短至5-10分钟。若未设置该参数，默认超时时间为3小时。
当面付订单支持部分退款吗？退款有金额限制吗？
支持部分退款。当面付订单允许单次部分退款或多次部分退款，每次退款金额需大于0.01元，且累计退款金额不可超过原订单金额。 100元订单可先退30元，再退50元，剩余20元可再次退款，但三次退款总和不可超过100元。退款时需调用“alipay.trade.refund”接口，传入原订单号（out_trade_no）、退款金额（refund_amount）等参数，且退款接口需单独申请权限（在支付宝开放平台“接口权限”页面开通）。
