Accept payments with Checkout.com in DaloyJS

CKO_SECRET_KEY=sk_sbox_replace_me              # server only
CKO_PUBLIC_KEY=pk_sbox_replace_me              # public, used by Flow
CKO_SUBDOMAIN=replace_me                       # 8-character account prefix
CKO_PROCESSING_CHANNEL_ID=pc_replace_me
CKO_WEBHOOK_SIGNATURE_KEY=replace_me           # Cko-Signature HMAC key
CKO_WEBHOOK_AUTH_KEY=replace_me                # optional Authorization header value
APP_URL=https://your-app.example.com

import { Checkout } from "checkout-sdk-node";
import { timingSafeEqual, verifyWebhookSignature } from "@daloyjs/core";
import type { App } from "@daloyjs/core";

// sk_sbox_ keys select sandbox automatically; sk_ keys select production.
const cko = new Checkout(process.env.CKO_SECRET_KEY!, {
  pk: process.env.CKO_PUBLIC_KEY!,
  subdomain: process.env.CKO_SUBDOMAIN!, // required: the SDK throws without it
});

export interface CkoPaymentSession {
  id: string;
  payment_session_secret: string;
  payment_session_token: string;
}

export interface CkoPayment {
  id: string;
  status: string; // for example "Captured"
  amount: number;
  balances?: { total_captured?: number; total_refunded?: number };
  currency: string;
  reference?: string;
  metadata?: Record<string, string>;
}

export interface CheckoutComClient {
  createPaymentSession(input: {
    orderId: string;
    amountMinor: number;
    currency: string;
    billingCountry: string;
    email?: string;
  }): Promise<CkoPaymentSession>;
  getPayment(paymentId: string): Promise<CkoPayment>;
  refund(input: { paymentId: string; amountMinor: number; reference: string; idempotencyKey: string }): Promise<{ action_id: string }>;
  verifyWebhook(raw: Uint8Array, headers: Headers): Promise<boolean>;
}

// Exported so job handlers (which run outside a request) can use it too.
export const checkoutComClient: CheckoutComClient = {
  async createPaymentSession({ orderId, amountMinor, currency, billingCountry, email }) {
    const base = process.env.APP_URL!;
    return (await cko.paymentSessions.request({
      amount: amountMinor, // minor units, from the stored order
      currency,
      reference: orderId,
      processing_channel_id: process.env.CKO_PROCESSING_CHANNEL_ID!,
      billing: { address: { country: billingCountry } },
      customer: email ? { email } : undefined,
      metadata: { orderId },
      success_url: `${base}/checkout/return?order=${encodeURIComponent(orderId)}`,
      failure_url: `${base}/checkout/failed?order=${encodeURIComponent(orderId)}`,
    })) as CkoPaymentSession;
  },

  async getPayment(paymentId) {
    return (await cko.payments.get(paymentId)) as CkoPayment;
  },

  async refund({ paymentId, amountMinor, reference, idempotencyKey }) {
    return (await cko.payments.refund(paymentId, { amount: amountMinor, reference }, idempotencyKey)) as { action_id: string };
  },

  async verifyWebhook(raw, headers) {
    // Optional second factor: the fixed key set on the webhook configuration.
    const expectedAuth = process.env.CKO_WEBHOOK_AUTH_KEY;
    const authOk = expectedAuth ? timingSafeEqual(headers.get("authorization") ?? "", expectedAuth) : true;
    const sigOk = await verifyWebhookSignature({
      payload: raw,
      signature: headers.get("cko-signature") ?? "", // hex
      secret: process.env.CKO_WEBHOOK_SIGNATURE_KEY!,
      algorithm: "sha256",
    });
    return authOk && sigOk;
  },
};

// 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 checkoutComPlugin(app: App) {
  app.decorate("checkoutCom", checkoutComClient);
}

declare module "@daloyjs/core" {
  interface AppState {
    checkoutCom: CheckoutComClient;
  }
}

import { z } from "zod";
import { HttpError, idempotency } from "@daloyjs/core";
import { checkoutComPlugin } from "../plugins/checkout-com.ts";
import { orders } from "../orders.ts";
import { db } from "../db.ts";

checkoutComPlugin(app);

app.post(
  "/checkout/checkout-com/session",
  {
    operationId: "createCheckoutComPaymentSession",
    // Safe client retries of this POST (scoped per signed-in user).
    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: "payment session",
        body: z.object({ id: z.string(), payment_session_secret: z.string(), payment_session_token: z.string() }),
      },
    },
  },
  async ({ body, state }) => {
    const userId = state.session.get<string>("userId");
    const order = await orders.forCheckout(body.orderId, userId);
    const customer = await db.users.billingProfile(userId!); // country (and email) from your records
    try {
      const session = await state.checkoutCom.createPaymentSession({
        orderId: order.id,
        amountMinor: order.amountMinor,
        currency: order.currency,
        billingCountry: customer.country,
        email: customer.email,
      });
      return {
        status: 201,
        body: { id: session.id, payment_session_secret: session.payment_session_secret, payment_session_token: session.payment_session_token },
      };
    } catch (e) {
      const err = e as { name?: string; http_code?: number; body?: { request_id?: string; error_codes?: string[] } };
      // Keep Checkout.com's request id and error codes in your logs, not in the response.
      app.log.warn(
        { event: "cko.session_failed", name: err.name, status: err.http_code, requestId: err.body?.request_id, codes: err.body?.error_codes },
        "Checkout.com rejected the payment session",
      );
      throw new HttpError(502, {
        type: "https://your-app.example.com/problems/payment-provider",
        title: "Payment provider error",
        detail: "Checkout could not be started. Please try again.",
      });
    }
  },
);

// <script src="https://checkout-web-components.checkout.com/index.js"></script>
export async function mountFlow(orderId: string, csrfToken: string) {
  const res = await fetch("/checkout/checkout-com/session", {
    method: "POST",
    headers: { "content-type": "application/json", "x-csrf-token": csrfToken, "idempotency-key": `cko-${orderId}` },
    body: JSON.stringify({ orderId }),
  });
  if (!res.ok) throw new Error("Could not start checkout");
  const paymentSession = await res.json();

  const checkout = await window.CheckoutWebComponents({
    paymentSession,
    publicKey: process.env.NEXT_PUBLIC_CKO_PUBLIC_KEY!,
    environment: "sandbox", // "production" in live
    onPaymentCompleted: () => window.location.assign(`/checkout/thanks?order=${encodeURIComponent(orderId)}`),
    onError: (_component, error) => console.error("Flow error", error),
  });
  checkout.create("flow").mount("#flow-container");
}

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

app.post(
  "/webhooks/checkout-com",
  {
    operationId: "checkoutComWebhook",
    // No request.body schema: the raw bytes stay readable for the HMAC check.
    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 raw = await readBodyLimited(request, 1_048_576);
    if (!(await state.checkoutCom.verifyWebhook(raw, request.headers))) {
      return { status: 401, body: { error: "invalid signature" } };
    }
    const event = safeJsonParse(new TextDecoder().decode(raw)) as { id?: string; type?: string; data?: { id?: string } };
    if (!event.id) return { status: 401, body: { error: "missing event id" } };

    if (event.type?.startsWith("payment_") && event.data?.id) {
      await app.jobs!.enqueue({
        name: "checkout_com.payment",
        payload: { eventId: event.id, type: event.type, paymentId: event.data.id },
        idempotencyKey: jobIdempotencyKey({ name: "checkout_com.payment", 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 { checkoutComClient } from "../plugins/checkout-com.ts";
import { orders } from "../orders.ts";

export const handleCheckoutComPayment: JobHandler<{ eventId: string; paymentId: string }> = async ({ job }) => {
  const payment = await checkoutComClient.getPayment(job.payload.paymentId); // authoritative state
  const orderId = payment.metadata?.orderId ?? payment.reference;
  // balances survive later state changes (a partial refund moves status past "Captured").
  const captured = payment.balances?.total_captured ?? 0;
  if (captured === 0 || !orderId) return;
  await orders.markPaid(orderId, {
    amountMinor: captured,
    currency: payment.currency,
    providerRef: payment.id,
  });
};
// Register it in your single app.useJobs() call (see the payments overview).

const refundKey = await db.refunds.idempotencyKeyFor(order.id, order.refundedMinor, 250); // a stored crypto.randomUUID()
await state.checkoutCom.refund({
  paymentId: order.providerRef!,
  amountMinor: 250,
  reference: `refund-${order.id}`,
  idempotencyKey: refundKey,
});

const hpp = (await cko.hostedPayments.create({
  amount: order.amountMinor,
  currency: order.currency,
  reference: order.id,
  processing_channel_id: process.env.CKO_PROCESSING_CHANNEL_ID!,
  billing: { address: { country: customer.country } },
  metadata: { orderId: order.id },
  success_url: `${process.env.APP_URL}/checkout/return?order=${encodeURIComponent(order.id)}`,
  failure_url: `${process.env.APP_URL}/checkout/failed?order=${encodeURIComponent(order.id)}`,
  cancel_url: `${process.env.APP_URL}/cart`,
})) as { id: string; _links: { redirect: { href: string } } };
// return { status: 201, body: { redirectUrl: hpp._links.redirect.href } }