t1k:web:commerce:payment-integration

Field	Value
Module	`commerce`
Version	`1.7.0`
Effort	`medium`
Tools	—

Keywords: checkout, Paddle, payment, Polar, SePay, Stripe, subscriptions, VietQR, webhooks

How to invoke

/t1k:web:commerce:payment-integration
[provider] [task]

Payment Integration

Production-proven payment processing with SePay (Vietnamese banks), Polar (global SaaS), Stripe (global infrastructure), Paddle (MoR subscriptions), and Creem.io (MoR + licensing).

When to Use

Payment gateway integration (checkout, processing)
Subscription management (trials, upgrades, billing)
Webhook handling (notifications, idempotency)
QR code payments (VietQR, NAPAS)
Software licensing (device activation)
Multi-provider order management
Revenue splits and commissions

Platform Selection

Platform	Best For
SePay	Vietnamese market, VND, bank transfers, VietQR
Polar	Global SaaS, subscriptions, automated benefits (GitHub/Discord)
Stripe	Enterprise payments, Connect platforms, custom checkout
Paddle	MoR subscriptions, global tax compliance, churn prevention
Creem.io	MoR + licensing, revenue splits, no-code checkout

Quick Reference

SePay

references/sepay/overview.md - Auth, supported banks
references/sepay/api.md - Endpoints, transactions
references/sepay/webhooks.md - Setup, verification
references/sepay/sdk.md - Node.js, PHP, Laravel
references/sepay/qr-codes.md - VietQR generation
references/sepay/best-practices.md - Production patterns

Polar

references/polar/overview.md - Auth, MoR concept
references/polar/products.md - Pricing models
references/polar/checkouts.md - Checkout flows
references/polar/subscriptions.md - Lifecycle management
references/polar/webhooks.md - Event handling
references/polar/benefits.md - Automated delivery
references/polar/sdk.md - Multi-language SDKs
references/polar/best-practices.md - Production patterns

Stripe

references/stripe/stripe-best-practices.md - Integration design
references/stripe/stripe-sdks.md - Server SDKs
references/stripe/stripe-js.md - Payment Element
references/stripe/stripe-cli.md - Local testing
references/stripe/stripe-upgrade.md - Version upgrades
External: https://docs.stripe.com/llms.txt

Paddle

references/paddle/overview.md - MoR, auth, entity IDs
references/paddle/api.md - Products, prices, transactions
references/paddle/paddle-js.md - Checkout overlay/inline
references/paddle/subscriptions.md - Trials, upgrades, pause
references/paddle/webhooks.md - SHA256 verification
references/paddle/sdk.md - Node, Python, PHP, Go
references/paddle/best-practices.md - Production patterns
External: https://developer.paddle.com/llms.txt

Creem.io

references/creem/overview.md - MoR, auth, global support
references/creem/api.md - Products, checkout sessions
references/creem/checkouts.md - No-code links, storefronts
references/creem/subscriptions.md - Trials, seat-based
references/creem/licensing.md - Device activation
references/creem/webhooks.md - Signature verification
references/creem/sdk.md - Next.js, Better Auth
External: https://docs.creem.io/llms.txt

Multi-Provider

references/multi-provider-order-management-patterns.md - Unified orders, currency conversion

Scripts

scripts/sepay-webhook-verify.js - SePay webhook verification
scripts/polar-webhook-verify.js - Polar webhook verification
scripts/checkout-helper.js - Checkout session generator

Key Capabilities

Platform	Highlights
SePay	QR/bank/cards, 44+ VN banks, webhooks, 2 req/s
Polar	MoR, subscriptions, usage billing, benefits, 300 req/min
Stripe	CheckoutSessions, Billing, Connect, Payment Element
Paddle	MoR, overlay/inline checkout, Retain (churn prevention), tax
Creem.io	MoR, licensing, revenue splits, no-code checkout

Implementation

See references/implementation-workflows.md for step-by-step guides per platform.

General flow: auth → products → checkout → webhooks → events

Gotchas

Idempotency-key required on every payment retry — without it, double-charging is a bounded UUID set away from production. Use BoundedUUIDSet (FIFO, max 10k entries) for in-memory, plus a server-side dedup table for cross-restart.
Per-provider 401 retry table differs — Stripe: 3 retries with jitter; PayPal: 1 retry then human; Adyen: never retry. Code one per-provider table.
Webhook signature verification is per-payload, NOT per-request — Stripe rotates signing secrets; cache + grace period both prev and current.
3DS challenge windows time out — bound the challenge wait to 5 minutes server-side or risk dangling order rows.
SCA/PSD2 requires re-authentication on saved cards in EU — silent decline if your flow assumes US-style frictionless reuse.