Sumup

Start Here

1. 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)
2. 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
3. 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
4. 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)
5. Apply the implementation pattern from references/checkout-playbook.md.
6. Use references/README.md and open only the single most relevant entrypoint for the request.

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.

Implementation Workflow

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

Required Response Contract

Every solution should state:

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

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).

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.