sumup

构建 SumUp 支付集成

根据所需流程和现有实现开展工作。除非任务要求更改，否则保留已选的集成方式和已安装的 SDK 版本。在询问缺失的商户、平台或凭据详情之前，先检查可用代码和配置；只有缺失信息会阻碍工作时才询问。

通过文档索引、API 参考索引或 OpenAPI 规范核实当前契约。使用已安装 SDK 的类型验证方法名称和请求模型。如果无法访问当前来源，请区分随附指南和已验证的行为。

选择相关参考资料

打开任务所需的参考资料；一个流程可能同时需要渠道指南以及后端或回调详情。以下路径均相对于此技能目录。

任务	参考资料
重定向到托管支付页面	托管结账
在网站中嵌入支付收集功能	Card Widget
在网站上添加 Apple Pay 或 Google Pay 按钮	Swift Checkout JavaScript SDK
显示移动支付面板	React Native Checkout
保存卡片或向已保存的令牌扣款	令牌化
创建、处理或检索在线结账	Checkouts API
将原生应用连接到读卡器	iOS 或 Android
在手机上接受非接触式支付	Android Tap to Pay 或 iPhone 指南
从 POS/后端控制 Solo 读卡器	Cloud API
处理回调或 3DS	Webhooks 和 3DS
恢复状态不确定的支付或退款	安全重试
检查凭据、范围或联盟设置	授权
查找语言示例、APM、测试或旧版 Payment Switch	参考资料索引

支付规则

• 在后端创建在线结账。将密钥 sup_sk_ 和 OAuth 客户端密钥保存在后端；受支持的前端结账 SDK 使用公开的 sup_pk_ 商户密钥。
• 优先使用受支持的托管式、组件式或 SDK 支付收款方式，不要引入原始银行卡信息处理。Swift Checkout 是浏览器 JavaScript SDK，不是原生 iOS SDK。
• 使用密钥所属商户的 API 密钥，并通过 OAuth 访问委托商户。确认所选端点的权限，以及凭据对应的商户上下文。
• 对于终端支付流程，请提供所需的 Affiliate Key 和匹配的应用标识符。Android Tap-to-Pay 需要单独的 SDK 和 Affiliate 元数据。
• 在处理结果前，持久化支付尝试引用和返回的 ID。为已确认的新尝试分配单独的引用；checkout_reference 不能替代重复支付检查。
• 对于在线订单，检索预期结账记录，并在履行订单前确认 status: "PAID"，以及商户、引用、金额和币种均匹配。重定向或客户端回调不能证明支付成功。
• Cloud API 结账的受理是异步的。使用其 client_transaction_id 进行关联，并核对最终交易结果。
• 将回调视为通知，并确保订单更新具备幂等性。在线结账回调文档未说明使用 HMAC 签名；仅当所选产品明确要求时，才执行签名检查。
• 超时、响应丢失或出现 5xx 后，先核对现有支付或退款，再重试。如果创建结账时未返回 ID，请通过原始 checkout_reference 查找。
• 新开发应使用当前未弃用的端点；与请求变更无关的迁移应单独处理。

验证受影响的流程

使用项目现有的检查和相关沙盒场景。对于支付流程变更，覆盖成功、拒绝（文档注明时使用 11.00），以及任何受影响的回调、身份验证、取消或结果不确定的路径。基于读卡器的测试与在线测试卡使用不同的设置。说明运行了哪些检查，以及哪些内容仍需设备、凭据或实时服务提供商验证。

如果已安装，sumup-best-practices、sumup-debug、sumup-testing、sumup-mcp 和 upgrade-sumup 分别用于方案选择、问题诊断、测试、MCP 和迁移。用户要求这些任务时再使用；它们不是使用此技能的前提。对于范围较窄的问题，请直接回答，无需提供完整的集成计划。