[YOLO-3035] support tips in unified checkout

.changeset/fruity-dots-jog.md

@@ -0,0 +1,7 @@
+---
+"@godaddy/react": minor
+---
+
+Support tips in unified checkout
+
+Adds the `tips` session config surface (`default` and threshold-based `amounts`/`percentages` presets) alongside `enableTips`, and includes the selected tip in wallet sheet totals and the authorized/confirmed amount.

examples/nextjs/app/page.tsx

@@ -21,6 +21,19 @@ export default async function Home() {
       enableTaxCollection: true,
       enableNotesCollection: true,
       enablePromotionCodes: true,
+      enableTips: true,
+      tips: {
+        default: {
+          percentages: [ 20, 40, 60 ]
+        },
+        thresholds: [
+          {
+            minSubtotal: 0,
+            maxSubtotal: 1000,
+            amounts: [ 300, 500, 700 ]
+          }
+        ]
+      },
       shipping: {
         fulfillmentLocationId: 'default-location',
         originAddress: {

packages/react/README.md

@@ -41,6 +41,7 @@ The first parameter accepts all checkout session configuration options from the
 - **`enableSurcharge`** (boolean): Enable surcharge fees
 - **`enableTaxCollection`** (boolean): Enable tax collection
 - **`enableTips`** (boolean): Enable tip/gratuity options
+- **`tips`** (CheckoutSessionTipsInput): Tip option configuration (see [Tips](#tips))
 - **`enabledLocales`** ([String!]): List of enabled locales
 - **`enabledPaymentProviders`** ([String!]): List of enabled payment providers
 - **`environment`** (enum): Environment - `ote`, `prod`
@@ -135,6 +136,64 @@ operatingHours: {
 - **Timezone handling** — All date/time logic uses the store's `timeZone`, not the customer's browser timezone. A store in Phoenix shows Phoenix hours regardless of where the customer is browsing from.
 - **No available slots** — In `dateAndTime` mode, when leadTime exceeds the entire pickup window, no days are enabled, or no selectable slots exist, a "No available time slots" banner is shown.
 
+### Tips
+
+The `tips` field configures preset tip options shown to the customer when `enableTips` is `true`. Tips supports a `default` preset and optional `thresholds` that activate based on the order subtotal.
+
+Throughout this section, "subtotal" means the order's **item subtotal** (`totals.subTotal`) — the sum of item prices **before** discounts, shipping, fees and tax. It is not the order total the customer pays. See [Subtotal basis](#behavior-notes) below.
+
+Every option list — `default` and each threshold — must supply **exactly one** of `amounts` or `percentages`, with **exactly three** values. The API rejects sessions that provide both, neither, or a different number of values. Three values is also what the tip selector is laid out for.
+
+```typescript
+tips: {
+  default: {
+    percentages: [15, 18, 20],
+  },
+  thresholds: [
+    {
+      minSubtotal: 0,
+      maxSubtotal: 999,
+      amounts: [100, 200, 500],
+    },
+    {
+      minSubtotal: 1000,
+      maxSubtotal: 4999,
+      amounts: [200, 400, 700],
+    },
+  ],
+}
+```
+
+#### `tips.default`
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `amounts` | number[] | Conditional | Fixed tip amounts in the smallest currency unit (e.g. cents). Exactly three values. Mutually exclusive with `percentages`. |
+| `percentages` | number[] | Conditional | Tip percentage options (integers between 0 and 100). Exactly three values. Mutually exclusive with `amounts`. |
+
+#### `tips.thresholds`
+
+An array of threshold objects that override the default tips when the order's item subtotal falls within the specified range.
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `minSubtotal` | number | Yes | Minimum item subtotal (inclusive) in the smallest currency unit for this threshold to apply. Required by the API — omitting it fails with `INVALID_TIP_THRESHOLD`. |
+| `maxSubtotal` | number | Yes | Maximum item subtotal (inclusive) in the smallest currency unit for this threshold to apply. Required by the API — omitting it fails with `INVALID_TIP_THRESHOLD`. Must be greater than `minSubtotal`. |
+| `amounts` | number[] | Conditional | Fixed tip amounts in the smallest currency unit (e.g. cents). Exactly three values. Mutually exclusive with `percentages`. |
+| `percentages` | number[] | Conditional | Tip percentage options (integers between 0 and 100). Exactly three values. Mutually exclusive with `amounts`. |
+
+#### Behavior Notes
+
+- **Subtotal basis** — `minSubtotal`, `maxSubtotal` and every `percentages` calculation use the order's item subtotal (`totals.subTotal`), which is the sum of item prices **before discounts, shipping, fees and tax**. A $50 cart with a $20 discount, $6 shipping and $2 tax has a subtotal of `5000`, not the `3800` the customer pays, so it matches a `0–5000` threshold and `20%` offers `1000`. Configure ranges against the pre-discount cart value, not the amount charged.
+- **Threshold matching is client-side** — Checkout selects the preset list. The API stores `tips` and validates its shape, but never re-derives which threshold applied.
+- **Tip ceiling is measured against the order total** — Independent of the presets, the API rejects a `tipAmount` above 100% of the **order total** (post-discount, tax and shipping included) or `2000` minor units, whichever is greater, with `TIP_EXCEEDS_LIMIT`. Note the asymmetry: thresholds bucket on the subtotal, this bound uses the total. Large fixed `amounts` can therefore be rejected on a heavily discounted order — e.g. `amounts: [2500, 5000, 10000]` on an order totalling `1000` allows at most `2000`.
+- **Threshold matching** — Checkout uses the **first** threshold whose range contains the item subtotal. Both bounds are inclusive, so a subtotal equal to `minSubtotal` or `maxSubtotal` matches.
+- **Overlaps are not validated** — The API checks neither overlap nor full coverage of the subtotal range. Adjacent thresholds that share a boundary (e.g. `0–1000` and `1000–2000`) are accepted and resolve silently to whichever comes first in the array. Make ranges contiguous but non-overlapping (e.g. `0–999` then `1000–1999`) so the applied threshold is unambiguous.
+- **Gaps fall back to `default`** — A subtotal outside every threshold range uses `tips.default`.
+- **No `tips` configured** — When `enableTips` is `true` but `tips` is omitted, checkout shows `15%`, `18%`, and `20%`.
+- **Both lists on one threshold** — Should a threshold reach checkout with both `amounts` and `percentages` (the API rejects this), `amounts` wins and the percentages are ignored.
+- **Customer overrides** — The presets are suggestions. The tip selector also offers "No tip" and "Custom amount", and the API does not check `tipAmount` against the configured options, so the confirmed tip need not match any preset.
+
 ### Appearance
 
 The `appearance` field customizes the checkout's look and feel.

packages/react/src/components/checkout/__tests__/checkout-ccavenue-tips.test.tsx

@@ -0,0 +1,223 @@
+import { screen, waitFor } from '@testing-library/react';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import {
+  clearRedirectTipAmount,
+  getRedirectTipAmount,
+  setRedirectTipAmount,
+} from '@/lib/redirect-tip-storage';
+import { CheckoutType, PaymentMethodType, PaymentProvider } from '@/types';
+import {
+  clearOperations,
+  getOperations,
+  renderCheckout,
+  setCheckoutUrl,
+  waitForCheckoutReady,
+  waitForOperation,
+} from './checkout-test-env';
+import { getLastConfirmInput } from './checkout-test-fixtures';
+
+const CCAVENUE_SESSION = {
+  enableTips: true,
+  enableShipping: false,
+  enableLocalPickup: false,
+  enableTaxCollection: false,
+  paymentMethods: {
+    card: null,
+    ccavenue: {
+      type: PaymentMethodType.CCAVENUE,
+      processor: PaymentProvider.CCAVENUE,
+      checkoutTypes: [CheckoutType.STANDARD],
+    },
+  },
+};
+
+const CCAVENUE_PROPS = {
+  ccavenueConfig: { accessCodeId: 'access-code-1' },
+};
+
+function renderCCAvenueCheckout() {
+  return renderCheckout({
+    checkoutProps: CCAVENUE_PROPS,
+    sessionOverrides: CCAVENUE_SESSION,
+  });
+}
+
+function getAuthorizeInput() {
+  return getOperations('AuthorizeCheckoutSession').at(-1)?.input as
+    | Record<string, unknown>
+    | undefined;
+}
+
+describe('Checkout CCAvenue tips', () => {
+  beforeEach(() => {
+    clearRedirectTipAmount();
+    setCheckoutUrl();
+  });
+
+  describe('redirect to the gateway', () => {
+    it('persists the tip the redirect authorized', async () => {
+      const submit = vi
+        .spyOn(HTMLFormElement.prototype, 'submit')
+        .mockImplementation(() => undefined);
+      const { user, session } = renderCCAvenueCheckout();
+      await waitForCheckoutReady();
+      clearOperations();
+
+      await user.click(await screen.findByRole('button', { name: /20%/ }));
+      await waitFor(() => {
+        expect(screen.getAllByText('$5.00').length).toBeGreaterThan(0);
+      });
+
+      await user.click(
+        await screen.findByRole('button', { name: /pay with ccavenue/i })
+      );
+      await waitForOperation('AuthorizeCheckoutSession');
+
+      expect(getAuthorizeInput()).toMatchObject({ tipAmount: 500 });
+      expect(getRedirectTipAmount(session.id)).toBe(500);
+      await waitFor(() => {
+        expect(submit).toHaveBeenCalled();
+      });
+    });
+
+    it('persists a zero tip when no tip is selected', async () => {
+      vi.spyOn(HTMLFormElement.prototype, 'submit').mockImplementation(
+        () => undefined
+      );
+      const { user, session } = renderCCAvenueCheckout();
+      await waitForCheckoutReady();
+      clearOperations();
+
+      await user.click(
+        await screen.findByRole('button', { name: /pay with ccavenue/i })
+      );
+      await waitForOperation('AuthorizeCheckoutSession');
+
+      expect(getRedirectTipAmount(session.id)).toBe(0);
+    });
+
+    it('does not persist a tip when tips are disabled', async () => {
+      vi.spyOn(HTMLFormElement.prototype, 'submit').mockImplementation(
+        () => undefined
+      );
+      const { user, session } = renderCheckout({
+        checkoutProps: CCAVENUE_PROPS,
+        sessionOverrides: { ...CCAVENUE_SESSION, enableTips: false },
+      });
+      await waitForCheckoutReady();
+      clearOperations();
+
+      await user.click(
+        await screen.findByRole('button', { name: /pay with ccavenue/i })
+      );
+      await waitForOperation('AuthorizeCheckoutSession');
+
+      expect(getRedirectTipAmount(session.id)).toBeNull();
+    });
+
+    it('does not persist a tip when the authorization fails', async () => {
+      vi.spyOn(HTMLFormElement.prototype, 'submit').mockImplementation(
+        () => undefined
+      );
+      const { user, session } = renderCheckout({
+        checkoutProps: CCAVENUE_PROPS,
+        sessionOverrides: CCAVENUE_SESSION,
+        apiOverrides: {
+          errors: { authorizeCheckoutSession: new Error('authorize failed') },
+        },
+      });
+      await waitForCheckoutReady();
+      clearOperations();
+
+      await user.click(await screen.findByRole('button', { name: /20%/ }));
+      await waitFor(() => {
+        expect(screen.getAllByText('$5.00').length).toBeGreaterThan(0);
+      });
+
+      await user.click(
+        await screen.findByRole('button', { name: /pay with ccavenue/i })
+      );
+      await waitForOperation('AuthorizeCheckoutSession');
+
+      expect(getRedirectTipAmount(session.id)).toBeNull();
+    });
+  });
+
+  describe('return from the gateway', () => {
+    it('confirms with the tip the redirect authorized', async () => {
+      setRedirectTipAmount('checkout-session-1', 500);
+      setCheckoutUrl({
+        pathname: '/checkout/checkout-session-1',
+        search: 'encResp=enc-resp-1',
+      });
+
+      renderCCAvenueCheckout();
+      await waitForOperation('ConfirmCheckoutSession');
+
+      expect(getLastConfirmInput()).toMatchObject({
+        paymentToken: 'enc-resp-1',
+        paymentType: 'ccavenue',
+        tipAmount: 500,
+      });
+    });
+
+    it('clears the persisted tip once the confirmation succeeds', async () => {
+      setRedirectTipAmount('checkout-session-1', 500);
+      setCheckoutUrl({
+        pathname: '/checkout/checkout-session-1',
+        search: 'encResp=enc-resp-1',
+      });
+
+      const { session } = renderCCAvenueCheckout();
+      await waitForOperation('ConfirmCheckoutSession');
+
+      await waitFor(() => {
+        expect(getRedirectTipAmount(session.id)).toBeNull();
+      });
+    });
+
+    it('keeps the persisted tip when the confirmation fails', async () => {
+      setRedirectTipAmount('checkout-session-1', 500);
+      setCheckoutUrl({
+        pathname: '/checkout/checkout-session-1',
+        search: 'encResp=enc-resp-1',
+      });
+
+      const { session } = renderCheckout({
+        checkoutProps: CCAVENUE_PROPS,
+        sessionOverrides: CCAVENUE_SESSION,
+        apiOverrides: {
+          errors: { confirmCheckout: new Error('confirm failed') },
+        },
+      });
+      await waitForOperation('ConfirmCheckoutSession');
+
+      expect(getRedirectTipAmount(session.id)).toBe(500);
+    });
+
+    it('ignores a tip persisted for a different checkout session', async () => {
+      setRedirectTipAmount('checkout-session-other', 500);
+      setCheckoutUrl({
+        pathname: '/checkout/checkout-session-1',
+        search: 'encResp=enc-resp-1',
+      });
+
+      renderCCAvenueCheckout();
+      await waitForOperation('ConfirmCheckoutSession');
+
+      expect(getLastConfirmInput()).toMatchObject({ tipAmount: 0 });
+    });
+
+    it('confirms with a zero tip when nothing was persisted', async () => {
+      setCheckoutUrl({
+        pathname: '/checkout/checkout-session-1',
+        search: 'encResp=enc-resp-1',
+      });
+
+      renderCCAvenueCheckout();
+      await waitForOperation('ConfirmCheckoutSession');
+
+      expect(getLastConfirmInput()).toMatchObject({ tipAmount: 0 });
+    });
+  });
+});