告别手动上传：用Label Studio的Local Storage功能搭建你的私有数据标注流水线
2026/6/1 18:50:07
Python wallee 包完整详解
一、wallee 包核心功能概述
wallee是wallee 支付平台官方提供的 Python SDK，用于无缝对接 wallee 跨境支付、收单、退款、订单管理、支付网关集成等核心支付业务。
核心功能
- 支付处理：创建支付订单、发起支付、查询支付状态、支付结果回调处理
- 订单管理：创建、查询、更新、取消交易订单
- 退款操作：全额退款、部分退款、退款状态查询
- 账户管理：商户信息查询、交易流水统计、对账数据获取
- 支付方式集成：支持信用卡、网银、电子钱包、跨境支付等全渠道支付方式
- 安全合规：内置加密、签名、身份验证，符合支付行业安全标准
- 异步通知：接收 wallee 平台的支付成功/失败/退款回调通知
适用场景
电商网站支付、跨境收款、SaaS 平台付费、企业财务对账、自动化退款系统。
二、wallee 包安装
1. 环境要求
- Python 3.6+
- 联网环境（依赖官方接口）
2. 安装命令
# 标准安装（推荐）pipinstallwallee# 升级到最新版本pipinstall--upgradewallee# 指定版本安装pipinstallwallee==3.0.03. 验证安装
importwalleeprint(wallee.__version__)# 输出版本号即安装成功三、基础语法与核心参数
1. 初始化配置（必写）
使用前必须配置商户 ID、应用密钥、环境（测试/生产），这是所有接口的基础。
importwalleefromwallee.apiimportTransactionApifromwallee.configurationimportConfigurationfromwallee.clientimportApiClient# 1. 基础配置config=Configuration()# 商户ID（wallee 后台获取）config.user_id="你的商户ID"# API 密钥（wallee 后台生成）config.api_key="你的API密钥"# 环境：测试环境（False）/ 生产环境（True）config.production_mode=False# 2. 创建 API 客户端api_client=ApiClient(config)# 3. 初始化核心接口transaction_api=TransactionApi(api_client)2. 核心通用参数
| 参数名 | 类型 | 说明 | 必填 |
|---|---|---|---|
| user_id | str | 商户唯一ID | 是 |
| api_key | str | API 安全密钥 | 是 |
| production_mode | bool | 环境切换：False=测试，True=生产 | 是 |
| space_id | int | 业务空间ID（wallee后台分配） | 是 |
| transaction_id | int | 交易订单ID | 接口调用必传 |
| amount | float | 交易金额（保留2位小数） | 支付/退款必传 |
| currency | str | 货币代码（如 USD、EUR、CNY） | 支付必传 |
| language | str | 语言（zh-CN、en-US） | 可选 |
四、8个实际应用案例（可直接运行）
案例1：创建支付订单（最常用）
功能：生成一个可支付的订单，返回支付链接/二维码
importwalleefromwallee.apiimportTransactionApifromwallee.configurationimportConfigurationfromwallee.clientimportApiClientfromwallee.modelsimportTransactionCreate# 配置config=Configuration()config.user_id="123456"# 替换为你的商户IDconfig.api_key="your_api_key"config.production_mode=Falseapi_client=ApiClient(config)transaction_api=TransactionApi(api_client)# 订单参数space_id=1000# 替换为你的空间IDorder=TransactionCreate(amount=99.99,# 订单金额currency="USD",# 货币allowed_payment_method_brands=["VISA","MASTERCARD"],# 支持的支付方式customer_email="user@example.com",# 用户邮箱order_id="ORDER_20250101_001",# 自定义订单号success_url="shturl.cc/RxCCvF5rS2MlB2nigeB24rGpQ",# 支付成功跳转页failed_url="shturl.cc/yKOemiUbb6uQBGX03niZbr0w"# 支付失败跳转页)# 创建订单result=transaction_api.create(space_id,order)# 输出结果print("订单ID:",result.id)print("支付链接:",result.payment_page_url)# 直接访问该链接即可支付案例2：查询订单支付状态
功能：根据订单ID查询是否支付成功
# 沿用案例1的配置和 api_clientspace_id=1000transaction_id=12345678# 订单ID（案例1返回的result.id）# 查询订单transaction=transaction_api.read(space_id,transaction_id)# 状态判断print("订单状态:",transaction.state)iftransaction.state=="COMPLETED":print("✅ 支付成功")eliftransaction.state=="PENDING":print("⏳ 支付中")eliftransaction.state=="FAILED":print("❌ 支付失败")案例3：全额退款
功能：对已支付订单发起全额退款
fromwallee.apiimportRefundApifromwallee.modelsimportRefundCreate# 初始化退款接口refund_api=RefundApi(api_client)space_id=1000transaction_id=12345678# 退款参数refund=RefundCreate(transaction=transaction_id,amount=99.99,# 退款金额（全额）reason="用户申请退款"# 退款原因)# 发起退款result=refund_api.create(space_id,refund)print("退款ID:",result.id)print("退款状态:",result.state)案例4：部分退款
功能：仅退还订单部分金额
# 仅需修改退款金额即可refund=RefundCreate(transaction=transaction_id,amount=30.00,# 部分退款：30美元reason="部分商品退款")result=refund_api.create(space_id,refund)print("部分退款成功，退款ID：",result.id)案例5：取消未支付订单
功能：关闭超时未支付的订单
space_id=1000transaction_id=12345678# 取消订单result=transaction_api.cancel(space_id,transaction_id)print("订单取消状态:",result.state)# 输出 CANCELED 即成功案例6：获取支付方式列表
功能：查询当前商户支持的所有支付渠道
fromwallee.apiimportPaymentMethodBrandApi payment_api=PaymentMethodBrandApi(api_client)space_id=1000# 获取所有支付方式methods=payment_api.all(space_id)formethodinmethods:print(f"支付方式：{method.name}，代码：{method.brand}")案例7：处理支付回调通知（后端必备）
功能：接收 wallee 推送的支付结果，自动更新订单状态
fromflaskimportFlask,request,jsonify app=Flask(__name__)# 回调接口@app.route('/wallee/callback',methods=['POST'])defcallback():data=request.get_json()transaction_id=data['entityId']state=data['state']# 根据状态更新本地订单ifstate=="COMPLETED":print(f"订单{transaction_id}支付成功，更新数据库")returnjsonify({"status":"success"})if__name__=='__main__':app.run(port=8000)案例8：批量查询交易流水（对账用）
功能：按时间范围查询所有交易记录，用于财务对账
fromwallee.apiimportTransactionApifromwallee.modelsimportEntityQuery space_id=1000query=EntityQuery(filter="created_on > '2025-01-01' and created_on < '2025-01-31'")# 批量查询transactions=transaction_api.search(space_id,query)print(f"1月总交易数：{len(transactions)}")fortintransactions:print(f"订单：{t.id}，金额：{t.amount}，状态：{t.state}")五、常见错误与解决方案
1. 认证错误：Authentication failed
原因：商户ID/API密钥错误，或环境（测试/生产）不匹配
解决：
- 核对
user_id和api_key - 确认
production_mode与密钥环境一致
2. 参数错误：Invalid parameters
原因：金额格式错误、货币代码无效、必填参数缺失
解决：
- 金额保留2位小数（如
99.99） - 货币使用标准代码（USD/EUR/CNY）
- 必传
space_id、transaction_id
3. 订单不存在：Transaction not found
原因：transaction_id错误或不属于当前商户
解决：使用接口返回的真实订单ID，核对space_id
4. 退款失败：Refund not allowed
原因：订单未支付、已退款、金额超过原订单
解决：
- 仅对
COMPLETED状态订单退款 - 退款金额≤原订单金额
5. 网络错误：Connection refused
原因：网络不通、防火墙拦截、域名无法访问
解决：
- 检查网络连接
- 关闭本地防火墙/代理
六、使用注意事项
- 环境区分
- 开发/测试用
production_mode=False - 上线必须改为
production_mode=True
- 开发/测试用
- 安全规范
- API 密钥不要硬编码在代码中，建议存入环境变量
- 回调接口必须做签名验证，防止伪造请求
- 幂等性
- 退款/支付接口调用失败时，不要重复频繁调用，先查询状态再操作
- 状态判断
- 订单状态以 wallee 接口返回为准，不要依赖前端跳转
- 货币精度
- 所有金额必须保留2位小数，避免浮点误差
- 日志记录
- 所有支付、退款操作必须记录日志，方便对账排查
- 版本兼容
- 固定使用稳定版本，不要随意升级 SDK
- 合规要求
- 跨境支付需遵守当地金融监管，保留交易凭证
总结
wallee是wallee 支付官方 Python SDK，核心用于支付、退款、订单管理、对账；- 安装仅需
pip install wallee，使用前必须配置商户ID、API密钥、环境； - 8个案例覆盖创建订单、查状态、全额/部分退款、取消订单、回调、对账等全场景；
- 核心注意事项：区分环境、保护密钥、校验订单状态、做好日志。
《动手学PyTorch建模与应用:从深度学习到大模型》是一本从零基础上手深度学习和大模型的PyTorch实战指南。全书共11章，前6章涵盖深度学习基础，包括张量运算、神经网络原理、数据预处理及卷积神经网络等；后5章进阶探讨图像、文本、音频建模技术，并结合Transformer架构解析大语言模型的开发实践。书中通过房价预测、图像分类等案例讲解模型构建方法，每章附有动手练习题，帮助读者巩固实战能力。内容兼顾数学原理与工程实现，适配PyTorch框架最新技术发展趋势。