Next.js 集成

✨ 利用 AI 安装

将此提示词复制到你的 AI 代码编辑器（Cursor、Copilot、Claude Code 等）中，即可自动完成集成：

使用官方 TypeScript SDK 将 Waffo Pancake 支付集成到我的 Next.js 应用中。

npm install @waffo/pancake-ts

要求：
1. 创建 /app/api/checkout/route.ts — 使用 WaffoPancake 客户端调用 client.checkout.createSession()
2. 创建 /app/api/webhooks/waffo/route.ts — 使用 SDK 的 verifyWebhook() 验证 x-waffo-signature
3. 添加环境变量：WAFFO_MERCHANT_ID, WAFFO_PRIVATE_KEY, NEXT_PUBLIC_APP_URL

完整 API 参考请阅读 https://waffo.mintlify.app/llms-full.txt

你将构建什么

一个完整的 Next.js 收银台集成，包括：

服务端创建收银台会话
客户端重定向到托管收银台
Webhook 处理支付确认
基于支付状态的受保护路由

前置条件

Next.js 13+ 带 App Router
拥有 API 密钥的 Waffo Pancake 账户
在控制台中创建的产品

项目设置

1. 安装依赖

npm install @waffo/pancake-ts

2. 环境变量

# .env.local
WAFFO_MERCHANT_ID=your-merchant-id
WAFFO_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\nMIIE..."
NEXT_PUBLIC_APP_URL=http://localhost:3000

SDK 支持多种私钥格式：PEM、base64 或原始格式 — 初始化时会自动标准化。.env 文件中的字面量 \n 也能正常使用。

创建收银台 API 路由

使用 SDK 创建一个 API 路由来生成收银台会话：

// app/api/checkout/route.ts
import { NextRequest, NextResponse } from "next/server";
import { WaffoPancake, CheckoutSessionProductType, WaffoPancakeError } from "@waffo/pancake-ts";

const client = new WaffoPancake({
  merchantId: process.env.WAFFO_MERCHANT_ID!,
  privateKey: process.env.WAFFO_PRIVATE_KEY!,
});

export async function POST(req: NextRequest) {
  try {
    const { productId, email, metadata } = await req.json();

    const session = await client.checkout.createSession({
      storeId: "store_xxx",
      productId,
      productType: CheckoutSessionProductType.Onetime,
      currency: "USD",
      buyerEmail: email || undefined,
      metadata,
      successUrl: `${process.env.NEXT_PUBLIC_APP_URL}/success`,
    });

    return NextResponse.json({ checkoutUrl: session.checkoutUrl });
  } catch (error) {
    if (error instanceof WaffoPancakeError) {
      return NextResponse.json({ error: error.errors[0]?.message }, { status: error.status });
    }
    return NextResponse.json({ error: "Failed to create checkout" }, { status: 500 });
  }
}

SDK 会自动处理请求签名 — 无需手动设置请求头。幂等性需自行开启：重试不能产生第二条记录时，在写操作（或 server action）的最后一个参数传 { idempotencyKey }；不传就不发这个头，也不会有任何去重。

优惠

优惠适用于一次性商品、新购订阅与更换方案。Checkout Session 上有三个设置，couponId 不能与另外两个同传（同时传返回 400）：

couponId：应用一张优惠券，买家不能更换或移除
promotionCode：预填一个买家能看到的码 —— 锁定，除非同时传 allowPromotionCodes: true
allowPromotionCodes: true：在收银台显示输码框（不传时，只在店铺有可用于该商品的码时显示；传 false 则隐藏）

不要从请求体读取 couponId 或 promotionCode。 上面的路由用你的 API Key 签名，浏览器传来的任何值都会以你的权限生效 —— 买家可以给自己的订单套用你的任意优惠券。请在服务端决定优惠：

// app/api/checkout/route.ts — decide the discount on the server
const session = await client.checkout.createSession({
  productId,
  currency: "USD",
  // Apply a coupon only after your own check, e.g. the signed-in user is a VIP
  ...(user?.isVip ? { couponId: "CPN_xxx" } : { allowPromotionCodes: true }),
  successUrl: `${process.env.NEXT_PUBLIC_APP_URL}/success`,
});

如果使用 @waffo/pancake-nextjs 组件：链接收银台支持 discountCode（以 discount_code 传给商品页，应用并锁定）；createCheckoutAction() 生成的 server action 透传 allowPromotionCodes，但出于同样的原因会剥离 couponId 与 promotionCode。要应用优惠券或预填码，请像上面一样在你自己的服务端代码中调用 @waffo/pancake-ts。

import { CheckoutButton } from "@waffo/pancake-nextjs";
import { checkout } from "./lib/waffo"; // createCheckoutAction(config)

// Product link with a locked code — no server action needed
<CheckoutButton type="link" storeSlug="my-store" productId="PROD_xxx" currency="USD" discountCode="SPRING-20">
  Buy Now — 20% off
</CheckoutButton>

// Session created by the server action, with a code entry field on the checkout page
<CheckoutButton action={checkout} productId="PROD_xxx" currency="USD" allowPromotionCodes>
  Buy Now
</CheckoutButton>

规则与码被拒绝的原因见优惠与促销。

定价页面组件

创建带有收银台按钮的定价页面：

// app/pricing/page.tsx
'use client';

import { useState } from 'react';

const plans = [
  {
    name: 'Starter',
    price: '$9',
    period: 'month',
    productId: 'prod_starter',
    features: ['5 projects', '10GB storage', 'Email support'],
  },
  {
    name: 'Pro',
    price: '$29',
    period: 'month',
    productId: 'prod_pro',
    features: ['Unlimited projects', '100GB storage', 'Priority support', 'API access'],
    popular: true,
  },
  {
    name: 'Enterprise',
    price: '$99',
    period: 'month',
    productId: 'prod_enterprise',
    features: ['Everything in Pro', 'Custom integrations', 'Dedicated support', 'SLA'],
  },
];

export default function PricingPage() {
  const [loading, setLoading] = useState<string | null>(null);

  async function handleCheckout(productId: string) {
    setLoading(productId);

    try {
      const response = await fetch('/api/checkout', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ productId }),
      });

      const { checkoutUrl, error } = await response.json();

      if (error) {
        alert(error);
        return;
      }

      // 重定向到 Waffo Pancake 收银台
      window.location.href = checkoutUrl;

    } catch (error) {
      alert('Something went wrong');
    } finally {
      setLoading(null);
    }
  }

  return (
    <div className="py-12">
      <h1 className="text-4xl font-bold text-center mb-12">
        Choose Your Plan
      </h1>

      <div className="grid md:grid-cols-3 gap-8 max-w-5xl mx-auto px-4">
        {plans.map((plan) => (
          <div
            key={plan.name}
            className={`border rounded-lg p-6 ${
              plan.popular ? 'border-green-500 ring-2 ring-green-500' : ''
            }`}
          >
            {plan.popular && (
              <span className="bg-green-500 text-white text-sm px-3 py-1 rounded-full">
                Most Popular
              </span>
            )}

            <h2 className="text-2xl font-bold mt-4">{plan.name}</h2>
            <p className="text-4xl font-bold mt-2">
              {plan.price}
              <span className="text-lg font-normal">/{plan.period}</span>
            </p>

            <ul className="mt-6 space-y-3">
              {plan.features.map((feature) => (
                <li key={feature} className="flex items-center">
                  <CheckIcon className="w-5 h-5 text-green-500 mr-2" />
                  {feature}
                </li>
              ))}
            </ul>

            <button
              onClick={() => handleCheckout(plan.productId)}
              disabled={loading !== null}
              className="w-full mt-8 py-3 px-4 bg-black text-white rounded-lg hover:bg-gray-800 disabled:opacity-50"
            >
              {loading === plan.productId ? 'Loading...' : 'Get Started'}
            </button>
          </div>
        ))}
      </div>
    </div>
  );
}

function CheckIcon({ className }: { className: string }) {
  return (
    <svg className={className} fill="none" viewBox="0 0 24 24" stroke="currentColor">
      <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M5 13l4 4L19 7" />
    </svg>
  );
}

Webhook 处理器

使用 SDK 内置的 verifyWebhook() 处理支付确认 — 它内嵌了测试和生产两个环境的公钥，因此无需管理 Webhook 密钥：

// app/api/webhooks/waffo/route.ts
import { NextResponse } from "next/server";
import { verifyWebhook, WebhookEventType } from "@waffo/pancake-ts";

export async function POST(request: Request) {
  const body = await request.text();
  const signature = request.headers.get("x-waffo-signature");

  try {
    const event = verifyWebhook(body, signature);

    // 立即响应，异步处理业务逻辑
    switch (event.eventType) {
      case WebhookEventType.OrderCompleted:
        console.log(`Order completed: ${event.data.orderId}`);
        // 更新数据库、授予访问权限等
        break;
      case WebhookEventType.SubscriptionActivated:
        console.log(`Subscription activated: ${event.data.buyerEmail}`);
        break;
      case WebhookEventType.SubscriptionCanceling:
        console.log(`Subscription canceling: ${event.data.orderId}`);
        break;
      case WebhookEventType.SubscriptionCanceled:
        console.log(`Subscription canceled: ${event.data.orderId}`);
        break;
      case WebhookEventType.RefundSucceeded:
        console.log(`Refund succeeded: ${event.data.amount} ${event.data.currency}`);
        break;
    }

    return NextResponse.json({ received: true });
  } catch {
    return new Response("Invalid signature", { status: 401 });
  }
}

SDK 的 verifyWebhook() 使用内嵌公钥 — 无需 WAFFO_WEBHOOK_SECRET 环境变量。同时默认包含重放攻击防护。

成功页面

支付成功后显示确认信息：

// app/success/page.tsx
import { Suspense } from 'react';

export default function SuccessPage() {
  return (
    <Suspense fallback={<div>Loading...</div>}>
      <SuccessContent />
    </Suspense>
  );
}

async function SuccessContent() {
  return (
    <div className="min-h-screen flex items-center justify-center">
      <div className="text-center">
        <div className="w-16 h-16 bg-green-100 rounded-full flex items-center justify-center mx-auto mb-4">
          <svg className="w-8 h-8 text-green-500" fill="none" viewBox="0 0 24 24" stroke="currentColor">
            <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M5 13l4 4L19 7" />
          </svg>
        </div>

        <h1 className="text-2xl font-bold mb-2">Payment Successful!</h1>
        <p className="text-gray-600 mb-6">
          Thank you for your purchase. You now have access to all features.
        </p>

        <a
          href="/zh/dashboard"
          className="inline-block bg-black text-white px-6 py-3 rounded-lg hover:bg-gray-800"
        >
          Go to Dashboard
        </a>
      </div>
    </div>
  );
}

受保护路由中间件

根据订阅状态保护路由：

// middleware.ts
import { NextResponse } from 'next/server';
import type { NextRequest } from 'next/server';

export function middleware(request: NextRequest) {
  // 获取用户会话（实现你自己的鉴权逻辑）
  const session = request.cookies.get('session');

  // 受保护的路由
  const protectedPaths = ['/dashboard', '/settings', '/projects'];
  const isProtectedPath = protectedPaths.some(path =>
    request.nextUrl.pathname.startsWith(path)
  );

  if (isProtectedPath && !session) {
    return NextResponse.redirect(new URL('/login', request.url));
  }

  return NextResponse.next();
}

export const config = {
  matcher: ['/dashboard/:path*', '/settings/:path*', '/projects/:path*'],
};

服务端组件：检查订阅

// app/dashboard/page.tsx
import { redirect } from 'next/navigation';
import { getServerSession } from 'your-auth-library';

export default async function DashboardPage() {
  const session = await getServerSession();

  if (!session) {
    redirect('/login');
  }

  // 从数据库获取用户的订阅信息
  const user = await prisma.user.findUnique({
    where: { id: session.user.id },
    select: {
      plan: true,
      subscriptionActive: true,
      subscriptionEndsAt: true,
    },
  });

  if (!user?.subscriptionActive) {
    redirect('/pricing');
  }

  return (
    <div>
      <h1>Welcome to your Dashboard</h1>
      <p>Your current plan: {user.plan}</p>
      {/* 仪表盘内容 */}
    </div>
  );
}

客户门户链接

让已登录用户无需邮箱验证码即可自助管理订单和订阅。在你的服务端用一个 Route Handler 生成门户链接并跳转：

// app/account/portal/route.ts
// Signature summary — see the @waffo/pancake-nextjs reference for the exact types
import { createCustomerPortalRedirect } from "@waffo/pancake-nextjs/server";
import { auth } from "@/lib/auth"; // your own session check

export const GET = createCustomerPortalRedirect(
  {
    merchantId: process.env.WAFFO_MERCHANT_ID!,
    privateKey: process.env.WAFFO_PRIVATE_KEY!,
  },
  {
    // Take the identity from your session — the same buyerIdentity used at checkout
    resolveAuthenticatedCustomer: async () => {
      const session = await auth();
      return session?.user
        ? { storeId: process.env.WAFFO_STORE_ID!, buyerIdentity: session.user.id }
        : null;
    },
    // Fixed path you control; without loginUrl, signed-out visitors get a 401
    loginUrl: "/login?returnTo=/account/portal",
  },
);

// components/ManageSubscription.tsx
// A plain <a>, not next/link: prefetching would create portal links nobody clicked
const PORTAL_ROUTE = "/account/portal";

export function ManageSubscriptionButton() {
  return (
    <a href={PORTAL_ROUTE} className="text-blue-600 hover:underline">
      Manage Subscription
    </a>
  );
}

身份规则、会话有效期以及不使用辅助方法的写法，见让已登录顾客管理订单。

完整文件结构

app/
├── api/
│   ├── checkout/
│   │   └── route.ts        # 创建收银台会话
│   └── webhooks/
│       └── waffo/
│           └── route.ts    # 处理 Webhook
├── pricing/
│   └── page.tsx            # 定价页面
├── success/
│   └── page.tsx            # 成功页面
├── dashboard/
│   └── page.tsx            # 受保护的仪表盘
└── layout.tsx

middleware.ts               # 路由保护
.env.local                  # 环境变量

测试清单

上线前：

使用测试卡 4576 7500 0000 0110 测试收银台流程
验证 Webhook 已收到（检查控制台日志）
使用 4576 7500 0000 0220 测试拒绝支付
确认成功页面正确显示
切换到正式 API 密钥
更新 Webhook URL 为生产端点

AI 集成

商业模式

运维集成

你将构建什么

前置条件

项目设置

1. 安装依赖

2. 环境变量

创建收银台 API 路由

优惠

定价页面组件

Webhook 处理器

成功页面

受保护路由中间件

服务端组件：检查订阅

客户门户链接

完整文件结构

测试清单

下一步

处理 Webhooks

订阅管理

​你将构建什么

​前置条件

​项目设置

​1. 安装依赖

​2. 环境变量

​创建收银台 API 路由

​优惠

​定价页面组件

​Webhook 处理器

​成功页面

​受保护路由中间件

​服务端组件：检查订阅

​客户门户链接

​完整文件结构

​测试清单

​下一步

处理 Webhooks

订阅管理

你将构建什么

前置条件

项目设置

1. 安装依赖

2. 环境变量

创建收银台 API 路由

优惠

定价页面组件

Webhook 处理器

成功页面

受保护路由中间件

服务端组件：检查订阅

客户门户链接

完整文件结构

测试清单

下一步