Shopify Payments Are Simple, Until They Break

separation of concerns: the payment system determines financial state first, then synchronizes with Shopify. This ensures that external payment lifecycles are never constrained by Shopify's order model.

1. Architecture Decision: State Separation

Shopify owns the order. Your system owns the payment. Merging them prematurely destroys auditability and recovery capabilities. The payment engine must evaluate incoming signals, transition internal state, and only then push updates to Shopify via the Admin API.

2. Practical Payment State Machine

Real-world payments require granular states beyond binary paid/unpaid. The state machine explicitly handles partial payments, expirations, and gateway failures.

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

3. Data Model: Separate Storage & Event Logging

Webhooks are delivery signals, not authoritative records. A dedicated payments collection maintains the current state, while a webhook_events log enforces idempotency.

// payments table / collection
{
  id: "pay_123",
  shopifyOrderId: "gid://shopify/Order/123456789",
  providerInvoiceId: "inv_987",
  expectedAmount: 49.99,
  receivedAmount: 0,
  currency: "USD",
  status: "pending",
  expiresAt: "2026-05-05T12:00:00Z",
  createdAt: "2026-05-05T11:30:00Z",
  updatedAt: "2026-05-05T11:30:00Z"
}

// webhook_events table / collection
{
  eventId: "evt_abc123",
  providerInvoiceId: "inv_987",
  eventType: "payment.confirmed",
  processedAt: "2026-05-05T11:45:00Z"
}

4. Express Webhook Handler Implementation

The handler demonstrates idempotency enforcement, state transition logic, and Shopify synchronization.

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.