Flutter支付集成插件xpay_element_flutter_stage的使用

Flutter支付集成插件xpay_element_flutter_stage的使用

XPay Element for Flutter 是一个嵌入式支付系统，允许你在Flutter应用程序内直接从用户处收取付款。此包高度可定制，使你可以根据应用的主题和风格来调整支付表单的外观和功能。

特性

无缝支付集成

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

自定义样式

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

嵌入式认证

在应用内部进行OTP认证，确保顺畅且安全的用户体验。

事件处理

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

开始使用

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

dependencies:
  xpay_element_flutter_stage: ^3.0.1

使用方法

要使用XPay SDK，你需要遵循以下步骤：

导入包

import 'package:xpay_element_flutter_stage/xpay_element_flutter_stage.dart';

初始化元素控制器

创建一个带有XPay仪表板上可用的必要凭证的XPayElementController实例：

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的外观与你的应用主题无缝集成，你可以修改元素的样式和外观，使其适应各种设计需求。

初始化和应用自定义样式

初始化XPayElementCustomStyle并传递自定义样式配置给其构造函数。以下是如何定制支付元素外观的一个示例：

@override
XPayElementCustomStyle elementCustomStyle =
    XPayElementCustomStyle.configureCustomStyle({
  "inputConfiguration": {
    "cardNumber": {
      "label": "卡号",
      "placeholder": "请输入卡号"
    },
    "expiry": {"label": "有效期", "placeholder": "MM/YY"},
    "cvc": {"label": "CVC", "placeholder": "请输入CVC"}
  },
  "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方法。以下是你的Flutter应用中如何实现这一操作的方法：

void confirmPayment() async {
  try {
    // 假设'controller'是你的XPayElementController实例
    var paymentResponse = await controller.confirmPayment(
      customerName: "客户名称",
      clientSecret: "来自intent API的client_secret",
      encryptionKeys: "来自intent 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();