Payment Integration

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.

Payment Integration Skill

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

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.)

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
└── 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 .claude/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

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

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

License

MIT

Version

1.0.0

Polar Benefits

Automated benefit delivery system for digital products.

Philosophy

Configure once, automatic delivery. Polar handles granting and revoking based on subscription state.

Benefit Types

1. License Keys

Auto-generate unique keys with customizable branding.

Create:

const benefit = await polar.benefits.create({
  type: "license_keys",
  organization_id: "org_xxx",
  description: "Software License",
  properties: {
    prefix: "MYAPP",
    expires: false,
    activations: 1,
    limit_usage: false
  }
});

Validation API (unauthenticated):

const validation = await polar.licenses.validate({
  key: "MYAPP-XXXX-XXXX-XXXX",
  organization_id: "org_xxx"
});

if (validation.valid) {
  // Grant access
}

Activation/Deactivation:

await polar.licenses.activate(licenseKey, {
  label: "User's MacBook Pro"
});

await polar.licenses.deactivate(activationId);

Auto-revoke: On subscription cancellation or refund

2. GitHub Repository Access

Auto-invite to private repos with permission management.

Create:

const benefit = await polar.benefits.create({
  type: "github_repository",
  organization_id: "org_xxx",
  description: "Access to private repo",
  properties: {
    repository_owner: "myorg",
    repository_name: "private-repo",
    permission: "pull" // or "push", "admin"
  }
});

Multiple Repos:

{
  properties: {
    repositories: [
      { owner: "myorg", name: "repo1", permission: "pull" },
      { owner: "myorg", name: "repo2", permission: "push" }
    ]
  }
}

Behavior:

• Auto-invite on subscription activation
• Permission managed by Polar
• Auto-revoke on cancellation

3. Discord Access

Server invites and role assignment.

Create:

const benefit = await polar.benefits.create({
  type: "discord",
  organization_id: "org_xxx",
  description: "Premium Discord role",
  properties: {
    guild_id: "123456789",
    role_id: "987654321"
  }
});

Multiple Roles:

{
  properties: {
    guild_id: "123456789",
    roles: [
      { role_id: "role1", name: "Premium" },
      { role_id: "role2", name: "Supporter" }
    ]
  }
}

Requirements:

• Polar Discord app must be added to server
• Configure in Polar dashboard

Behavior:

• Auto-invite to server
• Assign roles automatically
• Remove roles on cancellation

4. Downloadable Files

Secure file delivery up to 10GB each.

Create:

const benefit = await polar.benefits.create({
  type: "downloadable",
  organization_id: "org_xxx",
  description: "Premium templates",
  properties: {
    files: [
      { name: "template1.zip", size: 5000000 },
      { name: "template2.psd", size: 10000000 }
    ]
  }
});

Upload Files:

• Via Polar dashboard
• Secure storage
• Access control

Customer Access:

• Download links in customer portal
• Secure, time-limited URLs
• Multiple files supported

5. Meter Credits

Pre-purchased usage for usage-based billing.

Create:

const benefit = await polar.benefits.create({
  type: "custom",
  organization_id: "org_xxx",
  description: "10,000 API credits",
  properties: {
    meter_id: "meter_xxx",
    credits: 10000
  }
});

Automatic Application:

• Credits added on subscription start
• Balance tracked via API
• Depletes with usage

Balance Check:

const balance = await polar.meters.getBalance({
  customer_id: "cust_xxx",
  meter_id: "meter_xxx"
});

6. Custom Benefits

Flexible placeholder for manual fulfillment.

Create:

const benefit = await polar.benefits.create({
  type: "custom",
  organization_id: "org_xxx",
  description: "Priority support via email",
  properties: {
    note: "Email support@example.com with your order ID for priority support"
  }
});

Use Cases:

• Cal.com booking links
• Email support access
• Community forum access
• Manual onboarding

Benefit Grants

Link between customer and benefit.

States

• created - Grant created
• active - Benefit delivered
• revoked - Access removed

Webhooks

• benefit_grant.created - Grant created
• benefit_grant.updated - Status changed
• benefit_grant.revoked - Access revoked

Auto-revoke Triggers

• Subscription canceled
• Subscription revoked
• Refund processed
• Product changed (if benefit not on new product)

Querying Grants

const grants = await polar.benefitGrants.list({
  customer_id: "cust_xxx",
  benefit_id: "benefit_xxx",
  is_granted: true
});

Attaching Benefits to Products

Via API

await polar.products.updateBenefits(productId, {
  benefits: [benefitId1, benefitId2, benefitId3]
});

Via Dashboard

1. Navigate to product 2. Benefits tab 3. Select benefits to attach 4. Save

Order

• Benefits granted in order attached
• Customers see in that order
• Reorder via dashboard or API

Customer Experience

Viewing Benefits

• Customer portal shows all active benefits
• Clear instructions for each type
• Download links for files
• License keys displayed

Accessing Benefits

// Generate customer portal link
const session = await polar.customerSessions.create({
  external_customer_id: userId
});

// Customer sees:
// - Active subscriptions
// - Granted benefits
// - Download links
// - License keys
// - Instructions

Implementation Patterns

License Key Validation

// In your application
async function validateLicense(key) {
  try {
    const result = await polar.licenses.validate({
      key: key,
      organization_id: process.env.POLAR_ORG_ID
    });

    if (!result.valid) {
      return { valid: false, reason: 'Invalid license' };
    }

    if (result.limit_usage && result.usage >= result.limit_usage) {
      return { valid: false, reason: 'Usage limit exceeded' };
    }

    return { valid: true, customer: result.customer };
  } catch (error) {
    console.error('License validation failed:', error);
    return { valid: false, reason: 'Validation error' };
  }
}

GitHub Access Check

// Listen to benefit grant webhook
app.post('/webhook/polar', async (req, res) => {
  const event = validateEvent(req.body, req.headers, secret);

  if (event.type === 'benefit_grant.created') {
    const grant = event.data;

    if (grant.benefit.type === 'github_repository') {
      // Update user's GitHub access in your system
      await updateGitHubAccess(grant.customer.external_id, true);
    }
  }

  res.json({ received: true });
});

Discord Role Sync

// Monitor benefit grants
if (event.type === 'benefit_grant.created') {
  const grant = event.data;

  if (grant.benefit.type === 'discord') {
    // Notify user to connect Discord
    await sendDiscordInvite(grant.customer.email);
  }
}

if (event.type === 'benefit_grant.revoked') {
  const grant = event.data;

  if (grant.benefit.type === 'discord') {
    // Roles removed automatically by Polar
    await notifyRoleRemoval(grant.customer.external_id);
  }
}

Best Practices

1. Benefit Selection:

• Choose appropriate benefit types
• Consider automation capabilities
• Plan for revocation scenarios

2. License Keys:

• Set appropriate activation limits
• Monitor usage patterns
• Provide clear validation errors
• Allow customers to manage activations

3. GitHub Access:

• Set minimum required permissions
• Use separate repos for different tiers
• Monitor repository access
• Communicate access removal

4. Discord Roles:

• Clear role hierarchy
• Meaningful role names
• Separate roles per product tier
• Welcome messages for new members

5. Files:

• Organize files clearly
• Provide README/instructions
• Keep files updated
• Version control important files

6. Credits:

• Clear credit value communication
• Usage tracking and display
• Alerts near depletion
• Easy credit top-up

7. Custom Benefits:

• Clear, actionable instructions
• Provide contact information
• Set expectations for timing
• Track manual fulfillment

8. Customer Communication:

• Welcome email with benefit access info
• Instructions for each benefit type
• Support contact for issues
• Revocation warnings before cancellation

Polar Best Practices

Security, patterns, and monitoring for production Polar integrations.

Security

Credential Management

// ✓ Good: Environment variables
const polar = new Polar({
  accessToken: process.env.POLAR_ACCESS_TOKEN
});

// ✗ Bad: Hardcoded
const polar = new Polar({
  accessToken: 'polar_live_abc123'
});

Webhook Security

// Always verify signatures
app.post('/webhook/polar', async (req, res) => {
  try {
    const event = validateEvent(req.body, req.headers, secret);
    // Process verified event
  } catch (error) {
    return res.status(400).json({ error: 'Invalid signature' });
  }
});

Never Expose Tokens Client-Side

// ✓ Good: Server-side API route
export async function POST(req: Request) {
  const polar = new Polar({ accessToken: process.env.POLAR_ACCESS_TOKEN });
  const checkout = await polar.checkouts.create(...);
  return Response.json({ url: checkout.url });
}

// ✗ Bad: Client-side
const polar = new Polar({ accessToken: 'visible_in_browser' });

Implementation Patterns

Complete Payment Flow

class PaymentService {
  async createCheckout(userId, priceId) {
    // 1. Create checkout session
    const session = await polar.checkouts.create({
      product_price_id: priceId,
      external_customer_id: userId,
      success_url: `${baseUrl}/success?checkout_id={CHECKOUT_ID}`,
      metadata: {
        user_id: userId,
        source: 'web'
      }
    });

    // 2. Log checkout creation
    await db.checkouts.insert({
      checkout_id: session.id,
      user_id: userId,
      status: 'pending'
    });

    return session.url;
  }

  async handleWebhook(event) {
    switch (event.type) {
      case 'order.paid':
        await this.fulfillOrder(event.data);
        break;

      case 'subscription.active':
        await this.grantAccess(event.data.customer.external_id);
        break;

      case 'subscription.revoked':
        await this.revokeAccess(event.data.customer.external_id);
        break;
    }
  }

  async fulfillOrder(order) {
    // Verify not already fulfilled
    const existing = await db.orders.findOne({ polar_id: order.id });
    if (existing) return;

    // Save order
    await db.orders.insert({
      polar_id: order.id,
      user_id: order.customer.external_id,
      amount: order.amount,
      status: 'paid'
    });

    // Grant access
    await this.grantAccess(order.customer.external_id);

    // Send confirmation
    await this.sendConfirmation(order);
  }
}

Customer Portal Integration

app.get('/portal', async (req, res) => {
  const session = await polar.customerSessions.create({
    external_customer_id: req.user.id
  });

  res.redirect(session.url);
});

Usage-Based Tracking

class UsageTracker {
  async trackUsage(userId, eventName, properties) {
    // Track in your system
    await db.usage.insert({
      user_id: userId,
      event_name: eventName,
      properties: properties,
      timestamp: new Date()
    });

    // Send to Polar for billing
    await polar.events.create({
      external_customer_id: userId,
      event_name: eventName,
      properties: properties
    });
  }

  async getBalance(userId, meterId) {
    const balance = await polar.meters.getBalance({
      external_customer_id: userId,
      meter_id: meterId
    });

    return balance.amount;
  }

  async showUsage(userId) {
    // Show customer their usage
    const usage = await db.usage.aggregate({
      user_id: userId,
      date: { $gte: startOfMonth() }
    });

    const balance = await this.getBalance(userId, meterId);

    return { usage, remaining: balance };
  }
}

Data Management

External ID Strategy

// ✓ Good: Set external_id consistently
await polar.checkouts.create({
  external_customer_id: user.id, // Your user ID
  // ...
});

// Query by external_id
const customer = await polar.customers.get({
  external_id: user.id
});

// ✗ Bad: Storing Polar customer IDs
// Don't store polar_customer_id in your database
// Use external_id for all lookups

Metadata Best Practices

// Use metadata for:
{
  metadata: {
    user_id: '123',           // Internal ID
    source: 'web',            // Traffic source
    campaign: 'summer_sale',  // Marketing campaign
    referrer: 'partner_123'   // Referral tracking
  }
}

// Don't store sensitive data in metadata
// ✗ Bad: PII, passwords, payment details

Database Sync

async function syncSubscription(subscription) {
  await db.subscriptions.upsert({
    where: { polar_id: subscription.id },
    update: {
      status: subscription.status,
      current_period_end: subscription.current_period_end,
      cancel_at_period_end: subscription.cancel_at_period_end
    },
    create: {
      polar_id: subscription.id,
      user_id: subscription.customer.external_id,
      status: subscription.status,
      // ... other fields
    }
  });
}

Performance Optimization

Caching

// Cache products list
const productCache = new Map();

async function getProducts(orgId) {
  if (!productCache.has(orgId)) {
    const products = await polar.products.list({
      organization_id: orgId,
      is_archived: false
    });
    productCache.set(orgId, products);
    setTimeout(() => productCache.delete(orgId), 300000); // 5 min
  }

  return productCache.get(orgId);
}

Batch Operations

// Batch event ingestion
const eventQueue = [];

async function trackEvent(userId, event) {
  eventQueue.push({ external_customer_id: userId, ...event });

  if (eventQueue.length >= 100) {
    await flushEvents();
  }
}

async function flushEvents() {
  const batch = eventQueue.splice(0, 100);
  await Promise.all(
    batch.map(event => polar.events.create(event))
  );
}

Rate Limit Handling

async function callWithRetry(fn, maxRetries = 3) {
  let attempt = 0;

  while (attempt < maxRetries) {
    try {
      return await fn();
    } catch (error) {
      if (error.statusCode === 429) {
        const retryAfter = error.headers?.['retry-after'] || 1;
        await sleep(retryAfter * 1000);
        attempt++;
      } else {
        throw error;
      }
    }
  }
}

Monitoring & Logging

Essential Metrics

const metrics = {
  checkouts_created: counter('polar_checkouts_created_total'),
  orders_completed: counter('polar_orders_completed_total'),
  subscriptions_active: gauge('polar_subscriptions_active'),
  revenue: counter('polar_revenue_total'),
  webhook_processing_time: histogram('polar_webhook_duration_seconds')
};

// Track metrics
metrics.checkouts_created.inc({ product: productId });
metrics.orders_completed.inc({ amount: order.amount });
metrics.revenue.inc(order.amount);

Structured Logging

logger.info('Checkout created', {
  checkout_id: session.id,
  user_id: userId,
  product_id: priceId,
  amount: amount
});

logger.info('Order paid', {
  order_id: order.id,
  user_id: order.customer.external_id,
  amount: order.amount,
  billing_reason: order.billing_reason
});

logger.error('Webhook processing failed', {
  event_type: event.type,
  error: error.message,
  stack: error.stack
});

Alerting

// Alert on failed webhooks
if (webhookFailures > threshold) {
  alert.send({
    severity: 'high',
    message: 'Polar webhook failures exceed threshold',
    details: { failures: webhookFailures, threshold }
  });
}

// Alert on subscription churn
if (churnRate > 0.05) { // 5%
  alert.send({
    severity: 'medium',
    message: 'Subscription churn rate elevated',
    details: { churnRate, period: 'month' }
  });
}

Testing Strategy

Sandbox Testing

// Use sandbox for development
const polar = new Polar({
  accessToken: process.env.POLAR_SANDBOX_TOKEN,
  server: "sandbox"
});

// Test scenarios:
// 1. Successful purchase
// 2. Failed payment
// 3. Subscription creation
// 4. Subscription upgrade/downgrade
// 5. Subscription cancellation
// 6. Refund processing
// 7. Webhook delivery
// 8. Benefit granting/revoking

Test Cards

const testCards = {
  success: '4242 4242 4242 4242',
  decline: '4000 0000 0000 0002',
  authRequired: '4000 0025 0000 3155'
};

Integration Tests

describe('Polar Integration', () => {
  it('creates checkout and processes payment', async () => {
    const session = await polar.checkouts.create({...});
    expect(session.url).toBeDefined();

    // Simulate successful payment (webhook)
    await simulateWebhook('order.paid', { ... });

    // Verify order fulfilled
    const order = await db.orders.findOne({ polar_id: orderId });
    expect(order.status).toBe('paid');
  });
});

Production Checklist

• [ ] Environment variables configured
• [ ] Sandbox testing completed
• [ ] Production tokens obtained
• [ ] Webhook endpoint configured and tested
• [ ] Webhook signature verification implemented
• [ ] Error monitoring enabled
• [ ] Logging infrastructure ready
• [ ] Metrics collection configured
• [ ] Alerting rules set up
• [ ] Database indexes created
• [ ] Rate limiting handled
• [ ] Customer portal linked
• [ ] Email notifications configured
• [ ] Refund policy documented
• [ ] Support process established
• [ ] Team trained on platform
• [ ] Documentation updated
• [ ] Compliance requirements met (if applicable)
• [ ] Acceptable use policy reviewed

Common Pitfalls

1. Not Verifying Webhooks

// ✗ Bad: Trusting webhook data without verification
app.post('/webhook/polar', async (req, res) => {
  await handleEvent(req.body); // Vulnerable!
});

// ✓ Good: Always verify
app.post('/webhook/polar', async (req, res) => {
  const event = validateEvent(req.body, req.headers, secret);
  await handleEvent(event);
});

2. Trusting Only Success Redirects

// ✗ Bad: Fulfilling based on redirect
app.get('/success', async (req, res) => {
  await fulfillOrder(req.query.checkout_id); // Insecure!
});

// ✓ Good: Verify via API or wait for webhook
app.get('/success', async (req, res) => {
  const checkout = await polar.checkouts.get(req.query.checkout_id);
  if (checkout.status === 'confirmed') {
    // Safe to show success page
  }
  // Still wait for webhook for fulfillment
});

3. Not Handling Duplicate Webhooks

// ✓ Good: Idempotent webhook handling
async function handleOrderPaid(order) {
  const existing = await db.orders.findOne({ polar_id: order.id });
  if (existing) {
    console.log('Order already processed');
    return;
  }

  await fulfillOrder(order);
}

4. Hardcoding External IDs

// ✗ Bad: Using Polar customer IDs
const customerId = 'cust_abc123';

// ✓ Good: Using your user IDs
const userId = user.id;
await polar.checkouts.create({
  external_customer_id: userId
});

5. Not Handling Failed Payments

// Listen to subscription.past_due
if (event.type === 'subscription.past_due') {
  // Notify customer
  // Provide grace period
  // Update UI to show payment issue
}

Polar Checkouts

Checkout flows, embedded checkout, and session management.

Checkout Approaches

1. Checkout Links

• Pre-configured shareable links
• Created via dashboard or API
• For marketing campaigns
• Can pre-apply discounts

Create via API:

const link = await polar.checkoutLinks.create({
  product_price_id: "price_xxx",
  success_url: "https://example.com/success"
});
// Returns: link.url

2. Checkout Sessions (API)

• Programmatically created
• Server-side API call
• Dynamic workflows
• Custom logic

Create Session:

const session = await polar.checkouts.create({
  product_price_id: "price_xxx",
  success_url: "https://example.com/success?checkout_id={CHECKOUT_ID}",
  customer_email: "user@example.com",
  external_customer_id: "user_123",
  metadata: {
    user_id: "123",
    source: "web"
  }
});

// Redirect to: session.url

Response:

{
  "id": "checkout_xxx",
  "url": "https://polar.sh/checkout/...",
  "client_secret": "cs_xxx",
  "status": "open",
  "expires_at": "2025-01-15T10:00:00Z"
}

3. Embedded Checkout

• Inline checkout within your site
• Seamless purchase experience
• Theme customization

Implementation:

<script src="https://polar.sh/embed.js"></script>

<div id="polar-checkout"></div>

<script>
  const checkout = await fetch('/api/create-checkout', {
    method: 'POST',
    body: JSON.stringify({ productPriceId: 'price_xxx' })
  }).then(r => r.json());

  Polar('checkout', {
    checkoutId: checkout.id,
    clientSecret: checkout.client_secret,
    onSuccess: () => {
      window.location.href = '/success';
    },
    theme: 'dark' // or 'light'
  });
</script>

Server-side (create session):

app.post('/api/create-checkout', async (req, res) => {
  const session = await polar.checkouts.create({
    product_price_id: req.body.productPriceId,
    embed_origin: "https://example.com",
    external_customer_id: req.user.id
  });

  res.json({
    id: session.id,
    client_secret: session.client_secret
  });
});

Configuration Parameters

Required

• product_price_id - Product to checkout (or products array for multiple)
• success_url - Post-payment redirect (absolute URL)

Optional

• external_customer_id - Your user ID mapping
• embed_origin - For embedded checkouts
• customer_email - Pre-fill email
• customer_name - Pre-fill name
• discount_id - Pre-apply discount code
• allow_discount_codes - Allow customer to enter codes (default: true)
• metadata - Custom data (key-value)
• custom_field_data - Pre-fill custom fields
• customer_billing_address - Pre-fill billing address

Success URL Placeholder

{
  success_url: "https://example.com/success?checkout_id={CHECKOUT_ID}"
}
// Polar replaces {CHECKOUT_ID} with actual checkout ID

Multi-Product Checkout

const session = await polar.checkouts.create({
  products: [
    { product_price_id: "price_1", quantity: 1 },
    { product_price_id: "price_2", quantity: 2 }
  ],
  success_url: "https://example.com/success"
});

Discount Application

Pre-apply Discount

const session = await polar.checkouts.create({
  product_price_id: "price_xxx",
  discount_id: "discount_xxx",
  success_url: "https://example.com/success"
});

Allow Customer Codes

{
  allow_discount_codes: true // default
  // Set to false to disable code entry
}

Checkout States

• open - Ready for payment
• confirmed - Payment successful
• expired - Session expired (typically 24 hours)

Events

Webhook Events:

• checkout.created - Session created
• checkout.updated - Session updated
• order.created - Order created after successful payment
• order.paid - Payment confirmed

Handle Success:

// Listen to order.paid webhook
app.post('/webhook/polar', async (req, res) => {
  const event = validateEvent(req.body, req.headers, secret);

  if (event.type === 'order.paid') {
    const order = event.data;
    await fulfillOrder(order);
  }

  res.json({ received: true });
});

Best Practices

1. Success URL:

• Must be absolute URL: https://example.com/success
• Use {CHECKOUT_ID} placeholder to retrieve checkout details
• Verify payment via webhook, not just success redirect

2. External Customer ID:

• Set on first checkout
• Never change once set
• Use for all customer operations
• Enables customer lookup without storing Polar IDs

3. Pre-filling Data:

• Pre-fill customer info when available
• Reduces friction in checkout
• Improves conversion rates

4. Embedded Checkout:

• Provide seamless experience
• Match your site's theme
• Handle errors gracefully
• Show loading states

5. Metadata:

• Store tracking info (source, campaign, etc.)
• Link to your internal systems
• Use for analytics and reporting

6. Error Handling:

• Handle expired sessions
• Provide clear error messages
• Offer to create new session
• Log failures for debugging

7. Mobile Optimization:

• Test on mobile devices
• Ensure responsive design
• Consider mobile payment methods
• Test embedded checkout on mobile

Framework Examples

Next.js

// app/actions/checkout.ts
'use server'

export async function createCheckout(productPriceId: string) {
  const session = await polar.checkouts.create({
    product_price_id: productPriceId,
    success_url: `${process.env.NEXT_PUBLIC_URL}/success?checkout_id={CHECKOUT_ID}`,
    external_customer_id: await getCurrentUserId()
  });

  return session.url;
}

// app/product/page.tsx
export default function ProductPage() {
  async function handleCheckout() {
    const url = await createCheckout(productPriceId);
    window.location.href = url;
  }

  return <button onClick={handleCheckout}>Buy Now</button>;
}

Laravel

Route::post('/checkout', function (Request $request) {
    $polar = new Polar(config('polar.access_token'));

    $session = $polar->checkouts->create([
        'product_price_id' => $request->input('product_price_id'),
        'success_url' => route('checkout.success'),
        'external_customer_id' => auth()->id(),
    ]);

    return redirect($session['url']);
});

Polar Overview

Comprehensive payment & billing platform for software monetization with Merchant of Record services.

Core Capabilities

Platform Features:

• Digital product sales (one-time, recurring, usage-based)
• Merchant of Record - handles global tax compliance
• Subscription lifecycle management
• Automated benefit distribution
• Customer self-service portal
• Real-time webhook system
• Analytics dashboard
• Multi-language SDKs

Merchant of Record Benefits:

• Global tax compliance (VAT, GST, sales tax)
• Tax calculations for all jurisdictions
• B2B reverse charge, B2C tax collection
• Invoicing from Polar to customers
• Payout invoicing to merchants
• Transparent fees (20% discount vs other MoRs)

Authentication

Organization Access Tokens (OAT)

For: Server-side API access

Create: 1. Org Settings → Developers 2. Create new access token 3. Copy and store securely

Usage:

Authorization: Bearer polar_xxxxxxxxxxxxxxxx

Security: Never expose client-side (auto-revoked if leaked)

OAuth 2.0

For: Third-party app integration

Authorization URL: https://polar.sh/oauth2/authorize Token URL: https://api.polar.sh/v1/oauth2/token

Flow:

1. Redirect to authorize URL with scopes
2. User approves permissions
3. Receive authorization code
4. Exchange code for access_token + refresh_token
5. Use access_token for API calls

Scopes:

• products:read/write - Product management
• checkouts:read/write - Checkout operations
• orders:read - View orders
• subscriptions:read/write - Subscription management
• benefits:read/write - Benefit configuration
• customers:read/write - Customer management
• discounts:read/write - Discount codes
• refunds:read/write - Refund processing

Customer Sessions

For: Customer-facing portal operations

Create: Server-side API call returns customer access token Usage: Pre-authenticated customer portal links Scope: Restricted to customer-specific operations

Base URLs

Production:

• Dashboard: https://polar.sh
• API: https://api.polar.sh/v1/

Sandbox:

• Dashboard: https://sandbox.polar.sh
• API: https://sandbox-api.polar.sh/v1/

SDK Configuration:

const polar = new Polar({
  accessToken: process.env.POLAR_ACCESS_TOKEN,
  server: "production" // or "sandbox"
});

Rate Limits

Limits:

• 300 requests/minute per org/customer/OAuth2 client
• 3 requests/second for unauthenticated license validation

Response: HTTP 429 with Retry-After header

Handling:

if (response.status === 429) {
  const retryAfter = response.headers.get('Retry-After');
  await sleep(retryAfter * 1000);
  return retry();
}

Key Concepts

External Customer ID

• Map your user IDs to Polar customers
• Set at checkout: external_customer_id
• Query API by external_id
• Immutable once set
• Use for all customer operations

Metadata

• Custom key-value storage
• Available on products, customers, subscriptions, orders
• For reporting and filtering
• Not indexed, use for supplementary data

Billing Reasons

Track order types via billing_reason:

• purchase - One-time product
• subscription_create - New subscription
• subscription_cycle - Renewal invoice
• subscription_update - Plan change

Environments

Sandbox:

• Separate account required
• Separate organization
• Separate access tokens (production tokens don't work)
• Test with Stripe test cards

Test Cards (Stripe):

• Success: 4242 4242 4242 4242
• Decline: 4000 0000 0000 0002
• Auth Required: 4000 0025 0000 3155
• Expiry: Any future date
• CVC: Any 3 digits

SDKs

Official SDKs:

• TypeScript/JavaScript: @polar-sh/sdk
• Python: polar-sdk
• PHP: polar-sh/sdk
• Go: Official SDK

Framework Adapters:

• Next.js: @polar-sh/nextjs (quickstart: npx polar-init)
• Laravel: polar-sh/laravel
• Remix, Astro, Express, TanStack Start
• Elysia, Fastify, Hono, SvelteKit

BetterAuth Integration:

• Package: @polar-sh/better-auth
• Auto-create customers on signup
• External ID mapping
• User-customer sync

Support & Resources

• Docs: https://polar.sh/docs
• API Reference: https://polar.sh/docs/api-reference
• LLMs.txt: https://polar.sh/docs/llms.txt
• GitHub: https://github.com/polarsource/polar
• Discussions: https://github.com/orgs/polarsource/discussions

Next Steps

• For products: Load products.md
• For checkout: Load checkouts.md
• For subscriptions: Load subscriptions.md
• For webhooks: Load webhooks.md
• For benefits: Load benefits.md
• For SDK usage: Load sdk.md

Polar Products & Pricing

Product management, pricing models, and usage-based billing.

Billing Cycles

Options:

• One-time: Charged once, forever access
• Monthly: Charged every month
• Yearly: Charged every year

Important: Cannot change after product creation

Pricing Types

Fixed Price: Set amount Pay What You Want: Customer decides (optional minimum) Free: No charge

Important: Cannot change after product creation

Advanced Pricing Models

Seat-Based Pricing

• Team access with assignable seats
• Works for recurring or one-time
• Tiered pricing structures
• Customer manages seat assignments

Configuration:

const product = await polar.products.create({
  name: "Team Plan",
  prices: [{
    type: "recurring",
    recurring_interval: "month",
    price_amount: 5000, // per seat
    pricing_type: "fixed"
  }],
  is_seat_based: true,
  max_seats: 100
});

Usage-Based Billing

Architecture: Events → Meters → Metered Prices

1. Events: Usage data from your application

await polar.events.create({
  external_customer_id: "user_123",
  event_name: "api_call",
  properties: {
    tokens: 1000,
    model: "gpt-4"
  }
});

2. Meters: Filter & aggregate events

const meter = await polar.meters.create({
  name: "API Tokens",
  slug: "api_tokens",
  event_name: "api_call",
  aggregation: {
    type: "sum",
    property: "tokens"
  }
});

3. Metered Prices: Billing based on usage

const price = await polar.products.createPrice(productId, {
  type: "metered",
  meter_id: meter.id,
  price_per_unit: 10, // 10 cents per 1000 tokens
  billing_interval: "month"
});

Credits System:

• Pre-purchased usage credits
• Credit customer's meter balance
• Use as subscription benefit
• Balance tracking API

Ingestion Strategies:

• LLM Strategy: AI/ML tracking
• S3 Strategy: Bulk import
• Stream Strategy: Real-time
• Delta Time Strategy: Time-based

Product Features

Metadata

const product = await polar.products.create({
  name: "Pro Plan",
  metadata: {
    feature_x: "enabled",
    tier: "pro",
    custom_field: "value"
  }
});

Custom Fields

const product = await polar.products.create({
  name: "Enterprise Plan",
  custom_fields: [
    {
      slug: "company_name",
      label: "Company Name",
      type: "text",
      required: true
    },
    {
      slug: "employees",
      label: "Number of Employees",
      type: "number"
    }
  ]
});

Data collected at checkout, accessible via Orders/Subscriptions API in custom_field_data.

Trials

• Set on recurring products
• Customer not charged during trial
• Benefits granted immediately
• Configure at product or checkout level

const product = await polar.products.create({
  name: "Pro Plan",
  prices: [{
    type: "recurring",
    recurring_interval: "month",
    price_amount: 2000,
    trial_period_days: 14
  }]
});

Product Operations

Create Product

const product = await polar.products.create({
  organization_id: "org_xxx",
  name: "Pro Plan",
  description: "Professional features",
  prices: [{
    type: "recurring",
    recurring_interval: "month",
    price_amount: 2000,
    pricing_type: "fixed"
  }]
});

List Products

const products = await polar.products.list({
  organization_id: "org_xxx",
  is_archived: false
});

Update Product

const product = await polar.products.update(productId, {
  name: "Pro Plan Updated",
  description: "New description"
});

Archive Product

await polar.products.archive(productId);
// Products can be unarchived later
// Cannot be deleted (maintains order history)

Update Benefits

await polar.products.updateBenefits(productId, {
  benefits: [benefitId1, benefitId2]
});

Important Constraints

1. Cannot change after creation:

• Billing cycle (one-time, monthly, yearly)
• Pricing type (fixed, pay-what-you-want, free)

2. Price changes don't affect existing subscribers:

• Current subscribers keep their original price
• New subscribers get new price
• Use separate products for significant changes

3. Products cannot be deleted:

• Archive instead
• Maintains order history integrity
• Archived products not shown to new customers

4. Metadata vs Custom Fields:

• Metadata: For internal use, not shown to customers
• Custom Fields: Collected from customers at checkout

Best Practices

1. Product Strategy:

• Plan billing cycle carefully before creation
• Use separate products for different tiers
• Archive unused products rather than delete

2. Pricing Changes:

• Create new product for major changes
• Grandfather existing customers
• Communicate changes clearly

3. Usage-Based:

• Define clear meter aggregations
• Set appropriate billing intervals
• Monitor usage patterns
• Provide usage dashboards to customers

4. Custom Fields:

• Collect only necessary information
• Validate on frontend before checkout
• Use for personalization and support

5. Trials:

• Set appropriate trial duration
• Communicate trial end clearly
• Notify before trial expires
• Easy cancellation during trial

Polar SDK Usage

Multi-language SDKs and framework adapters.

TypeScript/JavaScript

Installation:

npm install @polar-sh/sdk

Configuration:

import { Polar } from '@polar-sh/sdk';

const polar = new Polar({
  accessToken: process.env.POLAR_ACCESS_TOKEN,
  server: "production" // or "sandbox"
});

Usage:

// Products
const products = await polar.products.list({ organization_id: "org_xxx" });
const product = await polar.products.create({ name: "Pro Plan", ... });

// Checkouts
const checkout = await polar.checkouts.create({
  product_price_id: "price_xxx",
  success_url: "https://example.com/success"
});

// Subscriptions
const subs = await polar.subscriptions.list({ customer_id: "cust_xxx" });
await polar.subscriptions.update(subId, { metadata: { plan: "pro" } });

// Orders
const orders = await polar.orders.list({ organization_id: "org_xxx" });
const order = await polar.orders.get(orderId);

// Customers
const customer = await polar.customers.get({ external_id: "user_123" });

// Events (usage-based)
await polar.events.create({
  external_customer_id: "user_123",
  event_name: "api_call",
  properties: { tokens: 1000 }
});

Pagination:

// Automatic pagination
for await (const product of polar.products.listAutoPaging()) {
  console.log(product.name);
}

// Manual pagination
let page = 1;
while (true) {
  const response = await polar.products.list({ page, limit: 100 });
  if (response.items.length === 0) break;
  // Process items
  page++;
}

Python

Installation:

pip install polar-sdk

Configuration:

from polar_sdk import Polar

polar = Polar(
    access_token=os.environ["POLAR_ACCESS_TOKEN"],
    server="production"  # or "sandbox"
)

Sync Usage:

# Products
products = polar.products.list(organization_id="org_xxx")
product = polar.products.create(name="Pro Plan", ...)

# Checkouts
checkout = polar.checkouts.create(
    product_price_id="price_xxx",
    success_url="https://example.com/success"
)

# Subscriptions
subs = polar.subscriptions.list(customer_id="cust_xxx")
polar.subscriptions.update(sub_id, metadata={"plan": "pro"})

# Orders
orders = polar.orders.list(organization_id="org_xxx")
order = polar.orders.get(order_id)

# Events
polar.events.create(
    external_customer_id="user_123",
    event_name="api_call",
    properties={"tokens": 1000}
)

Async Usage:

import asyncio
from polar_sdk import AsyncPolar

async def main():
    polar = AsyncPolar(access_token=os.environ["POLAR_ACCESS_TOKEN"])

    products = await polar.products.list(organization_id="org_xxx")
    checkout = await polar.checkouts.create(...)

asyncio.run(main())

PHP

Installation:

composer require polar-sh/sdk

Configuration:

use Polar\Polar;

$polar = new Polar(
    accessToken: $_ENV['POLAR_ACCESS_TOKEN'],
    server: 'production' // or 'sandbox'
);

Usage:

// Products
$products = $polar->products->list(['organization_id' => 'org_xxx']);
$product = $polar->products->create(['name' => 'Pro Plan', ...]);

// Checkouts
$checkout = $polar->checkouts->create([
    'product_price_id' => 'price_xxx',
    'success_url' => 'https://example.com/success'
]);

// Subscriptions
$subs = $polar->subscriptions->list(['customer_id' => 'cust_xxx']);
$polar->subscriptions->update($subId, ['metadata' => ['plan' => 'pro']]);

// Orders
$orders = $polar->orders->list(['organization_id' => 'org_xxx']);
$order = $polar->orders->get($orderId);

// Events
$polar->events->create([
    'external_customer_id' => 'user_123',
    'event_name' => 'api_call',
    'properties' => ['tokens' => 1000]
]);

Go

Installation:

go get github.com/polarsource/polar-go

Usage:

import (
    "github.com/polarsource/polar-go"
)

client := polar.NewClient(
    polar.WithAccessToken(os.Getenv("POLAR_ACCESS_TOKEN")),
    polar.WithEnvironment("production"),
)

// Products
products, err := client.Products.List(ctx, &polar.ProductListParams{
    OrganizationID: "org_xxx",
})

// Checkouts
checkout, err := client.Checkouts.Create(ctx, &polar.CheckoutCreateParams{
    ProductPriceID: "price_xxx",
    SuccessURL:     "https://example.com/success",
})

Framework Adapters

Next.js (@polar-sh/nextjs)

Quick Start:

npx polar-init

Configuration:

// lib/polar.ts
import { PolarClient } from '@polar-sh/nextjs';

export const polar = new PolarClient({
  accessToken: process.env.POLAR_ACCESS_TOKEN!,
  webhookSecret: process.env.POLAR_WEBHOOK_SECRET!
});

Checkout Handler:

// app/actions/checkout.ts
'use server'

import { polar } from '@/lib/polar';

export async function createCheckout(priceId: string) {
  const session = await polar.checkouts.create({
    product_price_id: priceId,
    success_url: `${process.env.NEXT_PUBLIC_URL}/success?checkout_id={CHECKOUT_ID}`
  });

  return session.url;
}

Webhook Handler:

// app/api/webhook/polar/route.ts
import { polar } from '@/lib/polar';

export async function POST(req: Request) {
  const event = await polar.webhooks.validate(req);

  switch (event.type) {
    case 'order.paid':
      await handleOrderPaid(event.data);
      break;
    // ... other events
  }

  return Response.json({ received: true });
}

Laravel (polar-sh/laravel)

Installation:

composer require polar-sh/laravel
php artisan vendor:publish --tag=polar-config
php artisan vendor:publish --tag=polar-migrations
php artisan migrate

Configuration:

// config/polar.php
return [
    'access_token' => env('POLAR_ACCESS_TOKEN'),
    'webhook_secret' => env('POLAR_WEBHOOK_SECRET'),
];

Checkout:

use Polar\Facades\Polar;

Route::post('/checkout', function (Request $request) {
    $checkout = Polar::checkouts()->create([
        'product_price_id' => $request->input('price_id'),
        'success_url' => route('checkout.success'),
        'external_customer_id' => auth()->id(),
    ]);

    return redirect($checkout['url']);
});

Webhook:

use Polar\Events\WebhookReceived;

// app/Listeners/PolarWebhookHandler.php
class PolarWebhookHandler
{
    public function handle(WebhookReceived $event)
    {
        match ($event->payload['type']) {
            'order.paid' => $this->handleOrderPaid($event->payload['data']),
            'subscription.revoked' => $this->handleRevoked($event->payload['data']),
            default => null,
        };
    }
}

Express

const express = require('express');
const { Polar } = require('@polar-sh/sdk');
const { validateEvent } = require('@polar-sh/sdk/webhooks');

const app = express();
const polar = new Polar({ accessToken: process.env.POLAR_ACCESS_TOKEN });

app.use(express.json());

app.post('/checkout', async (req, res) => {
  const session = await polar.checkouts.create({
    product_price_id: req.body.priceId,
    success_url: 'https://example.com/success',
    external_customer_id: req.user.id
  });

  res.json({ url: session.url });
});

app.post('/webhook/polar', (req, res) => {
  const event = validateEvent(
    req.body,
    req.headers,
    process.env.POLAR_WEBHOOK_SECRET
  );

  handleEvent(event);
  res.json({ received: true });
});

Remix

import { Polar } from '@polar-sh/sdk';

const polar = new Polar({ accessToken: process.env.POLAR_ACCESS_TOKEN });

export async function action({ request }: ActionFunctionArgs) {
  const formData = await request.formData();
  const priceId = formData.get('priceId');

  const session = await polar.checkouts.create({
    product_price_id: priceId,
    success_url: `${request.url}/success`
  });

  return redirect(session.url);
}

BetterAuth Integration

Installation:

npm install @polar-sh/better-auth

Configuration:

import { betterAuth } from 'better-auth';
import { polarPlugin } from '@polar-sh/better-auth';

export const auth = betterAuth({
  database: db,
  plugins: [
    polarPlugin({
      organizationId: process.env.POLAR_ORG_ID!,
      accessToken: process.env.POLAR_ACCESS_TOKEN!
    })
  ]
});

Features:

• Auto-create Polar customers on signup
• Automatic external_id mapping
• User-customer sync
• Access customer data in auth session

Error Handling

TypeScript:

try {
  const product = await polar.products.get(productId);
} catch (error) {
  if (error.statusCode === 404) {
    console.error('Product not found');
  } else if (error.statusCode === 429) {
    console.error('Rate limit exceeded');
  } else {
    console.error('API error:', error.message);
  }
}

Python:

from polar_sdk.exceptions import PolarException

try:
    product = polar.products.get(product_id)
except PolarException as e:
    if e.status_code == 404:
        print("Product not found")
    elif e.status_code == 429:
        print("Rate limit exceeded")
    else:
        print(f"API error: {e.message}")

Best Practices

1. Environment Variables: Store credentials securely 2. Error Handling: Catch and handle API errors appropriately 3. Rate Limiting: Implement backoff for 429 responses 4. Pagination: Use auto-paging for large datasets 5. Webhooks: Always verify signatures 6. Testing: Use sandbox for development 7. Logging: Log API calls for debugging 8. Retry Logic: Implement for transient failures

Polar Subscriptions

Subscription lifecycle, upgrades, downgrades, and trial management.

Lifecycle States

• created - New subscription, payment pending
• active - Payment successful, benefits granted
• canceled - Scheduled cancellation at period end
• revoked - Billing stopped, benefits revoked immediately
• past_due - Payment failed, in dunning period

API Operations

List Subscriptions

const subscriptions = await polar.subscriptions.list({
  organization_id: "org_xxx",
  product_id: "prod_xxx",
  customer_id: "cust_xxx",
  status: "active"
});

Get Subscription

const subscription = await polar.subscriptions.get(subscriptionId);

Update Subscription

const updated = await polar.subscriptions.update(subscriptionId, {
  product_price_id: "newPriceId",
  discount_id: "discount_xxx",
  metadata: { plan: "pro" }
});

Upgrades & Downgrades

Proration Options

Next Invoice (default):

• Credit/charge applied to upcoming invoice
• Subscription updates immediately
• Customer billed at next cycle

Invoice Immediately:

• Credit/charge processed right away
• Subscription updates immediately
• New invoice generated

await polar.subscriptions.update(subscriptionId, {
  product_price_id: "higher_tier_price",
  proration: "invoice_immediately" // or "next_invoice"
});

Customer-Initiated Changes

Enable in Product Settings:

• Toggle "Allow price change"
• Customer can upgrade/downgrade via portal
• Admin-only changes if disabled

Implementation:

// Check if changes allowed
const product = await polar.products.get(productId);
if (product.allow_price_change) {
  // Customer can change via portal
}

Trials

Configuration

Product-level:

const product = await polar.products.create({
  name: "Pro Plan",
  prices: [{
    trial_period_days: 14
  }]
});

Checkout-level:

const session = await polar.checkouts.create({
  product_price_id: "price_xxx",
  trial_period_days: 7 // Overrides product setting
});

Trial Behavior

• Customer not charged during trial
• Benefits granted immediately
• Can cancel anytime during trial
• Charged at trial end if not canceled

Trial Events

// Listen to webhooks
subscription.created // Trial starts
subscription.active // Trial ends, first charge
subscription.canceled // Trial canceled

Cancellations

Cancel at Period End

await polar.subscriptions.update(subscriptionId, {
  cancel_at_period_end: true
});
// Subscription remains active
// Benefits continue until period end
// Webhooks: subscription.updated, subscription.canceled

Immediate Revocation

// Happens automatically at period end
// Or manually via API (future feature)
// Status changes to "revoked"
// Billing stops, benefits revoked
// Webhooks: subscription.updated, subscription.revoked

Reactivate Canceled

await polar.subscriptions.update(subscriptionId, {
  cancel_at_period_end: false
});
// Removes cancellation
// Subscription continues normally

Renewals

Listening to Renewals

app.post('/webhook/polar', async (req, res) => {
  const event = validateEvent(req.body, req.headers, secret);

  if (event.type === 'order.created') {
    const order = event.data;

    if (order.billing_reason === 'subscription_cycle') {
      // This is a renewal
      await handleRenewal(order.subscription_id);
    }
  }

  res.json({ received: true });
});

Failed Renewals

• subscription.past_due webhook fired
• Dunning process initiated
• Customer notified via email
• Multiple retry attempts
• Eventually revoked if payment fails

Discounts

Apply Discount

await polar.subscriptions.update(subscriptionId, {
  discount_id: "discount_xxx"
});

Remove Discount

await polar.subscriptions.update(subscriptionId, {
  discount_id: null
});

Discount Types

• Percentage off: 20% off
• Fixed amount: $5 off
• Duration: once, forever, repeating

Customer Portal

Generate Portal Access

const session = await polar.customerSessions.create({
  customer_id: "cust_xxx"
});

// Redirect to: session.url

Portal Features

• View subscriptions
• Upgrade/downgrade plans
• Cancel subscriptions
• Update billing info
• View invoices
• Access benefits

Pre-authenticated Links

// From your app, create session and redirect
app.get('/portal', async (req, res) => {
  const session = await polar.customerSessions.create({
    external_customer_id: req.user.id
  });

  res.redirect(session.url);
});

Metadata

Update Subscription Metadata

await polar.subscriptions.update(subscriptionId, {
  metadata: {
    internal_id: "sub_123",
    tier: "pro",
    source: "web"
  }
});

Query by Metadata

const subscriptions = await polar.subscriptions.list({
  organization_id: "org_xxx",
  metadata: { tier: "pro" }
});

Best Practices

1. Lifecycle Management:

• Listen to all subscription webhooks
• Handle each state appropriately
• Sync state to your database
• Grant/revoke access based on state

2. Upgrades/Downgrades:

• Use proration for fair billing
• Communicate changes clearly
• Preview invoice before change
• Allow customer self-service

3. Trials:

• Set appropriate trial duration
• Notify before trial ends
• Easy cancellation during trial
• Clear trial end date in UI

4. Cancellations:

• Make cancellation easy
• Offer alternatives (pause, downgrade)
• Collect feedback
• Keep benefits until period end
• Send confirmation email

5. Failed Payments:

• Handle past_due webhook
• Notify customer promptly
• Provide retry mechanism
• Grace period before revocation
• Clear reactivation path

6. Customer Communication:

• Renewal reminders
• Payment confirmations
• Failed payment notifications
• Upgrade/downgrade confirmations
• Cancellation confirmations

7. Analytics:

• Track churn reasons
• Monitor upgrade/downgrade patterns
• Analyze trial conversion
• Measure payment failure rates
• Lifetime value calculations

Common Patterns

Subscription Status Check

async function hasActiveSubscription(userId) {
  const subscriptions = await polar.subscriptions.list({
    external_customer_id: userId,
    status: "active"
  });

  return subscriptions.items.length > 0;
}

Grace Period Handler

app.post('/webhook/polar', async (req, res) => {
  const event = validateEvent(req.body, req.headers, secret);

  if (event.type === 'subscription.past_due') {
    const subscription = event.data;

    // Grant 3-day grace period
    await grantGracePeriod(subscription.customer_id, 3);

    // Notify customer
    await sendPaymentFailedEmail(subscription.customer_id);
  }

  res.json({ received: true });
});

Upgrade Path

async function upgradeSubscription(subscriptionId, newPriceId) {
  // Preview invoice
  const preview = await polar.subscriptions.previewUpdate(subscriptionId, {
    product_price_id: newPriceId,
    proration: "invoice_immediately"
  });

  // Show customer preview
  if (await confirmUpgrade(preview)) {
    await polar.subscriptions.update(subscriptionId, {
      product_price_id: newPriceId,
      proration: "invoice_immediately"
    });
  }
}

Polar Webhooks

Event handling, signature verification, and monitoring.

Setup

1. Org Settings → Webhooks 2. Enter endpoint URL (publicly accessible) 3. Receive webhook secret (base64 encoded) 4. Select event types 5. Save configuration

Requirements:

• HTTPS endpoint
• Respond within 20 seconds
• Return 2xx status code

Signature Verification

Headers

webhook-id: msg_xxx
webhook-signature: v1,signature_xxx
webhook-timestamp: 1642000000

TypeScript Verification

import { validateEvent, WebhookVerificationError } from '@polar-sh/sdk/webhooks';

app.post('/webhook/polar', (req, res) => {
  try {
    const event = validateEvent(
      req.body,
      req.headers,
      process.env.POLAR_WEBHOOK_SECRET
    );

    // Event is valid, process it
    await handleEvent(event);

    res.json({ received: true });
  } catch (error) {
    if (error instanceof WebhookVerificationError) {
      console.error('Invalid webhook signature');
      return res.status(400).json({ error: 'Invalid signature' });
    }
    throw error;
  }
});

Python Verification

from polar_sdk.webhooks import validate_event, WebhookVerificationError

@app.route('/webhook/polar', methods=['POST'])
def polar_webhook():
    try:
        event = validate_event(
            request.get_data(),
            dict(request.headers),
            os.environ['POLAR_WEBHOOK_SECRET']
        )

        handle_event(event)
        return {'received': True}

    except WebhookVerificationError:
        return {'error': 'Invalid signature'}, 400

Manual Verification

import crypto from 'crypto';

function verifySignature(payload, headers, secret) {
  const timestamp = headers['webhook-timestamp'];
  const signatures = headers['webhook-signature'].split(',');

  const signedPayload = `${timestamp}.${payload}`;
  const expectedSignature = crypto
    .createHmac('sha256', Buffer.from(secret, 'base64'))
    .update(signedPayload)
    .digest('base64');

  return signatures.some(sig => {
    const [version, signature] = sig.split('=');
    return version === 'v1' && signature === expectedSignature;
  });
}

Event Types

Checkout

• checkout.created - Checkout session created
• checkout.updated - Session updated

Order

• order.created - Order created (check billing_reason)
• purchase - One-time product
• subscription_create - New subscription
• subscription_cycle - Renewal
• subscription_update - Plan change
• order.paid - Payment confirmed
• order.updated - Order updated
• order.refunded - Refund processed

Subscription

• subscription.created - Subscription created
• subscription.active - Subscription activated
• subscription.updated - Subscription modified
• subscription.canceled - Cancellation scheduled
• subscription.revoked - Subscription terminated

Note: Multiple events may fire for single action

Customer

• customer.created - Customer created
• customer.updated - Customer modified
• customer.deleted - Customer deleted
• customer.state_changed - Benefits/subscriptions changed

Benefit Grant

• benefit_grant.created - Benefit granted
• benefit_grant.updated - Grant modified
• benefit_grant.revoked - Benefit revoked

Refund

• refund.created - Refund initiated
• refund.updated - Refund status changed

Product

• product.created - Product created
• product.updated - Product modified

Event Structure

{
  "type": "order.paid",
  "data": {
    "id": "order_xxx",
    "amount": 2000,
    "currency": "USD",
    "billing_reason": "purchase",
    "customer": { ... },
    "product": { ... },
    "subscription": null,
    "metadata": { ... }
  }
}

Handler Implementation

Basic Handler

async function handleEvent(event) {
  switch (event.type) {
    case 'order.paid':
      await handleOrderPaid(event.data);
      break;

    case 'subscription.active':
      await grantAccess(event.data.customer_id);
      break;

    case 'subscription.revoked':
      await revokeAccess(event.data.customer_id);
      break;

    case 'benefit_grant.created':
      await notifyBenefitGranted(event.data);
      break;

    default:
      console.log(`Unhandled event: ${event.type}`);
  }
}

Order Handler

async function handleOrderPaid(order) {
  // Handle different billing reasons
  switch (order.billing_reason) {
    case 'purchase':
      await fulfillOneTimeOrder(order);
      break;

    case 'subscription_create':
      await handleNewSubscription(order);
      break;

    case 'subscription_cycle':
      await handleRenewal(order);
      break;

    case 'subscription_update':
      await handleUpgrade(order);
      break;
  }
}

Customer State Handler

async function handleCustomerStateChanged(customer) {
  // Customer state includes:
  // - active_subscriptions
  // - active_benefits

  const hasActiveSubscription = customer.active_subscriptions.length > 0;

  if (hasActiveSubscription) {
    await enableFeatures(customer.external_id);
  } else {
    await disableFeatures(customer.external_id);
  }
}

Best Practices

1. Respond Immediately

app.post('/webhook/polar', async (req, res) => {
  // Respond quickly
  res.json({ received: true });

  // Queue for background processing
  await webhookQueue.add('polar-webhook', req.body);
});

2. Idempotency

async function handleEvent(event) {
  // Check if already processed
  const exists = await db.processedEvents.findOne({
    webhook_id: event.id
  });

  if (exists) {
    console.log('Event already processed');
    return;
  }

  // Process event
  await processEvent(event);

  // Mark as processed
  await db.processedEvents.insert({
    webhook_id: event.id,
    processed_at: new Date()
  });
}

3. Retry Logic

async function processWithRetry(event, maxRetries = 3) {
  let attempt = 0;

  while (attempt < maxRetries) {
    try {
      await handleEvent(event);
      return;
    } catch (error) {
      attempt++;
      if (attempt >= maxRetries) throw error;
      await sleep(1000 * attempt);
    }
  }
}

4. Error Handling

app.post('/webhook/polar', async (req, res) => {
  try {
    const event = validateEvent(req.body, req.headers, secret);
    res.json({ received: true });

    await processWithRetry(event);
  } catch (error) {
    console.error('Webhook processing failed:', error);
    // Log to error tracking service
    await logError(error, req.body);

    if (error instanceof WebhookVerificationError) {
      return res.status(400).json({ error: 'Invalid signature' });
    }

    // Return 2xx even on processing errors
    // Polar will retry if non-2xx
    res.json({ received: true });
  }
});

5. Logging

logger.info('Webhook received', {
  event_type: event.type,
  event_id: event.id,
  customer_id: event.data.customer?.id,
  amount: event.data.amount
});

Monitoring

Dashboard Features

• View webhook attempts
• Check response status
• Review retry history
• Manual retry option
• Filter by event type
• Search by customer

Application Monitoring

const metrics = {
  webhooks_received: counter('polar_webhooks_received_total'),
  webhooks_processed: counter('polar_webhooks_processed_total'),
  webhooks_failed: counter('polar_webhooks_failed_total'),
  processing_time: histogram('polar_webhook_processing_seconds')
};

app.post('/webhook/polar', async (req, res) => {
  metrics.webhooks_received.inc({ type: req.body.type });

  const timer = metrics.processing_time.startTimer();

  try {
    await handleEvent(req.body);
    metrics.webhooks_processed.inc({ type: req.body.type });
  } catch (error) {
    metrics.webhooks_failed.inc({ type: req.body.type });
  } finally {
    timer();
  }

  res.json({ received: true });
});

Framework Adapters

Next.js

import { validateEvent } from '@polar-sh/nextjs/webhooks';

export async function POST(req: Request) {
  const event = await validateEvent(req);

  await handleEvent(event);

  return Response.json({ received: true });
}

Laravel

use Polar\Webhooks\WebhookHandler;

Route::post('/webhook/polar', function (Request $request) {
    $event = WebhookHandler::validate(
        $request->getContent(),
        $request->headers->all(),
        config('polar.webhook_secret')
    );

    dispatch(new ProcessPolarWebhook($event));

    return response()->json(['received' => true]);
});

Testing

Manual Testing

# Use Polar dashboard to send test webhooks
# Or use webhook testing tools

curl -X POST https://your-domain.com/webhook/polar \
  -H "Content-Type: application/json" \
  -H "webhook-id: msg_test" \
  -H "webhook-timestamp: $(date +%s)" \
  -H "webhook-signature: v1,test_signature" \
  -d '{"type":"order.paid","data":{...}}'

Local Testing with ngrok

# Expose local server
ngrok http 3000

# Use ngrok URL in Polar webhook settings
https://abc123.ngrok.io/webhook/polar

SePay API Reference

Base URL: https://my.sepay.vn/userapi/ Rate Limit: 2 calls/second

Transaction API

List Transactions

GET /userapi/transactions/list

Parameters:

• account_number (string) - Bank account ID
• transaction_date_min/max (yyyy-mm-dd) - Date range
• since_id (integer) - Start from ID
• limit (integer) - Max 5000 per request
• reference_number (string) - Transaction reference
• amount_in (number) - Incoming amount
• amount_out (number) - Outgoing amount

Response:

{
  "status": 200,
  "transactions": [{
    "id": 92704,
    "gateway": "Vietcombank",
    "transaction_date": "2023-03-25 14:02:37",
    "account_number": "0123499999",
    "content": "payment content",
    "transfer_type": "in",
    "transfer_amount": 2277000,
    "accumulated": 19077000,
    "reference_number": "MBVCB.3278907687",
    "bank_account_id": 123
  }]
}

Transaction Details

GET /userapi/transactions/details/{transaction_id}

Count Transactions

GET /userapi/transactions/count

Bank Account API

List Bank Accounts

GET /userapi/bankaccounts/list

Parameters:

• short_name - Bank identifier
• last_transaction_date_min/max - Date range
• since_id - Starting account ID
• limit - Results per page (default 100)
• accumulated_min/max - Balance range

Response:

{
  "id": 123,
  "account_holder_name": "NGUYEN VAN A",
  "account_number": "0123456789",
  "accumulated": 50000000,
  "last_transaction": "2025-01-13 10:30:00",
  "bank_short_name": "VCB",
  "active": 1
}

Account Details

GET /userapi/bankaccounts/details/{bank_account_id}

Count Accounts

GET /userapi/bankaccounts/count

Order-Based Virtual Account API

Concept: Each order gets unique VA with exact amount matching for automated confirmation.

Flow: 1. Create order → API generates unique VA 2. Display VA + QR to customer 3. Customer transfers to VA 4. Bank notifies SePay on success 5. SePay triggers webhook 6. Update order status

Advantages:

• Precision: VA accepts only exact amounts
• Independence: Each order has own VA (no content parsing)
• Security: VAs auto-cancel after success/expiration
• Integration: RESTful API

Supported Banks: BIDV and others (check docs for full list)

Error Handling

HTTP Status Codes:

• 200 OK - Successful
• 201 Created - Resource created
• 400 Bad Request - Invalid parameters
• 401 Unauthorized - Invalid/missing auth
• 403 Forbidden - Insufficient permissions
• 404 Not Found - Resource not found
• 429 Too Many Requests - Rate limit exceeded
• 500 Internal Server Error - Server error
• 503 Service Unavailable - Temporarily unavailable

Rate Limit Response:

{
  "status": 429,
  "error": "rate_limit_exceeded",
  "message": "Too many requests"
}

Check x-sepay-userapi-retry-after header for retry timing.

Best Practices

1. Pagination: Use limit and since_id for large datasets 2. Date Ranges: Query specific periods to reduce response size 3. Rate Limiting: Implement exponential backoff 4. Error Handling: Log all errors with context 5. Caching: Cache bank account lists 6. Monitoring: Track API response times and error rates 7. Reconciliation: Regular transaction matching

SePay Best Practices

Security, patterns, and monitoring for production SePay integrations.

Security

Credential Management

// ✓ Good: Environment variables
const client = new SePayClient({
  merchant_id: process.env.SEPAY_MERCHANT_ID,
  secret_key: process.env.SEPAY_SECRET_KEY,
  env: process.env.NODE_ENV === 'production' ? 'production' : 'sandbox'
});

// ✗ Bad: Hardcoded credentials
const client = new SePayClient({
  merchant_id: 'SP-TEST-12345',
  secret_key: 'spsk_test_xxxxxxx'
});

Webhook Security

1. IP Whitelisting: Restrict endpoint to SePay IPs 2. API Key Verification: Validate authorization header 3. HTTPS Only: Never accept HTTP webhooks 4. Validate Payload: Check all required fields exist 5. Duplicate Detection: Use transaction ID for deduplication

Transaction Verification

// Always verify payment status via API, don't trust only redirects
app.get('/payment/success', async (req, res) => {
  const orderId = req.query.order_id;

  // Verify via API call
  const order = await sePayClient.order.retrieve(orderId);

  if (order.status === 'completed') {
    await updateOrderStatus(orderId, 'paid');
    res.redirect(`/order/${orderId}/confirmation`);
  } else {
    res.redirect(`/order/${orderId}/pending`);
  }
});

Implementation Patterns

Payment Flow Pattern

class PaymentService {
  async createPayment(order) {
    // 1. Create order in your system
    const paymentCode = `ORDER_${order.id}_${Date.now()}`;
    await this.savePaymentCode(order.id, paymentCode);

    // 2. Generate checkout form
    const fields = this.client.checkout.initOneTimePaymentFields({
      order_invoice_number: paymentCode,
      order_amount: order.total,
      currency: 'VND',
      success_url: `${config.baseUrl}/payment/success?order=${order.id}`,
      error_url: `${config.baseUrl}/payment/error?order=${order.id}`,
      cancel_url: `${config.baseUrl}/payment/cancel?order=${order.id}`,
      order_description: `Payment for Order #${order.id}`,
    });

    return fields;
  }

  async verifyPayment(orderId) {
    const paymentCode = await this.getPaymentCode(orderId);
    const payment = await this.client.order.retrieve(paymentCode);

    return {
      isPaid: payment.status === 'completed',
      amount: payment.amount,
      paidAt: payment.completed_at,
    };
  }
}

Webhook Resilience Pattern

async function handleWebhook(data) {
  const maxRetries = 3;
  let attempt = 0;

  while (attempt < maxRetries) {
    try {
      await db.transaction(async (trx) => {
        // Check duplicate
        const exists = await trx('transactions')
          .where('sepay_id', data.id)
          .first();

        if (exists) return;

        // Save transaction
        await trx('transactions').insert({
          sepay_id: data.id,
          amount: data.transferAmount,
          content: data.content,
          reference_code: data.referenceCode,
        });

        // Process payment
        const order = await findOrderByPaymentCode(data.content);
        if (order) {
          await markOrderAsPaid(order.id, trx);
        }
      });

      return { success: true };
    } catch (error) {
      attempt++;
      if (attempt >= maxRetries) throw error;
      await sleep(1000 * attempt); // Exponential backoff
    }
  }
}

Reconciliation Pattern

async function reconcilePayments(fromDate, toDate) {
  // Get all pending orders
  const pendingOrders = await Order.findPending();

  // Fetch SePay transactions in batches
  let sinceId = 0;
  const batchSize = 1000;

  while (true) {
    const transactions = await sePayClient.transaction.list({
      transaction_date_min: fromDate,
      transaction_date_max: toDate,
      transfer_type: 'in',
      since_id: sinceId,
      limit: batchSize,
    });

    if (transactions.length === 0) break;

    // Match and update
    for (const transaction of transactions) {
      const order = pendingOrders.find(o =>
        transaction.content.includes(o.payment_code)
      );

      if (order) {
        await order.markAsPaid(transaction);
      }
    }

    sinceId = transactions[transactions.length - 1].id;
  }
}

Performance Optimization

Caching

// Cache bank list
const getBankList = memoize(
  async () => {
    const response = await fetch('https://qr.sepay.vn/banks.json');
    return response.json();
  },
  { maxAge: 86400000 } // 24 hours
);

// Cache QR codes for fixed amounts
const qrCache = new Map();

function getCachedQRUrl(account, bank, amount) {
  const key = `${account}-${bank}-${amount}`;
  if (!qrCache.has(key)) {
    const url = generateQRUrl(account, bank, amount);
    qrCache.set(key, url);
  }
  return qrCache.get(key);
}

Rate Limit Management

const RateLimiter = require('bottleneck');

const limiter = new RateLimiter({
  maxConcurrent: 1,
  minTime: 500, // 2 requests per second
  reservoir: 100,
  reservoirRefreshAmount: 100,
  reservoirRefreshInterval: 60000, // per minute
});

// Wrap API calls
const apiCall = limiter.wrap(async (endpoint, params) => {
  return await sePayClient.api.call(endpoint, params);
});

Async Processing

// Queue webhook processing
app.post('/webhook/sepay', async (req, res) => {
  // Respond immediately
  res.json({ success: true });

  // Queue for background processing
  await webhookQueue.add('process-sepay-webhook', req.body, {
    attempts: 3,
    backoff: {
      type: 'exponential',
      delay: 2000,
    },
  });
});

// Process in background worker
webhookQueue.process('process-sepay-webhook', async (job) => {
  await handleWebhook(job.data);
});

Monitoring & Logging

Essential Metrics

const metrics = {
  payment_initiated: counter('sepay_payment_initiated_total'),
  payment_success: counter('sepay_payment_success_total'),
  payment_failed: counter('sepay_payment_failed_total'),
  webhook_received: counter('sepay_webhook_received_total'),
  webhook_processed: counter('sepay_webhook_processed_total'),
  api_errors: counter('sepay_api_errors_total'),
  processing_time: histogram('sepay_processing_duration_seconds'),
};

// Track metrics
metrics.payment_initiated.inc();
const timer = metrics.processing_time.startTimer();
// ... process payment
timer();

Structured Logging

logger.info('Payment initiated', {
  order_id: order.id,
  amount: order.total,
  payment_method: 'sepay',
  customer_id: customer.id,
});

logger.info('Webhook received', {
  transaction_id: webhook.id,
  amount: webhook.transferAmount,
  type: webhook.transferType,
  reference: webhook.referenceCode,
});

logger.error('Payment failed', {
  order_id: order.id,
  error: error.message,
  stack: error.stack,
  sepay_response: response,
});

Alerting

// Alert on high failure rate
if (failureRate > 0.1) { // 10%
  alert.send({
    severity: 'high',
    message: 'SePay payment failure rate exceeds 10%',
    details: { failureRate, total, failed },
  });
}

// Alert on webhook delivery failures
if (webhookFailures > 10) {
  alert.send({
    severity: 'medium',
    message: 'SePay webhook delivery failures',
    details: { failures: webhookFailures },
  });
}

Testing Strategy

Sandbox Testing Checklist

• [ ] Successful payment flow
• [ ] Failed payment handling
• [ ] Canceled payment handling
• [ ] Webhook delivery and processing
• [ ] Duplicate webhook handling
• [ ] Rate limit handling
• [ ] Error scenarios (network, timeout, invalid data)
• [ ] Payment verification via API
• [ ] QR code generation
• [ ] Order reconciliation

Load Testing

// Simulate high volume
for (let i = 0; i < 1000; i++) {
  await createPayment({
    amount: 100000,
    orderId: `LOAD_TEST_${i}`,
  });
  await sleep(100); // Respect rate limits
}

Production Checklist

• [ ] Environment variables configured
• [ ] Production credentials obtained
• [ ] HTTPS enabled for all endpoints
• [ ] Webhook endpoint publicly accessible
• [ ] IP whitelisting configured
• [ ] Error monitoring set up
• [ ] Logging infrastructure ready
• [ ] Alerting configured
• [ ] Rate limiting implemented
• [ ] Database indexes created
• [ ] Reconciliation job scheduled
• [ ] Backup strategy in place
• [ ] Documentation updated
• [ ] Team trained on operations

SePay Overview

Vietnamese payment automation platform serving as intermediary between applications and banks.

Core Capabilities

Payment Methods:

• VietQR - QR code bank transfers (NAPAS standard)
• NAPAS QR - National payment gateway QR
• Bank Cards - Visa/Mastercard/JCB
• Bank Transfers - Direct bank-to-bank
• Virtual Accounts - Order-specific VAs with exact matching

Supported Banks: 44+ banks via NAPAS, 37+ with VietQR (Vietcombank, VPBank, BIDV, etc.)

Use Cases:

• Payment gateway for online payments
• Bank API direct connection
• Transaction verification automation
• Real-time balance monitoring

Authentication

API Token (Simple)

Create: 1. Company Configuration → API Access → "+ Add API" 2. Provide name, set status "Active" 3. Copy token from list

Usage:

Authorization: Bearer {API_TOKEN}
Content-Type: application/json

Note: All tokens have full access (no permission levels currently)

OAuth2 (Advanced)

Scopes:

• bank-account:read - View accounts, balances
• transaction:read - Transaction history
• webhook:read/write/delete - Webhook management
• profile - User information
• company - Company details

Authorization Code Flow:

1. Authorization Request:

GET https://my.sepay.vn/oauth/authorize?
  response_type=code&
  client_id={CLIENT_ID}&
  redirect_uri={REDIRECT_URI}&
  scope={SCOPES}&
  state={CSRF_TOKEN}

2. Token Exchange (server-side only):

POST https://my.sepay.vn/oauth/token
{
  "grant_type": "authorization_code",
  "client_id": "{CLIENT_ID}",
  "client_secret": "{CLIENT_SECRET}",
  "code": "{AUTHORIZATION_CODE}"
}

3. Token Refresh:

POST https://my.sepay.vn/oauth/token
{
  "grant_type": "refresh_token",
  "refresh_token": "{REFRESH_TOKEN}",
  "client_id": "{CLIENT_ID}",
  "client_secret": "{CLIENT_SECRET}"
}

Security: Access tokens expire ~1 hour, never expose client_secret, use state for CSRF protection

Payment Gateway Flow (13 Steps)

1. Customer selects products, initiates payment 2. Merchant creates order record 3. Generate checkout form with HMAC-SHA256 signature 4. Send request to /v1/checkout/init 5. SePay validates signature 6. Redirect customer to SePay gateway 7. Customer selects payment method 8. SePay communicates with banks/card networks 9. Financial institution returns result 10. Callback notification sent to merchant 11. IPN (Instant Payment Notification) transmitted 12. Customer redirected to merchant result page 13. Final outcome displayed

Environments

Sandbox:

• Dashboard: https://my.sepay.vn (free tier)
• Endpoint: https://sandbox.pay.sepay.vn/v1/init
• Credentials: SP-TEST-XXXXXXX, spsk_test_xxxxxxxxxxxxx

Production:

• Endpoint: https://pay.sepay.vn/v1/init
• Requirements: Personal/business bank account, completed testing
• Approval: 3-7 days for NAPAS QR/cards (requires documentation)

Rate Limits

Limit: 2 calls/second Response: HTTP 429 with x-sepay-userapi-retry-after header (seconds to wait)

Handling:

if (response.status === 429) {
  const retryAfter = response.headers.get('x-sepay-userapi-retry-after');
  await sleep(retryAfter * 1000);
  return retry();
}

Support

• Email: info@sepay.vn
• Hotline: 02873059589 (24/7)
• Docs: https://developer.sepay.vn/en
• GitHub: https://github.com/sepayvn

Next Steps

• For API integration: Load api.md
• For SDK integration: Load sdk.md
• For webhook setup: Load webhooks.md
• For QR generation: Load qr-codes.md

SePay VietQR Generation

Dynamic QR code generation service compatible with VietQR standard (NAPAS).

API Endpoint

https://qr.sepay.vn/img?acc={ACCOUNT}&bank={BANK}&amount={AMOUNT}&des={DESCRIPTION}

Parameters

Required:

• acc - Bank account number
• bank - Bank code or short name

Optional:

• amount - Transfer amount (omit for flexible amount)
• des - Transfer description/content (URL encoded)
• template - QR image template (empty/compact/qronly)
• download - Set to "true" to download image

Examples

Complete QR (Fixed Amount)

https://qr.sepay.vn/img?
  acc=0010000000355&
  bank=Vietcombank&
  amount=100000&
  des=ung%20ho%20quy%20bao%20tro%20tre%20em

Flexible QR (Customer Enters Amount)

https://qr.sepay.vn/img?acc=0010000000355&bank=Vietcombank

QR Only Template

https://qr.sepay.vn/img?
  acc=0010000000355&
  bank=Vietcombank&
  amount=100000&
  template=qronly

Integration

HTML

<img src="https://qr.sepay.vn/img?acc=0010000000355&bank=Vietcombank&amount=100000"
     alt="Payment QR Code" />

JavaScript (Dynamic)

function generatePaymentQR(account, bank, amount, description) {
  const params = new URLSearchParams({
    acc: account,
    bank: bank,
    amount: amount,
    des: description
  });
  return `https://qr.sepay.vn/img?${params}`;
}

// Usage
const qrUrl = generatePaymentQR(
  '0010000000355',
  'Vietcombank',
  100000,
  'Order #12345'
);

document.getElementById('qr-code').src = qrUrl;

PHP (Dynamic)

<?php
function generatePaymentQR($account, $bank, $amount, $description) {
    return 'https://qr.sepay.vn/img?' . http_build_query([
        'acc' => $account,
        'bank' => $bank,
        'amount' => $amount,
        'des' => $description
    ]);
}

// Usage
$qrUrl = generatePaymentQR(
    '0010000000355',
    'Vietcombank',
    100000,
    'Order #' . $orderId
);

echo "<img src='{$qrUrl}' alt='Payment QR' />";
?>

Node.js (Express)

app.get('/payment/:orderId/qr', async (req, res) => {
  const order = await Order.findById(req.params.orderId);

  const qrUrl = new URL('https://qr.sepay.vn/img');
  qrUrl.searchParams.set('acc', process.env.SEPAY_ACCOUNT);
  qrUrl.searchParams.set('bank', process.env.SEPAY_BANK);
  qrUrl.searchParams.set('amount', order.total);
  qrUrl.searchParams.set('des', `Order ${order.id}`);

  res.render('payment', { qrUrl: qrUrl.toString() });
});

React Component

function PaymentQR({ account, bank, amount, description }) {
  const qrUrl = useMemo(() => {
    const params = new URLSearchParams({
      acc: account,
      bank: bank,
      amount: amount,
      des: description
    });
    return `https://qr.sepay.vn/img?${params}`;
  }, [account, bank, amount, description]);

  return (
    <div className="payment-qr">
      <img src={qrUrl} alt="Payment QR Code" />
      <p>Scan to pay {amount.toLocaleString('vi-VN')} VND</p>
    </div>
  );
}

Templates

Default:

• Full QR with bank logo
• Account information displayed
• Branded with bank colors

Compact:

• Smaller version
• Minimal branding
• More space-efficient

QR Only:

• Pure QR code
• No decorations
• For custom layouts

Bank Codes

Get Bank List:

GET https://qr.sepay.vn/banks.json

Common Banks:

• Vietcombank (VCB)
• VPBank
• BIDV
• Techcombank (TCB)
• ACB
• MB Bank
• Sacombank
• VietinBank
• And 40+ others

Cache Bank List:

// Fetch once and cache
const banks = await fetch('https://qr.sepay.vn/banks.json')
  .then(res => res.json());

// Store in memory or Redis
cache.set('sepay_banks', banks, 86400); // 24 hours

Best Practices

1. Cache Bank List: Avoid repeated API calls 2. URL Encode Descriptions: Use encodeURIComponent() or http_build_query() 3. Error Handling: Provide fallback for QR generation failures 4. Amount Validation: Ensure amount is positive integer 5. Flexible vs Fixed: Use flexible QR for varying amounts 6. Template Selection: Choose based on UI design 7. Responsive Design: Scale QR code for mobile devices 8. Alt Text: Always provide descriptive alt text 9. Loading State: Show placeholder while QR loads 10. Print Support: Ensure QR codes are print-friendly

Integration Patterns

Checkout Page

<div class="payment-methods">
  <h3>Pay via Bank Transfer</h3>
  <img src="[QR_URL]" alt="Payment QR Code" class="qr-code" />
  <p>Scan this QR code with your banking app</p>
  <div class="payment-details">
    <p><strong>Account:</strong> 0010000000355</p>
    <p><strong>Bank:</strong> Vietcombank</p>
    <p><strong>Amount:</strong> 100,000 VND</p>
    <p><strong>Content:</strong> Order #12345</p>
  </div>
</div>

Email Receipt

<table>
  <tr>
    <td align="center">
      <img src="[QR_URL]" alt="Payment QR Code" width="200" />
      <p>Scan to pay for your order</p>
    </td>
  </tr>
</table>

PDF Invoice

Use QR URL in PDF generation libraries (wkhtmltopdf, Puppeteer, etc.)

SePay SDK Integration

Official SDKs for Node.js, PHP, and Laravel.

Node.js SDK (sepay-pg-node)

Installation:

npm install github:sepay/sepay-pg-node

Requirements: Node.js 16+

Configuration:

import { SePayPgClient } from 'sepay-pg-node';

const client = new SePayPgClient({
  env: 'sandbox',  // or 'production'
  merchant_id: 'SP-TEST-XXXXXXX',
  secret_key: 'spsk_test_xxxxxxxxxxxxx',
});

Create Payment:

const fields = client.checkout.initOneTimePaymentFields({
  operation: 'PURCHASE',
  order_invoice_number: 'DH0001',
  order_amount: 10000,
  currency: 'VND',
  success_url: 'https://example.com/success',
  error_url: 'https://example.com/error',
  cancel_url: 'https://example.com/cancel',
  order_description: 'Payment for order DH0001',
});

Render Payment Form:

<form action={client.checkout.initCheckoutUrl()} method="POST">
  {Object.keys(fields).map(field =>
    <input type="hidden" name={field} value={fields[field]} key={field} />
  )}
  <button type="submit">Pay Now</button>
</form>

API Methods:

// List all orders
await client.order.all({
  per_page: 50,
  q: 'search_term',
  order_status: 'completed',
  from_created_at: '2025-01-01',
  to_created_at: '2025-01-31'
});

// Get order details
await client.order.retrieve('DH0001');

// Void transaction (cards only)
await client.order.voidTransaction('DH0001');

// Cancel order (QR payments)
await client.order.cancel('DH0001');

Endpoints:

• Sandbox: https://sandbox.pay.sepay.vn/v1/init
• Production: https://pay.sepay.vn/v1/init

PHP SDK (sepay/sepay-pg)

Installation:

composer require sepay/sepay-pg

Requirements: PHP 7.4+, ext-json, ext-curl, Guzzle

Quick Start:

use SePay\SePayClient;
use SePay\Builders\CheckoutBuilder;

$sepay = new SePayClient(
    'SP-TEST-XXXXXXX',
    'spsk_live_xxxxxxxxxxxxx',
    SePayClient::ENVIRONMENT_SANDBOX
);

$checkoutData = CheckoutBuilder::make()
    ->currency('VND')
    ->orderAmount(100000)
    ->operation('PURCHASE')
    ->orderDescription('Test payment')
    ->orderInvoiceNumber('INV_001')
    ->successUrl('https://yoursite.com/success')
    ->errorUrl('https://yoursite.com/error')
    ->cancelUrl('https://yoursite.com/cancel')
    ->build();

echo $sepay->checkout()->generateFormHtml($checkoutData);

Error Handling:

try {
    $order = $sepay->orders()->retrieve('INV_001');
} catch (AuthenticationException $e) {
    // Invalid credentials
} catch (ValidationException $e) {
    // Invalid request data
    $errors = $e->getErrors();
} catch (NotFoundException $e) {
    // Resource not found
} catch (RateLimitException $e) {
    // Rate limit exceeded
    $retryAfter = $e->getRetryAfter();
} catch (ServerException $e) {
    // Server error (5xx)
}

Configuration:

$sepay->setConfig([
    'timeout' => 30,
    'retry_attempts' => 3,
    'retry_delay' => 1000,
    'debug' => true,
    'user_agent' => 'MyApp/1.0',
    'logger' => $psrLogger
]);

Laravel Package (laravel-sepay)

Installation:

composer require sepayvn/laravel-sepay

# For Laravel 7-8 with PHP 7.4+
composer require "sepayvn/laravel-sepay:dev-lite"

Setup:

php artisan vendor:publish --tag="sepay-migrations"
php artisan migrate
php artisan vendor:publish --tag="sepay-config"
php artisan vendor:publish --tag="sepay-views"  # optional

Configuration (.env):

SEPAY_WEBHOOK_TOKEN=your_secret_key
SEPAY_MATCH_PATTERN=SE

Create Event Listener:

php artisan make:listener SePayWebhookListener

Listener Implementation:

<?php

namespace App\Listeners;

use SePayWebhookEvent;

class SePayWebhookListener
{
    public function handle(SePayWebhookEvent $event)
    {
        $transaction = $event->transaction;

        if ($transaction->transfer_type === 'in') {
            // Handle incoming payment
            Order::where('code', $transaction->content)
                ->update(['status' => 'paid']);

            // Send confirmation email
            Mail::to($order->customer->email)
                ->send(new PaymentConfirmation($order));
        }
    }
}

Register Listener:

// app/Providers/EventServiceProvider.php
protected $listen = [
    SePayWebhookEvent::class => [
        SePayWebhookListener::class,
    ],
];

Best Practices

1. Environment Variables: Store credentials securely 2. Error Handling: Catch and log all exceptions 3. Retry Logic: Implement for transient failures 4. Logging: Log all API calls and responses 5. Testing: Use sandbox extensively before production 6. Validation: Validate data before API calls 7. Monitoring: Track success/failure rates

SePay Webhooks

Real-time payment notifications from SePay to your server.

Setup

1. Access WebHooks menu in dashboard 2. Click "+ Add webhooks" 3. Configure:

• Name: Descriptive identifier
• Event Selection: All, In_only, Out_only
• Conditions: Bank accounts, VA filtering, payment code requirements
• Webhook URL: Your callback endpoint (must be publicly accessible)
• Is Verify Payment: Flag for validation
• Authentication: No_Authen, OAuth2.0, or Api_Key

4. Click "Add" to finalize

Payload Structure

{
  "id": 92704,
  "gateway": "Vietcombank",
  "transactionDate": "2023-03-25 14:02:37",
  "accountNumber": "0123499999",
  "code": null,
  "content": "payment content",
  "transferType": "in",
  "transferAmount": 2277000,
  "accumulated": 19077000,
  "subAccount": null,
  "referenceCode": "MBVCB.3278907687"
}

Fields:

• id - Unique transaction ID (use for deduplication)
• gateway - Bank name
• transactionDate - Transaction timestamp
• accountNumber - Bank account number
• code - Payment code (if available)
• content - Transfer description/content
• transferType - "in" (incoming) or "out" (outgoing)
• transferAmount - Transaction amount
• accumulated - Account balance after transaction
• subAccount - Sub-account identifier
• referenceCode - Bank transaction reference

Authentication

API Key:

Authorization: Apikey YOUR_KEY
Content-Type: application/json

OAuth 2.0: Provide token endpoint, client ID, and client secret in dashboard.

No Authentication: Available but not recommended for production. Consider IP whitelisting.

Response Requirements

Success Response:

HTTP/1.1 200 OK
{
  "success": true
}

Accepted: Any 2xx status code (200-201) Timeout: Respond within 5 seconds

Auto-Retry Mechanism

Policy:

• Retries up to 7 times over ~5 hours
• Fibonacci sequence intervals (1, 1, 2, 3, 5, 8, 13... minutes)

Duplicate Prevention:

// Primary: Use transaction ID
const exists = await db.transactions.findOne({ sepay_id: data.id });
if (exists) return { success: true };

// Alternative: Composite key
const key = `${data.referenceCode}-${data.transferType}-${data.transferAmount}`;

Implementation Examples

Node.js/Express

app.post('/webhook/sepay', async (req, res) => {
  const transaction = req.body;

  // Check duplicates
  if (await isDuplicate(transaction.id)) {
    return res.json({ success: true });
  }

  // Process transaction
  if (transaction.transferType === 'in') {
    await processPayment({
      amount: transaction.transferAmount,
      content: transaction.content,
      referenceCode: transaction.referenceCode
    });
  }

  // Save to database
  await db.transactions.insert(transaction);

  res.json({ success: true });
});

PHP

<?php
$data = json_decode(file_get_contents('php://input'), true);

// Check duplicates
$exists = $db->query("SELECT id FROM transactions WHERE sepay_id = ?", [$data['id']]);
if ($exists) {
    echo json_encode(['success' => true]);
    exit;
}

// Process payment
if ($data['transferType'] == 'in') {
    processPayment($data['transferAmount'], $data['content']);
}

// Save to database
$db->insert('transactions', [
    'sepay_id' => $data['id'],
    'amount' => $data['transferAmount'],
    'content' => $data['content'],
    'reference_code' => $data['referenceCode']
]);

header('Content-Type: application/json');
echo json_encode(['success' => true]);

Security Best Practices

1. IP Whitelisting: Restrict endpoint to SePay IPs 2. API Key Verification: Validate authorization header 3. HTTPS Only: Use SSL/TLS 4. Duplicate Detection: Prevent double processing 5. Logging: Maintain webhook logs 6. Timeout Handling: Respond quickly (<5s) 7. Idempotency: Same webhook multiple times = same result

Monitoring

Dashboard Features:

• View webhook attempts
• Check response status
• Review retry history
• Manual retry option

Application Monitoring:

• Log all webhook receipts
• Track processing time
• Alert on failures
• Monitor duplicate rate

OAuth2 Webhook Management API

Available Scopes: webhook:read, webhook:write, webhook:delete

List Webhooks:

GET /api/v1/webhooks

Get Details:

GET /api/v1/webhooks/{id}

Create:

POST /api/v1/webhooks
{
  "bank_account_id": 123,
  "name": "My Webhook",
  "event_type": "All",
  "authen_type": "Api_Key",
  "webhook_url": "https://example.com/webhook",
  "is_verify_payment": true
}

Update:

PATCH /api/v1/webhooks/{id}

Delete:

DELETE /api/v1/webhooks/{id}