Shopify Payments Are Simple, Until They Break

"payment.confirmed", processedAt: "2026-05-05T11:45:00Z" }

### 4. Express Webhook Handler Implementation
The handler demonstrates idempotency enforcement, state transition logic, and Shopify synchronization.

```javascript
import express from "express";
import crypto from "crypto";

const app = express();

// Important: For production, you should use raw body for signature verification
app.use(express.json());

const PaymentState = Object.freeze({
  PENDING: "pending",
  AWAITING_CONFIRMATION: "awaiting_confirmation",
  CONFIRMED: "confirmed",
  UNDERPAID: "underpaid",
  OVERPAID: "overpaid",
  EXPIRED: "expired",
  FAILED: "failed",
});

const db = {
  payments: new Map(),       // key = providerInvoiceId
  webhookEvents: new Set(),  // for idempotency

  getPayment(invoiceId) {
    return this.payments.get(invoiceId);
  },

  savePayment(payment) {
    this.payments.set(payment.providerInvoiceId, payment);
  },

  hasProcessedEvent(eventId) {
    return this.webhookEvents.has(eventId);
  },

  storeEvent(eventId) {
    this.webhookEvents.add(eventId);
  },
};

function verifySignature(req) {
  // TODO: Implement real signature verification in production
  // Example:
  // const signature = req.headers["x-signature"];
  // const payload = JSON.stringify(req.body); // Use raw body in real implementation
  // const expected = crypto
  //   .createHmac("sha256", process.env.WEBHOOK_SECRET)
  //   .update(payload)
  //   .digest("hex");
  // return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));

  return true; // For development only
}

function calculateNextPaymentState(payment, event) {
  const expected = Number(payment.expectedAmount);
  const received = Number(event.receivedAmount || 0);

  if (event.status === "failed") {
    return PaymentState.FAILED;
  }

  if (event.status === "expired") {
    return PaymentState.EXPIRED;
  }

  if (event.status === "pending") {
    return PaymentState.AWAITING_CONFIRMATION;
  }

  if (event.status === "confirmed") {
    if (received < expected) return PaymentState.UNDERPAID;
    if (received > expected) return PaymentState.OVERPAID;
    return PaymentState.CONFIRMED;
  }

  return payment.status;
}

async function markShopifyOrderAsPaid(orderId) {
  // Implement Shopify Admin API call here
  console.log(`[Shopify] Marking order as paid: ${orderId}`);
}

async function addShopifyOrderNote(orderId, note) {
  // Implement Shopify Admin API call here
  console.log(`[Shopify] Adding note to order ${orderId}: ${note}`);
}

async function syncShopifyOrder(payment) {
  if (payment.status === PaymentState.CONFIRMED) {
    await markShopifyOrderAsPaid(payment.shopifyOrderId);
    return;
  }

  if (payment.status === PaymentState.UNDERPAID) {
    await addShopifyOrderNote(
      payment.shopifyOrderId,
      `Payment underpaid. Expected ${payment.expectedAmount}, received ${payment.receivedAmount}.`
    );
    return;
  }

  if (payment.status === PaymentState.EXPIRED) {
    await addShopifyOrderNote(
      payment.shopifyOrderId,
      "Payment request expired before confirmation."
    );
  }
}

// ====================== WEBHOOK ENDPOINT ======================
app.post("/webhooks/payment", async (req, res) => {
  try {
    if (!verifySignature(req)) {
      return res.status(401).json({ error: "Invalid signature" });
    }

    const event = req.body;

    if (!event.eventId || !event.invoiceId) {
      return res.status(400).json({ error: "Invalid webhook payload" });
    }

    // Idempotency check
    if (db.hasProcessedEvent(event.eventId)) {
      return res.status(200).json({ status: "duplicate_ignored" });
    }

    const payment = db.getPayment(event.invoiceId);

    if (!payment) {
      return res.status(404).json({ error: "Payment not found" });
    }

    // Calculate new state
    const nextState = calculateNextPaymentState(payment, event);

    // Update payment
    payment.status = nextState;
    payment.receivedAmount = event.receivedAmount || payment.receivedAmount;
    payment.updatedAt = new Date().toISOString();

    // Save changes
    db.savePayment(payment);
    db.storeEvent(event.eventId);

    // Sync with Shopify
    await syncShopifyOrder(payment);

    return res.status(200).json({ 
      status: "processed", 
      paymentStatus: nextState 
    });

  } catch (error) {
    console.error("Webhook handling faile

Pitfall Guide

1. Merging Order & Payment State Prematurely: Treating Shopify's order object as the financial source of truth eliminates your ability to handle partial payments, expirations, or gateway timeouts. Always maintain a separate payment ledger.
2. Treating Webhooks as Source of Truth: Webhooks are asynchronous delivery signals, not authoritative records. Network retries and provider outages will cause duplicate or out-of-order events. Your database must be the single source of truth.
3. Ignoring Idempotency Enforcement: Payment gateways guarantee delivery, not exactly-once processing. Without a webhook_events log and eventId deduplication, duplicate webhooks will trigger double-fulfillment or financial reconciliation failures.
4. Oversimplifying Payment States: Assuming only paid/unpaid ignores real-world edge cases like underpayments, overpayments, gateway timeouts, and expired invoices. A granular state machine is mandatory for production resilience.
5. Skipping Raw Body Signature Verification: Using parsed JSON (req.body) for HMAC verification fails due to formatting, whitespace, or key-ordering differences introduced by middleware. Always verify signatures against the raw request payload.
6. Lacking Scheduled Reconciliation: Relying exclusively on webhooks leaves orphaned transactions unhandled during gateway outages or missed deliveries. Implement a cron job to poll payment providers and reconcile state drift.

Deliverables

• 📐 Decoupled Payment Architecture Blueprint: System diagram illustrating the separation between Shopify Order Service, Payment State Engine, Webhook Ingestion Layer, and Idempotency Log. Includes data flow for async events, retry handling, and reconciliation cycles.
• ✅ Production-Ready Webhook Checklist: 12-point verification matrix covering signature validation, raw body parsing, idempotency key design, state transition guards, Shopify API rate-limit handling, and dead-letter queue fallbacks.
• ⚙️ Configuration Templates: Pre-configured DB schema definitions (payments, webhook_events), Express middleware setup for raw body extraction, environment variable templates for webhook secrets, and Shopify Admin API scopes required for order synchronization.