支付、订阅与账单

报价与确认购买、Paywall、订阅变更、试用、退款、发票与原生购买。

API v1更新于 2026年10月22日

发起一次购买

调用 previewAttach 生成报价和 operationId，此时不扣款。
调用 attach 确认；返回 checkoutUrl 时跳转到 Stripe 付款页。
用户回来后调用 readSubscriptionOperation 读取结果，complete 表示已支付并生效。

purchase.tsTypeScript

1import { createIndiana } from "@tinkerlandai/indiana-sdk";2 3const indiana = createIndiana({4  baseUrl: "https://api.tinker.cash",5  scope: { projectId: "<APP_UUID>", environment: "sandbox" },6});7 8export async function buy(customerToken: string, requestId: string) {9  indiana.identify(customerToken);10  const { quote } = await indiana.previewAttach({11    requestId, // persisted before the first attempt12    plans: [{ productVersionId: "<PRODUCT_VERSION_UUID>" }],13    provider: "stripe",14    currency: "USD",15  });16  const { operation } = await indiana.attach({ operationId: quote.operationId });17  if (operation.checkoutUrl) window.location.assign(operation.checkoutUrl);18  return operation.operationId;19}20 21export async function afterReturn(operationId: string) {22  const { operation } = await indiana.readSubscriptionOperation({ operationId });23  return operation.status; // "pending" | "complete" | "cancelled" | "failed"24}

先在 Console 的支付连接中为该 App 和环境连接 Stripe；Sandbox 使用 Stripe 测试模式。
浏览器只能为当前用户购买；后端用 Server Key 调用时传入 customerId。
保存 requestId，重试时使用同一个值；不要根据跳转结果判断是否付款成功。

展示 Paywall

在 Console 发布 Paywall 后，用它的 ID 在页面中展示。用户购买后，SDK 自动完成报价与确认。

paywall.tsTypeScript

1import { createPaywallSession, showPaywall } from "@tinkerlandai/indiana-sdk";2 3const options = {4  baseUrl: "https://api.tinker.cash",5  scope: { projectId: "<APP_UUID>", environment: "sandbox" as const },6};7 8export function openPaywall(container: HTMLElement, customerToken: string) {9  return showPaywall(container, {10    start: () =>11      createPaywallSession(options, {12        paywallId: "<PAYWALL_UUID>",13        customerToken,14        commerce: { provider: "stripe", currency: "USD" },15        locale: "en",16      }),17    onCheckoutUrl: (url) => window.location.assign(url),18    onAccessGranted: (check) => console.log("access", check.allowed),19  });20}

变更订阅、试用与退款

app/change-plan.tsTypeScript

1import { createIndiana } from "@tinkerlandai/indiana-sdk";2 3const indiana = createIndiana({4  baseUrl: "https://api.tinker.cash",5  scope: { projectId: "<APP_UUID>", environment: "sandbox" },6});7 8export async function changePlan(customerToken: string, requestId: string, productVersionId: string) {9  indiana.identify(customerToken);10  const { holdings } = await indiana.readHoldings();11  const membership = holdings.memberships[0];12  if (!membership) throw new Error("No membership to change");13 14  // 1. Quote the change; nothing is charged yet.15  const { quote } = await indiana.previewUpdate({16    requestId, // persisted before the first attempt17    membershipId: membership.id,18    timing: "immediate",19    change: { type: "plan", productVersionId },20  });21 22  // 2. After the user accepts the quote, confirm it.23  const { operation } = await indiana.update({ operationId: quote.operationId });24  return operation;25}

常见任务
任务	方法	说明
升级、降级或取消	`previewUpdate` → `update` → `readSubscriptionUpdate`	`timing` 选择立即、续订时或在商店中生效。
保存付款方式	`setupPayment` → `readPaymentSetup`	不扣款。
开始、延长或结束试用	`manageSubscriptionTrial`, `readSubscriptionTrial`	后端调用。
退款	`previewRefund` → `refund` → `readRefund`	全额或部分；可选择是否撤销权益。
查询订阅与购买	`listSubscriptions`, `listPurchases`, `verifySubscriptions`	后端调用。
处理订阅冲突	`listSubscriptionConflicts`, `retrySubscriptionConflict`	后端调用。

常见任务

升级、降级或取消
方法
previewUpdate → update → readSubscriptionUpdate
说明
timing 选择立即、续订时或在商店中生效。
保存付款方式
方法
setupPayment → readPaymentSetup
说明
不扣款。
开始、延长或结束试用
方法
manageSubscriptionTrial, readSubscriptionTrial
说明
后端调用。
退款
方法
previewRefund → refund → readRefund
说明
全额或部分；可选择是否撤销权益。
查询订阅与购买
方法
listSubscriptions, listPurchases, verifySubscriptions
说明
后端调用。
处理订阅冲突
方法
listSubscriptionConflicts, retrySubscriptionConflict
说明
后端调用。

开启自动充值

余额低于 threshold 时自动购买，使用用户已保存的付款方式。必须先向用户展示 prepared.terms，用户同意后再确认。

auto-topup.tsTypeScript

1import { createIndiana } from "@tinkerlandai/indiana-sdk";2 3const indiana = createIndiana({4  baseUrl: "https://api.tinker.cash",5  scope: { projectId: "<APP_UUID>", environment: "sandbox" },6});7 8type UUID = ReturnType<typeof crypto.randomUUID>;9 10export async function prepareAutoTopup(customerToken: string, requestId: UUID) {11  indiana.identify(customerToken);12  const { prepared } = await indiana.prepareBillingAuthorization({13    requestId,14    kind: "auto_topup",15    productVersionId: "<CREDIT_PACK_VERSION_UUID>",16    internal_feature_id: "<CREDIT_FEATURE_UUID>",17    currency: "USD",18    threshold: "100",19    quantity: "1",20  });21  return prepared; // show prepared.terms to the Customer22}23 24// Call only after the Customer explicitly accepts the displayed terms.25export async function acceptAutoTopup(authorizationId: string) {26  return indiana.confirmBillingAuthorization({ authorizationId, accepted: true });27}

发票与用量上限

常见任务
任务	方法	调用方
创建与管理发票	`previewInvoice`, `createInvoice`, `manageInvoice`, `readInvoiceOperation`	后端
查询发票	`listInvoiceTemplates`, `listInvoices`, `getInvoice`	后端
设置用量上限与提醒	`manageBillingLimits`	后端
用户查看自己的账单	`listBillingInvoices`, `readBillingInvoice`, `readBillingControls`	浏览器
用户为会员选择优惠	`setBillingCoupons`	浏览器