指南
Next.js
按照本指南在 Next.js App Router 中整合 StableOps：在伺服器端建立冪等付款訂單，使用錢包 SDK 發起鏈上轉帳，接收並驗證簽名 Webhook，再以可靠的狀態查詢完成履約；同時覆蓋金鑰隔離、錯誤處理和本地測試。
本指南使用 App Router 和目前的 TypeScript SDK。
安裝
pnpm add @stableops/api-sdk設定
STABLEOPS_API_KEY=sk_sandbox_...
STABLEOPS_WEBHOOK_SECRET=whsec_...建立 lib/stableops.ts：
import { StableOps } from '@stableops/api-sdk'
export const stableops = new StableOps({
apiKey: process.env.STABLEOPS_API_KEY!,
})建立訂單
建立 app/actions/payment.ts：
'use server'
import { revalidatePath } from 'next/cache'
import { stableops } from '@/lib/stableops'
export async function createPaymentOrder(formData: FormData) {
const amount = String(formData.get('amount') ?? '')
const merchantOrderId = String(formData.get('orderId') ?? '')
const order = await stableops.paymentOrders.create(
{
merchantOrderId,
amount,
acceptedAssets: [{ chain: 'base', asset: 'USDC' }],
expiresAt: new Date(Date.now() + 30 * 60 * 1000).toISOString(),
metadata: { source: 'nextjs_checkout' },
},
{ idempotencyKey: merchantOrderId },
)
revalidatePath('/payments')
return order
}把返回的一條候選支付指令展示給使用者：
{
order.paymentInstructions[0] ? (
<div>
在 {order.paymentInstructions[0].chain} 上向以下地址傳送 {order.amount}{' '}
{order.paymentInstructions[0].asset}：<code>{order.paymentInstructions[0].address}</code>
</div>
) : null
}驗證 Webhook
建立 app/api/webhooks/stableops/route.ts：
import { SIGNATURE_HEADER, verifySignature } from '@stableops/api-sdk/webhooks'
const WEBHOOK_SECRET = process.env.STABLEOPS_WEBHOOK_SECRET!
export async function POST(req: Request) {
const rawBody = await req.text()
const result = verifySignature({
secrets: [WEBHOOK_SECRET],
header: req.headers.get(SIGNATURE_HEADER) ?? undefined,
rawBody,
})
if (!result.ok) {
return new Response(`invalid signature: ${result.reason}`, { status: 400 })
}
const event = JSON.parse(rawBody) as {
type: string
data: { payment_order_id?: string }
}
switch (event.type) {
case 'payment.detected':
break
case 'payment.confirmed':
break
case 'payment.finalized':
// 做完自家冪等檢查後再履約。
break
case 'payment.expired':
case 'payment.reverted':
break
}
return new Response('ok')
}修改本地訂單狀態前請先在資料庫裡登記 X-Event-Id，避免 Webhook 重投導致重複履約。
這篇文件怎麼樣？
最後更新