218 lines
7.3 KiB
Markdown
218 lines
7.3 KiB
Markdown
# 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:**
|
|
```bash
|
|
cd $HOME/.opencode/skills/payment-integration/scripts
|
|
node sepay-webhook-verify.js '{"id":12345,"gateway":"Vietcombank",...}'
|
|
```
|
|
|
|
**Polar Webhook Verification:**
|
|
```bash
|
|
node polar-webhook-verify.js '{"type":"order.paid","data":{...}}' base64secret
|
|
```
|
|
|
|
**Checkout Helper:**
|
|
```bash
|
|
# SePay
|
|
node checkout-helper.js sepay '{"orderInvoiceNumber":"ORD001","orderAmount":100000,...}'
|
|
|
|
# Polar
|
|
node checkout-helper.js polar '{"productPriceId":"price_xxx","successUrl":"https://..."}'
|
|
```
|
|
|
|
**Run Tests:**
|
|
```bash
|
|
npm test
|
|
```
|
|
|
|
## Environment Variables
|
|
|
|
Copy `.env.example` to `.env` and configure:
|
|
|
|
```env
|
|
# 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
|
|
- Docs: https://developer.sepay.vn/en
|
|
- Email: info@sepay.vn
|
|
- Hotline: 02873059589
|
|
|
|
### Polar
|
|
- Docs: https://polar.sh/docs
|
|
- API Reference: https://polar.sh/docs/api-reference
|
|
- GitHub: https://github.com/polarsource/polar
|
|
|
|
### Stripe
|
|
- Docs: https://docs.stripe.com
|
|
- API Reference: https://docs.stripe.com/api
|
|
- Changelog: https://docs.stripe.com/changelog
|
|
- Go Live Checklist: https://docs.stripe.com/get-started/checklist/go-live
|
|
|
|
## License
|
|
|
|
MIT
|
|
|
|
## Version
|
|
|
|
1.1.0
|