IAP 定期订阅

用于自动续订订阅商品。会按固定周期自动扣费，直到取消前都可以继续使用。服务介绍和控制台设置方法在 应用内支付介绍文档请参考。

getProductItemList中介绍了订阅商品是如何下发的，以及创建订阅订单的 createSubscriptionPurchaseOrder的使用方法。还会说明在续订、解约等订阅状态变更时，如何通过 Webhook 接收服务器通知。

目前沙盒应用不支持测试订阅功能。

预计后续支持。

联动流程请按以下顺序进行。

1. 获取订阅商品列表 — getProductItemList
2. 创建订阅订单 — createSubscriptionPurchaseOrder
3. 查询订阅状态 — getSubscriptionInfo
4. 通过 Webhook 接收订阅状态变更 — 服务器回调
5. 恢复购买 — getPendingOrders, completeProductGrant

---

应用内支付对象

SDK 对象： IAP

现有 IAP 对象新增/扩展了以下功能。

签名

IAP {
  getProductItemList: typeof getProductItemList;
  createOneTimePurchaseOrder: typeof createOneTimePurchaseOrder;
  createSubscriptionPurchaseOrder: typeof createSubscriptionPurchaseOrder;
  getSubscriptionInfo: typeof getSubscriptionInfo;
  getPendingOrders: typeof getPendingOrders;
  getCompletedOrRefundedOrders: typeof getCompletedOrRefundedOrders;
  completeProductGrant: typeof completeProductGrant;
}

createSubscriptionPurchaseOrder是订阅专用的订单创建函数，与现有的一次性订单流程类似，但会处理订阅专用参数（如 offerId、renewalCycle 暴露等）。返回的 cleanup 函数与以往相同，用于释放 App Bridge 资源。

查询商品列表

SDK 函数： getProductItemList

getProductItemList()现在可以返回包含订阅商品（type: 'SUBSCRIPTION'）的商品列表。订阅商品会带有额外字段。

签名

function getProductItemList(): Promise<{ products: IapProductListItem[] } | undefined>;

返回值

• Promise<{ products: IapProductListItem\[] } | undefined>

  会返回包含商品列表的对象。若应用版本低于最低支持版本（Android 5.248.0, iOS 5.250.0）以下时 undefined则返回。

属性

/** 基本返回 **/
interface IapProductListItemBase {
  type: 'CONSUMABLE' | 'NON_CONSUMABLE' | 'SUBSCRIPTION';
  sku: string;
  displayAmount: string;
  displayName: string;
  iconUrl: string;
  description: string;
  hint?: Record<string, string>;
}

/** 订阅专用扩展返回 **/
interface IapSubscriptionProduct extends IapProductListItemBase {
  type: 'SUBSCRIPTION';
  renewalCycle: 'WEEKLY' | 'MONTHLY' | 'YEARLY';
  offers?: Offer[];
}

/** 订阅 Offer 类型 */
type Offer = FreeTrial | NewSubscription | Returning;

// 1. 免费试用
interface FreeTrial {
  type: 'FREE_TRIAL';
  offerId: string;
  period: string;
}

// 2. 新订阅用户
interface NewSubscription {
  type: 'NEW_SUBSCRIPTION';
  offerId: string;
  period: string;
  displayAmount: string;
}

// 3. 回归用户
interface Returning {
  type: 'RETURNING';
  offerId: string;
  period: string;
  displayAmount: string;
}

字段	类型	说明
类型	string	是商品类型
sku	string	是商品的唯一 ID
displayAmount	string	是包含货币单位的价格信息
displayName	string	是要显示在界面上的商品名称
iconUrl	string	是商品图标图片的 URL
description	string	是商品说明

商品类型区分

getProductItemList可以返回以下三种商品类型。

type IapProductType = 'CONSUMABLE' | 'NON_CONSUMABLE' | 'SUBSCRIPTION';

各类型的含义如下。

1. 消耗型商品（CONSUMABLE）

使用一次后即消失的商品。例如：金币、货币、爱心等

{
  type: 'CONSUMABLE';
  sku: string;
  displayAmount: string;
  displayName: string;
  iconUrl: string;
  description: string;
  hint?: Record<string, string>;
}

• 购买后可以多次重复购买。
• 支付成功后，需要在服务器发放商品并调用 completeProductGrant。
• 没有自动续订的概念。

2. 非消耗型商品（NON_CONSUMABLE）

购买一次后即可永久拥有的商品。例如：去广告、永久升级

{
  type: 'NON_CONSUMABLE';
  sku: string;
  displayAmount: string;
  displayName: string;
  iconUrl: string;
  description: string;
  hint?: Record<string, string>;
}

• 同一账号下不会重复购买。
• 更换设备时可能需要恢复逻辑。
• 不会自动续订。

3. 订阅商品（SUBSCRIPTION）

会按固定周期自动续订的商品。例如：月度/年度会员

{
  type: 'SUBSCRIPTION';
  sku: string;
  displayAmount: string;
  displayName: string;
  iconUrl: string;
  description: string;
  hint?: Record<string, string>;
  renewalCycle: 'WEEKLY' | 'MONTHLY' | 'YEARLY';
  offers?: Offer[];
}

字段	类型	说明
renewalCycle	string	是订阅续订周期
offers	Offer[]	是用户可获得的订阅权益列表。

• 会自动续订。
• 可包含免费试用、新用户优惠、回归优惠等 offers。
• 订单需要通过 createSubscriptionPurchaseOrder 创建。
• 需要在服务器端同步订阅状态（续订/取消/退款处理）。

按类型整理的订单创建函数

类型	订单创建函数
CONSUMABLE	createOneTimePurchaseOrder
NON_CONSUMABLE	createOneTimePurchaseOrder
SUBSCRIPTION	createSubscriptionPurchaseOrder

---

创建订阅订单

SDK 函数： createSubscriptionPurchaseOrder

用于为订阅商品创建专用订单，并跳转到订阅支付页面的函数。可在用户点击订阅商品购买按钮时使用。

签名

function createSubscriptionPurchaseOrder(params: CreateSubscriptionPurchaseOrderOptions): () => void;

属性

interface CreateSubscriptionPurchaseOrderOptions {
  options: {
    sku: string; // 必填：要购买的订阅 SKU
    offerId?: string | null; // 可选：要应用的 offer ID（如果没有则使用默认价格）
    processProductGrant: (params: { orderId: string; subscriptionId?: string }) => boolean | Promise<boolean>;
  };
  onEvent: (event: SubscriptionSuccessEvent) => void | Promise<void>;
  onError: (error: unknown) => void | Promise<void>;
}

使用示例

import { IAP } from '@apps-in-toss/web-framework';
import { useCallback } from 'react';

interface Props {
  sku: string;
  offerId?: string;
}

function SubscriptionPurchaseButton({ sku, offerId }: Props) {
  const handleClick = useCallback(async () => {
    const cleanup = IAP.createSubscriptionPurchaseOrder({
      options: {
        sku,
        offerId,
        processProductGrant: ({ orderId, subscriptionId }) => {
          // 商品发放逻辑编写
          console.log(orderId, subscriptionId);
          return true; // 是否发放商品
        },
      },
      onEvent: (event) => {
        console.log(event);
        cleanup();
      },
      onError: (error) => {
        console.error(error);
        cleanup();
      },
    });
  }, [sku, offerId]);

  return <button onClick={handleClick}>订阅</button>;
}

---

查询订阅状态

SDK 函数： getSubscriptionInfo

用于获取订阅订单当前状态信息的函数。

最低支持版本

• Toss App 最低支持版本为 Android 5.253.0, iOS 5.250.0 及以上。低于该版本时 undefined可能会返回。

签名

function getSubscriptionInfo(params: {
  params: { orderId: string };
}): Promise<{ subscription: IapSubscriptionInfoResult } | undefined>;

参数

• params 对象

  是包含要查询的订阅订单信息的对象。

  • params.orderId
  • string

    是订单的唯一 ID。

返回值

• Promise<{ subscription: IapSubscriptionInfoResult } | undefined>

  会返回包含订阅状态信息的对象。若应用版本低于最低支持版本（Android 5.253.0, iOS 5.250.0）以下时 undefined则返回。

属性

interface IapSubscriptionInfoResult {
  catalogId: number;
  status: 'ACTIVE' | 'EXPIRED' | 'IN_GRACE_PERIOD' | 'ON_HOLD' | 'PAUSED' | 'REVOKED';
  expiresAt: string | null;
  isAutoRenew: boolean;
  gracePeriodExpiresAt: string | null;
  isAccessible: boolean;
}

字段	类型	说明
catalogId	number	是订阅商品的标识符。
status	'ACTIVE' | 'EXPIRED' | 'IN_GRACE_PERIOD' | 'ON_HOLD' | 'PAUSED' | 'REVOKED'	是表示订阅状态的值。
expiresAt	string | null	是订阅预计到期时间。若没有到期信息，则 null。
isAutoRenew	boolean	是订阅是否自动续订。
gracePeriodExpiresAt	string | null	是付款宽限期到期时间。若没有宽限期，则 null。
isAccessible	boolean	是当前是否可以使用该订阅商品。

使用示例

React

import { IAP } from '@apps-in-toss/web-framework';

async function fetchSubscriptionInfo(orderId: string) {
  try {
    const response = await IAP.getSubscriptionInfo({ params: { orderId } });
    return response?.subscription;
  } catch (error) {
    console.error(error);
  }
}

React Native

import { IAP } from '@apps-in-toss/framework';

async function fetchSubscriptionInfo(orderId: string) {
  try {
    const response = await IAP.getSubscriptionInfo({ params: { orderId } });
    return response?.subscription;
  } catch (error) {
    console.error(error);
  }
}

---

通过 Webhook 接收订阅状态变更

当订阅续订、解约、暂停等订阅状态发生变化时，WebHook 事件会发送到服务器。在控制台注册回调 URL 后即可接收事件。

• 时间值(occurredAt, expiresAt 等）是没有时区的 ISO-8601 字符串。例如： "2026-05-06T00:00:00"
• orderId虽然不是直接的用户标识符，但如果正在将订单与用户进行映射，可将其用作关联标识符。

事件类型

eventType	说明
callback.registration_verification	注册/变更回调 URL 时发送
subscription.status_changed	订阅状态变更时发送

---

callback.registration_verification

注册或变更回调 URL 时会发送。必须正常接收此事件，回调 URL 才会激活。

{
  "eventType": "callback.registration_verification",
  "occurredAt": "2026-05-06T00:00:00"
}

---

subscription.status_changed

订阅状态确认后发送。

{
  "eventType": "subscription.status_changed",
  "eventVersion": "1.0",
  "occurredAt": "2026-05-06T00:00:00",
  "orderId": "order-1",
  "sku": "premium.monthly",
  "changeReason": "RENEWED",
  "subscription": {
    "previous": {
      "status": "ACTIVE",
      "accessGranted": true,
      "expiresAt": "2026-05-06T00:00:00",
      "autoRenew": true
    },
    "current": {
      "status": "ACTIVE",
      "accessGranted": true,
      "expiresAt": "2026-06-06T00:00:00",
      "autoRenew": true
    }
  }
}

CREATED等没有前一状态的情况 subscription.previous可以省略。

{
  "eventType": "subscription.status_changed",
  "eventVersion": "1.0",
  "occurredAt": "2026-05-06T00:00:00",
  "orderId": "order-1",
  "sku": "premium.monthly",
  "changeReason": "CREATED",
  "subscription": {
    "current": {
      "status": "ACTIVE",
      "accessGranted": true,
      "expiresAt": null,
      "autoRenew": true
    }
  }
}

字段

字段	类型	说明
eventType	string	固定值： subscription.status_changed
eventVersion	string	固定值： 1.0
occurredAt	string	是通知发生时间
orderId	string	是订单标识符
sku	string	是商品 SKU
changeReason	string	是订阅状态变更原因
subscription.previous	object?	是变更前的订阅状态。在创建事件中可能会省略
subscription.current	object	是变更后的订阅状态

Snapshot 字段

subscription.previous和 subscription.current具有相同的结构。

字段	类型	说明
status	string	是订阅状态
accessGranted	boolean	是当前是否已授予访问权限
expiresAt	string | null	是订阅到期时间。可能不存在
autoRenew	boolean	是是否自动续订

changeReason 值

值	含义
CREATED	订阅创建
RENEWED	订阅续订
RECOVERED	从支付失败状态恢复
RESTARTED	订阅重新开始
ENTERED_GRACE_PERIOD	进入宽限期
ON_HOLD	付款保留
PAUSED	订阅暂停
AUTO_RENEW_ENABLED	自动续订启用
AUTO_RENEW_DISABLED	自动续订禁用
EXTENDED	订阅期限延长
EXPIRED	订阅到期
REVOKED	订阅回收或退款处理

status 值

值	含义
ACTIVE	活跃
EXPIRED	到期
IN_GRACE_PERIOD	宽限期
ON_HOLD	搁置
PAUSED	暂停
REVOKED	已回收

---

恢复购买

即使支付已完成，也可能因网络错误或服务器错误导致商品发放失败。发生发放错误时，请务必添加购买恢复逻辑，以确保用户能够正常收到商品。

推荐流程

如果没有购买恢复逻辑，可能会出现支付已完成但用户却无法获得订阅权益的情况。建议在应用初始化时 getPendingOrders调用 以处理未完成订单。

恢复流程

1. getPendingOrders — 查询已支付但尚未发放的订阅订单列表
2. 商品发放处理 — 在服务器实际发放订阅商品
3. completeProductGrant — 完成发放处理

使用示例

React

import { IAP } from '@apps-in-toss/web-framework';

async function recoverPendingOrders() {
  const result = await IAP.getPendingOrders();

  if (!result?.orders?.length) return;

  for (const order of result.orders) {
    // 向服务器请求发放订阅商品
    const granted = await grantSubscriptionProduct(order.orderId);

    if (granted) {
      await IAP.completeProductGrant({ params: { orderId: order.orderId } });
    }
  }
}

React Native

import { IAP } from '@apps-in-toss/framework';

async function recoverPendingOrders() {
  const result = await IAP.getPendingOrders();

  if (!result?.orders?.length) return;

  for (const order of result.orders) {
    const granted = await grantSubscriptionProduct(order.orderId);

    if (granted) {
      await IAP.completeProductGrant({ params: { orderId: order.orderId } });
    }
  }
}