renolation/english
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
english/.opencode/skills/payment-integration/README.md
renolation 10d660cbcb init
2026-04-12 01:06:31 +07:00

7.3 KiB
Raw Permalink Blame History

Payment Integration Skill

Comprehensive payment integration skill for SePay (Vietnamese payment gateway), Polar (global SaaS monetization platform), and Stripe (global payment infrastructure).

Features

SePay Integration

  • Vietnamese payment gateway with VietQR, NAPAS, bank transfers, and cards
  • 44+ supported banks
  • Webhook verification with API Key/OAuth2 authentication
  • QR code generation API
  • Order-based virtual accounts
  • SDK support for Node.js, PHP, and Laravel

Polar Integration

  • Global SaaS monetization platform
  • Merchant of Record (handles global tax compliance)
  • Subscription management with trials, upgrades, downgrades
  • Usage-based billing with events and meters
  • Automated benefit delivery (GitHub repos, Discord roles, license keys, files)
  • Customer self-service portal
  • Multi-language SDKs (TypeScript, Python, PHP, Go)
  • Framework adapters (Next.js, Laravel, Remix, etc.)

Stripe Integration

  • Global payment infrastructure
  • CheckoutSessions, PaymentIntents, SetupIntents APIs
  • Billing and subscriptions at scale
  • Connect for marketplaces and platforms
  • Payment Element for custom checkout experiences
  • Multi-language SDKs (Node.js, Python, Ruby, PHP, Java, Go, .NET)
  • Best practices for integration design and API version upgrades

Structure

payment-integration/
├── SKILL.md                      # Main skill definition
├── README.md                     # This file
├── references/                   # Progressive disclosure documentation
│   ├── sepay/                   # SePay integration guides
│   │   ├── overview.md          # Auth, capabilities, environments
│   │   ├── api.md               # API endpoints and operations
│   │   ├── webhooks.md          # Webhook setup and handling
│   │   ├── sdk.md               # SDK usage (Node.js, PHP, Laravel)
│   │   ├── qr-codes.md          # VietQR generation
│   │   └── best-practices.md    # Security, patterns, monitoring
│   ├── polar/                   # Polar integration guides
│   │   ├── overview.md          # Auth, MoR concept, environments
│   │   ├── products.md          # Products, pricing, usage-based billing
│   │   ├── checkouts.md         # Checkout flows and embedded checkout
│   │   ├── subscriptions.md     # Lifecycle, upgrades, trials
│   │   ├── webhooks.md          # Event handling and verification
│   │   ├── benefits.md          # Automated benefit delivery
│   │   ├── sdk.md               # Multi-language SDK usage
│   │   └── best-practices.md    # Security, patterns, monitoring
│   └── stripe/                  # Stripe integration guides
│       ├── stripe-best-practices.md  # Integration design, API selection
│       └── stripe-upgrade.md         # API versions, SDK upgrades
└── scripts/                      # Integration helper scripts
    ├── sepay-webhook-verify.js   # SePay webhook verification
    ├── polar-webhook-verify.js   # Polar webhook verification
    ├── checkout-helper.js        # Checkout session generation
    ├── test-scripts.js           # Test suite for all scripts
    ├── package.json              # Node.js package configuration
    └── .env.example              # Environment variable template

Usage

Activate the Skill

Claude Code will automatically activate this skill when you mention payment integration, subscriptions, webhooks, or platform-specific terms (SePay, Polar).

Manual Activation

In conversations, simply reference the platforms:

  • "Implement SePay payment integration"
  • "Set up Polar subscriptions with usage-based billing"
  • "Create webhook handler for payment notifications"

Using Scripts

SePay Webhook Verification:

cd $HOME/.opencode/skills/payment-integration/scripts
node sepay-webhook-verify.js '{"id":12345,"gateway":"Vietcombank",...}'

Polar Webhook Verification:

node polar-webhook-verify.js '{"type":"order.paid","data":{...}}' base64secret

Checkout Helper:

# SePay
node checkout-helper.js sepay '{"orderInvoiceNumber":"ORD001","orderAmount":100000,...}'

# Polar
node checkout-helper.js polar '{"productPriceId":"price_xxx","successUrl":"https://..."}'

Run Tests:

npm test

Environment Variables

Copy .env.example to .env and configure:

# SePay
SEPAY_MERCHANT_ID=SP-TEST-XXXXXXX
SEPAY_SECRET_KEY=spsk_test_xxxxxxxxxxxxx
SEPAY_ENV=sandbox
SEPAY_WEBHOOK_API_KEY=your_key

# Polar
POLAR_ACCESS_TOKEN=polar_xxxxxxxxxxxxxxxx
POLAR_SERVER=sandbox
POLAR_WEBHOOK_SECRET=base64_secret

Progressive Disclosure

The skill uses progressive disclosure to minimize context usage:

  1. SKILL.md - Overview and quick reference (~99 lines)
  2. references/ - Detailed guides loaded as needed (<100 lines each)
  3. scripts/ - Executable helpers with embedded examples

Load only the references you need for your current task.

Platform Selection Guide

Choose SePay for:

  • Vietnamese market targeting
  • Bank transfer automation
  • Local payment methods
  • QR code payments (VietQR/NAPAS)
  • Direct bank monitoring

Choose Polar for:

  • Global market
  • SaaS/subscription business
  • Usage-based billing
  • Automated benefit delivery
  • Tax compliance (Merchant of Record)
  • Customer self-service

Choose Stripe for:

  • Global payment infrastructure
  • Enterprise-grade payment processing
  • Connect platforms (marketplaces)
  • Billing/subscriptions at scale
  • Custom checkout experiences (Payment Element)
  • Maximum payment method coverage

Examples

SePay Payment Flow

  1. Load references/sepay/overview.md for authentication
  2. Load references/sepay/sdk.md for integration
  3. Use checkout-helper.js to generate payment form
  4. Load references/sepay/webhooks.md for notifications
  5. Use sepay-webhook-verify.js to verify authenticity

Polar Subscription Flow

  1. Load references/polar/overview.md for setup
  2. Load references/polar/products.md for pricing
  3. Load references/polar/checkouts.md for payment
  4. Load references/polar/subscriptions.md for lifecycle
  5. Load references/polar/webhooks.md for events
  6. Load references/polar/benefits.md for automation

Stripe Integration Flow

  1. Load references/stripe/stripe-best-practices.md for integration design
  2. Choose: Checkout (hosted/embedded) or Payment Element
  3. Use CheckoutSessions API for most use cases
  4. Load references/stripe/stripe-upgrade.md when upgrading API versions

Testing

All scripts include comprehensive test coverage:

  • SePay webhook verification (with/without authentication)
  • Polar webhook signature validation
  • Checkout configuration generation
  • Error handling and edge cases

Run npm test in the scripts directory to verify functionality.

Support

SePay

Polar

Stripe

License

MIT

Version

1.1.0