@birtalanrobert/commerce 1.0.0

package/src/nestjs/payout-account.entity.ts

@@ -0,0 +1,56 @@
+import { Column, Entity, Index, Unique } from 'typeorm';
+import { BaseEntity } from '@birtalanrobert/database';
+import type { PayoutStatus } from '../deposits';
+
+/**
+ * Where a business's money goes, and whether the provider will send it yet.
+ *
+ * **We never hold anybody's funds.** A customer pays the business directly and
+ * our fee is taken on top as an application fee — which is a hard architectural
+ * rule rather than a preference, because holding third-party money turns a
+ * software company into a regulated payments business.
+ *
+ * The consequence is this table. Until the provider has verified who the
+ * business is, there is nowhere for a payment to land, so every product that
+ * takes money on somebody's behalf has to gate its selling on the same fact.
+ */
+@Entity('mortar_payout_accounts')
+@Unique('uq_payout_accounts_tenant', ['tenantId', 'provider'])
+@Index('ix_payout_accounts_external', ['provider', 'externalId'])
+export class PayoutAccount extends BaseEntity {
+  @Column('uuid')
+  tenantId!: string;
+
+  /**
+   * Which provider this account is with.
+   *
+   * A column rather than an assumption, because the markets differ: a local
+   * processor with faster onboarding beats a lower fee for a restaurant that
+   * wants to be live this afternoon, and one of the seventeen will need one.
+   */
+  @Column('varchar', { length: 32, default: 'stripe' })
+  provider!: string;
+
+  /** The provider's own identifier for the account. */
+  @Column('varchar', { length: 128 })
+  externalId!: string;
+
+  @Column('varchar', { length: 16, default: 'pending' })
+  status!: PayoutStatus;
+
+  /**
+   * What the provider still wants, in its own words.
+   *
+   * Kept verbatim rather than translated into a status of ours. "We need a
+   * photograph of the director's identity document" is actionable; "restricted"
+   * is a support conversation, and the difference is a business that finishes
+   * onboarding on a Sunday evening rather than on Tuesday when somebody
+   * telephones them.
+   */
+  @Column('jsonb', { default: () => `'[]'::jsonb` })
+  requirements!: string[];
+
+  /** Set the first time the provider said it would pay out. */
+  @Column('timestamptz', { nullable: true })
+  readyAt!: Date | null;
+}

package/src/providers/port.ts

@@ -0,0 +1,108 @@
+/**
+ * What a payment provider has to be able to do, and nothing more.
+ *
+ * A port rather than the vendor's client, for the reason `@birtalanrobert/files`
+ * has one over S3: the day a market needs a local processor — and one will,
+ * because a restaurant that can be onboarded this afternoon beats a lower fee —
+ * nothing above this interface moves.
+ *
+ * Deliberately small. Everything that can be decided without the provider is
+ * decided without it: what a deposit comes to, whether a business may sell yet,
+ * what a refund leaves. This is only the part that genuinely needs somebody
+ * else's money-moving licence.
+ */
+
+/** Where a business's money goes, as the provider knows it. */
+export interface ProviderAccount {
+  readonly externalId: string;
+  readonly status: 'pending' | 'restricted' | 'ready';
+  /** What the provider still wants, in its own words. */
+  readonly requirements: readonly string[];
+}
+
+export interface OnboardingLink {
+  readonly url: string;
+  readonly expiresAt: Date;
+}
+
+export interface ChargeRequest {
+  /** The business being paid, as the provider knows it. */
+  readonly account: string;
+  readonly amount: number;
+  readonly currency: string;
+  /** Our cut, taken on top rather than out of the business's money. */
+  readonly applicationFee: number;
+  /** What it is for, carried through so a webhook can be matched back. */
+  readonly subject: string;
+  /**
+   * Whether to take the money now or only hold it.
+   *
+   * Holding is the anti-no-show mechanism: a card is authorised and charged
+   * only if a fee is actually applied, and **that decision is a human one**.
+   */
+  readonly capture: boolean;
+  readonly description?: string;
+  /** An idempotency key, so a retried request does not charge twice. */
+  readonly reference: string;
+}
+
+export interface ChargeResult {
+  readonly externalId: string;
+  readonly state: 'pending' | 'authorized' | 'captured' | 'failed';
+  /**
+   * Where to send the customer to finish, when the provider needs them.
+   *
+   * 3-D Secure and bank redirects are the ordinary case in both target
+   * markets rather than an exception, so a charge that returns a URL is not a
+   * failure and must not be handled as one.
+   */
+  readonly redirectUrl?: string;
+  readonly instrument?: string;
+  readonly detail?: string;
+}
+
+export interface RefundRequest {
+  readonly externalId: string;
+  readonly amount: number;
+  readonly reason: string;
+  readonly reference: string;
+}
+
+/** What a provider's webhook turned out to be about. */
+export interface ProviderEvent {
+  readonly kind: 'payment' | 'account' | 'other';
+  readonly externalId: string;
+  readonly state?: 'authorized' | 'captured' | 'failed' | 'refunded';
+  readonly accountStatus?: ProviderAccount;
+  readonly instrument?: string;
+  readonly detail?: string;
+}
+
+export interface PaymentProvider {
+  readonly name: string;
+
+  /** Starts or resumes onboarding, and says where to send the business. */
+  onboard(tenantId: string, returnUrl: string, refreshUrl: string): Promise<OnboardingLink>;
+
+  /** Creates the account if there is none, and reports where it stands. */
+  account(externalId: string | null, country: string, email?: string): Promise<ProviderAccount>;
+
+  charge(request: ChargeRequest): Promise<ChargeResult>;
+
+  /** Takes money that was only held. The human decision has been made. */
+  capture(externalId: string, amount?: number): Promise<ChargeResult>;
+
+  /** Releases a hold without taking anything. */
+  release(externalId: string): Promise<void>;
+
+  refund(request: RefundRequest): Promise<{ externalId: string }>;
+
+  /**
+   * Whether a webhook really came from the provider, and what it says.
+   *
+   * `undefined` rather than a thrown error: the caller's answer to a request
+   * that did not come from the provider is a flat acknowledgement, not a
+   * message describing what was wrong with the forgery.
+   */
+  verify(payload: string | Buffer, signature: string | undefined): ProviderEvent | undefined;
+}

package/src/providers/stripe.ts

@@ -0,0 +1,274 @@
+import Stripe from 'stripe';
+import type {
+  ChargeRequest,
+  ChargeResult,
+  OnboardingLink,
+  PaymentProvider,
+  ProviderAccount,
+  ProviderEvent,
+  RefundRequest,
+} from './port';
+
+export interface StripeConnectOptions {
+  secretKey: string;
+  /** The endpoint's signing secret, as the dashboard gives it: `whsec_…`. */
+  webhookSecret?: string;
+  /** An already-built client, for tests and for a deployment that shares one. */
+  client?: Stripe;
+}
+
+/**
+ * Stripe Connect, as the port describes it.
+ *
+ * **Destination charges throughout.** The money is created on our platform
+ * account and transferred immediately to the business, with our cut taken as an
+ * application fee — which is what keeps this a software company rather than a
+ * regulated one, and what lets the business see its own payouts in its own
+ * Stripe dashboard.
+ *
+ * Everything the provider does *not* need to decide is decided before this file
+ * is reached: what a deposit comes to, whether a business may sell, what a
+ * refund leaves. What is here is the part that genuinely needs somebody else's
+ * money-moving licence.
+ */
+export class StripeConnect implements PaymentProvider {
+  readonly name = 'stripe';
+  private readonly stripe: Stripe;
+
+  constructor(private readonly options: StripeConnectOptions) {
+    this.stripe = options.client ?? new Stripe(options.secretKey);
+  }
+
+  async account(
+    externalId: string | null,
+    country: string,
+    email?: string,
+  ): Promise<ProviderAccount> {
+    const account = externalId
+      ? await this.stripe.accounts.retrieve(externalId)
+      : await this.stripe.accounts.create({
+          type: 'express',
+          country,
+          ...(email ? { email } : {}),
+          capabilities: { card_payments: { requested: true }, transfers: { requested: true } },
+        });
+
+    return interpretAccount(account);
+  }
+
+  async onboard(
+    externalId: string,
+    returnUrl: string,
+    refreshUrl: string,
+  ): Promise<OnboardingLink> {
+    const link = await this.stripe.accountLinks.create({
+      account: externalId,
+      type: 'account_onboarding',
+      return_url: returnUrl,
+      /*
+       * Where the business lands if the link has aged out.
+       *
+       * Stripe's onboarding links are short-lived and somebody *will* open one
+       * the next morning. Without this they meet an error page from a company
+       * they have never heard of, halfway through giving it their passport.
+       */
+      refresh_url: refreshUrl,
+    });
+
+    return { url: link.url, expiresAt: new Date(link.expires_at * 1000) };
+  }
+
+  async charge(request: ChargeRequest): Promise<ChargeResult> {
+    try {
+      const intent = await this.stripe.paymentIntents.create(
+        {
+          amount: request.amount,
+          currency: request.currency.toLowerCase(),
+          /*
+           * The money lands on the business's account, not ours.
+           *
+           * `transfer_data.destination` with `application_fee_amount` is the
+           * destination-charge shape: we never hold their funds, and their
+           * payouts appear in their own dashboard.
+           */
+          transfer_data: { destination: request.account },
+          ...(request.applicationFee > 0 ? { application_fee_amount: request.applicationFee } : {}),
+          capture_method: request.capture ? 'automatic' : 'manual',
+          ...(request.description ? { description: request.description } : {}),
+          // Carried through so a webhook can be matched back to what it paid
+          // for without a lookup table of our own.
+          metadata: { subject: request.subject },
+          automatic_payment_methods: { enabled: true },
+        },
+        // The provider's own idempotency, so a retried request — a timeout, a
+        // double submit — does not charge somebody twice.
+        { idempotencyKey: request.reference },
+      );
+
+      return interpretIntent(intent);
+    } catch (error) {
+      return failure(error);
+    }
+  }
+
+  async capture(externalId: string, amount?: number): Promise<ChargeResult> {
+    try {
+      const intent = await this.stripe.paymentIntents.capture(
+        externalId,
+        amount === undefined ? undefined : { amount_to_capture: amount },
+      );
+
+      return interpretIntent(intent);
+    } catch (error) {
+      return failure(error);
+    }
+  }
+
+  async release(externalId: string): Promise<void> {
+    await this.stripe.paymentIntents.cancel(externalId);
+  }
+
+  async refund(request: RefundRequest): Promise<{ externalId: string }> {
+    const refund = await this.stripe.refunds.create(
+      {
+        payment_intent: request.externalId,
+        amount: request.amount,
+        metadata: { reason: request.reason.slice(0, 500) },
+      },
+      { idempotencyKey: request.reference },
+    );
+
+    return { externalId: refund.id };
+  }
+
+  verify(payload: string | Buffer, signature: string | undefined): ProviderEvent | undefined {
+    if (!signature || !this.options.webhookSecret) return undefined;
+
+    let event: Stripe.Event;
+
+    try {
+      event = this.stripe.webhooks.constructEvent(payload, signature, this.options.webhookSecret);
+    } catch {
+      /*
+       * A forgery, or a payload something re-encoded on the way in.
+       *
+       * `undefined` rather than a thrown error: the caller answers a request
+       * that did not come from Stripe with a flat acknowledgement, not with a
+       * message describing what was wrong with it.
+       */
+      return undefined;
+    }
+
+    return interpretEvent(event);
+  }
+}
+
+/** Stripe's account shape, reduced to the question anybody actually asks. */
+function interpretAccount(account: Stripe.Account): ProviderAccount {
+  const requirements = [
+    ...(account.requirements?.currently_due ?? []),
+    ...(account.requirements?.past_due ?? []),
+  ];
+
+  /*
+   * `charges_enabled` and `payouts_enabled` together, not either alone.
+   *
+   * A business that can take money but cannot be paid out is worse than one
+   * that cannot sell yet: the customer is charged and the money sits with the
+   * provider, and the first anybody hears is the business asking where it is.
+   */
+  const ready = account.charges_enabled === true && account.payouts_enabled === true;
+
+  return {
+    externalId: account.id,
+    status: ready ? 'ready' : requirements.length > 0 ? 'restricted' : 'pending',
+    requirements: [...new Set(requirements)],
+  };
+}
+
+function interpretIntent(intent: Stripe.PaymentIntent): ChargeResult {
+  const state =
+    intent.status === 'succeeded'
+      ? 'captured'
+      : intent.status === 'requires_capture'
+        ? 'authorized'
+        : intent.status === 'canceled'
+          ? 'failed'
+          : 'pending';
+
+  const charge = intent.latest_charge;
+  const card =
+    typeof charge === 'object' && charge?.payment_method_details?.card
+      ? `${charge.payment_method_details.card.brand} ending ${charge.payment_method_details.card.last4}`
+      : undefined;
+
+  return {
+    externalId: intent.id,
+    state,
+    ...(intent.next_action?.redirect_to_url?.url
+      ? { redirectUrl: intent.next_action.redirect_to_url.url }
+      : {}),
+    ...(card ? { instrument: card } : {}),
+    ...(intent.last_payment_error?.message ? { detail: intent.last_payment_error.message } : {}),
+  };
+}
+
+function interpretEvent(event: Stripe.Event): ProviderEvent {
+  switch (event.type) {
+    case 'payment_intent.succeeded':
+    case 'payment_intent.amount_capturable_updated':
+    case 'payment_intent.payment_failed': {
+      const intent = event.data.object as Stripe.PaymentIntent;
+      const result = interpretIntent(intent);
+
+      return {
+        kind: 'payment',
+        externalId: intent.id,
+        state:
+          event.type === 'payment_intent.payment_failed'
+            ? 'failed'
+            : result.state === 'captured'
+              ? 'captured'
+              : 'authorized',
+        ...(result.instrument ? { instrument: result.instrument } : {}),
+        ...(result.detail ? { detail: result.detail } : {}),
+      };
+    }
+
+    case 'charge.refunded': {
+      const charge = event.data.object as Stripe.Charge;
+      return {
+        kind: 'payment',
+        externalId: typeof charge.payment_intent === 'string' ? charge.payment_intent : charge.id,
+        state: 'refunded',
+      };
+    }
+
+    case 'account.updated': {
+      const account = event.data.object as Stripe.Account;
+      return { kind: 'account', externalId: account.id, accountStatus: interpretAccount(account) };
+    }
+
+    default:
+      /*
+       * Everything else is acknowledged and ignored.
+       *
+       * Stripe sends a great many event types and a deployment's subscription
+       * will drift; treating an unknown one as an error means retries and an
+       * alert for something that was never any of our business.
+       */
+      return { kind: 'other', externalId: event.id };
+  }
+}
+
+/** A provider's refusal, as a result rather than an exception. */
+function failure(error: unknown): ChargeResult {
+  const message =
+    error instanceof Stripe.errors.StripeError
+      ? (error.message ?? 'The payment was refused.')
+      : error instanceof Error
+        ? error.message
+        : 'The payment was refused.';
+
+  return { externalId: '', state: 'failed', detail: message };
+}