Checkout.com

You are integrating Checkout.com as a payment gateway into a [Django / Next.js / etc.] application.

## Prerequisites
Checkout.com is sales-led — you cannot self-serve. Before writing code, confirm: (a) you have an approved merchant account, (b) you have access to the Hub dashboard, (c) you've received your Public API key, Secret API key, and Processing Channel ID. If any of these are missing, stop and contact your account manager.

## Setup
1. Install the official server SDK: `pip install checkout-sdk` (Python) or `npm install @checkout.com/checkout-sdk-node` (Node).
2. Store credentials in environment variables — NEVER hardcode:
   - `CKO_SECRET_KEY` (server-side, starts with `sk_`)
   - `CKO_PUBLIC_KEY` (client-side, starts with `pk_`)
   - `CKO_PROCESSING_CHANNEL_ID` (per-merchant; required on most API calls)
   - `CKO_WEBHOOK_SECRET` (signing key — set when you register the webhook)
3. Use the sandbox environment first (`environment='sandbox'`); promote to `production` only after end-to-end test card flows pass.

## Recommended Integration: Flow (drop-in component)
For most web checkouts, use **Flow** — it's PCI-SAQ-A scoped (card data never touches your server), supports cards + Apple Pay + Google Pay + local APMs from a single integration, and handles 3DS2 challenges automatically.

**Server: create a Payment Session**
```python
from checkout_sdk import CheckoutSdk
from checkout_sdk.environment import Environment

api = CheckoutSdk.builder() \
    .secret_key(settings.CKO_SECRET_KEY) \
    .environment(Environment.sandbox()) \
    .build()

session = api.payment_sessions.create_payment_sessions({
    'amount': 2000,            # $20.00 in minor units
    'currency': 'USD',
    'reference': 'order_internal_id',
    'processing_channel_id': settings.CKO_PROCESSING_CHANNEL_ID,
    'success_url': 'https://yourdomain.com/success',
    'failure_url': 'https://yourdomain.com/cancel',
    'customer': {'email': customer.email, 'name': customer.name},
})
# Pass session.payment_session_token to the browser
```

**Browser: mount Flow**
```html
<script src="https://checkout-web-components.checkout.com/index.js"></script>
<div id="flow-container"></div>
<script>
  const checkout = await CheckoutWebComponents({
    publicKey: '{{ CKO_PUBLIC_KEY }}',
    environment: 'sandbox',
    paymentSession: { id: '{{ session.id }}', payment_session_token: '{{ session.payment_session_token }}' },
    onPaymentCompleted: (component, paymentResponse) => { window.location = '/success'; },
  });
  checkout.create('flow').mount('#flow-container');
</script>
```

## Alternative integrations
- **Frames** (legacy iframe card form) — use only if you need full visual control of the card UI and accept higher PCI scope.
- **Hosted Payment Page (HPP)** — full redirect; no embedding; quickest to ship if you don't need on-site checkout. NOTE: HPP cannot be embedded inside an iframe.
- **Direct Payments API** — only if you're already PCI DSS certified and tokenize cards yourself.

## Webhooks (mandatory — do not trust the redirect)
The success/failure URL is a UX hint, not authoritative. Always confirm payment via webhook.

1. Register the webhook in the Hub dashboard or via the Workflows API. Subscribe to `payment_approved`, `payment_declined`, `payment_captured`, `payment_refunded`, `payment_chargeback`.
2. ALWAYS verify the `cko-signature` HMAC-SHA256 header against your webhook secret:
```python
import hmac, hashlib

def verify(payload_bytes: bytes, signature_header: str) -> bool:
    expected = hmac.new(
        settings.CKO_WEBHOOK_SECRET.encode(),
        payload_bytes,
        hashlib.sha256,
    ).hexdigest()
    return hmac.compare_digest(expected, signature_header)
```
3. Make the handler idempotent — keyed on the event `id` — Checkout.com retries on non-2xx responses for up to 24 hours.
4. Return 200 quickly; do heavy work in a background queue.

## Recurring / subscriptions
Store the first transaction's `id`, then pass it as `previous_payment_id` on subsequent merchant-initiated transactions (MIT). For full subscription billing UX (dunning, upgrades, proration) pair with Chargebee or Recurly — Checkout.com handles the rails, not the lifecycle.

## Marketplaces (split payments)
Use the **Integrated Platforms** product. Onboard sellers as sub-entities, then split funds at authorization or capture by passing `marketplace.sub_entities[]` with amounts and reference IDs.

## Security checklist
- [ ] All card data flows through Flow / Frames / HPP — never POST raw PAN to your server.
- [ ] 3DS2 enabled on every transaction (`'3ds': {'enabled': True}`); use the SCA exemption matrix only with explicit fraud-risk sign-off.
- [ ] Webhook handler verifies signature on every request.
- [ ] Secret key only loaded server-side; rotate quarterly.
- [ ] Network tokens enabled in the Vault for stored cards (improves auth rate, survives card replacement).

## Common pitfalls (from real merchant reports)
- The MSA is the source of truth for fees, reserves, and termination terms — not the website. Read it and negotiate.
- Reserve clauses can hold all funds for weeks past the last transaction if the account is closed. Plan cash-flow accordingly.
- Sandbox access can lag the production approval — request explicitly during onboarding so you can build in parallel.
- Sub-$1M/year merchants typically get worse commercial terms than at Stripe; reconsider fit before integrating.

## Reference
- API reference: https://api-reference.checkout.com/
- Docs: https://www.checkout.com/docs
- Status: https://status.checkout.com