Payment Integration

Quick Reference

SePay

• references/sepay/overview.md - Auth, supported banks
• references/sepay/api.md - Endpoints, transactions
• references/sepay/webhooks.md - Setup, verification
• references/sepay/sdk.md - Node.js, PHP, Laravel
• references/sepay/qr-codes.md - VietQR generation
• references/sepay/best-practices.md - Production patterns

Polar

• references/polar/overview.md - Auth, MoR concept
• references/polar/products.md - Pricing models
• references/polar/checkouts.md - Checkout flows
• references/polar/subscriptions.md - Lifecycle management
• references/polar/webhooks.md - Event handling
• references/polar/benefits.md - Automated delivery
• references/polar/sdk.md - Multi-language SDKs
• references/polar/best-practices.md - Production patterns

Stripe

• references/stripe/stripe-best-practices.md - Integration design
• references/stripe/stripe-sdks.md - Server SDKs
• references/stripe/stripe-js.md - Payment Element
• references/stripe/stripe-cli.md - Local testing
• references/stripe/stripe-upgrade.md - Version upgrades
• External: https://docs.stripe.com/llms.txt

Paddle

• references/paddle/overview.md - MoR, auth, entity IDs
• references/paddle/api.md - Products, prices, transactions
• references/paddle/paddle-js.md - Checkout overlay/inline
• references/paddle/subscriptions.md - Trials, upgrades, pause
• references/paddle/webhooks.md - SHA256 verification
• references/paddle/sdk.md - Node, Python, PHP, Go
• references/paddle/best-practices.md - Production patterns
• External: https://developer.paddle.com/llms.txt

Creem.io

• references/creem/overview.md - MoR, auth, global support
• references/creem/api.md - Products, checkout sessions
• references/creem/checkouts.md - No-code links, storefronts
• references/creem/subscriptions.md - Trials, seat-based
• references/creem/licensing.md - Device activation
• references/creem/webhooks.md - Signature verification
• references/creem/sdk.md - Next.js, Better Auth
• External: https://docs.creem.io/llms.txt

Multi-Provider & Scripts

• references/multi-provider-schema-and-currency.md - Unified orders schema, currency conversion, commission system, referrer tiers
• references/multi-provider-webhooks-and-revenue.md - Revenue tracking, refunds, webhook idempotency, discount cross-provider sync
• scripts/sepay-webhook-verify.js - SePay HMAC webhook verification
• scripts/polar-webhook-verify.js - Polar webhook verification
• scripts/checkout-helper.js - Checkout session generator

Key Capabilities

Common Mistakes

1. No idempotency keys - Duplicate webhook events cause double-charges; always use idempotency keys
2. Webhook signature skip - Always verify HMAC signature before processing any webhook
3. Sync webhook processing - Return 200 immediately; process events async to avoid timeouts
4. Currency mismatch - Store amounts in smallest unit (cents/piastres), convert only at display
5. No retry logic - Payment APIs are network I/O; wrap all calls with exponential backoff
6. Exposing secret keys - API secrets must be server-side only, never in client bundles
7. Skipping test mode - Use sandbox/test environments before going live; use Stripe CLI for local webhooks

Code Examples

Webhook signature verification (generic pattern)

import crypto from 'crypto';

function verifyWebhook(payload: Buffer, signature: string, secret: string): boolean {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}

// Express handler — always use raw body for signature verification
app.post('/webhooks/payment', express.raw({ type: 'application/json' }), (req, res) => {
  if (!verifyWebhook(req.body, req.headers['x-signature'] as string, process.env.WEBHOOK_SECRET!)) {
    return res.status(401).send('Invalid signature');
  }
  res.status(200).send('ok'); // Respond fast, process async
  processEventAsync(JSON.parse(req.body.toString()));
});

Idempotent payment creation

async function createCheckout(orderId: string, amount: number) {
  return stripe.checkout.sessions.create({
    payment_method_types: ['card'],
    line_items: [{ price_data: { currency: 'usd', unit_amount: amount, product_data: { name: 'Order' } }, quantity: 1 }],
    mode: 'payment',
    success_url: `${BASE_URL}/success?order=${orderId}`,
    cancel_url: `${BASE_URL}/cancel`,
    metadata: { orderId }, // For webhook reconciliation
  }, { idempotencyKey: `checkout-${orderId}` });
}

Implementation

See references/implementation-workflows.md for step-by-step guides per platform.

General flow: auth → products → checkout → webhooks → events