企业官网建设流程全解析

简介：这是一份面向Java Web开发者的支付宝面对面支付完整实例，重点覆盖扫码枪收款场景，适合需要快速接入支付宝当面付、理解预下单与条码支付流程的初中级开发者参考。资源包共24个文件，约2.37MB，包含8个class、6个jar、3个java源码、3个jsp页面、3个smap及1个properties配置文件，其中jar为支付宝SDK依赖，java与class对应核心支付逻辑，jsp承担预支付与收款码支付入口，properties用于存放从支付宝平台获取的商户参数。使用时将文件解压至web服务目录，配置好参数后访问预支付页面即可生成支付二维码，访问收款码支付页面并传入扫码枪扫到的条码内容即可完成收款。目前已有834人学习下载，实例结构清晰、依赖完整，能帮助读者快速跑通面对面支付主流程，并作为二次开发与排错的基础模板。

1. 扫码枪一响，钱到账：一个能跑通的支付宝面对面支付实例

扫码枪“滴”一声，收银台屏幕上弹出支付成功，整个过程不到两秒。这个场景背后，是一套完整的面对面支付链路在支撑——商户系统生成订单、调用支付宝接口创建交易、用户出示付款码、扫码枪读取后发起扣款、异步通知回来更新订单状态。听起来简单，但真动手写的时候，签名怎么签、异步通知怎么验签、退款怎么处理，每一步都有坑。

这份资源就是一个完整的支付宝面对面支付实例，覆盖了扫码枪支付的核心流程。它适合正在对接支付宝当面付的开发者，尤其是需要快速跑通主流程、不想在文档里反复翻找参数的人。代码结构清晰，从配置到调用到回调都有对应实现，拿来就能改。下面我按实际落地顺序，把这份实例拆开讲一遍。

2. 面对面支付的核心链路：从付款码到异步通知

2.1 扫码枪支付到底走的是哪条接口

很多人第一次接触当面付，会以为扫码枪支付和APP支付、网页支付差不多，其实差别很大。扫码枪支付属于“条码支付”范畴，用户出示的是付款码，商户用扫码枪读取后主动发起扣款。这条链路的核心接口是alipay.trade.pay，而不是alipay.trade.create或alipay.trade.precreate。

为什么强调这个？因为选错接口会导致整个流程走不通。alipay.trade.pay是直接扣款接口，传入用户的付款码（一串18位数字，通常以25、26、27、28、29、30开头），支付宝会实时返回扣款结果。而alipay.trade.precreate是生成二维码让用户扫，方向反了。

这份实例里，扫码枪支付的主逻辑就是围绕alipay.trade.pay展开的。调用时需要传几个关键参数：

注意auth_code是一次性的，同一个付款码不能重复使用。如果调用返回“付款码已使用”或“付款码过期”，说明这个码已经被扣过款或者超时了。常见做法是让用户刷新付款码后重新扫码。

2.2 签名与验签：为什么你的请求总是被拒

支付宝接口对签名的要求非常严格，这也是新手最容易翻车的地方。这份实例用的是 RSA2 签名，密钥长度2048位。整个签名过程分两步：构造待签名字符串、用私钥签名。

待签名字符串的构造规则是：把所有请求参数（除了 sign 本身）按 key 的字典序排列，用&连接成key=value的形式，然后拼上应用私钥进行 SHA256withRSA 签名。听起来简单，但有几个细节容易出错：

• 参数值必须做 URL 编码，且编码后的值参与签名
• 空值参数不参与签名
• 签名结果需要 Base64 编码后再做 URL 编码

实例里封装了一个buildSignContent方法，专门处理这个逻辑。我一般会建议在本地先跑一遍签名验证，用支付宝提供的验签工具确认无误后再上测试环境。

import hashlib import base64 from urllib.parse import quote_plus, urlencode from Crypto.PublicKey import RSA from Crypto.Signature import pkcs1_15 from Crypto.Hash import SHA256 def build_sign_content(params: dict) -> str: """构造待签名字符串""" # 过滤空值和 sign 字段 filtered = {k: v for k, v in params.items() if v and k != 'sign'} # 按 key 字典序排序 sorted_keys = sorted(filtered.keys()) # 拼接成 key=value 形式，value 不做 URL 编码（签名时用原始值） content = '&'.join([f'{k}={filtered[k]}' for k in sorted_keys]) return content def sign_with_rsa2(content: str, private_key_str: str) -> str: """使用 RSA2 私钥签名""" private_key = RSA.import_key(private_key_str) # SHA256 摘要 digest = SHA256.new(content.encode('utf-8')) # PKCS1 v1.5 签名 signature = pkcs1_15.new(private_key).sign(digest) # Base64 编码 return base64.b64encode(signature).decode('utf-8')

这段代码的关键点在于：build_sign_content里没有对 value 做 URL 编码，因为签名用的是原始值。但在最终发送 HTTP 请求时，需要对所有参数做 URL 编码。很多开发者在这里搞混，导致签名一直验证失败。参数private_key_str是应用私钥，不是支付宝公钥，别搞反了。

2.3 异步通知处理：订单状态不能只靠同步返回

同步返回告诉你扣款成功，但不代表订单最终状态已经确定。支付宝的异步通知才是最终依据。这份实例里有一个notify_url的处理逻辑，接收支付宝 POST 过来的 XML 或 JSON 数据，验签后更新本地订单。

异步通知有几个必须做的动作：

1. 验证out_trade_no是否存在于本地订单
2. 验证total_amount是否与本地订单金额一致
3. 验证trade_status是否为TRADE_SUCCESS或TRADE_FINISHED
4. 验签，确认通知来自支付宝
5. 处理完业务后返回success字符串

如果返回的不是success，支付宝会按策略重试通知，频率大概是 4m、10m、10m、1h、2h、6h、15h。所以处理逻辑必须幂等，同一笔订单重复通知不能重复发货。

def handle_notify(request_data: dict, alipay_public_key: str) -> str: """处理支付宝异步通知""" # 1. 验签 sign = request_data.pop('sign', None) sign_type = request_data.pop('sign_type', None) if not verify_sign(request_data, sign, alipay_public_key): return 'failure' out_trade_no = request_data.get('out_trade_no') trade_status = request_data.get('trade_status') total_amount = request_data.get('total_amount') # 2. 查询本地订单 order = query_order(out_trade_no) if not order: return 'failure' # 3. 金额校验 if str(order['amount']) != str(total_amount): return 'failure' # 4. 状态处理（幂等） if trade_status in ('TRADE_SUCCESS', 'TRADE_FINISHED'): if order['status'] != 'paid': update_order_status(out_trade_no, 'paid') return 'success'

验签时注意，sign和sign_type不参与验签内容的构造，需要先剔除。alipay_public_key是支付宝公钥，不是应用公钥。这两个密钥在支付宝开放平台里都能找到，但位置不同，别复制错了。

3. 把实例跑起来：环境配置与扫码枪联调

3.1 沙箱环境配置与密钥生成

这份实例默认用的是支付宝沙箱环境，适合开发和测试阶段。沙箱环境需要单独生成密钥对，不能用生产环境的。具体步骤是：

1. 登录支付宝开放平台，进入沙箱环境
2. 在“RSA2密钥”页面生成应用私钥和公钥
3. 把应用公钥上传到沙箱，获取支付宝公钥
4. 把应用私钥和支付宝公钥填入实例的配置文件

配置文件通常是一个config.py或alipay_config.py，里面包含APP_ID、APP_PRIVATE_KEY、ALIPAY_PUBLIC_KEY、GATEWAY_URL等字段。沙箱的网关地址是https://openapi.alipaydev.com/gateway.do，生产环境是https://openapi.alipay.com/gateway.do。

# alipay_config.py ALIPAY_CONFIG = { 'app_id': '你的沙箱APPID', 'app_private_key': '''-----BEGIN RSA PRIVATE KEY----- 你的应用私钥 -----END RSA PRIVATE KEY-----''', 'alipay_public_key': '''-----BEGIN PUBLIC KEY----- 你的支付宝公钥 -----END PUBLIC KEY-----''', 'gateway_url': 'https://openapi.alipaydev.com/gateway.do', 'notify_url': 'http://你的公网地址/notify', 'sign_type': 'RSA2', 'charset': 'utf-8', 'format': 'JSON', 'version': '1.0' }

notify_url必须是公网可访问的地址，本地开发可以用内网穿透工具临时映射一个。沙箱环境下，支付宝会主动请求这个地址发送异步通知。如果本地没有公网地址，异步通知收不到，订单状态就更新不了。

3.2 扫码枪支付请求的完整代码实现

实例里把扫码枪支付的请求封装成了一个face_to_face_pay方法，接收订单号和付款码，返回支付结果。核心逻辑是构造请求参数、签名、发送 HTTP 请求、解析响应。

import requests import json from alipay_config import ALIPAY_CONFIG from sign_utils import build_sign_content, sign_with_rsa2 def face_to_face_pay(out_trade_no: str, auth_code: str, total_amount: str, subject: str): """扫码枪支付""" # 1. 构造公共参数 params = { 'app_id': ALIPAY_CONFIG['app_id'], 'method': 'alipay.trade.pay', 'charset': ALIPAY_CONFIG['charset'], 'sign_type': ALIPAY_CONFIG['sign_type'], 'timestamp': '2025-01-01 12:00:00', 'version': ALIPAY_CONFIG['version'], 'notify_url': ALIPAY_CONFIG['notify_url'], 'biz_content': json.dumps({ 'out_trade_no': out_trade_no, 'scene': 'bar_code', 'auth_code': auth_code, 'subject': subject, 'total_amount': total_amount }, ensure_ascii=False) } # 2. 签名 sign_content = build_sign_content(params) params['sign'] = sign_with_rsa2(sign_content, ALIPAY_CONFIG['app_private_key']) # 3. 发送请求 response = requests.post(ALIPAY_CONFIG['gateway_url'], data=params) result = response.json() # 4. 解析响应 if 'alipay_trade_pay_response' in result: pay_response = result['alipay_trade_pay_response'] if pay_response.get('code') == '10000': return {'success': True, 'trade_no': pay_response.get('trade_no')} else: return {'success': False, 'msg': pay_response.get('sub_msg')} return {'success': False, 'msg': '未知错误'}

biz_content是一个 JSON 字符串，里面放业务参数。注意scene固定为bar_code，auth_code就是扫码枪读到的付款码。timestamp格式是yyyy-MM-dd HH:mm:ss，时区是 GMT+8。如果时间偏差太大，支付宝会拒绝请求。

响应里code为10000表示成功，其他值都是失败。常见的失败码有40004（业务处理失败）、20000（系统异常）、40002（参数错误）。sub_msg里会有具体原因，比如“付款码无效”“余额不足”等。

3.3 退款与查询：别等用户找上门才想起来

支付跑通之后，退款和查询是必须补上的。这份实例里也包含了alipay.trade.refund和alipay.trade.query的调用示例。

退款接口需要传out_trade_no或trade_no，以及refund_amount。如果只退一部分，还要传out_request_no作为退款请求号，用于幂等控制。退款是异步的，调用成功不代表钱立刻到账，但支付宝会保证最终退款成功。

def refund(out_trade_no: str, refund_amount: str, out_request_no: str): """发起退款""" params = { 'app_id': ALIPAY_CONFIG['app_id'], 'method': 'alipay.trade.refund', 'charset': ALIPAY_CONFIG['charset'], 'sign_type': ALIPAY_CONFIG['sign_type'], 'timestamp': '2025-01-01 12:00:00', 'version': ALIPAY_CONFIG['version'], 'biz_content': json.dumps({ 'out_trade_no': out_trade_no, 'refund_amount': refund_amount, 'out_request_no': out_request_no }, ensure_ascii=False) } sign_content = build_sign_content(params) params['sign'] = sign_with_rsa2(sign_content, ALIPAY_CONFIG['app_private_key']) response = requests.post(ALIPAY_CONFIG['gateway_url'], data=params) return response.json()

查询接口alipay.trade.query用来主动查订单状态，适合在异步通知丢失时做补偿。传入out_trade_no或trade_no，返回trade_status。如果查到TRADE_SUCCESS但本地还是未支付，就手动补一次状态更新。

4. 避坑指南：扫码枪支付最容易翻车的五个地方

4.1 付款码无效或已使用

现象：调用alipay.trade.pay返回sub_msg为“付款码无效”或“付款码已使用”。

原因：付款码是一次性的，有效期通常只有1分钟。如果扫码后没有立即发起请求，或者同一个码被重复提交，就会报这个错。另外，沙箱环境的付款码和生产环境不通用，用错了也会无效。

解决：让用户刷新付款码后重新扫码，确保扫码到发起请求在1分钟内完成。沙箱测试时，用沙箱版支付宝APP生成的付款码。

4.2 签名验证失败

现象：请求返回sub_code为isv.invalid-signature，提示签名错误。

原因：待签名字符串构造错误，常见的有：参数值做了 URL 编码、空值参数没过滤、sign_type参与签名、私钥格式不对（比如多了换行或空格）。

解决：用支付宝提供的签名验证工具本地跑一遍，确认待签名字符串和签名结果一致。私钥字符串要确保是完整的 PEM 格式，开头和结尾的标记不能少。

4.3 异步通知收不到

现象：支付成功了，但本地订单状态一直是未支付。

原因：notify_url不是公网地址，或者防火墙拦截了支付宝的请求。另外，如果处理通知时返回的不是success，支付宝会重试，但重试期间订单状态可能一直不更新。

解决：确保notify_url公网可访问，本地开发用内网穿透工具映射。处理逻辑里加日志，记录每次收到的通知内容和返回结果。如果确认收不到，用查询接口做主动补偿。

4.4 金额精度问题

现象：异步通知里的total_amount和本地订单金额比对失败。

原因：浮点数精度问题。比如本地存的是0.1，支付宝返回的是0.10，字符串比对就不相等。

解决：金额统一用字符串存储和比对，或者转成整数分处理。实例里用的是字符串直接比对，但要求两边格式一致。我一般会在订单表里存整数分，避免浮点误差。

4.5 沙箱环境与生产环境混淆

现象：沙箱测试通过，切到生产环境后全部报错。

原因：网关地址、APPID、密钥都不同。沙箱的网关是openapi.alipaydev.com，生产是openapi.alipay.com。沙箱的密钥不能用于生产。

解决：配置文件里区分环境，用环境变量或配置项控制。上线前把网关地址、APPID、私钥、公钥全部替换成生产环境的，并重新跑一遍完整流程。

5. 进阶技巧：用对账和日志把支付系统管起来

支付跑通只是第一步，真正上线后，对账和日志才是保命的东西。我一般会在实例基础上加两个东西：每日对账任务和全链路日志。

对账的逻辑是：每天凌晨拉取支付宝的账单文件，和本地订单逐笔比对。支付宝提供了alipay.data.dataservice.bill.downloadurl.query接口，可以获取账单下载地址。下载下来的 CSV 文件里包含每笔交易的out_trade_no、trade_no、total_amount、trade_status。和本地订单比对后，差异记录单独存表，人工排查。

def daily_reconcile(bill_date: str): """每日对账""" # 1. 获取账单下载地址 params = { 'app_id': ALIPAY_CONFIG['app_id'], 'method': 'alipay.data.dataservice.bill.downloadurl.query', 'charset': ALIPAY_CONFIG['charset'], 'sign_type': ALIPAY_CONFIG['sign_type'], 'timestamp': '2025-01-01 12:00:00', 'version': ALIPAY_CONFIG['version'], 'biz_content': json.dumps({ 'bill_type': 'trade', 'bill_date': bill_date }, ensure_ascii=False) } sign_content = build_sign_content(params) params['sign'] = sign_with_rsa2(sign_content, ALIPAY_CONFIG['app_private_key']) response = requests.post(ALIPAY_CONFIG['gateway_url'], data=params) result = response.json() # 2. 下载账单并解析 download_url = result['alipay_data_dataservice_bill_downloadurl_query_response']['bill_download_url'] bill_data = requests.get(download_url).text # 3. 逐笔比对 for line in bill_data.split('\n')[1:]: fields = line.split(',') if len(fields) < 10: continue out_trade_no = fields[0].strip() total_amount = fields[3].strip() trade_status = fields[4].strip() order = query_order(out_trade_no) if not order: log_diff(out_trade_no, '本地订单不存在') continue if str(order['amount']) != total_amount: log_diff(out_trade_no, f'金额不一致: 本地{order["amount"]} vs 支付宝{total_amount}') if trade_status == 'TRADE_SUCCESS' and order['status'] != 'paid': log_diff(out_trade_no, '状态不一致: 支付宝成功，本地未支付')

日志方面，我会在三个关键节点打点：请求前记录请求参数（脱敏后）、响应后记录返回结果、异步通知记录完整内容。日志里带上out_trade_no，方便按订单号追踪全链路。这样出问题时，直接搜订单号就能看到每一步的状态。

还有一个技巧是给异步通知加一个重试队列。如果处理通知时数据库挂了或者超时了，先把通知内容丢到队列里，后台任务慢慢消费。这样即使支付宝重试次数用完了，本地也能补上。

从那以后我每次对接新的支付接口，都会先把对账和日志框架搭好，再写业务逻辑。支付这东西，不怕一万就怕万一，等用户找上门说“我付了钱但订单没反应”的时候，后悔药是买不到的。希望帮到你。

本文还有配套的精品资源，点击获取