Flutter支付集成插件xpay_element_flutter的使用

XPay Element for Flutter 是一个嵌入式支付系统，允许你在 Flutter 应用程序中直接从用户处收集付款。此包高度可定制，使你能够调整支付表单的外观和功能，以无缝地与你的应用程序样式和主题保持一致。

功能

无缝支付集成

轻松将支付功能集成到你的 Flutter 应用程序中，而无需重定向用户到外部应用程序或页面。

自定义样式

根据应用的主题样式化支付 SDK，可以自定义标签、占位符等。

嵌入式认证

在应用内进行一次性密码（OTP）认证，确保流畅和安全的用户体验。

事件处理

利用内置事件（如 onBinDiscount 和 onReady）动态管理更改并验证输入。

开始使用

要将 XPay 嵌入式支付系统集成到你的 Flutter 应用程序中，请首先在 pubspec.yaml 文件中添加以下依赖：

dependencies:
  xpay_element_flutter: ^3.0.1

使用方法

要在应用中使用 XPay SDK，请遵循以下步骤：

导入包

import 'package:xpay_element_flutter/xpay_element_flutter.dart';

初始化元素控制器

创建一个带有必要凭证的 XPayElementController 实例，这些凭证可以在你的 XPay 仪表板上找到：

final XPayElementController controller = XPayElementController(
  publicKey: "your_account_public_key",
  hmacKey: "your_account_hmac_key",
  accountId: "your_account_id"
);

嵌入支付小部件

将 XPayElementWidget 集成到应用的 widget 树中，并使用控制器进行配置：

@override
Widget build(BuildContext context) {
  return Scaffold(
    appBar: AppBar(title: const Text('XPay 支付示例')),
    body: XPayElementWidget(controller: controller),
  );
}

自定义样式

自定义 SDK 的外观，使其无缝集成到应用的样式和主题中。XPay SDK 允许你修改元素的样式和外观，使其适应各种设计需求。

初始化并应用自定义样式

初始化 XPayElementCustomStyle 并传入自定义样式配置。以下是如何自定义支付元素外观的一个例子：

@override
XPayElementCustomStyle elementCustomStyle =
    XPayElementCustomStyle.configureCustomStyle({
  "inputConfiguration": {
    "cardNumber": {
      "label": "卡号",
      "placeholder": "输入卡号"
    },
    "expiry": {"label": "有效期", "placeholder": "MM/YY"},
    "cvc": {"label": "CVV", "placeholder": "输入 CVV"}
  },
  "inputStyle": {
    "height": 40,
    "textColor": 0xff000000,
    "textSize": 16,
    "fontWeight": 400,
    "borderColor": 0xffe6e6e6,
    "borderRadius": 5,
    "borderWidth": 1
  },
  "inputLabelStyle": {
    "textSize": 16,
    "fontWeight": 400,
    "textColor": 0xff000000
  },
  "onFocusInputStyle": {
    "textColor": 0xff000000,
    "textSize": 16,
    "fontWeight": 400,
    "borderColor": 0xffc8dbf9,
    "borderWidth": 1
  },
  "invalidStyle": {
    "borderColor": 0xffff0000,
    "borderWidth": 1,
    "textColor": 0xffff0000,
    "textSize": 14,
    "fontWeight": 400
  },
  "errorMessageStyle": {
    "textColor": 0xffff0000,
    "textSize": 14,
    "fontWeight": 400
  }
});

应用自定义样式

配置好样式后，将其应用于 XPayElementWidget 以增强用户界面：

@override
Widget build(BuildContext context) {
  return Scaffold(
    appBar: AppBar(title: Text('自定义样式的 XPay 元素')),
    body: XPayElementWidget(style: elementCustomStyle, controller: controller)
  );
}

上述样式属性都是可选的；你可以只定义你需要的那些属性，以确保灵活性和自定义性。

元素事件

处理特定于元素的事件以增强用户体验：

onReady 事件

当所有表单字段有效且表单准备好提交时触发此事件。

@override
Widget build(BuildContext context) {
  return Scaffold(
    appBar: AppBar(title: Text('自定义样式的 XPay 元素')),
    body: XPayElementWidget(
            controller: controller,
            onReady: (bool isReady) {
                // 更新状态以启用支付提交
            },
        )
    );
}

onBinDiscount

当用户输入卡号时接收与卡的 BIN 相关的数据，可用于实施折扣或促销活动。

@override
Widget build(BuildContext context) {
  return Scaffold(
    appBar: AppBar(title: Text('自定义样式的 XPay 元素')),
    body: XPayElementWidget(
            controller: controller,
            onBinDiscount: (dynamic binDiscountData) {
                // 处理并应用基于 BIN 的折扣
            },
        )
    );
}

确认支付

当所有表单字段有效且 onReady 事件返回 true 时，应执行一些必要的步骤来确认支付。首先，确保你已经启动了一个服务器端的 API 调用来创建支付意图。此创建意图 API 负责生成用于安全发起支付过程的 clientSecret 和用于传输前加密敏感信息的 encryptionKey。

服务器端支付意图创建

在客户端调用支付确认之前，你的后端应该调用创建意图 API 以获取：

• clientSecret: 用于安全发起支付过程的秘密密钥。
• encryptionKey: 用于在传输前加密敏感信息。

确认支付

一旦从后端获得了必要的密钥，使用早期初始化的 XPayElementController 调用 confirmPayment 方法。以下是实现此功能的方法：

void confirmPayment() async {
  try {
    // 假设 'controller' 是你的 XPayElementController 实例
    var paymentResponse = await controller.confirmPayment(
      customerName: "客户姓名",
      clientSecret: "来自意图 API 的 client_secret",
      encryptionKeys: "来自意图 API 的 encryption_keys"
    );

    if (paymentResponse.error) {
      // 处理支付失败
      print("支付失败: ${paymentResponse.message}");
    } else {
      // 处理支付成功
      print("支付成功: ${paymentResponse.message}");
    }
  } catch (e) {
    // 处理异常
    print("支付错误: $e");
  }
}

确认支付响应

confirmPayment 的响应包含两个键：

• error: 一个布尔值，指示支付是否不成功。如果为真，则表示支付失败。
• message: 一个包含来自服务器的消息的字符串。该消息提供了支付结果或错误信息的详细信息。

清除方法

clear 方法用于重置支付表单。如果你有一个按钮用于清除表单或重置结账过程，这特别有用。

// 假设 'controller' 是你的 XPayElementController 实例
controller.clear();