beecloud 跳转带参数

这里的“跳转”通常指两种情况：

1. 从你的 App/网站跳转到 BeeCloud 支付页面/SDK。
2. 用户支付完成后，从 BeeCloud 的支付结果页跳转回你的 App 或网站。

第二种情况是“带参数”最核心和最常见的应用场景，因为它需要将支付结果（如支付成功、失败、订单号等）信息传递回来，让你的服务器或 App 能够知晓支付状态并进行后续处理（如发货、更新订单状态等）。

下面我将分步骤详细说明,并以常见的场景为例。

假设你的用户在你的 App 或网站上购买了一件商品，你需要引导他去支付，支付完成后，他需要被带回你的应用或网站,并且你希望知道这笔支付是成功了还是失败了。

第一步：发起支付时带上你的自定义参数

在用户点击“支付”按钮后，你的服务器需要生成一个支付订单，并调用 BeeCloud 的 API 创建支付请求，在这个请求中，你可以带上一些自定义参数,这些参数会在支付成功后原样返回给你。

核心目的：

• 订单标识：最常用的是 billNo（订单号）,用于唯一标识这笔交易。
• 用户信息：如 userId, userName 等,方便在支付回调中识别是哪个用户的订单。
• 业务信息：如 productId, subject）等,用于在支付结果页展示或后续业务处理。

示例代码（后端调用 BeeCloud API）

以 Java 为例,创建一个微信支付请求：

import com.beecloud.BeeCloud;
import com.beecloud.bean.BillInfo;
import com.beecloud.bean.WeChatPayRequest;
import com.beecloud.exception.BeeCloudException;
public class PaymentService {
    public void createWeChatPayOrder(String userId, String productTitle, String billNo) {
        // 1. 设置你的 BeeCloud AppID 和 SecretKey (通常在初始化时设置一次即可)
        BeeCloud.APP_ID = "你的_AppID";
        BeeCloud.SECRET_KEY = "你的_SecretKey";
        // 2. 创建微信支付请求对象
        WeChatPayRequest weChatPayRequest = new WeChatPayRequest();
        // 3. 设置支付参数
        weChatPayRequest.setBillNo(billNo); // 你的订单号，必须唯一！
        weChatPayRequest.setTitle(productTitle); // 订单标题/商品名称
        weChatPayRequest.setTotalFee(100); // 支付金额，单位：分
        weChatPayRequest.setBillType(BillInfo.BILL_TYPE_WECHAT); // 支付类型：微信
        // 4. 【关键】设置自定义参数（可选，但强烈推荐）
        // 这些参数会在支付成功后，在异步通知和同步跳转中返回给你
        weChatPayRequest.setOptionalParams("userId", userId);
        weChatPayRequest.setOptionalParams("productId", "prod_12345");
        weChatPayRequest.setOptionalParams("customMemo", "用户备注信息");
        try {
            // 5. 发起支付请求，BeeCloud 会返回一个包含支付跳转URL或SDK参数的对象
            BillInfo billInfo = BeeCloud.requestPay(weChatPayRequest);
            // 6. 根据返回结果，引导用户支付
            if (billInfo != null) {
                // 如果是扫码支付，billInfo.getPayUrl() 就是支付二维码的链接
                // 如果是App支付，billInfo.getPayData() 就是SDK需要调用的JSON数据
                System.out.println("支付请求成功，请引导用户支付。");
                System.out.println("支付URL: " + billInfo.getPayUrl());
                System.out.println("SDK数据: " + billInfo.getPayData());
                // 将 billInfo 返回给前端/App，用于调起支付
            } else {
                System.out.println("支付请求失败，请检查参数。");
            }
        } catch (BeeCloudException e) {
            // 处理 BeeCloud 返回的业务异常
            System.err.println("BeeCloud 异常: " + e.getErrCode() + " - " + e.getErrMsg());
        } catch (Exception e) {
            // 处理其他异常
            e.printStackTrace();
        }
    }
}

说明：

• setOptionalParams(key, value) 方法就是用来添加自定义参数的,你可以添加多个。
• billNo (订单号) 是最重要的参数，必须保证其唯一性,用于后续对账和查询。

第二步：支付完成后的跳转与参数接收

用户完成支付（成功或取消）后，BeeCloud 会根据你的配置进行跳转,并带上支付结果参数。

1 同步跳转（Sync Return）

这是用户在支付完成后，被立即跳转回你指定的页面（通常是 App 的某个页面或网站的某个页面），这种方式响应快，但可能因为网络问题导致丢失，因此不能完全依赖它来确认支付结果。

如何配置： 在调用 BeeCloud API 时，可以指定一个 returnUrl。

// 在 WeChatPayRequest 对象中设置
weChatPayRequest.setReturnUrl("https://www.yourwebsite.com/payment/result");
// 或者 App 的回调 Scheme
// weChatPayRequest.setReturnUrl("yourappscheme://payment/callback");

参数格式： BeeCloud 会将支付结果作为 URL 查询参数附加在 returnUrl 后面。

示例返回链接： https://www.yourwebsite.com/payment/result?billNo=20251027123456&result=success&totalFee=100&...

参数说明：

• result: 支付结果，success (成功), fail (失败), user_cancel (用户取消)。
• billNo: 你发起支付时传入的订单号。
• totalFee: 支付金额。
• 你通过 setOptionalParams 设置的所有参数,也会被原样带回来。

你的后端/前端如何处理： 当用户跳转到这个 returnUrl 时，你的服务器需要解析 URL 中的参数，并根据 result 来初步判断支付状态。再次强调，这仅用于前端展示，真正的支付结果应以异步通知为准。

2 异步通知（Asynchronous Notification）【最重要！】

这是 BeeCloud 在支付状态最终确定后，主动、安全地向你的服务器发送一个 HTTP POST 请求的方式，这是确认支付最终状态最可靠的方式，必须处理。

如何配置： 在 BeeCloud 的后台管理系统中，你需要配置一个“异步通知 URL”。

• 登录 BeeCloud 控制台。
• 进入你的应用 -> 应用设置 -> 支付配置。
• 找到“异步通知地址”或“回调 URL”选项，并填入你的服务器上一个可公开访问的 URL，https://api.yourwebsite.com/payment/webhook。

通知流程：

1. 用户在微信/支付宝等支付渠道完成支付。
2. 支付渠道将支付结果通知给 BeeCloud。
3. BeeCloud 验证该笔交易。
4. BeeCloud 向你配置的 异步通知 URL 发送一个 POST 请求。

请求体（Body）格式： 请求体是 JSON 格式，包含了完整的支付信息,包括你设置的自定义参数。

{
  "billNo": "20251027123456",
  "billTime": "2025-10-27 12:34:56",
  "channel": "wx_pub", // 支付渠道
  "currency": "CNY",
  "payChannel": "1", // 1-微信, 2-支付宝
  "result": "success", // 核心结果
  "totalFee": 100,
  "transactionId": "微信支付返回的交易号",
  "type": "bill", // 固定值
  "version": "3.0",
  "timestamp": 1698378896000,
  "signature": "a1b2c3d4e5f6...", // BeeCloud 的签名，用于验证请求的合法性
  // ======== 以下是你的自定义参数 ========
  "userId": "user_789",
  "productId": "prod_12345",
  "customMemo": "用户备注信息"
}

你的服务器如何处理：

1. 接收请求：创建一个 API 接口（如 /payment/webhook）来接收这个 POST 请求。
2. 验证签名：这是安全的关键！ 使用 BeeCloud 提供的验签方法（SDK 通常会提供）来验证 signature 是否合法，这可以确保请求确实来自 BeeCloud,而不是恶意攻击。
3. 处理业务逻辑：
   • 验证通过后，检查 result 字段。
   • result 是 success，则根据 billNo 查找你的订单，将订单状态更新为“已支付”，然后执行发货、增加积分等后续操作。
   • result 是 fail 或 user_cancel，则记录日志，无需做特殊处理（或标记订单为“支付失败”）。
4. 返回响应：处理完成后，必须向 BeeCloud 返回一个特定的响应，告知它你已经成功接收，通常是 XML 格式：

   <xml>
       <return_code><![CDATA[SUCCESS]]></return_code>
       <return_msg><![CDATA[OK]]></return_msg>
   </xml>

   如果返回的不是 SUCCESS，BeeCloud 会认为你没有收到通知，并会在一定时间内（如几小时）重复发送通知，直到你返回 SUCCESS 为止。

总结与最佳实践

完整的支付流程建议：

1. 发起支付：你的服务器调用 BeeCloud API，带上 billNo 和 optionalParams。
2. 调起支付：将 BeeCloud 返回的支付信息（URL 或 SDK Data）交给前端/App,调起支付界面。
3. 用户支付：用户完成支付操作。
4. 同步跳转：用户被立即跳转回 returnUrl，前端解析参数，展示“支付成功/失败”的页面，并提示用户即将返回。此时不要立即发货。
5. 异步通知：BeeCloud 向你的服务器发送 POST 请求。
6. 后端处理：
   • 你的服务器接收通知，验证签名。
   • 验证通过后，根据 result 更新数据库中的订单状态（从“待支付”改为“已支付”）。
   • 执行发货、发邮件通知等后续操作。
   • 向 BeeCloud 返回 SUCCESS。
7. 最终确认：App 或网站可以通过轮询或 WebSocket 的方式，从自己的服务器查询最新的订单状态,以获得最权威的支付结果。

通过以上步骤，你就可以安全、可靠地实现 BeeCloud 支付的“跳转带参数”功能了。