Flutter支付终端集成插件square_reader_sdk的使用

简介

Square Reader SDK 让开发者可以将 Square 的支付流程嵌入到自定义应用中，并使用 Square Readers 接受面对面支付。SDK 支持授权、交易处理和 Reader 管理。

使用 Square 官方的 Flutter 插件 square_reader_sdk 可以在 Android 和 iOS 上构建面对面支付解决方案。

迁移指南

从 3.x 到 4.x 的迁移

在 Android 部分的应用类中的 onCreate 方法中移除初始化方法：

package <YOUR_PACKAGE_NAME>;

- import com.squareup.sdk.reader.ReaderSdk;   
import io.flutter.app.FlutterApplication;

public class MainApplication extends FlutterApplication {

 @Override
 public void onCreate() {
   super.onCreate();
-   ReaderSdk.initialize(this);
 }
}

如果目标 SDK 为 31 或更高

如果你的目标 SDK 为 31 或更高，需要在调用任何 Reader 插件方法之前请求 BLUETOOTH_SCAN 和 BLUETOOTH_CONNECT 权限。

使用方法

兼容性

Flutter 插件 square_reader_sdk 目前兼容以下原生 Reader SDK 版本：

• iOS: 1.6.0 及以上
• Android: 1.7.5 及以上

你可以尝试 示例应用 来查看插件的实际效果，或者按照 入门指南 构建自定义解决方案。

额外文档

除了此 README，GitHub 仓库中还提供了以下文档：

• 入门指南
• 技术参考
• 故障排除
• doc - 所有文档的根目录
• example - Flutter 示例应用的根目录（附带引导）

构建要求

Flutter

• Flutter 版本 2.0 或更高
• Dart 版本 2.12 或更高

Android

• minSdkVersion 是 API 24 或更高
• Android SDK 平台：API 31
• Android SDK 构建工具：28.0.2
• Android Gradle 插件：3.0.0 或更高
• Support 库：26.0.2
• Google Play 服务：16.0.1
• Google APIs Intel x86 Atom_64 系统映像

iOS

• Xcode 版本：10.2 或更高
• iOS 基础 SDK：11.1 或更高
• 部署目标：iOS 11.0 或更高

Reader SDK 要求和限制

• Reader SDK 仅适用于美国账户。基于其他国家/地区的账户的授权请求将返回错误。
• Reader SDK 不得用于无人值守的终端。使用 Reader SDK 在无人值守的终端或自助服务终端（例如，自动售货机）中实现支付解决方案是严格禁止的。
• Reader SDK 需要来自 Mobile Authorization API 的授权令牌才能连接 Square Readers 并接受支付。
• Reader SDK 仅支持屏幕上的小费。数字收据和小费可以在 Reader SDK 中配置。目前不支持打印收据上的小费。
• Reader SDK 不能退款。退款可以通过 Refunds API 程序化地发出，也可以在 Square Dashboard 中手动发出。
• Reader SDK 不支持 Square 沙箱。请参阅 测试移动应用 获取测试建议。
• 你的 Reader SDK 版本必须遵守 Square SDK 更新策略。为了降低开发人员及其用户的风险，Square 强制执行 Reader SDK 更新策略，要求开发人员保持其 Reader SDK 版本的最新状态。

许可证

Copyright 2022 Square Inc.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

示例代码

以下是 square_reader_sdk 插件的一个简单示例应用，展示了如何使用该插件进行支付授权和结算。

main.dart

/*
Copyright 2022 Square Inc.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
*/

import 'package:flutter/material.dart';
import 'screens/authorize_screen.dart';
import 'screens/checkout_screen.dart';
import 'screens/manual_authorize_screen.dart';
import 'screens/splash_screen.dart';

void main() => runApp(ExampleApp());

/// The root of this example app
class ExampleApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) => MaterialApp(
        theme: _buildTheme(),
        initialRoute: '/',
        routes: {
          '/': (context) => SplashScreen(),
          '/authorize': (context) => AuthorizeScreen(),
          '/authorize/manual': (context) => ManualAuthorizeScreen(),
          '/checkout': (context) => CheckoutScreen(),
        },
      );
}

// override default theme
ThemeData _buildTheme() {
  var base = ThemeData.light();
  return base.copyWith(
    canvasColor: Colors.transparent,
    scaffoldBackgroundColor: Color.fromRGBO(64, 135, 225, 1.0),
    buttonTheme: ButtonThemeData(
      height: 64.0,
    ),
    hintColor: Colors.transparent,
    inputDecorationTheme: InputDecorationTheme(
      labelStyle: TextStyle(
        color: Colors.white,
      ),
    ),
    textTheme: TextTheme(
      labelLarge: TextStyle(
        fontSize: 20.0,
        fontWeight: FontWeight.w600,
        color: Colors.white,
      ),
      bodyLarge: TextStyle(
        fontSize: 24.0,
        fontWeight: FontWeight.w600,
        color: Colors.white,
      ),
    ),
  );
}

screens/splash_screen.dart

import 'package:flutter/material.dart';
import 'package:square_reader_sdk/square_reader_sdk.dart';

class SplashScreen extends StatefulWidget {
  @override
  _SplashScreenState createState() => _SplashScreenState();
}

class _SplashScreenState extends State<SplashScreen> {
  @override
  void initState() {
    super.initState();
    _initializeReaderSdk();
  }

  Future<void> _initializeReaderSdk() async {
    try {
      await SquareReaderSdk.initialize(
        applicationId: 'YOUR_APPLICATION_ID',
        locationId: 'YOUR_LOCATION_ID',
        accessToken: 'YOUR_ACCESS_TOKEN',
      );
      Navigator.pushReplacementNamed(context, '/authorize');
    } catch (e) {
      print('Failed to initialize Reader SDK: $e');
    }
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: [
            Text('Initializing Reader SDK...'),
            CircularProgressIndicator(),
          ],
        ),
      ),
    );
  }
}

screens/authorize_screen.dart

import 'package:flutter/material.dart';
import 'package:square_reader_sdk/square_reader_sdk.dart';

class AuthorizeScreen extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: Text('Authorize Payment')),
      body: Center(
        child: ElevatedButton(
          onPressed: () async {
            try {
              final result = await SquareReaderSdk.authorizePayment(
                amountMoney: Money(amount: 100, currency: Currency.usd),
                note: 'Test Payment',
              );
              if (result.isSuccess) {
                ScaffoldMessenger.of(context).showSnackBar(
                  SnackBar(content: Text('Payment authorized successfully!')),
                );
              } else {
                ScaffoldMessenger.of(context).showSnackBar(
                  SnackBar(content: Text('Payment authorization failed.')),
                );
              }
            } catch (e) {
              ScaffoldMessenger.of(context).showSnackBar(
                SnackBar(content: Text('Error: $e')),
              );
            }
          },
          child: Text('Authorize Payment'),
        ),
      ),
    );
  }
}

screens/checkout_screen.dart

import 'package:flutter/material.dart';
import 'package:square_reader_sdk/square_reader_sdk.dart';

class CheckoutScreen extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: Text('Checkout')),
      body: Center(
        child: ElevatedButton(
          onPressed: () async {
            try {
              final result = await SquareReaderSdk.checkout(
                amountMoney: Money(amount: 100, currency: Currency.usd),
                note: 'Test Checkout',
              );
              if (result.isSuccess) {
                ScaffoldMessenger.of(context).showSnackBar(
                  SnackBar(content: Text('Checkout successful!')),
                );
              } else {
                ScaffoldMessenger.of(context).showSnackBar(
                  SnackBar(content: Text('Checkout failed.')),
                );
              }
            } catch (e) {
              ScaffoldMessenger.of(context).showSnackBar(
                SnackBar(content: Text('Error: $e')),
              );
            }
          },
          child: Text('Checkout'),
        ),
      ),
    );
  }
}

screens/manual_authorize_screen.dart

import 'package:flutter/material.dart';
import 'package:square_reader_sdk/square_reader_sdk.dart';

class ManualAuthorizeScreen extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: Text('Manual Authorize Payment')),
      body: Center(
        child: ElevatedButton(
          onPressed: () async {
            try {
              final result = await SquareReaderSdk.manualAuthorizePayment(
                amountMoney: Money(amount: 100, currency: Currency.usd),
                note: 'Test Manual Payment',
              );
              if (result.isSuccess) {
                ScaffoldMessenger.of(context).showSnackBar(
                  SnackBar(content: Text('Manual payment authorized successfully!')),
                );
              } else {
                ScaffoldMessenger.of(context).showSnackBar(
                  SnackBar(content: Text('Manual payment authorization failed.')),
                );
              }
            } catch (e) {
              ScaffoldMessenger.of(context).showSnackBar(
                SnackBar(content: Text('Error: $e')),
              );
            }
          },
          child: Text('Manual Authorize Payment'),
        ),
      ),
    );
  }
}

以上代码展示了如何使用 square_reader_sdk 插件进行支付授权和结算。希望这些示例对你有所帮助！