tamnguyendinh Payment Integration
Repo-agnostic payment integration guidance for target apps using SePay, Polar, Stripe, Paddle, Creem.io, or multiple providers.
Do not assume this skill is for integrating payments into the current repository. Apply provider and template guidance to the target app's domain model.
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 rulesreferences/sepay/api.md- API v2, transactions, reconciliation, Order VAsreferences/sepay/webhooks.md- Bank-account webhook setup, HMAC, replay safetyreferences/sepay/payment-gateway.md- Hosted checkout, gateway API, IPNreferences/sepay/sdk.md- Official Payment Gateway Node.js/PHP SDKsreferences/sepay/qr-codes.md- VietQR generation and bank-specific rulesreferences/sepay/best-practices.md- Repo-agnostic production patterns
Polar
references/polar/overview.md- Auth, MoR conceptreferences/polar/products.md- Product model, pricing, currencies, taxreferences/polar/checkouts.md- Checkout sessions, links, embedded checkoutreferences/polar/subscriptions.md- Lifecycle managementreferences/polar/webhooks.md- Event handlingreferences/polar/benefits.md- Automated deliveryreferences/polar/usage-based-billing.md- Events, meters, creditsreferences/polar/customer-portal.md- Customer sessions and self-servicereferences/polar/customer-state.md- Entitlement state and access syncreferences/polar/orders-refunds-discounts.md- Orders, refunds, discountsreferences/polar/sdk.md- Multi-language SDKsreferences/polar/best-practices.md- Production patterns
Stripe
references/stripe/stripe-best-practices.md- Integration designreferences/stripe/stripe-sdks.md- Server SDKsreferences/stripe/stripe-js.md- Payment Elementreferences/stripe/stripe-cli.md- Local testingreferences/stripe/stripe-upgrade.md- Version upgrades- External: https://docs.stripe.com/llms.txt
Paddle
references/paddle/overview.md- MoR, auth, entity IDsreferences/paddle/api.md- Products, prices, transactionsreferences/paddle/paddle-js.md- Checkout overlay/inlinereferences/paddle/subscriptions.md- Trials, upgrades, pausereferences/paddle/webhooks.md- SHA256 verificationreferences/paddle/sdk.md- Node, Python, PHP, Goreferences/paddle/best-practices.md- Production patterns- External: https://developer.paddle.com/llms.txt
Creem.io
references/creem/overview.md- MoR, auth, global supportreferences/creem/api.md- Products, checkout sessionsreferences/creem/checkouts.md- No-code links, storefrontsreferences/creem/subscriptions.md- Trials, seat-basedreferences/creem/licensing.md- Device activationreferences/creem/webhooks.md- Signature verificationreferences/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 design rules and template routingreferences/multi-provider/templates/local-data-model-template.md- Orders, provider IDs, events, refunds, entitlements, campaignsreferences/multi-provider/templates/webhook-processing-template.md- Verification, event ledger, dispatcher, retriesreferences/multi-provider/templates/checkout-factory-template.md- Provider-neutral checkout command and provider buildersreferences/multi-provider/templates/fulfillment-entitlements-template.md- Paid handlers and entitlement grantsreferences/multi-provider/templates/refunds-disputes-campaigns-template.md- Refunds, disputes, access consequences, campaignsreferences/multi-provider/templates/revenue-commissions-reconciliation-template.md- FX, reporting, commissions, reconciliationreferences/multi-provider/templates/admin-support-app-variants-template.md- Admin views, support actions, app variants
Scripts
scripts/sepay-webhook-verify.js- SePay webhook verificationscripts/polar-webhook-verify.js- Polar webhook verificationscripts/checkout-helper.js- Legacy checkout helper examples; prefer provider references for new API work
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 order state, provider event ledgers, refunds, entitlements, reporting, reusable templates |
Implementation
See references/implementation-workflows.md for step-by-step guides per platform.
For multi-provider work, load references/multi-provider-order-management-patterns.md first, then load only the focused template needed for the current slice.
General flow: auth -> products/prices -> checkout/payment instruction -> webhooks/IPN -> orders/refunds/entitlements -> reconciliation