Accept payments with PayPal Checkout in DaloyJS

PAYPAL_ENVIRONMENT=sandbox                  # or live
PAYPAL_CLIENT_ID=replace_me                 # public, also used by the JS SDK
PAYPAL_CLIENT_SECRET=replace_me             # server only
PAYPAL_WEBHOOK_ID=replace_me                # from the webhook subscription

import { resilientFetch, safeJsonParse } from "@daloyjs/core";
import type { App } from "@daloyjs/core";
import { formatMinor } from "../money.ts";

const BASE = process.env.PAYPAL_ENVIRONMENT === "live" ? "https://api-m.paypal.com" : "https://api-m.sandbox.paypal.com";

// GETs are retried by default. POSTs are retried only when they carry a
// PayPal-Request-Id, which makes the retry return the original result.
const getFetch = resilientFetch({ timeoutMs: 15_000, retries: 2 });
const idempotentPostFetch = resilientFetch({ timeoutMs: 15_000, retries: 2, retryableMethods: ["GET", "POST"] });

export class PayPalApiError extends Error {
  constructor(readonly status: number, readonly debugId: string | null, readonly issue?: string) {
    super(`paypal ${status}`);
  }
}

// One cached token per process or isolate, refreshed a minute before expiry.
let cachedToken: { value: string; expiresAt: number } | undefined;
let inflightToken: Promise<string> | undefined;

function accessToken(): Promise<string> {
  if (cachedToken && Date.now() < cachedToken.expiresAt) return Promise.resolve(cachedToken.value);
  // Concurrent requests share one refresh instead of each asking for a token.
  inflightToken ??= (async () => {
    const basic = btoa(`${process.env.PAYPAL_CLIENT_ID}:${process.env.PAYPAL_CLIENT_SECRET}`);
    const res = await getFetch(`${BASE}/v1/oauth2/token`, {
      method: "POST", // not retried: a token request has no side effects worth repeating
      headers: { Authorization: `Basic ${basic}`, "Content-Type": "application/x-www-form-urlencoded" },
      body: "grant_type=client_credentials",
    });
    if (!res.ok) throw new PayPalApiError(res.status, res.headers.get("paypal-debug-id"), "oauth");
    const body = safeJsonParse(await res.text()) as { access_token: string; expires_in: number };
    cachedToken = { value: body.access_token, expiresAt: Date.now() + Math.max(0, body.expires_in - 60) * 1000 };
    return body.access_token;
  })().finally(() => {
    inflightToken = undefined;
  });
  return inflightToken;
}

async function call<T>(path: string, init: { method?: "GET" | "POST"; body?: string; requestId?: string } = {}): Promise<T> {
  const headers: Record<string, string> = {
    Authorization: `Bearer ${await accessToken()}`,
    "Content-Type": "application/json",
    Prefer: "return=representation",
  };
  if (init.requestId) headers["PayPal-Request-Id"] = init.requestId;
  const doFetch = init.method === "POST" && init.requestId ? idempotentPostFetch : getFetch;
  const res = await doFetch(`${BASE}${path}`, { method: init.method ?? "GET", headers, body: init.body });
  const text = await res.text();
  if (res.status === 401) cachedToken = undefined; // revoked or expired early: refresh next call
  if (!res.ok) {
    const err = (text ? safeJsonParse(text) : {}) as { debug_id?: string; details?: Array<{ issue?: string }> };
    // Keep PayPal's debug id and issue code for your logs; never forward them to the client.
    throw new PayPalApiError(res.status, err.debug_id ?? res.headers.get("paypal-debug-id"), err.details?.[0]?.issue);
  }
  return (text ? safeJsonParse(text) : undefined) as T;
}

type Money = { currency_code: string; value: string };
export interface PayPalCapture { id: string; status: string; amount: Money; custom_id?: string }
export interface PayPalOrder {
  id: string;
  status: string;
  purchase_units?: Array<{ custom_id?: string; payments?: { captures?: PayPalCapture[] } }>;
}

export interface PayPalClient {
  createOrder(input: { orderId: string; amountMinor: number; currency: string; requestId: string }): Promise<PayPalOrder>;
  captureOrder(paypalOrderId: string, requestId: string): Promise<PayPalOrder>;
  getCapture(captureId: string): Promise<PayPalCapture>;
  refundCapture(input: { captureId: string; amountMinor: number; currency: string; requestId: string }): Promise<{ id: string; status: string }>;
  verifyWebhook(headers: Headers, rawText: string): Promise<boolean>;
}

// Exported so job handlers (which run outside a request) can use it too.
export const paypalClient: PayPalClient = {
  createOrder({ orderId, amountMinor, currency, requestId }) {
    return call<PayPalOrder>("/v2/checkout/orders", {
      method: "POST",
      requestId,
      body: JSON.stringify({
        intent: "CAPTURE",
        purchase_units: [
          {
            reference_id: orderId,
            custom_id: orderId, // returned on the capture, so the worker can find the order
            amount: { currency_code: currency, value: formatMinor(amountMinor, currency) },
          },
        ],
      }),
    });
  },

  captureOrder(paypalOrderId, requestId) {
    return call<PayPalOrder>(`/v2/checkout/orders/${encodeURIComponent(paypalOrderId)}/capture`, {
      method: "POST",
      requestId,
      body: "{}",
    });
  },

  getCapture(captureId) {
    return call<PayPalCapture>(`/v2/payments/captures/${encodeURIComponent(captureId)}`);
  },

  refundCapture({ captureId, amountMinor, currency, requestId }) {
    return call(`/v2/payments/captures/${encodeURIComponent(captureId)}/refund`, {
      method: "POST",
      requestId,
      body: JSON.stringify({ amount: { currency_code: currency, value: formatMinor(amountMinor, currency) } }),
    });
  },

  async verifyWebhook(headers, rawText) {
    const field = (name: string) => headers.get(name) ?? "";
    // PayPal requires webhook_event exactly as received, so the raw text is
    // embedded, not re-serialized. The caller has already proven rawText is a
    // single valid JSON value (safeJsonParse), so it cannot inject sibling keys.
    const body =
      `{"auth_algo":${JSON.stringify(field("paypal-auth-algo"))}` +
      `,"cert_url":${JSON.stringify(field("paypal-cert-url"))}` +
      `,"transmission_id":${JSON.stringify(field("paypal-transmission-id"))}` +
      `,"transmission_sig":${JSON.stringify(field("paypal-transmission-sig"))}` +
      `,"transmission_time":${JSON.stringify(field("paypal-transmission-time"))}` +
      `,"webhook_id":${JSON.stringify(process.env.PAYPAL_WEBHOOK_ID!)}` +
      `,"webhook_event":${rawText}}`;
    const result = await call<{ verification_status: "SUCCESS" | "FAILURE" }>(
      "/v1/notifications/verify-webhook-signature",
      { method: "POST", body },
    );
    return result.verification_status === "SUCCESS";
  },
};

// Call with the root app, not through app.register(): a decoration made
// inside a registered plugin is visible only to that plugin's own routes.
export function paypalPlugin(app: App) {
  app.decorate("paypal", paypalClient);
}

declare module "@daloyjs/core" {
  interface AppState {
    paypal: PayPalClient;
  }
}

import { z } from "zod";
import { ConflictError, HttpError, idempotency } from "@daloyjs/core";
import { paypalPlugin, PayPalApiError } from "../plugins/paypal.ts";
import { orders } from "../orders.ts";
import { db } from "../db.ts";

paypalPlugin(app);

const providerError = () =>
  new HttpError(502, {
    type: "https://your-app.example.com/problems/payment-provider",
    title: "Payment provider error",
    detail: "The payment could not be completed. Please try again.",
  });

app.post(
  "/checkout/paypal/orders",
  {
    operationId: "createPayPalOrder",
    hooks: idempotency({ scope: (ctx) => ctx.state.session.get<string>("userId") }),
    request: { body: z.object({ orderId: z.string().min(1).max(80) }).strict() },
    responses: {
      201: { description: "PayPal order created", body: z.object({ paypalOrderId: z.string() }) },
    },
  },
  async ({ body, state }) => {
    const order = await orders.forCheckout(body.orderId, state.session.get<string>("userId"));
    try {
      const paypalOrder = await state.paypal.createOrder({
        orderId: order.id,
        amountMinor: order.amountMinor, // server-side total
        currency: order.currency,
        // Same order + same cart version = same PayPal order on a retry.
        requestId: `create:${order.id}:v${order.version}`,
      });
      await db.orders.setProviderRef(order.id, paypalOrder.id);
      return { status: 201, body: { paypalOrderId: paypalOrder.id } };
    } catch (e) {
      if (e instanceof PayPalApiError) {
        app.log.warn({ event: "paypal.create_failed", status: e.status, debugId: e.debugId, issue: e.issue }, "PayPal rejected the order");
        throw providerError();
      }
      throw e;
    }
  },
);

app.post(
  "/checkout/paypal/capture",
  {
    operationId: "capturePayPalOrder",
    request: { body: z.object({ orderId: z.string().min(1).max(80) }).strict() },
    responses: {
      200: { description: "capture submitted", body: z.object({ status: z.string() }) },
    },
  },
  async ({ body, state }) => {
    const order = await orders.forCheckout(body.orderId, state.session.get<string>("userId"));
    if (!order.providerRef) throw new ConflictError("Start PayPal checkout first.");
    try {
      const captured = await state.paypal.captureOrder(order.providerRef, `capture:${order.id}:v${order.version}`);
      // A UX answer only. The webhook worker marks the order paid after the amount check.
      return { status: 200, body: { status: captured.status } };
    } catch (e) {
      if (e instanceof PayPalApiError) {
        // INSTRUMENT_DECLINED means the buyer can pick another funding source; map it to your own message.
        app.log.warn({ event: "paypal.capture_failed", status: e.status, debugId: e.debugId, issue: e.issue }, "PayPal capture failed");
        throw providerError();
      }
      throw e;
    }
  },
);

// Loaded by <script async src="https://www.sandbox.paypal.com/web-sdk/v6/core"></script>
// (https://www.paypal.com/web-sdk/v6/core in live).
export async function mountPayPal(orderId: string, csrfToken: string, clientId: string) {
  const post = (path: string) =>
    fetch(path, {
      method: "POST",
      headers: { "content-type": "application/json", "x-csrf-token": csrfToken },
      body: JSON.stringify({ orderId }),
    }).then((res) => {
      if (!res.ok) throw new Error("PayPal checkout failed");
      return res.json();
    });

  const sdk = await window.paypal.createInstance({ clientId, components: ["paypal-payments"], pageType: "checkout" });
  const session = sdk.createPayPalOneTimePaymentSession({
    onApprove: async () => {
      await post("/checkout/paypal/capture"); // the server captures its own stored PayPal order
      window.location.assign(`/checkout/thanks?order=${encodeURIComponent(orderId)}`);
    },
  });

  document.querySelector("#paypal-button")!.addEventListener("click", async () => {
    const createOrder = () => post("/checkout/paypal/orders").then((data) => ({ orderId: data.paypalOrderId }));
    // Pass the promise, not the function reference.
    await session.start({ presentationMode: "auto" }, createOrder());
  });
}

import { z } from "zod";
import { readBodyLimited, safeJsonParse, jobIdempotencyKey } from "@daloyjs/core";

app.post(
  "/webhooks/paypal",
  {
    operationId: "paypalWebhook",
    // No request.body schema: the raw bytes stay readable for verification.
    responses: {
      200: { description: "ack", body: z.object({ ok: z.literal(true) }) },
      401: { description: "bad signature", body: z.object({ error: z.string() }) },
    },
  },
  async ({ request, state }) => {
    const rawText = new TextDecoder().decode(await readBodyLimited(request, 1_048_576));
    // Throws BadRequestError (400) on anything that is not valid JSON.
    const event = safeJsonParse(rawText) as { id?: string; event_type?: string; resource?: { id?: string } };

    if (!(await state.paypal.verifyWebhook(request.headers, rawText))) {
      return { status: 401, body: { error: "invalid signature" } };
    }
    if (!event.id) return { status: 401, body: { error: "missing event id" } };

    if (event.event_type?.startsWith("PAYMENT.CAPTURE.") && event.resource?.id) {
      await app.jobs!.enqueue({
        name: "paypal.capture",
        payload: { eventId: event.id, captureId: event.resource.id },
        idempotencyKey: jobIdempotencyKey({ name: "paypal.capture", key: event.id }),
      });
    }
    // Ack every verified event, including types you do not handle.
    return { status: 200, body: { ok: true as const } };
  },
);

import type { JobHandler } from "@daloyjs/core";
import { paypalClient } from "../plugins/paypal.ts";
import { orders } from "../orders.ts";
import { toMinor } from "../money.ts";

export const handlePayPalCapture: JobHandler<{ eventId: string; captureId: string }> = async ({ job }) => {
  const capture = await paypalClient.getCapture(job.payload.captureId); // authoritative state
  if (capture.status !== "COMPLETED" || !capture.custom_id) return; // PENDING: wait for the next event
  await orders.markPaid(capture.custom_id, {
    amountMinor: toMinor(capture.amount.value, capture.amount.currency_code),
    currency: capture.amount.currency_code,
    providerRef: capture.id,
  });
};
// Register it in your single app.useJobs() call (see the payments overview).

import { X509Certificate, verify } from "node:crypto";
import { crc32 } from "node:zlib";
import { fetchGuard } from "@daloyjs/core";

// The cert URL arrives in an attacker-controllable header. Only fetch it from
// PayPal's API hosts over HTTPS, through fetchGuard, with redirects refused.
const CERT_HOSTS = new Set(["api.paypal.com", "api.sandbox.paypal.com", "api-m.paypal.com", "api-m.sandbox.paypal.com"]);
const certFetch = fetchGuard({ maxRedirects: 0 });
const certCache = new Map<string, X509Certificate>();

async function loadCert(certUrl: string): Promise<X509Certificate | null> {
  let url: URL;
  try {
    url = new URL(certUrl);
  } catch {
    return null;
  }
  if (url.protocol !== "https:" || !CERT_HOSTS.has(url.hostname) || !url.pathname.startsWith("/v1/notifications/certs/")) return null;
  const cached = certCache.get(url.href);
  if (cached) return cached;
  const res = await certFetch(url.href);
  if (!res.ok) return null;
  const cert = new X509Certificate(await res.text());
  const now = Date.now();
  if (now < Date.parse(cert.validFrom) || now > Date.parse(cert.validTo)) return null;
  if (certCache.size > 16) certCache.clear(); // bounded: PayPal rotates certificates rarely
  certCache.set(url.href, cert);
  return cert;
}

export async function selfVerifyPayPalWebhook(headers: Headers, raw: Uint8Array): Promise<boolean> {
  const id = headers.get("paypal-transmission-id");
  const time = headers.get("paypal-transmission-time");
  const sig = headers.get("paypal-transmission-sig");
  const certUrl = headers.get("paypal-cert-url");
  if (!id || !time || !sig || !certUrl || headers.get("paypal-auth-algo") !== "SHA256withRSA") return false;
  const cert = await loadCert(certUrl);
  if (!cert) return false;
  const message = `${id}|${time}|${process.env.PAYPAL_WEBHOOK_ID}|${crc32(raw)}`;
  return verify("sha256", Buffer.from(message), cert.publicKey, Buffer.from(sig, "base64"));
}

await state.paypal.refundCapture({
  captureId: order.providerRef!, // the capture id saved by orders.markPaid()
  amountMinor: 250,
  currency: order.currency,
  requestId: `refund:${order.id}:${order.refundedMinor}:250`,
});

import { CheckoutPaymentIntent, Client, Environment, OrdersController } from "@paypal/paypal-server-sdk";
import { formatMinor } from "../money.ts";

const client = new Client({
  clientCredentialsAuthCredentials: {
    oAuthClientId: process.env.PAYPAL_CLIENT_ID!,
    oAuthClientSecret: process.env.PAYPAL_CLIENT_SECRET!,
  },
  environment: process.env.PAYPAL_ENVIRONMENT === "live" ? Environment.Production : Environment.Sandbox,
});
const ordersApi = new OrdersController(client);

export async function createOrder(order: { id: string; amountMinor: number; currency: string; version: number }) {
  const { result } = await ordersApi.createOrder({
    body: {
      intent: CheckoutPaymentIntent.Capture,
      purchaseUnits: [
        {
          referenceId: order.id,
          customId: order.id,
          amount: { currencyCode: order.currency, value: formatMinor(order.amountMinor, order.currency) },
        },
      ],
    },
    paypalRequestId: `create:${order.id}:v${order.version}`,
  });
  return result;
}