kempo-payments 0.1.1

package/server/utils/payments/actions.js

@@ -0,0 +1,149 @@
+import { providerForPayment } from '../../providers/index.js';
+import { formatAmount } from '../money/currencies.js';
+import { hasNulByte } from './text.js';
+import { canCancel, canCapture, refundableAmount } from './statuses.js';
+import { getPayment } from './store.js';
+import { applyProviderState, applyRefunds } from './sync.js';
+
+/*
+  The three things somebody does to a payment after it exists: take the money that was held,
+  release it, or give it back.
+
+  Each of them goes back to the processor the payment was originally made through, not the one the
+  site is configured to use now. Money that is sitting at Stripe is not refundable by PayPal, and a
+  site that switched processors last month still has last month's payments to answer for.
+*/
+
+/*
+  Turns an authorisation into a charge.
+
+  Only meaningful for a manual-capture payment. An automatic one was already charged when the
+  customer confirmed it, and asking the processor to capture it returns an error whose wording
+  ("payment_intent_unexpected_state") explains nothing to the person who pressed the button — so
+  the refusal happens here, in words.
+*/
+export const capturePayment = async (id, { amount } = {}) => {
+  const [loadError, payment] = await getPayment(id);
+  if(loadError) return [loadError, null];
+
+  if(!canCapture(payment)){
+    return [{
+      code: 409,
+      msg: payment.captureMethod === 'automatic'
+        ? 'This payment was charged when the customer confirmed it — there is nothing left to capture'
+        : `A payment can only be captured while it is awaiting capture, and this one is ${payment.status.replace(/_/g, ' ')}`,
+    }, null];
+  }
+
+  /*
+    Capturing less than was authorised is allowed and normal — an order that shipped short. More is
+    not: the hold is for a fixed amount and the customer never agreed to anything above it.
+  */
+  if(amount !== undefined && amount !== null){
+    if(!Number.isInteger(amount) || amount <= 0){
+      return [{ code: 400, msg: 'A capture amount must be a whole number of the currency’s smallest unit' }, null];
+    }
+    if(amount > payment.amount){
+      return [{ code: 400, msg: 'Cannot capture more than was authorised' }, null];
+    }
+  }
+
+  const [providerError, provider] = providerForPayment(payment);
+  if(providerError) return [providerError, null];
+
+  const [captureError, state] = await provider.capture(payment.providerRef, { amount });
+  if(captureError) return [captureError, null];
+
+  return applyProviderState(payment, state);
+};
+
+/*
+  Releases a payment that has not been taken.
+
+  Not a refund: nothing has moved, so nothing comes back. The hold on the customer's card
+  disappears — though their bank may take a few days to stop showing it, which is worth saying on
+  screen because it is the single most common "you charged me twice" support ticket.
+*/
+export const cancelPayment = async id => {
+  const [loadError, payment] = await getPayment(id);
+  if(loadError) return [loadError, null];
+
+  if(!canCancel(payment)){
+    return [{ code: 409, msg: `This payment is already ${payment.status.replace(/_/g, ' ')}` }, null];
+  }
+
+  const [providerError, provider] = providerForPayment(payment);
+  if(providerError) return [providerError, null];
+
+  const [cancelError, state] = await provider.cancel(payment.providerRef);
+  if(cancelError) return [cancelError, null];
+
+  return applyProviderState(payment, state);
+};
+
+/*
+  Gives money back, in full or in part.
+
+  Omitting the amount refunds everything still outstanding, which is what a "Refund" button should
+  do and what most callers want. Passing one refunds exactly that much, and several partial refunds
+  can be issued until the outstanding amount reaches zero.
+*/
+export const refundPayment = async (id, { amount, reason, issuedBy } = {}) => {
+  // Checked before the processor is asked: once it has refunded, a failed insert is a refund nobody recorded.
+  if(hasNulByte(reason, issuedBy)){
+    return [{ code: 400, msg: 'A refund reason cannot contain null characters' }, null];
+  }
+
+  const [loadError, payment] = await getPayment(id);
+  if(loadError) return [loadError, null];
+
+  const outstanding = refundableAmount(payment);
+
+  if(!outstanding){
+    return [{
+      code: 409,
+      msg: payment.status === 'requires_capture'
+        ? 'Nothing has been charged yet — cancel the payment to release the hold instead'
+        : payment.status === 'succeeded'
+          ? 'This payment has already been refunded in full'
+          : `A payment can only be refunded once it has succeeded, and this one is ${payment.status.replace(/_/g, ' ')}`,
+    }, null];
+  }
+
+  const requested = amount === undefined || amount === null ? outstanding : amount;
+
+  if(!Number.isInteger(requested) || requested <= 0){
+    return [{ code: 400, msg: 'A refund amount must be a whole number of the currency’s smallest unit' }, null];
+  }
+  if(requested > outstanding){
+    return [{ code: 400, msg: `Only ${formatAmount(outstanding, payment.currency)} is left to refund on this payment` }, null];
+  }
+
+  const [providerError, provider] = providerForPayment(payment);
+  if(providerError) return [providerError, null];
+
+  const [refundError, refund] = await provider.refund(payment.providerRef, { amount: requested, reason });
+  if(refundError) return [refundError, null];
+
+  return applyRefunds(payment, [refund], { issuedBy });
+};
+
+/*
+  The client secret for a payment that is already in flight, fetched fresh from the processor.
+
+  A checkout page that was reloaded, or a customer coming back to finish paying, needs this to
+  mount the payment form again — and it is deliberately not something the payment row carries
+  around, so it is here rather than on every read.
+*/
+export const getClientSecret = async id => {
+  const [loadError, payment] = await getPayment(id);
+  if(loadError) return [loadError, null];
+
+  const [providerError, provider] = providerForPayment(payment);
+  if(providerError) return [providerError, null];
+
+  const [fetchError, state] = await provider.retrieveIntent(payment.providerRef);
+  if(fetchError) return [fetchError, null];
+
+  return [null, { payment, clientSecret: state.clientSecret }];
+};

package/server/utils/payments/create.js

@@ -0,0 +1,116 @@
+import { activeProvider } from '../../providers/index.js';
+import { isValidAmount, isValidCurrency, normaliseCurrency } from '../money/currencies.js';
+import { CAPTURE_METHODS, parseCaptureMethod, readConfig } from '../config/settings.js';
+import { insertPayment, newId } from './store.js';
+import { firePaymentCreated } from './sync.js';
+import { hasNulByte } from './text.js';
+
+/*
+  Starting a payment: ask the processor for an intent, write down what it said, hand back the one
+  piece the browser needs.
+
+  The client secret is returned and never stored. It is short-lived, it is derivable from the
+  processor at any time, and a copy in the database is one more place it can leak from for no
+  benefit at all — `getClientSecret` re-fetches it when a page needs it again.
+*/
+
+export const createPayment = async ({
+  amount,
+  currency,
+  description = null,
+  metadata = null,
+  captureMethod = null,
+  owner = null,
+  reference = null,
+  userId = null,
+  customerEmail = null,
+} = {}) => {
+  if(hasNulByte(description, metadata, owner, reference, userId, customerEmail)){
+    return [{ code: 400, msg: 'Payment details cannot contain null characters' }, null];
+  }
+
+  /*
+    A capture method the caller actually passed is validated, never guessed at — and before any
+    provider is contacted. Falling back to the site default here would turn a mistyped "hold this
+    card" into "charge this card", which is the one direction this parameter must never fail in.
+  */
+  let method = null;
+  if(captureMethod){
+    method = parseCaptureMethod(captureMethod);
+    if(!method) return [{ code: 400, msg: `Capture method must be one of: ${CAPTURE_METHODS.join(', ')}` }, null];
+  }
+
+  const config = await readConfig();
+  method ??= config.captureMethod;
+  const code = normaliseCurrency(currency || config.currency);
+
+  /*
+    Validated here rather than left to the processor. A caller that passes 12.99 instead of 1299 is
+    charging a hundredth of what it meant to, and Stripe would take that instruction happily — it
+    is a perfectly valid amount, just not the one anybody intended. Refusing a non-integer is the
+    only place that mistake can be caught.
+  */
+  if(!isValidCurrency(code)){
+    return [{ code: 400, msg: `"${currency}" is not a currency code` }, null];
+  }
+  if(!Number.isInteger(amount)){
+    return [{ code: 400, msg: 'Amount must be a whole number of the currency’s smallest unit — 1299 for $12.99' }, null];
+  }
+  if(!isValidAmount(amount, code)){
+    return [{ code: 400, msg: `${amount} is not a chargeable amount in ${code.toUpperCase()}` }, null];
+  }
+
+  const [providerError, provider] = await activeProvider();
+  if(providerError) return [providerError, null];
+
+  /*
+    Our id is generated before the intent and sent as the idempotency key, so a request that times
+    out and is retried by the caller lands on the same intent instead of a second one. Two intents
+    for one order is two authorisation holds on a real customer's card.
+  */
+  const id = newId();
+
+  const [intentError, intent] = await provider.createIntent({
+    amount,
+    currency: code,
+    description,
+    metadata: { ...(metadata || {}), kempoPaymentId: id, ...(owner ? { kempoOwner: owner } : {}), ...(reference ? { kempoReference: reference } : {}) },
+    captureMethod: method,
+    customerEmail,
+    idempotencyKey: id,
+  });
+  if(intentError) return [intentError, null];
+
+  const [insertError, payment] = await insertPayment({
+    id,
+    provider: provider.name,
+    providerRef: intent.ref,
+    livemode: intent.livemode,
+    status: intent.status,
+    captureMethod: method,
+    amount,
+    amountCaptured: intent.amountCaptured,
+    currency: code,
+    owner,
+    reference,
+    description,
+    metadata,
+    userId,
+    customerEmail,
+  });
+
+  /*
+    An intent that exists at the processor with no row here is invisible: nothing would ever
+    capture it, refund it or release the hold. Cancelling it is best-effort — if that fails too,
+    the intent expires on its own, and the id is logged so it can be found by hand in the meantime.
+  */
+  if(insertError){
+    const [cancelError] = await provider.cancel(intent.ref);
+    if(cancelError) console.error(`[kempo-payments] Orphaned ${provider.name} intent ${intent.ref} — could not be recorded or cancelled`);
+    return [insertError, null];
+  }
+
+  await firePaymentCreated(payment);
+
+  return [null, { payment, clientSecret: intent.clientSecret }];
+};

package/server/utils/payments/statuses.js

@@ -0,0 +1,55 @@
+/*
+  The status vocabulary every provider maps onto, so that nothing outside server/providers/ ever
+  has to know whose words it is reading.
+
+  These happen to be Stripe's names, which is not laziness — they are the clearest description of
+  the states a card payment actually passes through, and a second processor with fewer states maps
+  into a subset rather than needing new ones. What matters is that the mapping lives in the
+  provider module and this list is the only thing the rest of the extension matches against.
+*/
+export const STATUSES = [
+  'requires_payment_method',  // started; nobody has entered a card yet, or the last one was declined
+  'requires_confirmation',    // a card is attached, waiting to be submitted
+  'requires_action',          // the bank wants the customer to do something — 3-D Secure, usually
+  'processing',               // submitted; the processor has not finished
+  'requires_capture',         // authorised only. The money is held, not taken. Capture or it expires
+  'succeeded',                // taken
+  'canceled',                 // abandoned or released before capture
+  'failed',                   // the processor gave up on it
+];
+
+export const isStatus = status => STATUSES.includes(status);
+
+/*
+  Nothing more will happen to a payment in one of these states without somebody starting a new one.
+  Refunds are not a status change — a fully refunded payment is still `succeeded`, with
+  `amountRefunded === amountCaptured`, because the charge did happen and the money did move twice.
+*/
+export const FINAL = new Set(['succeeded', 'canceled', 'failed']);
+
+export const isFinal = status => FINAL.has(status);
+
+/*
+  A payment still expecting something from the customer's browser. The distinction the checkout UI
+  cares about: these are the states where showing the payment form again is the right thing to do,
+  and every other state is one where it is not.
+*/
+export const AWAITING_CUSTOMER = new Set(['requires_payment_method', 'requires_confirmation', 'requires_action']);
+
+export const isAwaitingCustomer = status => AWAITING_CUSTOMER.has(status);
+
+export const canCapture = payment =>
+  payment?.captureMethod === 'manual' && payment?.status === 'requires_capture';
+
+export const canCancel = payment =>
+  !isFinal(payment?.status);
+
+/*
+  What is left to give back. A payment that was only authorised has nothing to refund — releasing
+  the hold is a cancel, not a refund, and offering the wrong one produces a processor error the
+  person reading it cannot act on.
+*/
+export const refundableAmount = payment => {
+  if(payment?.status !== 'succeeded') return 0;
+  return Math.max(0, (payment.amountCaptured || 0) - (payment.amountRefunded || 0));
+};

package/server/utils/payments/store.js

@@ -0,0 +1,250 @@
+import crypto from 'crypto';
+import { and, desc, eq, inArray, sql } from 'drizzle-orm';
+import db from 'kempo/server/db/index.js';
+import { kempoPayment, kempoPaymentRefund } from '../../db/schema.js';
+import { hasNulByte } from './text.js';
+
+/*
+  Every read and write of this extension's own rows, and nothing else. No provider calls, no
+  permission checks, no hooks — those belong to the layers either side, and keeping them out is
+  what lets the data-layer test suite exercise all of this against a real database without a Stripe
+  account existing anywhere.
+*/
+
+export const newId = () => crypto.randomBytes(8).toString('hex');
+
+export const getPayment = async id => {
+  if(!id) return [{ code: 400, msg: 'A payment id is required' }, null];
+
+  try {
+    const [row] = await db.select().from(kempoPayment).where(eq(kempoPayment.id, id)).limit(1);
+    if(!row) return [{ code: 404, msg: 'No such payment' }, null];
+    return [null, row];
+  } catch {
+    return [{ code: 500, msg: 'Could not load the payment' }, null];
+  }
+};
+
+/*
+  The lookup a webhook needs: the processor knows its own id for a payment and nothing about ours.
+*/
+export const getPaymentByRef = async (provider, providerRef) => {
+  if(!provider || !providerRef) return [{ code: 400, msg: 'A provider and reference are required' }, null];
+
+  try {
+    const [row] = await db.select().from(kempoPayment)
+      .where(and(eq(kempoPayment.provider, provider), eq(kempoPayment.providerRef, providerRef)))
+      .limit(1);
+    if(!row) return [{ code: 404, msg: 'No such payment' }, null];
+    return [null, row];
+  } catch {
+    return [{ code: 500, msg: 'Could not load the payment' }, null];
+  }
+};
+
+/*
+  The lookup a consumer extension needs: it knows its own order number, not a payment id. Newest
+  first, because a retried checkout leaves earlier abandoned attempts against the same reference
+  and the live one is the last.
+*/
+export const paymentsForReference = async (owner, reference) => {
+  if(!owner || !reference) return [{ code: 400, msg: 'An owner and reference are required' }, null];
+
+  try {
+    const rows = await db.select().from(kempoPayment)
+      .where(and(eq(kempoPayment.owner, owner), eq(kempoPayment.reference, reference)))
+      .orderBy(desc(kempoPayment.createdAt));
+    return [null, rows];
+  } catch {
+    return [{ code: 500, msg: 'Could not load payments for that reference' }, null];
+  }
+};
+
+export const insertPayment = async values => {
+  const now = new Date();
+  const row = {
+    id: values.id || newId(),
+    provider: values.provider,
+    providerRef: values.providerRef,
+    livemode: !!values.livemode,
+    status: values.status,
+    captureMethod: values.captureMethod || 'automatic',
+    amount: values.amount,
+    amountCaptured: values.amountCaptured || 0,
+    amountRefunded: values.amountRefunded || 0,
+    currency: values.currency,
+    owner: values.owner || null,
+    reference: values.reference || null,
+    description: values.description || null,
+    metadata: values.metadata || null,
+    userId: values.userId || null,
+    customerEmail: values.customerEmail || null,
+    lastError: values.lastError || null,
+    disputed: false,
+    createdAt: now,
+    updatedAt: now,
+  };
+
+  try {
+    await db.insert(kempoPayment).values(row);
+    return [null, row];
+  } catch {
+    return [{ code: 500, msg: 'Could not record the payment' }, null];
+  }
+};
+
+export const updatePayment = async (id, changes) => {
+  try {
+    const [row] = await db.update(kempoPayment)
+      .set({ ...changes, updatedAt: new Date() })
+      .where(eq(kempoPayment.id, id))
+      .returning();
+    if(!row) return [{ code: 404, msg: 'No such payment' }, null];
+    return [null, row];
+  } catch {
+    return [{ code: 500, msg: 'Could not update the payment' }, null];
+  }
+};
+
+/*
+  Filtered, paged, newest first. `status` accepts a list so the admin screen can offer "needs
+  attention" as one filter rather than making somebody look at four.
+*/
+export const listPayments = async ({ status, provider, owner, reference, userId, limit = 50, offset = 0 } = {}) => {
+  if(hasNulByte(status, provider, owner, reference, userId)){
+    return [{ code: 400, msg: 'Filters cannot contain null characters' }, null];
+  }
+
+  const conditions = [];
+  if(status) conditions.push(Array.isArray(status) ? inArray(kempoPayment.status, status) : eq(kempoPayment.status, status));
+  if(provider) conditions.push(eq(kempoPayment.provider, provider));
+  if(owner) conditions.push(eq(kempoPayment.owner, owner));
+  if(reference) conditions.push(eq(kempoPayment.reference, reference));
+  if(userId) conditions.push(eq(kempoPayment.userId, userId));
+
+  const where = conditions.length ? and(...conditions) : undefined;
+  const take = Math.min(200, Math.max(1, Number(limit) || 50));
+  const skip = Math.max(0, Number(offset) || 0);
+
+  try {
+    const rows = await db.select().from(kempoPayment)
+      .where(where)
+      .orderBy(desc(kempoPayment.createdAt))
+      .limit(take)
+      .offset(skip);
+
+    const [counted] = await db.select({ total: sql`count(*)::int` }).from(kempoPayment).where(where);
+
+    return [null, { payments: rows, total: counted?.total ?? rows.length, limit: take, offset: skip }];
+  } catch {
+    return [{ code: 500, msg: 'Could not list payments' }, null];
+  }
+};
+
+/*
+  What the admin screen puts across the top. One grouped query rather than one per status, and the
+  gross/net pair kept separate on purpose — a day with £1,000 taken and £900 refunded is not the
+  same day as one with £100 taken, and a single "total" would show them identically.
+*/
+export const summary = async () => {
+  try {
+    const rows = await db.select({
+      status: kempoPayment.status,
+      currency: kempoPayment.currency,
+      count: sql`count(*)::int`,
+      captured: sql`coalesce(sum(${kempoPayment.amountCaptured}), 0)::int`,
+      refunded: sql`coalesce(sum(${kempoPayment.amountRefunded}), 0)::int`,
+    })
+      .from(kempoPayment)
+      .groupBy(kempoPayment.status, kempoPayment.currency);
+
+    const [disputes] = await db.select({ count: sql`count(*)::int` })
+      .from(kempoPayment)
+      .where(eq(kempoPayment.disputed, true));
+
+    return [null, { byStatus: rows, disputed: disputes?.count ?? 0 }];
+  } catch {
+    return [{ code: 500, msg: 'Could not summarise payments' }, null];
+  }
+};
+
+export const listRefunds = async paymentId => {
+  try {
+    const rows = await db.select().from(kempoPaymentRefund)
+      .where(eq(kempoPaymentRefund.paymentId, paymentId))
+      .orderBy(desc(kempoPaymentRefund.createdAt));
+    return [null, rows];
+  } catch {
+    return [{ code: 500, msg: 'Could not load refunds' }, null];
+  }
+};
+
+/*
+  Records a refund, or updates the one already recorded for the same provider reference.
+
+  Both paths reach here: the admin issuing one, and a webhook reporting one — including refunds
+  nobody here issued at all, made from the processor's own dashboard. Keying on the provider's
+  reference is what stops those two accounts of the same refund becoming two rows.
+*/
+export const recordRefund = async ({ paymentId, provider, providerRef, amount, currency, status, reason, issuedBy }) => {
+  const now = new Date();
+
+  try {
+    const [existing] = await db.select().from(kempoPaymentRefund)
+      .where(and(eq(kempoPaymentRefund.provider, provider), eq(kempoPaymentRefund.providerRef, providerRef)))
+      .limit(1);
+
+    if(existing){
+      const [row] = await db.update(kempoPaymentRefund)
+        .set({
+          status,
+          amount,
+          // A refund made in the dashboard has no kempo user behind it; one already attributed
+          // keeps whoever issued it rather than being blanked by the webhook that follows.
+          issuedBy: existing.issuedBy || issuedBy || null,
+          reason: existing.reason || reason || null,
+          updatedAt: now,
+        })
+        .where(eq(kempoPaymentRefund.id, existing.id))
+        .returning();
+      return [null, row];
+    }
+
+    const row = {
+      id: newId(),
+      paymentId,
+      provider,
+      providerRef,
+      amount,
+      currency,
+      status,
+      reason: reason || null,
+      issuedBy: issuedBy || null,
+      createdAt: now,
+      updatedAt: now,
+    };
+    await db.insert(kempoPaymentRefund).values(row);
+    return [null, row];
+  } catch {
+    return [{ code: 500, msg: 'Could not record the refund' }, null];
+  }
+};
+
+/*
+  The refunded total, recomputed from the refund rows rather than incremented.
+
+  Incrementing is what produces a payment that says it has been refunded twice, because the admin
+  action and the webhook that follows it are two reports of one refund. Summing rows that are
+  themselves deduplicated by provider reference cannot double-count, however many times an event
+  is redelivered.
+*/
+export const refundedTotal = async paymentId => {
+  try {
+    const [row] = await db.select({ total: sql`coalesce(sum(${kempoPaymentRefund.amount}), 0)::int` })
+      .from(kempoPaymentRefund)
+      .where(and(eq(kempoPaymentRefund.paymentId, paymentId), inArray(kempoPaymentRefund.status, ['succeeded', 'pending'])));
+    return [null, row?.total ?? 0];
+  } catch {
+    return [{ code: 500, msg: 'Could not total the refunds' }, null];
+  }
+};