Jeepay Python SDK 转账功能详解-优快云博客

Jeepay Python SDK 转账功能详解

【免费下载链接】jeepay-sdk-python Jeepay对应的python客户端实现项目地址: https://gitcode.com/jeequantech/jeepay-sdk-python

Jeepay Python SDK 提供了便捷的转账功能接口，支持支付宝、微信零钱及银行账户转账。本文详细介绍了发起转账请求、转账查询功能以及转账通知的处理与验证方法，帮助开发者快速集成转账功能到自己的应用中。

发起转账请求的接口调用

Jeepay Python SDK 提供了便捷的转账功能接口，允许开发者快速集成转账功能到自己的应用中。以下是发起转账请求的详细接口调用说明。

接口概述

jeepay.Transfer.create 是用于发起转账请求的核心方法，支持多种转账场景，包括支付宝转账、微信零钱转账以及银行账户转账。开发者只需提供必要的参数，即可完成转账操作。

参数说明

以下是 jeepay.Transfer.create 方法的参数及其说明：

参数名	类型	必填	说明
`mchOrderNo`	String	是	商户转账单号，需保证唯一性。
`amount`	Int	是	转账金额，单位为分。
`currency`	String	是	币种，目前仅支持 `cny`（法定货币）。
`ifCode`	String	是	接口代码，支持 `wxpay`（微信）、`alipay`（支付宝）、`aliaqfpay`（支付宝安全发接口）。
`entryType`	String	是	入账方式，支持 `ALIPAY_CASH`（支付宝转账）、`WX_CASH`（微信零钱）、`BANK_ACCOUNT`（银行账户）。
`accountNo`	String	是	收款账号。
`accountName`	String	是	收款人姓名。
`transferDesc`	String	是	转账备注信息。
`clientIp`	String	是	发起转账请求客户端的IP地址。
`notifyUrl`	String	否	异步通知地址，用于接收转账结果通知。

代码示例

以下是一个完整的发起转账请求的代码示例：

import time
import jeepay
from jeepay.app_config import AppConfig

# 配置商户信息
AppConfig.set_mch_no("M1679219294")  # 商户号
AppConfig.set_app_id("6416da5ee4b00bed884be286")  # 应用ID
AppConfig.set_api_key("your_api_key")  # API密钥

# 发起转账请求
try:
    response = jeepay.Transfer.create(
        mchOrderNo=f"mho{round(time.time() * 1000)}",  # 商户转账单号
        amount=100,  # 转账金额（1元）
        currency="cny",  # 币种
        ifCode="aliaqfpay",  # 接口代码
        entryType="ALIPAY_CASH",  # 入账方式
        accountNo="15521548748",  # 收款账号
        accountName="测试用户",  # 收款人姓名
        transferDesc="测试转账",  # 转账备注
        clientIp="192.168.1.132",  # 客户端IP
        notifyUrl="https://yourdomain.com/notify"  # 异步通知地址
    )
    print("转账请求响应:", response)
except Exception as e:
    print("转账请求失败:", e)

流程图

以下是发起转账请求的流程示意图：

mermaid

注意事项

唯一性：mchOrderNo 必须保证唯一，避免重复提交导致转账失败。
金额单位：amount 的单位为分，例如1元需填写为100。
异步通知：建议设置 notifyUrl 以接收转账结果通知，确保业务逻辑的完整性。
错误处理：调用时需捕获异常，处理可能的网络或参数错误。

通过以上步骤，开发者可以轻松实现转账功能，满足业务需求。

转账查询功能实现

在 Jeepay Python SDK 中，转账查询功能是一个重要的功能模块，用于查询转账订单的状态和详细信息。通过调用 jeepay.Transfer.transfer_query 方法，开发者可以轻松获取转账订单的当前状态，包括成功、失败或处理中等状态。以下将详细介绍转账查询功能的实现细节和使用方法。

功能概述

转账查询功能允许开发者通过转账订单号或商户转账单号查询转账订单的详细信息。该功能适用于需要实时监控转账状态的场景，例如订单对账或异常处理。

核心代码分析

转账查询功能的核心代码位于 jeepay/api_resources/transfer.py 文件中，具体实现如下：

class Transfer(RequestApi):

    @staticmethod
    def transfer_query(**params):
        url = AppConfig._get_base() + "/api/transfer/query"
        return RequestApi.call_api(url, params)

方法说明：
- transfer_query 是一个静态方法，接收可变参数 params。
- 通过拼接 AppConfig._get_base() 和 /api/transfer/query 构造完整的 API 请求地址。
- 调用 RequestApi.call_api 发送请求并返回结果。

使用方法

以下是一个完整的转账查询示例代码，展示了如何调用 transfer_query 方法：

import jeepay
from jeepay.app_config import AppConfig

# 配置信息
api_key = "your_api_key"
AppConfig.set_mch_no("your_mch_no")
AppConfig.set_app_id("your_app_id")
AppConfig.set_api_key(api_key)

# 调用转账查询
try:
    transfer_query = jeepay.Transfer.transfer_query(
        transferId="T1743191690773204994",  # 转账订单号
        # mchOrderNo="mho162913762435"  # 商户转账单号
    )
    print(transfer_query)
except Exception as e:
    print(e)

参数说明

transfer_query 方法支持以下参数：

参数名	类型	必填	说明
`transferId`	string	否	转账订单号，与 `mchOrderNo` 二选一。
`mchOrderNo`	string	否	商户转账单号，与 `transferId` 二选一。

返回结果

调用 transfer_query 方法后，返回的结果是一个包含转账订单详细信息的字典。以下是一个典型的返回示例：

{
    "code": 0,
    "message": "success",
    "data": {
        "transferId": "T1743191690773204994",
        "mchOrderNo": "mho162913762435",
        "amount": 100,
        "currency": "cny",
        "status": "SUCCESS",
        "transferDesc": "测试转账",
        "createTime": "2025-08-19 06:08:04",
        "updateTime": "2025-08-19 06:08:10"
    }
}

状态码说明

返回结果中的 status 字段表示转账订单的当前状态，可能的取值如下：

状态码	说明
`SUCCESS`	转账成功
`FAIL`	转账失败
`PROCESSING`	处理中
`CLOSED`	转账已关闭

流程图

以下是转账查询功能的流程图，展示了从发起查询到返回结果的完整流程：

mermaid

注意事项

参数校验：调用 transfer_query 方法时，必须确保至少传递 transferId 或 mchOrderNo 中的一个参数。
异常处理：建议在调用时捕获异常，避免因网络问题或参数错误导致程序中断。
状态监控：对于长时间处于 PROCESSING 状态的订单，建议设置定时任务进行轮询查询。

通过以上内容，开发者可以快速掌握 Jeepay Python SDK 中转账查询功能的实现和使用方法，从而更好地集成到自己的业务系统中。

转账通知的处理与验证

在 Jeepay Python SDK 中，转账通知是支付网关在转账完成后主动向商户系统发送的回调信息，用于通知转账状态（成功或失败）。正确处理和验证这些通知对于确保交易的安全性和可靠性至关重要。以下将详细介绍转账通知的处理流程、验证方法以及如何集成到您的系统中。

1. 转账通知的触发条件

转账通知会在以下情况下触发：

转账成功：资金已成功转入收款方账户。
转账失败：因账户问题、余额不足等原因导致转账失败。

通知会通过您在发起转账时设置的 notifyUrl 发送到您的服务器。如果通知未正确处理，支付网关会按照一定的策略（如延迟重试）重新发送通知。

2. 通知的数据结构

转账通知的数据以 POST 请求的形式发送到您的服务器，数据格式为 JSON，包含以下关键字段：

字段名	类型	描述
`transferId`	String	转账订单号，唯一标识一笔转账。
`mchOrderNo`	String	商户转账单号，由商户生成。
`amount`	Int	转账金额（单位：分）。
`currency`	String	币种，目前仅支持 `cny`（法定货币）。
`status`	Int	转账状态：`1` 表示成功，`2` 表示失败。
`errorMsg`	String	如果转账失败，返回失败原因。
`completeTime`	String	转账完成时间，格式为 `YYYY-MM-DD HH:mm:ss`。

3. 通知的处理流程

以下是一个典型的通知处理流程：

mermaid

关键步骤：

接收通知：您的服务器需要提供一个接口（如 /notice/transfer）来接收 POST 请求。
验证签名：确保通知来自 Jeepay 支付网关，防止伪造请求。
处理业务逻辑：根据通知状态更新订单状态、记录日志等。
返回响应：必须返回 HTTP 200 状态码，否则支付网关会认为通知失败并重试。

4. 签名验证

签名验证是确保通知安全性的关键步骤。以下是验证签名的代码示例：

import hashlib
import json

def verify_signature(data, api_key):
    # 获取签名
    sign = data.get("sign")
    if not sign:
        return False

    # 生成待签名字符串
    sorted_data = sorted(data.items(), key=lambda x: x[0])
    sign_str = "&".join([f"{k}={v}" for k, v in sorted_data if k != "sign"])
    sign_str += f"&key={api_key}"

    # 计算签名
    calculated_sign = hashlib.md5(sign_str.encode("utf-8")).hexdigest().upper()
    return calculated_sign == sign

5. 集成示例

以下是一个完整的通知处理示例：

from flask import Flask, request, jsonify
import hashlib

app = Flask(__name__)

API_KEY = "your_api_key_here"

@app.route("/notice/transfer", methods=["POST"])
def handle_transfer_notice():
    data = request.json
    if not verify_signature(data, API_KEY):
        return jsonify({"code": 400, "msg": "Invalid signature"}), 400

    # 处理业务逻辑
    transfer_id = data.get("transferId")
    status = data.get("status")
    if status == 1:
        print(f"转账成功: {transfer_id}")
    else:
        print(f"转账失败: {transfer_id}, 原因: {data.get('errorMsg')}")

    return jsonify({"code": 200, "msg": "Success"}), 200

def verify_signature(data, api_key):
    sign = data.get("sign")
    if not sign:
        return False
    sorted_data = sorted(data.items(), key=lambda x: x[0])
    sign_str = "&".join([f"{k}={v}" for k, v in sorted_data if k != "sign"])
    sign_str += f"&key={api_key}"
    calculated_sign = hashlib.md5(sign_str.encode("utf-8")).hexdigest().upper()
    return calculated_sign == sign

if __name__ == "__main__":
    app.run(host="0.0.0.0", port=5000)

6. 注意事项

幂等性处理：由于通知可能会重复发送，确保您的业务逻辑是幂等的，避免重复处理。
超时设置：支付网关的通知超时时间通常为 5秒，请确保您的接口能够快速响应。
日志记录：建议记录所有通知请求和响应，便于排查问题。

通过以上步骤，您可以安全、高效地处理 Jeepay Python SDK 的转账通知，确保您的系统与支付网关无缝集成。

【免费下载链接】jeepay-sdk-python Jeepay对应的python客户端实现项目地址: https://gitcode.com/jeequantech/jeepay-sdk-python

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考