@birtalanrobert/commerce 1.0.0 → 3.0.0

package/src/providers/port.ts

@@ -28,6 +28,20 @@ export interface OnboardingLink {
 export interface ChargeRequest {
   /** The business being paid, as the provider knows it. */
   readonly account: string;
+  /**
+   * The customer, where one is being charged again rather than for the first
+   * time. Held on *our* account rather than the business's, because that is
+   * where a saved card lives under a destination charge.
+   */
+  readonly customer?: string;
+  /**
+   * A card already saved, to charge without anybody present.
+   *
+   * The whole point of storing one: a no-show fee is decided days later, and
+   * asking somebody who did not turn up to enter a card is a conversation that
+   * does not happen.
+   */
+  readonly paymentMethod?: string;
   readonly amount: number;
   readonly currency: string;
   /** Our cut, taken on top rather than out of the business's money. */
@@ -57,10 +71,48 @@ export interface ChargeResult {
    * failure and must not be handled as one.
    */
   readonly redirectUrl?: string;
+  /**
+   * What the browser needs to finish paying, when the customer is present.
+   *
+   * A charge created on the server has no card attached to it yet — the card is
+   * entered in a browser, against the provider's own script, so that the number
+   * never reaches us. Without this the payment can be created and never paid,
+   * which is the state a customer reads as "it took my booking and lost my
+   * money".
+   */
+  readonly clientSecret?: string;
   readonly instrument?: string;
   readonly detail?: string;
 }
 
+/** A card being stored for later, rather than charged now. */
+export interface SaveCardRequest {
+  /** An existing customer to attach it to, where the person already has one. */
+  readonly customer?: string;
+  /** What it is being saved for, carried through for matching a webhook back. */
+  readonly subject: string;
+  readonly reference: string;
+}
+
+export interface SaveCardResult {
+  /** The customer the card will hang off, created here if there was none. */
+  readonly customer: string;
+  /** The provider's handle on this attempt, to read the result back from. */
+  readonly externalId: string;
+  /** What the browser confirms against. */
+  readonly clientSecret: string;
+}
+
+/** A card that was actually stored, read back after the browser confirmed it. */
+export interface StoredCard {
+  readonly customer: string;
+  readonly paymentMethod: string;
+  readonly brand?: string;
+  readonly last4?: string;
+  readonly expiryMonth?: number;
+  readonly expiryYear?: number;
+}
+
 export interface RefundRequest {
   readonly externalId: string;
   readonly amount: number;
@@ -95,6 +147,28 @@ export interface PaymentProvider {
   /** Releases a hold without taking anything. */
   release(externalId: string): Promise<void>;
 
+  /**
+   * Starts storing a card without charging it.
+   *
+   * The strongest thing a business can do about no-shows short of taking money:
+   * nothing leaves the customer's account, and the card is there if a fee is
+   * later decided on. A hold is not a substitute — providers expire one within
+   * days, and an appointment is usually further away than that.
+   */
+  saveCard(request: SaveCardRequest): Promise<SaveCardResult>;
+
+  /**
+   * What was actually stored, once the browser says it finished.
+   *
+   * Read back from the provider rather than believed from the browser: what a
+   * page reports is what a page was told to report, and a saved card is
+   * something a business will later charge money against.
+   */
+  storedCard(externalId: string): Promise<StoredCard | undefined>;
+
+  /** Forgets a stored card, at the customer's request or the business's. */
+  forgetCard(paymentMethod: string): Promise<void>;
+
   refund(request: RefundRequest): Promise<{ externalId: string }>;
 
   /**

package/src/providers/stripe.ts

@@ -7,6 +7,9 @@ import type {
   ProviderAccount,
   ProviderEvent,
   RefundRequest,
+  SaveCardRequest,
+  SaveCardResult,
+  StoredCard,
 } from './port';
 
 export interface StripeConnectOptions {
@@ -95,10 +98,31 @@ export class StripeConnect implements PaymentProvider {
           ...(request.applicationFee > 0 ? { application_fee_amount: request.applicationFee } : {}),
           capture_method: request.capture ? 'automatic' : 'manual',
           ...(request.description ? { description: request.description } : {}),
+          ...(request.customer ? { customer: request.customer } : {}),
+          /*
+           * A stored card is confirmed here and now, with nobody present.
+           *
+           * `off_session` is what tells the network the customer is not sitting
+           * there — it is also what makes the bank decline rather than ask for
+           * a code it has nobody to ask, which is the honest outcome for a fee
+           * charged three days after an appointment.
+           */
+          ...(request.paymentMethod
+            ? {
+                payment_method: request.paymentMethod,
+                confirm: true,
+                off_session: true,
+              }
+            : {}),
           // 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 },
+          /*
+           * Only where a card still has to be entered. Offering a redirect
+           * method to a charge that is already confirmed against a stored card
+           * is a contradiction the provider rejects.
+           */
+          ...(request.paymentMethod ? {} : { automatic_payment_methods: { enabled: true } }),
         },
         // The provider's own idempotency, so a retried request — a timeout, a
         // double submit — does not charge somebody twice.
@@ -128,6 +152,70 @@ export class StripeConnect implements PaymentProvider {
     await this.stripe.paymentIntents.cancel(externalId);
   }
 
+  /**
+   * Starts storing a card without charging it.
+   *
+   * The customer is created on **our** account rather than the business's. That
+   * is not a preference: under a destination charge the money lands on the
+   * business's account while the card is ours to charge, and a customer created
+   * on the business's account cannot be used from here at all.
+   */
+  async saveCard(request: SaveCardRequest): Promise<SaveCardResult> {
+    const customer =
+      request.customer ??
+      (
+        await this.stripe.customers.create(
+          { metadata: { subject: request.subject } },
+          { idempotencyKey: `customer-${request.reference}` },
+        )
+      ).id;
+
+    const intent = await this.stripe.setupIntents.create(
+      {
+        customer,
+        usage: 'off_session',
+        payment_method_types: ['card'],
+        metadata: { subject: request.subject },
+      },
+      { idempotencyKey: request.reference },
+    );
+
+    return {
+      customer,
+      externalId: intent.id,
+      // Non-null because a setup intent is created precisely to be confirmed.
+      clientSecret: intent.client_secret ?? '',
+    };
+  }
+
+  async storedCard(externalId: string): Promise<StoredCard | undefined> {
+    const intent = await this.stripe.setupIntents.retrieve(externalId, {
+      expand: ['payment_method'],
+    });
+
+    const method = intent.payment_method;
+    if (!method || typeof method === 'string' || !intent.customer) return undefined;
+
+    const customer = typeof intent.customer === 'string' ? intent.customer : intent.customer.id;
+
+    return {
+      customer,
+      paymentMethod: method.id,
+      ...(method.card
+        ? {
+            brand: method.card.brand,
+            last4: method.card.last4,
+            expiryMonth: method.card.exp_month,
+            expiryYear: method.card.exp_year,
+          }
+        : {}),
+    };
+  }
+
+  async forgetCard(paymentMethod: string): Promise<void> {
+    await this.stripe.paymentMethods.detach(paymentMethod);
+  }
+
   async refund(request: RefundRequest): Promise<{ externalId: string }> {
     const refund = await this.stripe.refunds.create(
       {
@@ -205,6 +293,7 @@ function interpretIntent(intent: Stripe.PaymentIntent): ChargeResult {
   return {
     externalId: intent.id,
     state,
+    ...(intent.client_secret ? { clientSecret: intent.client_secret } : {}),
     ...(intent.next_action?.redirect_to_url?.url
       ? { redirectUrl: intent.next_action.redirect_to_url.url }
       : {}),

package/stripe/package.json

@@ -0,0 +1,5 @@
+{
+  "main": "../dist/providers/stripe.js",
+  "types": "../dist/providers/stripe.d.ts",
+  "sideEffects": false
+}