sumup

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

SumUp Checkout Integrations

SumUp结账集成

Knowledge and APIs can change. Always prefer the latest SumUp docs in markdown format over stale memory.

Docs root:
```
https://developer.sumup.com/
```
LLM entrypoint:
```
https://developer.sumup.com/llms.txt
```

Markdown page format example:

https://developer.sumup.com/terminal-payments/cloud-api/index.md

Use this skill to implement end-to-end SumUp checkouts for:

Terminal payments (native mobile SDKs, Cloud API for Solo, or Payment Switch)
Online payments (Card Widget and API-orchestrated checkout flow)

知识和API可能会发生变化。请始终优先使用最新的Markdown格式SumUp文档，而非过时的记忆内容。

文档根目录：
```
https://developer.sumup.com/
```
LLM入口：
```
https://developer.sumup.com/llms.txt
```

Markdown页面格式示例：

https://developer.sumup.com/terminal-payments/cloud-api/index.md

使用本技能可实现端到端的SumUp结账，适用于：

终端支付（原生移动SDK、面向Solo的Cloud API或Payment Switch）
在线支付（Card Widget和API编排的结账流程）

Quick Decision Tree

快速决策树

text

Need to accept a payment?
├─ In-person (card-present) → terminal
│  ├─ Native mobile app + direct reader flow → terminal/mobile (iOS SDK or Android Reader SDK)
│  ├─ Non-native POS/backend controls Solo reader → terminal/platform-agnostic (Cloud API)
│  └─ Legacy app handoff to SumUp app explicitly required → terminal/legacy-lightweight (Payment Switch)
└─ Online (card-not-present) → online
   ├─ Fastest secure integration, hosted/embedded UI acceptable → online/low-complexity (Card Widget)
   └─ Custom orchestration and async lifecycle handling required → online/custom (Checkouts API + 3DS + webhooks)

text

需要接收付款？
├─ 面对面（刷卡支付）→ 终端
│  ├─ 原生移动应用+直接读卡器流程 → 终端/移动（iOS SDK或Android Reader SDK）
│  ├─ 非原生POS/后端控制Solo读卡器 → 终端/跨平台（Cloud API）
│  └─ 明确需要将旧版应用切换到SumUp应用 → 终端/轻量旧版方案（Payment Switch）
└─ 在线（无卡支付）→ 在线
   ├─ 最快的安全集成，可接受托管/嵌入式UI → 在线/低复杂度（Card Widget）
   └─ 需要自定义编排和异步生命周期处理 → 在线/自定义（Checkouts API + 3DS + webhooks）

Start Here

入门步骤

Classify the requested flow:
- ```
terminal
```
  : in-person card-present payment
- ```
online
```
  : e-commerce/web/app card-not-present payment
- ```
hybrid
```
  : both (for example, web checkout + in-store Solo)
Pick integration path:
- ```
terminal/mobile
```
  : iOS SDK or Android Reader SDK
- ```
terminal/platform-agnostic
```
  : Cloud API with Solo readers
- ```
terminal/legacy-lightweight
```
  : Payment Switch
- ```
online/low-complexity
```
  : Card Widget
- ```
online/custom
```
  : Checkouts API + 3DS + webhooks
Confirm credentials and environment:
- API key or OAuth access token
- Affiliate Key for card-present flows
- Merchant code and currency alignment
- Sandbox merchant account for non-production testing
Ask for missing critical inputs before implementation:
- integration channel (mobile SDK, Cloud API, Card Widget, or API-orchestrated)
- target market/currency and merchant code
- auth model (API key vs OAuth)
- webhook endpoint and idempotency strategy
- existing constraints (legacy compatibility, migration, PCI scope)
Apply the implementation pattern from
```
references/checkout-playbook.md
```
.
Use
```
references/README.md
```
and open only the single most relevant entrypoint for the request.

对所需流程进行分类：
- ```
terminal
```
  ：面对面刷卡支付
- ```
online
```
  ：电商/网页/应用无卡支付
- ```
hybrid
```
  ：两者兼具（例如网页结账+店内Solo读卡器）
选择集成路径：
- ```
terminal/mobile
```
  ：iOS SDK或Android Reader SDK
- ```
terminal/platform-agnostic
```
  ：搭配Solo读卡器的Cloud API
- ```
terminal/legacy-lightweight
```
  ：Payment Switch
- ```
online/low-complexity
```
  ：Card Widget
- ```
online/custom
```
  ：Checkouts API + 3DS + webhooks
确认凭证和环境：
- API密钥或OAuth访问令牌
- 刷卡支付流程所需的Affiliate Key
- 商户代码与货币匹配
- 用于非生产测试的沙箱商户账户
在实现前询问缺失的关键信息：
- 集成渠道（移动SDK、Cloud API、Card Widget或API编排）
- 目标市场/货币和商户代码
- 认证模式（API密钥 vs OAuth）
- Webhook端点和幂等策略
- 现有约束（旧版兼容性、迁移、PCI范围）
应用
```
references/checkout-playbook.md
```
中的实现模式。
使用
```
references/README.md
```
，仅打开与请求最相关的单个入口文件。

Non-Negotiable Rules

不可违反的规则

Keep secret API keys and OAuth client secrets server-side only.
Never handle raw PAN/card data directly.
Create online checkouts server-to-server.
Prefer Card Widget and SDK-provided checkout experiences to avoid handling raw card details.
For card-present integrations, include the Affiliate Key and ensure app identifiers match the key setup.
Avoid Payment Switch unless the user explicitly requests it or has a hard legacy constraint.
Use unique transaction references (
```
checkout_reference
```
,
```
foreignTransactionId
```
, or equivalent) to prevent duplicates and improve reconciliation.
Do not use endpoints marked as deprecated.
Prefer endpoints that accept
```
merchant_code
```
as an explicit parameter when equivalent alternatives exist.
Treat webhook events as notifications only; verify state through API reads.
After a widget/client callback reports success, always verify final checkout state on the backend before confirming order/payment success.

机密API密钥和OAuth客户端密钥仅保留在服务器端。
切勿直接处理原始PAN/银行卡数据。
通过服务器到服务器的方式创建在线结账。
优先使用Card Widget和SDK提供的结账体验，避免处理原始银行卡信息。
对于刷卡支付集成，请包含Affiliate Key并确保应用标识符与密钥设置匹配。
除非用户明确要求或存在严格的旧版约束，否则避免使用Payment Switch。
使用唯一的交易参考（
```
checkout_reference
```
、
```
foreignTransactionId
```
或等效字段）防止重复并提高对账效率。
不要使用标记为已弃用的端点。
当存在等效替代方案时，优先选择接受
```
merchant_code
```
作为显式参数的端点。
将Webhook事件仅视为通知；通过API读取验证状态。
在Widget/客户端回调报告成功后，始终在后端验证最终结账状态，然后再确认订单/付款成功。

Implementation Workflow

实现工作流

Set up auth and merchant context.
Create checkout request with unique reference and correct currency.
Complete checkout via chosen channel:
- terminal SDK checkout call
- Cloud API reader checkout
- Card Widget
- direct checkout processing flow
Handle async outcomes:
- SDK callback / activity result / event stream
- 3DS
```
next_step
```
  redirect flow
- webhook delivery + API verification
Return normalized result (status, transaction identifiers, retry guidance).

设置认证和商户上下文。
创建带有唯一参考和正确货币的结账请求。
通过所选渠道完成结账：
- 终端SDK结账调用
- Cloud API读卡器结账
- Card Widget
- 直接结账处理流程
处理异步结果：
- SDK回调 / 活动结果 / 事件流
- 3DS
```
next_step
```
  重定向流程
- Webhook交付 + API验证
返回标准化结果（状态、交易标识符、重试指导）。

Required Response Contract

必需的响应约定

Every solution should state:

Chosen integration path and why.
End-to-end sequence (server, client, webhook/async verification).
Exact endpoint set, confirming no deprecated endpoints and preference for
```
merchant_code
```
-accepting endpoints.
Failure and retry handling (timeouts, duplicate refs, webhook retries).
Test plan for success, deliberate failure, and reconciliation checks.

每个解决方案都应说明：

所选的集成路径及其原因。
端到端流程（服务器、客户端、Webhook/异步验证）。
确切的端点集合，确认无已弃用端点且优先选择接受
```
merchant_code
```
的端点。
失败和重试处理（超时、重复参考、Webhook重试）。
针对成功、故意失败和对账检查的测试计划。

Validation Checklist

验证清单

Test and capture both successful payment and deliberate failure case (
```
amount = 11
```
in test mode).
Verify behavior for duplicate transaction references.
Verify timeout/session expiry behavior in the selected checkout path.
Verify webhook retries and idempotent processing.
Verify reconciliation fields are stored (checkout id, transaction id/code, merchant code, reference).

测试并记录成功付款和故意失败的情况（测试模式下
```
amount = 11
```
）。
验证重复交易参考的行为。
验证所选结账路径中的超时/会话过期行为。
验证Webhook重试和幂等处理。
验证对账字段已存储（结账ID、交易ID/代码、商户代码、参考）。

References

参考资料

Use
```
references/README.md
```
to pick the right reference file.
Each reference file includes its own canonical markdown docs URL. Prefer that URL over stale memory.

使用
```
references/README.md
```
选择合适的参考文件。
每个参考文件都包含其自己的标准Markdown文档URL。请优先使用该URL而非过时的记忆内容。