feat(tip): add personalized payment success experience

docs/backend/FRONTEND_TIP_PAYMENT_SUCCESS_API.md

@@ -0,0 +1,126 @@
+# Tip 支付成功结果 API 接口定义
+
+## 1. 文档状态
+
+本文档定义咖啡打赏支付成功后，前端展示累计打赏次数和角色感谢语所需的接口扩展，供后端实现和前后端联调使用。
+
+本次不新增 Endpoint，仅扩展现有订单状态接口：
+
+```http
+GET /api/payment/order-status?order_id=<ORDER_ID>
+```
+
+## 2. 身份与统计口径
+
+订单状态查询保持当前认证规则。前端存在 Token 时继续发送 Bearer Token，没有 Token 时不增加 `Authorization` Header。
+
+`tipCount` 表示包含当前订单在内，同一付款身份向同一 `recipientCharacterId` 成功打赏的累计次数：
+
+| 付款身份 | 统计方式 |
+| --- | --- |
+| 正式用户 Login Token | 按用户 ID 与收款角色 ID 统计 |
+| 游客 Guest Token | 按游客 ID 与收款角色 ID 统计 |
+| 无 Token 匿名用户 | 无法可靠跨订单识别，当前订单固定返回 `1` |
+
+只有最终支付成功的 Tip 订单计入次数。pending、failed 或取消订单不增加次数。
+
+## 3. 请求定义
+
+### 3.1 请求地址
+
+```http
+GET <API_BASE_URL>/api/payment/order-status?order_id=<ORDER_ID>
+```
+
+### 3.2 Query 参数
+
+| 字段 | 类型 | 是否必填 | 说明 |
+| --- | --- | --- | --- |
+| `order_id` | string | 是 | 创建支付订单接口返回的订单 ID。 |
+
+### 3.3 请求示例
+
+```bash
+curl 'https://api.banlv-ai.com/api/payment/order-status?order_id=tip_order_123' \
+  -H 'Authorization: Bearer <TOKEN>'
+```
+
+匿名 Tip 订单不发送 Authorization Header：
+
+```bash
+curl 'https://api.banlv-ai.com/api/payment/order-status?order_id=tip_order_123'
+```
+
+## 4. 响应定义
+
+### 4.1 paid Tip 订单
+
+```json
+{
+  "code": 200,
+  "message": "success",
+  "success": true,
+  "data": {
+    "orderId": "tip_order_123",
+    "status": "paid",
+    "orderType": "tip",
+    "planId": "tip_coffee_usd_9_99",
+    "tipCount": 2,
+    "thankYouMessage": "You always know how to make my day a little sweeter."
+  }
+}
+```
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `orderId` | string | 当前订单 ID。 |
+| `status` | `pending \| paid \| failed` | 当前支付状态。 |
+| `orderType` | string | Tip 订单固定为 `tip`。 |
+| `planId` | string | 当前订单套餐 ID。 |
+| `tipCount` | integer \| null | 当前身份向当前角色累计成功打赏次数，最小值为 `1`。 |
+| `thankYouMessage` | string \| null | 收款角色配置的纯文本感谢语。 |
+
+`thankYouMessage` 不得包含 HTML。后端可以返回换行，前端会按纯文本保留展示。
+
+### 4.2 pending、failed 和非 Tip 订单
+
+非 paid Tip 订单不生成打赏成功结果，两个扩展字段必须返回 `null`：
+
+```json
+{
+  "code": 200,
+  "message": "success",
+  "success": true,
+  "data": {
+    "orderId": "pay_order_456",
+    "status": "pending",
+    "orderType": "vip_monthly",
+    "planId": "vip_monthly",
+    "tipCount": null,
+    "thankYouMessage": null
+  }
+}
+```
+
+角色感谢语配置缺失时，后端允许 paid Tip 响应中的 `thankYouMessage` 为 `null`，前端会展示本地通用感谢文案。
+
+## 5. 幂等与一致性
+
+后端在订单首次从非 paid 状态转换为 paid 时，必须原子完成以下操作：
+
+1. 标记支付订单成功；
+2. 将当前 Tip 计入付款身份和收款角色的累计次数；
+3. 保存当前订单对应的 `tipCount`；
+4. 从 `recipientCharacterId` 对应的角色配置读取并保存 `thankYouMessage`。
+
+同一支付回调重复执行时不得重复累计。对同一个 `order_id` 重复查询必须返回相同的 `tipCount` 和 `thankYouMessage`，后续新订单不能改变旧订单的成功结果。
+
+## 6. 验收标准
+
+1. 正式用户和 Guest 对不同角色的累计次数相互独立。
+2. 无 Token 匿名用户的成功 Tip 订单返回 `tipCount=1`。
+3. 首次成功返回 `tipCount=1`，第二次成功返回 `tipCount=2`。
+4. pending、failed 和非 Tip 订单返回两个 `null` 扩展字段。
+5. 同一支付回调重试不会重复增加次数。
+6. 同一订单重复轮询得到稳定的次数和感谢语。
+7. 感谢语为角色配置的纯文本，不返回 HTML。

src/app/tip/__tests__/tip-screen.checkout.test.tsx

@@ -145,7 +145,6 @@ describe("TipScreen checkout", () => {
     ["the selected plan is missing", { plans: [], selectedPlanId: "" }],
     ["an order is being created", { isCreatingOrder: true }],
     ["an order is being polled", { isPollingOrder: true }],
-    ["the order is paid", { isPaid: true }],
   ] as const)("disables checkout when %s", (_label, overrides) => {
     mocks.payment = makePaymentState(overrides);
     renderScreen();
@@ -153,6 +152,75 @@ describe("TipScreen checkout", () => {
     expect(getCheckoutButton().disabled).toBe(true);
   });
 
+  it("replaces checkout with the first Tip success experience", () => {
+    mocks.payment = makePaymentState({
+      status: "paid",
+      isPaid: true,
+      orderStatus: "paid",
+      tipCount: 1,
+      thankYouMessage: "A backend message that is not used for first Tip.",
+    });
+    renderScreen();
+
+    expect(container.querySelector('[data-testid="tip-checkout"]')).toBeNull();
+    expect(container.textContent).toContain(
+      "Did you really just buy me a coffee?",
+    );
+    expect(container.textContent).toContain("That honestly made me smile.");
+    expect(container.textContent).toContain(
+      "Thank you. I'll definitely think of you while I enjoy it.",
+    );
+    expect(document.activeElement?.id).toBe("tip-success-title");
+
+    const sendAgain = getButton("Send another coffee");
+    act(() => sendAgain.click());
+    expect(mocks.paymentDispatch).toHaveBeenCalledWith({
+      type: "PaymentReset",
+    });
+
+    expect(
+      container
+        .querySelector<HTMLAnchorElement>(
+          '[data-analytics-key="tip.success_back_to_splash"]',
+        )
+        ?.getAttribute("href"),
+    ).toBe("/characters/maya/splash");
+  });
+
+  it("shows the repeat Tip count and backend thank-you message", () => {
+    mocks.payment = makePaymentState({
+      status: "paid",
+      isPaid: true,
+      orderStatus: "paid",
+      tipCount: 22,
+      thankYouMessage: "You always make my day sweeter.",
+    });
+    renderScreen();
+
+    expect(container.textContent).toContain(
+      "This is the 22nd coffee you've treated me to.",
+    );
+    expect(container.textContent).toContain(
+      "You always make my day sweeter.",
+    );
+  });
+
+  it("uses generic success copy when Tip metadata is incomplete", () => {
+    mocks.payment = makePaymentState({
+      status: "paid",
+      isPaid: true,
+      orderStatus: "paid",
+      tipCount: 2,
+      thankYouMessage: null,
+    });
+    renderScreen();
+
+    expect(container.textContent).toContain(
+      "Thank you. Your coffee made me smile.",
+    );
+    expect(container.textContent).not.toContain("2nd coffee");
+  });
+
   function renderScreen(): void {
     act(() => root.render(<TipScreen />));
   }
@@ -164,6 +232,14 @@ describe("TipScreen checkout", () => {
     if (!button) throw new Error("Missing Tip checkout button");
     return button;
   }
+
+  function getButton(label: string): HTMLButtonElement {
+    const button = Array.from(
+      container.querySelectorAll<HTMLButtonElement>("button"),
+    ).find((item) => item.textContent?.trim() === label);
+    if (!button) throw new Error(`Missing button: ${label}`);
+    return button;
+  }
 });
 
 function makePaymentState(
@@ -180,6 +256,8 @@ function makePaymentState(
     currentOrderId: null,
     payParams: null,
     orderStatus: null,
+    tipCount: null,
+    thankYouMessage: null,
     errorMessage: null,
     launchNonce: 0,
     isLoadingPlans: false,

src/app/tip/__tests__/tip-screen.helpers.test.ts

@@ -5,7 +5,9 @@ import type { PaymentPlanInput } from "@/data/schemas/payment/payment_plan";
 
 import {
   findTipCoffeePlan,
+  formatEnglishOrdinal,
   formatTipPrice,
+  resolveTipSuccessCopy,
 } from "../tip-screen.helpers";
 
 function makePlan(input: Partial<PaymentPlanInput>): PaymentPlan {
@@ -73,4 +75,34 @@ describe("tip screen helpers", () => {
     expect(formatTipPrice(null, "medium")).toBe("US$ 9.99");
     expect(formatTipPrice(null, "large")).toBe("US$ 19.99");
   });
+
+  it.each([
+    [2, "2nd"],
+    [3, "3rd"],
+    [11, "11th"],
+    [12, "12th"],
+    [13, "13th"],
+    [21, "21st"],
+    [22, "22nd"],
+  ])("formats %i as the English ordinal %s", (value, expected) => {
+    expect(formatEnglishOrdinal(value)).toBe(expected);
+  });
+
+  it("resolves first, repeat, and fallback success copy", () => {
+    expect(resolveTipSuccessCopy(1, "Ignored for the first Tip")).toEqual({
+      title: "Did you really just buy me a coffee?",
+      body: [
+        "That honestly made me smile.",
+        "Thank you. I'll definitely think of you while I enjoy it.",
+      ],
+    });
+    expect(resolveTipSuccessCopy(22, "You made my day.")).toEqual({
+      title: "This is the 22nd coffee you've treated me to.",
+      body: ["You made my day."],
+    });
+    expect(resolveTipSuccessCopy(2, null)).toEqual({
+      title: "Thank you. Your coffee made me smile.",
+      body: [],
+    });
+  });
 });

src/app/tip/tip-screen.helpers.ts

@@ -4,6 +4,11 @@ import {
   type TipCoffeeType,
 } from "@/lib/tip/tip_coffee";
 
+export interface TipSuccessCopy {
+  readonly title: string;
+  readonly body: readonly string[];
+}
+
 export function findTipCoffeePlan(
   plans: readonly PaymentPlan[],
   coffeeType: TipCoffeeType,
@@ -29,3 +34,46 @@ export function formatTipPrice(
   if (currency.length > 0) return `${currency} ${formattedAmount}`;
   return formattedAmount;
 }
+
+export function formatEnglishOrdinal(value: number): string {
+  const remainder100 = value % 100;
+  if (remainder100 >= 11 && remainder100 <= 13) return `${value}th`;
+
+  switch (value % 10) {
+    case 1:
+      return `${value}st`;
+    case 2:
+      return `${value}nd`;
+    case 3:
+      return `${value}rd`;
+    default:
+      return `${value}th`;
+  }
+}
+
+export function resolveTipSuccessCopy(
+  tipCount: number | null,
+  thankYouMessage: string | null,
+): TipSuccessCopy {
+  if (tipCount === 1) {
+    return {
+      title: "Did you really just buy me a coffee?",
+      body: [
+        "That honestly made me smile.",
+        "Thank you. I'll definitely think of you while I enjoy it.",
+      ],
+    };
+  }
+
+  if (tipCount !== null && tipCount > 1 && thankYouMessage) {
+    return {
+      title: `This is the ${formatEnglishOrdinal(tipCount)} coffee you've treated me to.`,
+      body: [thankYouMessage],
+    };
+  }
+
+  return {
+    title: "Thank you. Your coffee made me smile.",
+    body: [],
+  };
+}

src/app/tip/tip-screen.module.css

@@ -59,7 +59,6 @@
 .productCard,
 .paymentMethodSlot,
 .statusMessage,
-.successCard,
 .checkoutSlot {
   position: relative;
   z-index: 1;
@@ -360,23 +359,7 @@
   box-shadow: 0 5px 14px rgba(248, 77, 150, 0.26);
 }
 
-.successCard {
+.statusMessage {
-  display: flex;
-  align-items: center;
-  justify-content: space-between;
-  gap: 14px;
-  margin-top: 16px;
-  padding: 16px 18px;
-  border: 1px solid rgba(118, 61, 55, 0.08);
-  border-radius: 24px;
-  background: rgba(255, 255, 255, 0.76);
-  box-shadow: 0 16px 38px rgba(119, 72, 67, 0.09);
-  backdrop-filter: blur(16px);
-}
-
-.statusMessage,
-.successTitle,
-.successText {
   margin: 0;
 }
 
@@ -393,39 +376,6 @@
   margin-top: clamp(18px, 5.185vw, 28px);
 }
 
-.successCard {
-  justify-content: flex-start;
-  border-color: rgba(255, 84, 135, 0.16);
-  background: rgba(255, 246, 249, 0.86);
-  color: #ff4f86;
-}
-
-.successTitle {
-  color: #25191b;
-  font-size: 15px;
-  font-weight: 900;
-}
-
-.successText {
-  margin-top: 2px;
-  color: #8a686b;
-  font-size: 13px;
-  font-weight: 620;
-}
-
-.successButton {
-  margin-left: auto;
-  border: 0;
-  border-radius: 999px;
-  padding: 9px 12px;
-  background: #231719;
-  color: #ffffff;
-  font: inherit;
-  font-size: 12px;
-  font-weight: 850;
-  cursor: pointer;
-}
-
 .checkoutSlot {
   margin-top: clamp(18px, 5.185vw, 28px);
 }

src/app/tip/tip-screen.tsx

@@ -2,7 +2,7 @@
 
 import { useEffect, useMemo, useState, type CSSProperties } from "react";
 import Image from "next/image";
-import { Heart, Sparkles } from "lucide-react";
+import { Sparkles } from "lucide-react";
 
 import { BackButton, CharacterAvatar } from "@/app/_components";
 import { MobileShell } from "@/app/_components/core";
@@ -38,6 +38,7 @@ import {
   findTipCoffeePlan,
   formatTipPrice,
 } from "./tip-screen.helpers";
+import { TipSuccessView } from "./tip-success-view";
 import styles from "./tip-screen.module.css";
 
 const TIP_ANALYTICS_CONTEXT: PaymentAnalyticsContext = {
@@ -197,6 +198,21 @@ export function TipScreen({
     paymentDispatch({ type: "PaymentReset" });
   };
 
+  if (payment.isPaid) {
+    return (
+      <TipSuccessView
+        characterName={character.displayName}
+        characterAvatar={character.assets.avatar}
+        characterCover={character.assets.cover}
+        coffeeOption={coffeeOption}
+        splashHref={characterRoutes.splash}
+        tipCount={payment.tipCount}
+        thankYouMessage={payment.thankYouMessage}
+        onSendAgain={handleResetPaidState}
+      />
+    );
+  }
+
   return (
     <MobileShell background="#fff5ed">
       <main
@@ -288,25 +304,6 @@ export function TipScreen({
           </p>
         ) : null}
 
-        {payment.isPaid ? (
-          <section className={styles.successCard} aria-live="polite">
-            <Heart size={18} aria-hidden="true" />
-            <div>
-              <p className={styles.successTitle}>Coffee sent</p>
-              <p className={styles.successText}>
-                Thank you. Your payment has been confirmed.
-              </p>
-            </div>
-            <button
-              type="button"
-              className={styles.successButton}
-              onClick={handleResetPaidState}
-            >
-              Send again
-            </button>
-          </section>
-        ) : null}
-
         <div className={styles.checkoutSlot}>
           <TipCheckoutButton
             coffeeType={selectedCoffeeType}

src/app/tip/tip-success-view.module.css

@@ -0,0 +1,315 @@
+.shell {
+  position: relative;
+  display: grid;
+  min-height: var(--app-viewport-height, 100dvh);
+  place-items: center;
+  padding:
+    calc(var(--app-safe-top, 0px) + clamp(24px, 7vw, 40px))
+    calc(var(--app-safe-right, 0px) + clamp(18px, 5.5vw, 30px))
+    calc(var(--app-safe-bottom, 0px) + clamp(24px, 7vw, 40px))
+    calc(var(--app-safe-left, 0px) + clamp(18px, 5.5vw, 30px));
+  overflow: hidden auto;
+  background:
+    radial-gradient(circle at 15% 18%, rgba(255, 183, 120, 0.28), transparent 30%),
+    radial-gradient(circle at 87% 77%, rgba(244, 111, 151, 0.17), transparent 31%),
+    #fff7f0;
+  color: #2b1a1e;
+  isolation: isolate;
+}
+
+.coverWash,
+.glowOne,
+.glowTwo {
+  position: absolute;
+  pointer-events: none;
+}
+
+.coverWash {
+  inset: 0 0 auto;
+  z-index: -3;
+  height: min(47vh, 420px);
+  background:
+    linear-gradient(180deg, rgba(255, 247, 240, 0.48), #fff7f0 96%),
+    var(--tip-success-cover) center 16% / cover no-repeat;
+  filter: saturate(0.82);
+  opacity: 0.32;
+}
+
+.glowOne,
+.glowTwo {
+  z-index: -2;
+  border-radius: 999px;
+  filter: blur(18px);
+}
+
+.glowOne {
+  top: 16%;
+  right: -90px;
+  width: 210px;
+  height: 210px;
+  background: rgba(255, 126, 157, 0.17);
+}
+
+.glowTwo {
+  bottom: 8%;
+  left: -110px;
+  width: 250px;
+  height: 250px;
+  background: rgba(255, 188, 119, 0.2);
+}
+
+.card {
+  width: min(100%, 420px);
+  box-sizing: border-box;
+  padding: clamp(30px, 8vw, 44px) clamp(22px, 7vw, 36px) clamp(24px, 7vw, 36px);
+  border: 1px solid rgba(88, 50, 55, 0.08);
+  border-radius: clamp(28px, 8vw, 36px);
+  background: rgba(255, 255, 255, 0.93);
+  box-shadow: 0 28px 74px rgba(101, 61, 61, 0.14);
+  text-align: center;
+  backdrop-filter: blur(20px);
+}
+
+.visual {
+  position: relative;
+  width: 164px;
+  height: 140px;
+  margin: 0 auto 16px;
+}
+
+.avatarFrame {
+  position: absolute;
+  top: 0;
+  left: 13px;
+  width: 112px;
+  height: 112px;
+  border: 4px solid rgba(255, 255, 255, 0.98);
+  border-radius: 999px;
+  background: #f4d4c4;
+  box-shadow: 0 17px 36px rgba(102, 54, 57, 0.18);
+  overflow: hidden;
+}
+
+.coffeeFrame {
+  position: absolute;
+  right: 3px;
+  bottom: 1px;
+  width: 76px;
+  height: 76px;
+  border: 4px solid #ffffff;
+  border-radius: 24px;
+  background: #c69c80;
+  box-shadow: 0 13px 28px rgba(86, 47, 42, 0.2);
+  overflow: hidden;
+  transform: rotate(3deg);
+}
+
+.coffeeImage {
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+}
+
+.sparkleOne,
+.sparkleTwo {
+  position: absolute;
+  z-index: 2;
+  display: grid;
+  place-items: center;
+  color: #ef4f87;
+}
+
+.sparkleOne {
+  top: 5px;
+  right: 6px;
+}
+
+.sparkleTwo {
+  bottom: 7px;
+  left: 0;
+  color: #f78a68;
+}
+
+.eyebrow {
+  display: inline-flex;
+  min-height: 32px;
+  align-items: center;
+  gap: 7px;
+  margin: 0;
+  padding: 0 13px;
+  border-radius: 999px;
+  background: #fff0f4;
+  color: #c74470;
+  font-size: 12px;
+  font-weight: 900;
+  letter-spacing: 0.055em;
+  text-transform: uppercase;
+}
+
+.title {
+  max-width: 340px;
+  margin: 18px auto 0;
+  color: #2b1a1e;
+  font-family: var(--font-athelas), Georgia, serif;
+  font-size: clamp(30px, 8vw, 42px);
+  font-weight: 760;
+  letter-spacing: -0.045em;
+  line-height: 1.04;
+  outline: none;
+}
+
+.copy {
+  display: grid;
+  gap: 8px;
+  max-width: 330px;
+  margin: 16px auto 0;
+  color: #756065;
+  font-size: clamp(14px, 3.7vw, 17px);
+  font-weight: 610;
+  line-height: 1.55;
+  white-space: pre-line;
+}
+
+.copy p {
+  margin: 0;
+}
+
+.actions {
+  display: grid;
+  gap: 10px;
+  margin-top: clamp(24px, 7vw, 34px);
+}
+
+.primaryAction,
+.secondaryAction {
+  display: inline-flex;
+  min-height: 54px;
+  box-sizing: border-box;
+  align-items: center;
+  justify-content: center;
+  border-radius: 999px;
+  font: inherit;
+  font-size: 15px;
+  font-weight: 900;
+  text-decoration: none;
+  transition: transform 0.18s ease, box-shadow 0.18s ease, background 0.18s ease;
+}
+
+.primaryAction {
+  border: 0;
+  background: #2b1a1e;
+  color: #ffffff;
+  box-shadow: 0 14px 30px rgba(58, 29, 35, 0.2);
+  cursor: pointer;
+}
+
+.secondaryAction {
+  border: 1px solid rgba(67, 40, 45, 0.1);
+  background: #faf6f4;
+  color: #594349;
+}
+
+.primaryAction:focus-visible,
+.secondaryAction:focus-visible {
+  outline: 3px solid rgba(239, 79, 135, 0.28);
+  outline-offset: 3px;
+}
+
+@media (hover: hover) {
+  .primaryAction:hover,
+  .secondaryAction:hover {
+    transform: translateY(-1px);
+  }
+
+  .primaryAction:hover {
+    box-shadow: 0 17px 34px rgba(58, 29, 35, 0.24);
+  }
+
+  .secondaryAction:hover {
+    background: #ffffff;
+  }
+}
+
+.primaryAction:active,
+.secondaryAction:active {
+  transform: translateY(1px) scale(0.99);
+}
+
+@media (max-width: 350px) {
+  .shell {
+    padding-right: calc(var(--app-safe-right, 0px) + 14px);
+    padding-left: calc(var(--app-safe-left, 0px) + 14px);
+  }
+
+  .card {
+    padding-right: 18px;
+    padding-left: 18px;
+  }
+}
+
+@media (prefers-reduced-motion: no-preference) {
+  .card {
+    animation: cardReveal 0.46s cubic-bezier(0.22, 0.8, 0.32, 1) both;
+  }
+
+  .avatarFrame {
+    animation: avatarReveal 0.52s 0.08s cubic-bezier(0.2, 0.9, 0.28, 1.15) both;
+  }
+
+  .coffeeFrame {
+    animation: coffeeReveal 0.54s 0.16s cubic-bezier(0.2, 0.9, 0.28, 1.15) both;
+  }
+
+  .sparkleOne,
+  .sparkleTwo {
+    animation: sparkleReveal 0.5s 0.34s ease both;
+  }
+}
+
+@keyframes cardReveal {
+  from {
+    opacity: 0;
+    transform: translateY(14px) scale(0.985);
+  }
+
+  to {
+    opacity: 1;
+    transform: translateY(0) scale(1);
+  }
+}
+
+@keyframes avatarReveal {
+  from {
+    opacity: 0;
+    transform: translateY(8px) scale(0.88);
+  }
+
+  to {
+    opacity: 1;
+    transform: translateY(0) scale(1);
+  }
+}
+
+@keyframes coffeeReveal {
+  from {
+    opacity: 0;
+    transform: translate(9px, 8px) rotate(8deg) scale(0.76);
+  }
+
+  to {
+    opacity: 1;
+    transform: translate(0, 0) rotate(3deg) scale(1);
+  }
+}
+
+@keyframes sparkleReveal {
+  from {
+    opacity: 0;
+    transform: scale(0.4) rotate(-10deg);
+  }
+
+  to {
+    opacity: 1;
+    transform: scale(1) rotate(0);
+  }
+}

src/app/tip/tip-success-view.tsx

@@ -0,0 +1,132 @@
+"use client";
+
+import { useEffect, useRef, type CSSProperties } from "react";
+import Image from "next/image";
+import Link from "next/link";
+import { Coffee, Heart, Sparkles } from "lucide-react";
+
+import { CharacterAvatar } from "@/app/_components";
+import { MobileShell } from "@/app/_components/core";
+import type { TipCoffeeOption } from "@/lib/tip/tip_coffee";
+
+import { resolveTipSuccessCopy } from "./tip-screen.helpers";
+import styles from "./tip-success-view.module.css";
+
+export interface TipSuccessViewProps {
+  characterName: string;
+  characterAvatar: string;
+  characterCover: string;
+  coffeeOption: TipCoffeeOption;
+  splashHref: string;
+  tipCount: number | null;
+  thankYouMessage: string | null;
+  onSendAgain: () => void;
+}
+
+export function TipSuccessView({
+  characterName,
+  characterAvatar,
+  characterCover,
+  coffeeOption,
+  splashHref,
+  tipCount,
+  thankYouMessage,
+  onSendAgain,
+}: TipSuccessViewProps) {
+  const titleRef = useRef<HTMLHeadingElement>(null);
+  const copy = resolveTipSuccessCopy(tipCount, thankYouMessage);
+
+  useEffect(() => {
+    titleRef.current?.focus({ preventScroll: true });
+  }, []);
+
+  return (
+    <MobileShell background="#fff7f0">
+      <main
+        className={styles.shell}
+        style={
+          {
+            "--tip-success-cover": `url("${characterCover}")`,
+          } as CSSProperties
+        }
+      >
+        <div className={styles.coverWash} aria-hidden="true" />
+        <div className={styles.glowOne} aria-hidden="true" />
+        <div className={styles.glowTwo} aria-hidden="true" />
+
+        <section
+          className={styles.card}
+          aria-live="polite"
+          aria-labelledby="tip-success-title"
+        >
+          <div className={styles.visual}>
+            <span className={styles.sparkleOne} aria-hidden="true">
+              <Sparkles size={22} strokeWidth={1.8} />
+            </span>
+            <span className={styles.sparkleTwo} aria-hidden="true">
+              <Heart size={17} fill="currentColor" strokeWidth={1.8} />
+            </span>
+            <div className={styles.avatarFrame}>
+              <CharacterAvatar
+                src={characterAvatar}
+                alt={characterName}
+                size="100%"
+                imageSize={112}
+                priority
+              />
+            </div>
+            <div className={styles.coffeeFrame}>
+              <Image
+                src={coffeeOption.image.src}
+                alt={`${coffeeOption.displayName} coffee`}
+                width={coffeeOption.image.width}
+                height={coffeeOption.image.height}
+                sizes="78px"
+                className={styles.coffeeImage}
+                priority
+              />
+            </div>
+          </div>
+
+          <p className={styles.eyebrow}>
+            <Coffee size={15} aria-hidden="true" />
+            Coffee received
+          </p>
+          <h1
+            ref={titleRef}
+            id="tip-success-title"
+            className={styles.title}
+            tabIndex={-1}
+          >
+            {copy.title}
+          </h1>
+          {copy.body.length > 0 ? (
+            <div className={styles.copy}>
+              {copy.body.map((paragraph) => (
+                <p key={paragraph}>{paragraph}</p>
+              ))}
+            </div>
+          ) : null}
+
+          <div className={styles.actions}>
+            <button
+              type="button"
+              className={styles.primaryAction}
+              data-analytics-key="tip.send_again"
+              onClick={onSendAgain}
+            >
+              Send another coffee
+            </button>
+            <Link
+              href={splashHref}
+              className={styles.secondaryAction}
+              data-analytics-key="tip.success_back_to_splash"
+            >
+              Back to {characterName}
+            </Link>
+          </div>
+        </section>
+      </main>
+    </MobileShell>
+  );
+}

src/data/schemas/payment/__tests__/payment_plan.test.ts

@@ -2,11 +2,62 @@ import { describe, expect, it } from "vitest";
 import { z } from "zod";
 
 import {
+  PaymentOrderStatusResponseSchema,
   PaymentPlanSchema,
   PaymentPlansResponseSchema,
   TipPaymentPlansResponseSchema,
 } from "@/data/schemas/payment";
 
+describe("PaymentOrderStatusResponse", () => {
+  it("parses paid Tip success metadata", () => {
+    const response = PaymentOrderStatusResponseSchema.parse({
+      orderId: "tip_order_123",
+      status: "paid",
+      orderType: "tip",
+      planId: "tip_coffee_usd_9_99",
+      tipCount: 2,
+      thankYouMessage: "  You made my day.  ",
+    });
+
+    expect(response).toEqual({
+      orderId: "tip_order_123",
+      status: "paid",
+      orderType: "tip",
+      planId: "tip_coffee_usd_9_99",
+      tipCount: 2,
+      thankYouMessage: "You made my day.",
+    });
+  });
+
+  it("degrades missing or invalid optional Tip metadata to null", () => {
+    expect(
+      PaymentOrderStatusResponseSchema.parse({
+        orderId: "pay_order_456",
+        status: "pending",
+        orderType: "vip_monthly",
+        planId: "vip_monthly",
+      }),
+    ).toMatchObject({
+      tipCount: null,
+      thankYouMessage: null,
+    });
+
+    expect(
+      PaymentOrderStatusResponseSchema.parse({
+        orderId: "tip_order_invalid",
+        status: "paid",
+        orderType: "tip",
+        planId: "tip_coffee_usd_4_99",
+        tipCount: 0,
+        thankYouMessage: "   ",
+      }),
+    ).toMatchObject({
+      tipCount: null,
+      thankYouMessage: null,
+    });
+  });
+});
+
 describe("PaymentPlan", () => {
   it("parses the camelCase payment plan shape", () => {
     const plan = PaymentPlanSchema.parse({

src/data/schemas/payment/response/payment_order_status_response.ts

@@ -5,12 +5,31 @@ import { z } from "zod";
 
 export const PaymentOrderStatusSchema = z.enum(["pending", "paid", "failed"]);
 
+const tipCountOrNull = z.preprocess(
+  (value) =>
+    typeof value === "number" && Number.isInteger(value) && value > 0
+      ? value
+      : null,
+  z.number().int().positive().nullable(),
+);
+
+const thankYouMessageOrNull = z.preprocess(
+  (value) => {
+    if (typeof value !== "string") return null;
+    const message = value.trim();
+    return message.length > 0 ? message : null;
+  },
+  z.string().nullable(),
+);
+
 export const PaymentOrderStatusResponseSchema = z
   .object({
     orderId: z.string(),
     status: PaymentOrderStatusSchema,
     orderType: z.string(),
     planId: z.string(),
+    tipCount: tipCountOrNull,
+    thankYouMessage: thankYouMessageOrNull,
   })
   .readonly();
 

src/stores/payment/__tests__/payment-machine.test-utils.ts

@@ -101,6 +101,10 @@ export function createTestPaymentMachine(
     createOrderError: Error;
     orderStatus: "pending" | "paid" | "failed";
     orderStatuses: ("pending" | "paid" | "failed")[];
+    orderType: string;
+    orderPlanId: string;
+    tipCount: number | null;
+    thankYouMessage: string | null;
   }> = {},
 ) {
   const createOrderSpy = overrides.createOrderSpy ?? vi.fn<CreateOrderSpy>();
@@ -150,8 +154,10 @@ export function createTestPaymentMachine(
         return PaymentOrderStatusResponseSchema.parse({
           orderId: "pay_test_001",
           status,
-          orderType: "vip_monthly",
+          orderType: overrides.orderType ?? "vip_monthly",
-          planId: "vip_monthly",
+          planId: overrides.orderPlanId ?? "vip_monthly",
+          tipCount: overrides.tipCount ?? null,
+          thankYouMessage: overrides.thankYouMessage ?? null,
         });
       }),
     },

src/stores/payment/__tests__/payment-order-flow.test.ts

@@ -65,6 +65,8 @@ describe("payment order flow", () => {
     expect(actor.getSnapshot().context).toMatchObject({
       currentOrderId: "pay_test_001",
       orderStatus: "paid",
+      tipCount: null,
+      thankYouMessage: null,
       orderPollingStartedAt: null,
       launchNonce: 1,
     });
@@ -79,6 +81,80 @@ describe("payment order flow", () => {
     actor.stop();
   });
 
+  it("stores a stable Tip success result and clears it on reset", async () => {
+    const actor = createActor(
+      createTestPaymentMachine({
+        orderType: "tip",
+        orderPlanId: "tip_coffee_usd_9_99",
+        tipCount: 2,
+        thankYouMessage: "You made my day.",
+      }),
+    ).start();
+    await initialize(actor);
+    actor.send({
+      type: "PaymentCreateOrderSubmitted",
+      recipientCharacterId: "maya-tan",
+    });
+    await waitFor(actor, (snapshot) => snapshot.matches("paid"));
+
+    expect(actor.getSnapshot().context).toMatchObject({
+      orderStatus: "paid",
+      tipCount: 2,
+      thankYouMessage: "You made my day.",
+    });
+
+    actor.send({ type: "PaymentReset" });
+    await waitFor(actor, (snapshot) => snapshot.matches("ready"));
+    expect(actor.getSnapshot().context).toMatchObject({
+      tipCount: null,
+      thankYouMessage: null,
+    });
+    actor.stop();
+  });
+
+  it("clears the previous Tip result before creating another order", async () => {
+    const actor = createActor(
+      createTestPaymentMachine({
+        orderType: "tip",
+        tipCount: 3,
+        thankYouMessage: "Another warm coffee.",
+      }),
+    ).start();
+    await initialize(actor);
+    actor.send({ type: "PaymentCreateOrderSubmitted" });
+    await waitFor(actor, (snapshot) => snapshot.matches("paid"));
+
+    actor.send({ type: "PaymentCreateOrderSubmitted" });
+    expect(actor.getSnapshot().matches("creatingOrder")).toBe(true);
+    expect(actor.getSnapshot().context).toMatchObject({
+      tipCount: null,
+      thankYouMessage: null,
+    });
+    actor.stop();
+  });
+
+  it("clears the previous Tip result when the payment channel changes", async () => {
+    const actor = createActor(
+      createTestPaymentMachine({
+        orderType: "tip",
+        tipCount: 4,
+        thankYouMessage: "That was so thoughtful.",
+      }),
+    ).start();
+    await initialize(actor);
+    actor.send({ type: "PaymentCreateOrderSubmitted" });
+    await waitFor(actor, (snapshot) => snapshot.matches("paid"));
+
+    actor.send({ type: "PaymentPayChannelChanged", payChannel: "ezpay" });
+    expect(actor.getSnapshot().matches("ready")).toBe(true);
+    expect(actor.getSnapshot().context).toMatchObject({
+      payChannel: "ezpay",
+      tipCount: null,
+      thankYouMessage: null,
+    });
+    actor.stop();
+  });
+
   it("passes the selected tip recipient to order creation", async () => {
     const createOrderSpy = vi.fn<CreateOrderSpy>();
     const actor = createActor(
@@ -135,6 +211,8 @@ describe("payment order flow", () => {
       currentOrderId: null,
       payParams: null,
       orderStatus: null,
+      tipCount: null,
+      thankYouMessage: null,
       orderPollingStartedAt: null,
       errorMessage: null,
     });

src/stores/payment/helper/order.ts

@@ -25,6 +25,8 @@ export function resetOrderState(): Partial<PaymentState> {
     currentOrderPlanId: null,
     payParams: null,
     orderStatus: null,
+    tipCount: null,
+    thankYouMessage: null,
     orderPollingStartedAt: null,
     errorMessage: null,
   };

src/stores/payment/machine/order-flow.ts

@@ -47,6 +47,8 @@ const applyReturnedOrderAction = catalogMachineSetup.assign(({ event }) => {
     currentOrderPlanId: null,
     payParams: null,
     orderStatus: "pending",
+    tipCount: null,
+    thankYouMessage: null,
     orderPollingStartedAt: event.createdAt ?? Date.now(),
     errorMessage: null,
   };
@@ -97,6 +99,8 @@ const applyCreateOrderSuccessAction = createOrderDoneSetup.assign(
     currentOrderPlanId: context.selectedPlanId,
     payParams: event.output.payParams,
     orderStatus: "pending",
+    tipCount: null,
+    thankYouMessage: null,
     orderPollingStartedAt: Date.now(),
     errorMessage: null,
     launchNonce: context.launchNonce + 1,
@@ -134,6 +138,8 @@ const trackPollTimeoutAction = pollOrderDoneSetup.createAction(
 
 const applyPaidOrderAction = pollOrderDoneSetup.assign(({ event }) => ({
   orderStatus: event.output.status,
+  tipCount: event.output.tipCount,
+  thankYouMessage: event.output.thankYouMessage,
   orderPollingStartedAt: null,
   errorMessage: null,
 }));

src/stores/payment/payment-context.tsx

@@ -24,6 +24,8 @@ export interface PaymentContextState {
   currentOrderId: string | null;
   payParams: Record<string, unknown> | null;
   orderStatus: MachineContext["orderStatus"];
+  tipCount: number | null;
+  thankYouMessage: string | null;
   errorMessage: string | null;
   launchNonce: number;
   isLoadingPlans: boolean;
@@ -72,6 +74,8 @@ function selectPaymentState(state: PaymentSnapshot): PaymentContextState {
     currentOrderId: state.context.currentOrderId,
     payParams: state.context.payParams,
     orderStatus: state.context.orderStatus,
+    tipCount: state.context.tipCount,
+    thankYouMessage: state.context.thankYouMessage,
     errorMessage: state.context.errorMessage,
     launchNonce: state.context.launchNonce,
     isLoadingPlans:

src/stores/payment/payment-state.ts

@@ -21,6 +21,8 @@ export interface PaymentState {
   currentOrderPlanId: string | null;
   payParams: Record<string, unknown> | null;
   orderStatus: PaymentOrderStatus | null;
+  tipCount: number | null;
+  thankYouMessage: string | null;
   orderPollingStartedAt: number | null;
   errorMessage: string | null;
   launchNonce: number;
@@ -38,6 +40,8 @@ export const initialState: PaymentState = {
   currentOrderPlanId: null,
   payParams: null,
   orderStatus: null,
+  tipCount: null,
+  thankYouMessage: null,
   orderPollingStartedAt: null,
   errorMessage: null,
   launchNonce: 0,