payment-integration v2.2.0A

Immutable. This exact content is served forever at /api/v1/blob/3ba20a66b73f18e8.

---
name: payment-integration
description: Use when the user asks to integrate payments.
version: 2.2.0
license: MIT
---

# 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` - Surface selection, environments, safety rules
- `references/sepay/api.md` - API v2, transactions, reconciliation, Order VAs
- `references/sepay/webhooks.md` - Bank-account webhook setup, HMAC, replay safety
- `references/sepay/payment-gateway.md` - Hosted checkout, gateway API, IPN
- `references/sepay/sdk.md` - Official Payment Gateway Node.js/PHP SDKs
- `references/sepay/qr-codes.md` - VietQR generation and bank-specific rules
- `references/sepay/best-practices.md` - Repo-agnostic production patterns

### Polar
- `references/polar/overview.md` - Auth, MoR concept
- `references/polar/products.md` - Product model, pricing, currencies, tax
- `references/polar/checkouts.md` - Checkout sessions, links, embedded checkout
- `references/polar/subscriptions.md` - Lifecycle management
- `references/polar/webhooks.md` - Event handling
- `references/polar/benefits.md` - Automated delivery
- `references/polar/usage-based-billing.md` - Events, meters, credits
- `references/polar/customer-portal.md` - Customer sessions and self-service
- `references/polar/customer-state.md` - Entitlement state and access sync
- `references/polar/orders-refunds-discounts.md` - Orders, refunds, discounts
- `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` - Provider-neutral orders, refunds, events, entitlements, revenue, reconciliation

### 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** | API v2, QR/bank/cards, VN banks, webhooks, gateway IPN |
| **Polar** | MoR, subscriptions, usage billing, benefits, customer portal |
| **Stripe** | CheckoutSessions, Billing, Connect, Payment Element |
| **Paddle** | MoR, overlay/inline checkout, Retain (churn prevention), tax |
| **Creem.io** | MoR, licensing, revenue splits, no-code checkout |
| **Multi-Provider** | Unified local order state, provider event ledgers, refunds, entitlements, reporting |

## Implementation

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

**General flow:** auth -> products/prices -> checkout/payment instruction -> webhooks/IPN -> orders/refunds/entitlements -> reconciliation