home / skills / jjuidev / jss / payment-integration

payment-integration skill

safe

/.claude/skills/payment-integration

This skill streamlines integrating SePay and Polar for checkout, subscriptions, webhooks, and automated benefits across global and Vietnamese payments.

npx playbooks add skill jjuidev/jss --skill payment-integration

Review the files below or copy the command above to add this skill to your agents.

Files (22)

SKILL.md

4.9 KB

---
name: payment-integration
description: Integrate payments with SePay (VietQR, Vietnamese bank transfers) and Polar (global SaaS subscriptions, billing). Use for checkout flows, webhooks, QR codes, subscription management.
version: 1.0.0
license: MIT
---

# Payment Integration

Implement payment processing with SePay (Vietnamese payments) and Polar (global SaaS monetization).

## When to Use

Use when implementing:
- Payment gateway integration (checkout, processing)
- Subscription management (trials, upgrades, billing)
- Webhook handling (payment notifications)
- QR code payments (VietQR, NAPAS)
- Usage-based billing (metering, credits)
- Automated benefit delivery (licenses, GitHub access, Discord roles)
- Customer portals (self-service management)
- Bank transfer automation (Vietnamese banks)
- Product catalogs with pricing

## Platform Selection

**Choose SePay for:**
- Vietnamese market (VND currency)
- Bank transfer automation
- VietQR/NAPAS payments
- Local payment methods
- Direct bank account monitoring

**Choose Polar for:**
- Global SaaS products
- Subscription management
- Usage-based billing
- Automated benefits (GitHub, Discord, licenses)
- Merchant of Record (tax compliance)
- Digital product sales

## Quick Reference

### SePay Integration
- **Overview & Auth**: `references/sepay/overview.md` - Platform capabilities, API/OAuth2 auth, supported banks
- **API Reference**: `references/sepay/api.md` - Endpoints, transactions, bank accounts, virtual accounts
- **Webhooks**: `references/sepay/webhooks.md` - Setup, payload structure, verification, retry logic
- **SDK Usage**: `references/sepay/sdk.md` - Node.js, PHP, Laravel implementations
- **QR Codes**: `references/sepay/qr-codes.md` - VietQR generation, templates, integration
- **Best Practices**: `references/sepay/best-practices.md` - Security, patterns, monitoring

### Polar Integration
- **Overview & Auth**: `references/polar/overview.md` - Platform capabilities, authentication methods, MoR concept
- **Products & Pricing**: `references/polar/products.md` - Product types, pricing models, usage-based billing
- **Checkouts**: `references/polar/checkouts.md` - Checkout flows, embedded checkout, links
- **Subscriptions**: `references/polar/subscriptions.md` - Lifecycle, upgrades, downgrades, trials
- **Webhooks**: `references/polar/webhooks.md` - Event types, signature verification, monitoring
- **Benefits**: `references/polar/benefits.md` - Automated delivery (GitHub, Discord, licenses, files)
- **SDK Usage**: `references/polar/sdk.md` - TypeScript, Python, PHP, Go, framework adapters
- **Best Practices**: `references/polar/best-practices.md` - Security, patterns, monitoring

### Integration Scripts
- **SePay Webhook Verification**: `scripts/sepay-webhook-verify.js` - Verify SePay webhook authenticity
- **Polar Webhook Verification**: `scripts/polar-webhook-verify.js` - Verify Polar webhook signatures
- **Checkout Helper**: `scripts/checkout-helper.js` - Generate checkout sessions for both platforms

## Implementation Workflow

### SePay Implementation
1. Load `references/sepay/overview.md` for auth setup
2. Load `references/sepay/api.md` or `references/sepay/sdk.md` for integration
3. Load `references/sepay/webhooks.md` for payment notifications
4. Use `scripts/sepay-webhook-verify.js` for webhook verification
5. Load `references/sepay/best-practices.md` for production readiness

### Polar Implementation
1. Load `references/polar/overview.md` for auth and concepts
2. Load `references/polar/products.md` for product setup
3. Load `references/polar/checkouts.md` for payment flows
4. Load `references/polar/webhooks.md` for event handling
5. Use `scripts/polar-webhook-verify.js` for webhook verification
6. Load `references/polar/benefits.md` if automating delivery
7. Load `references/polar/best-practices.md` for production readiness

## Key Capabilities

**SePay:**
- Payment gateway (QR, bank transfer, cards)
- Bank account monitoring with webhooks
- Order-based virtual accounts
- VietQR generation API
- 44+ Vietnamese banks supported
- Rate limit: 2 calls/second

**Polar:**
- Merchant of Record (global tax compliance)
- Subscription lifecycle management
- Usage-based billing (events, meters)
- Automated benefits (GitHub, Discord, licenses)
- Customer portal (self-service)
- Multi-language SDKs
- Rate limit: 300 req/min

## Instructions

When implementing payment integration:

1. **Identify platform** based on requirements (Vietnamese vs global, payment types)
2. **Load relevant references** progressively as needed
3. **Implement authentication** using platform-specific methods
4. **Set up products/pricing** according to business model
5. **Implement checkout flow** (hosted, embedded, or API-driven)
6. **Configure webhooks** with proper verification
7. **Handle payment events** (success, failure, refund)
8. **Test thoroughly** in sandbox before production
9. **Monitor and optimize** using platform analytics

Load only the references needed for current implementation step to maintain context efficiency.

Overview

This skill integrates payments with SePay (Vietnamese bank transfers, VietQR) and Polar (global SaaS subscriptions and billing). It provides authentication, checkout flows, webhook handling, QR code generation, and subscription/usage billing patterns to power checkout and post-purchase automation. Use it to implement secure, tested payment flows for both local Vietnam and global SaaS markets.

How this skill works

The skill exposes integration recipes and code samples for each platform: auth setup, API/SDK usage, product and pricing configuration, checkout session creation, and webhook verification. It guides you through SePay-specific features (VietQR, virtual accounts, bank monitoring) and Polar capabilities (subscriptions, usage meters, Merchant of Record, automated benefits), plus verification scripts and recommended workflows for testing and production.

When to use it

Building checkout flows for Vietnamese customers using VND, VietQR, or bank transfers
Launching global SaaS subscriptions with trials, upgrades, and billing via Polar
Implementing webhook handlers for payment notifications and signature verification
Automating delivery of benefits (licenses, GitHub/Discord roles) after payment
Implementing usage-based billing, metering events, or customer portals for self-service management

Best practices

Select the platform by market: SePay for Vietnam-specific payment methods, Polar for global subscriptions and MoR
Use SDKs and provided verification scripts to validate webhooks and avoid fraudulent events
Model products and pricing to match business logic: recurring plans, usage meters, or one-time purchases
Test end-to-end in sandbox environments and rehearse failure and retry scenarios
Monitor rate limits and implement exponential backoff; instrument analytics for payment success and churn

Example use cases

Checkout for a Vietnamese e-commerce site accepting VietQR and bank transfers with SePay webhook reconciliation
SaaS subscription management with Polar: free trial, upgrade path, usage billing, and Merchant of Record handling
Automated post-payment entitlement: issue licenses, add GitHub/Discord roles, or deliver files after confirmed payment
Customer portal where users view invoices, manage subscriptions, and update payment methods
Hybrid deployment: SePay for local payments and Polar for international customers, sharing order state and entitlements

FAQ

Which platform should I pick for Vietnamese customers?

Choose SePay for VND, bank transfers, VietQR, and direct bank monitoring; use Polar only if you need global subscription features in addition to local payments.

How do I secure webhook handling?

Verify signatures with the provided verification scripts, validate payloads, implement idempotency, and respond with proper status codes and retry handling.