Skip to content

README.md

Latest commit

 

History

History
215 lines (162 loc) · 6.72 KB

README.md

File metadata and controls

215 lines (162 loc) · 6.72 KB
Raw

Jeepay Python SDK

PyPI version License: MIT

Jeepay API 的官方 Python SDK 不是很 pythonic，这个是简化版本，简化了与 Jeepay 支付网关的交互。

功能特性

  • 支持 Jeepay API 的核心功能：支付、退款、转账、分账等。
  • 面向对象的接口设计 (client.resource.action())。
  • 自动处理签名生成。
  • 支持请求重试。
  • 提供 Webhook 签名验证工具。
  • 类型提示支持，提升开发体验。

要求

  • Python 3.7+

安装

选项 1: 从 Git 仓库安装 (推荐，如果未发布到 PyPI)

pip install git+https://github.com/your-repo/jeepay-sdk-python.git # 替换为你的仓库地址

选项 2: 本地安装 (用于开发)

克隆仓库后，在项目根目录下运行：

pip install .

选项 3: 从 PyPI 安装 (如果已发布)

pip install jeepay-sdk-python

基本用法

1. 初始化客户端

import os
import time
import jeepay
from jeepay.exceptions import JeepayError

# 强烈建议使用环境变量或其他安全方式管理凭据
api_key = os.getenv("JEEPAY_API_KEY", "YOUR_API_KEY")
mch_no = os.getenv("JEEPAY_MCH_NO", "YOUR_MCH_NO")
app_id = os.getenv("JEEPAY_APP_ID", "YOUR_APP_ID")
# api_base_url = os.getenv("JEEPAY_API_BASE_URL") # 可选，设置沙箱或特定环境 URL

# 检查凭据是否已配置
if api_key == "YOUR_API_KEY" or mch_no == "YOUR_MCH_NO" or app_id == "YOUR_APP_ID":
    print("错误：请设置 JEEPAY_API_KEY, JEEPAY_MCH_NO 和 JEEPAY_APP_ID 环境变量")
    # 在实际应用中，这里应该抛出异常或采取其他错误处理措施
    exit()

try:
    # 初始化 Client
    # 可以传入可选参数：api_base_url, timeout, max_retries, sign_type, verify_ssl
    client = jeepay.Client(
        api_key=api_key,
        mch_no=mch_no,
        app_id=app_id,
        # api_base_url="https://pay.jeepay.vip/api" # 例如，沙箱环境
    )
except ValueError as e:
    print(f"配置错误: {e}")
    exit()

2. 调用 API (以创建支付为例)

# 准备支付参数
mch_order_no = f"sdkpy_{int(time.time() * 1000)}"
payment_data = {
    "mch_order_no": mch_order_no,
    "way_code": "ALI_WAP",  # 支付方式，例如支付宝手机网站支付
    "amount": 1,           # 支付金额，单位：分
    "currency": "cny",
    "client_ip": "127.0.0.1",
    "subject": "商品标题",
    "body": "商品描述",
    "notify_url": "https://example.com/notify", # 异步通知地址
    # "return_url": "https://example.com/return", # 同步跳转地址
}

try:
    print(f"创建支付订单: {mch_order_no}")
    # 使用 client.pay 资源调用 create 方法
    response = client.pay.create(**payment_data)
    print("支付创建成功:")
    print(response)

    # 根据 payDataType 处理支付信息
    pay_data_type = response.get("payDataType")
    pay_data = response.get("payData")
    if pay_data_type == "redirectUrl":
        print(f"\n请跳转至: {pay_data}")
    # ... 处理其他 payDataType

except JeepayError as e:
    print(f"API 请求失败: {e}")
    # 可以访问 e.code, e.http_status, e.response_body 获取更详细信息
    # print(f"错误代码: {e.code}")
    # print(f"HTTP状态码: {e.http_status}")
except Exception as e:
    print(f"发生未知错误: {e}")

finally:
    # 建议在使用完 client 后关闭连接，或使用 'with' 语句
    client.close()

3. 异常处理

SDK 中的所有异常都继承自 jeepay.exceptions.JeepayError。你可以捕获基类或更具体的异常类型（如 APIError, APIConnectionError, AuthenticationError, InvalidRequestError）。

from jeepay.exceptions import JeepayError, APIError

try:
    # ... API 调用 ...
    pass
except APIError as e:
    print(f"Jeepay API 返回错误: {e.message} (Code: {e.code}, HTTP Status: {e.http_status})")
except JeepayError as e:
    print(f"Jeepay SDK 错误: {e}")
except Exception as e:
    print(f"其他错误: {e}")

4. Webhook 签名验证 (可选)

Jeepay 通过 Webhook 发送异步通知。验证签名的有效性对于确保通知来源可靠至关重要。

from jeepay.webhook import WebhookSignatureVerifier
from jeepay.exceptions import SignatureVerificationError

# 假设你从 Web 框架接收到请求体 (raw_body) 和签名头 (signature)
# raw_body 应该是原始的、未经修改的请求体字节串或 UTF-8 字符串
# signature 是从请求头（例如 'Jeepay-Signature'）获取的值

# raw_body = request.get_data() # 示例：从 Flask 获取原始请求体
# signature = request.headers.get('Jeepay-Signature') # 示例：从请求头获取签名

# 使用 client 获取验证器实例
verifier = client.webhook_verifier()

try:
    # 验证签名 (假设 payload 是 JSON 格式)
    is_valid = verifier.verify(raw_body, signature) # 默认 sign_type='MD5'

    if is_valid:
        print("Webhook 签名验证成功!")
        # 在这里处理 Webhook 事件逻辑...
        # event_data = json.loads(raw_body.decode('utf-8'))
        # ...
    else:
        print("Webhook 签名验证失败!")
        # 拒绝处理该通知

except SignatureVerificationError as e:
    print(f"Webhook 签名验证出错: {e}")
    # 拒绝处理该通知
except Exception as e:
    print(f"处理 Webhook 时发生错误: {e}")
    # 拒绝处理该通知

# 注意：处理完请求后，记得关闭 client (如果不再需要)
# client.close()

资源

SDK 将 API 划分为不同的资源，通过 client 实例访问：

  • client.pay: 支付、退款、查询订单等相关操作。
  • client.transfer: 转账、查询转账订单等相关操作。
  • client.division: 分账绑定、执行分账等相关操作。

每个资源对象都提供了对应 API 端点的方法（例如 create, query, refund, bind_user, exec 等）。请参考 examples/ 目录下的示例代码了解具体用法。

示例

examples/ 目录下包含了各种 API 功能的调用示例：

  • create_payment.py: 创建支付订单
  • query_payment.py: 查询支付订单
  • create_refund.py: 创建退款订单
  • query_refund.py: 查询退款订单
  • create_transfer.py: 创建转账订单
  • query_transfer.py: 查询转账订单
  • bind_division_receiver.py: 绑定分账接收者
  • execute_division.py: 执行订单分账

运行示例前，请确保已按照示例文件顶部的说明配置好环境变量（JEEPAY_API_KEY, JEEPAY_MCH_NO, JEEPAY_APP_ID）。

贡献

欢迎提交 Pull Request 或 Issue。

License

MIT