如何在Flutter应用中接入Square终端支付？含设备配对与异常排查

一、终端与Flutter应用配对 #

• 确保Square终端已激活并接入稳定网络（Wi-Fi/蜂窝数据）
• Flutter项目集成Square官方SDK：在pubspec.yaml中添加square_in_app_payments依赖，执行flutter pub get完成安装
• 初始化SDK：应用启动时调用SquareInAppPayments.setSquareApplicationId("你的Square应用ID")
• 完成配对：
  • 方式1：调用TerminalApi.createDeviceCode生成配对码，在Square终端上输入该码完成绑定
  • 方式2：通过Square Dashboard预先将设备绑定到你的账号，应用内调用TerminalApi.listDevices获取已绑定设备列表

二、通过终端完成支付 #

• 构造支付请求：创建CreateTerminalActionRequest对象，指定payment_type为PAYMENT，设置金额（单位为货币最小单位，如美元用分）、货币代码，关联目标设备ID
• 发起支付：调用TerminalApi.createTerminalAction接口提交请求
• 监听状态：通过轮询TerminalApi.getTerminalAction或配置Webhook，跟踪支付状态，状态变为COMPLETED即表示支付成功

三、支付记录同步至后端 #

• 支付成功后，从返回的TerminalAction对象中提取支付ID、交易金额、时间、设备ID等核心数据
• 调用后端自定义API，将数据以POST请求发送至后端接口
• 后端需验证Square请求签名（参考Square官方签名验证逻辑），验证通过后将数据存入数据库
• 可选配置：设置Square Webhook，当支付事件触发时自动推送数据至后端，确保记录完整性

四、Terminal Action pending后自动取消的排查 #

• 检查设备网络：终端需保持在线，网络不稳定会导致请求超时取消
• 验证权限：确认Square应用已开启PAYMENTS_WRITE和TERMINAL_WRITE权限
• 核对请求参数：确保device_id对应已配对设备，金额、货币代码格式合规
• 查看控制台日志：在Square开发者控制台的Logs模块查看具体错误信息，常见原因包括设备未激活、请求超时、权限不足
• 调整超时设置：在CreateTerminalActionRequest中设置合理的timeout_duration（默认5分钟，可按需调整）

官方参考资源 #

• Square Flutter SDK文档：含初始化、支付流程的代码示例
• Terminal API官方指南：详细说明终端配对、请求参数、状态码含义
• Square故障排查文档：针对Terminal Action状态异常的常见问题解析

内容的提问来源于stack exchange，提问作者Junayed Ahamed