payment-gateway-expert

Payment Gateway Expert / Ahli Payment Gateway

English | Bahasa Indonesia

---

English

Description

Expert guide for integrating major payment gateways (Stripe, PayPal, Xendit, Midtrans, DOKU) into modern SaaS platforms. Covers checkout flows, secure webhook handling, subscription management, and synchronization with local databases.

Instructions

• Security First: Always validate webhook signatures before processing any payment event. Never trust client-side data for prices or payment status. For DOKU, ensure signature components (like request target) are arranged strictly according to documentation.
• Idempotency: Implement idempotency keys for all payment creation requests to avoid duplicate charges. Webhook handlers must also be idempotent. For DOKU, include a unique Request-Id header.
• State Synchronization: Ensure the local database (e.g., PostgreSQL, Supabase) is updated immediately and transactionally upon receiving successful webhook events.
• Subscription Management: Map the provider's subscription statuses (e.g., active, past_due, canceled) accurately to the SaaS platform's internal state machine.
• Testing: Use sandbox/test environments provided by the gateways and simulate webhooks using CLI tools (like Stripe CLI) during development.

Implementation Checklist

• Create a dedicated Webhook endpoint (e.g., /api/webhooks/stripe).
• Use raw request body for signature verification (do not parse JSON before verification).
• Ensure idempotency by tracking processed event IDs in the database.
• Update local user/subscription state transactionally upon success.
• Handle asynchronous failures with a dead-letter queue or retry mechanism.

Example: Stripe Webhook Signature Verification (Next.js App Router)

import Stripe from 'stripe';
import { headers } from 'next/headers';

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);

export async function POST(req: Request) {
  const body = await req.text(); // Raw body required for signature
  const signature = headers().get('Stripe-Signature') as string;

  let event: Stripe.Event;

  try {
    event = stripe.webhooks.constructEvent(
      body,
      signature,
      process.env.STRIPE_WEBHOOK_SECRET!
    );
  } catch (err: any) {
    return new Response(`Webhook Error: ${err.message}`, { status: 400 });
  }

  // Handle the event
  if (event.type === 'checkout.session.completed') {
    // Process successful payment, check idempotency, update DB
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
}