应用内支付

这是用于耗材、非耗材等一次购买即完成的商品的一次性支付 SDK。服务介绍和控制台设置方法请参考 应用内支付介绍文档请参考。

BaseURL

https://apps-in-toss-api.toss.im

服务器间通信需要 mTLS 证书

应用内支付的订单状态查询 API 是合作方服务器调用 Apps in Toss 服务器的服务器间通信。为安全起见，请先在服务器上配置 mTLS 证书后再调用。证书签发方法请参考 mTLS 证书签发方法。

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

1. 获取商品列表 — getProductItemList
2. 发起支付请求 — createOneTimePurchaseOrder
3. 恢复未完成订单 — getPendingOrders, completeProductGrant
4. 查询订单状态 — getCompletedOrRefundedOrders 或 订单状态查询 API

请注意

• SDK 1.1.3 及以上版本请使用。

  • 从 SDK 1.1.3 版本开始， 商品发放完成流程新增后函数接口发生了变化。
• SDK 1.2.2 版本开始， 购买恢复功能已新增。
• 即使用户设备更换，也请务必联动，以确保应用内支付商品的发放状态能够保持。

  • 请利用原生存储功能。
  • 请利用 Toss 登录联动和应用内支付状态查询 API。
• 使用应用内支付状态查询 API 前，请务必先完成 Toss 登录联动。

---

IAP 对象

IAP是汇集应用内支付相关函数的对象。

请注意

从 Toss 应用 5.219.0 版本开始支持。在不支持应用内支付的版本中， undefined则返回。

签名

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

属性

• getProductItemListtypeof getProductItemList

  这是用于获取可通过应用内支付购买的商品列表的函数。详细内容请参考 getProductItemList。
• createOneTimePurchaseOrdertypeof createOneTimePurchaseOrder

  这是用于发起应用内支付请求的函数。详细内容请参考 createOneTimePurchaseOrder。
• getPendingOrderstypeof getPendingOrders

  获取待处理订单列表。详细内容请参考 getPendingOrders 文档。
• getCompletedOrRefundedOrderstypeof getCompletedOrRefundedOrders

  获取通过应用内支付购买或已退款的订单列表。详细内容请参考 getCompletedOrRefundedOrders 文档。
• completeProductGranttypeof completeProductGrant

  向应用传递商品发放处理已完成的消息。详细内容请参考 completeProductGrant 文档。

查询商品列表

SDK 函数： getProductItemList

getProductItemList 是包含可通过应用内支付购买的商品列表的函数。用于在界面上展示商品列表。

签名

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

返回值

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

  返回包含商品列表的对象。如果应用版本低于最低支持版本（5.219.0）， undefined则返回。

属性

interface IapProductListItem {
  sku: string;
  displayAmount: string;
  displayName: string;
  iconUrl: string;
  description: string;
}

• IapProductListItem

  这是包含可通过应用内支付购买的单个商品信息的对象。用于在界面上展示商品列表。
• sku · 必填 · string

  是商品的唯一 ID。 IAP.createOneTimePurchaseOrder调用时使用的 productId值相同。

示例

获取可购买的应用内支付商品列表

js

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

async function handleGetProductItemList() {
  const response = await IAP.getProductItemList();

  return response?.products ?? [];
}

React

import { IAP, IapProductListItem } from '@apps-in-toss/web-framework';
import { Button, List, ListRow } from '@toss/tds-mobile';
import { useEffect, useState, useCallback } from 'react';

function IapProductList() {
  const [products, setProducts] = useState<IapProductListItem[]>([]);

  const handleBuy = useCallback(() => {
    const cleanup = IAP.createOneTimePurchaseOrder({
      options: {
        sku,
        processProductGrant: ({ orderId }) => {
          // 编写商品发放逻辑。
          return true; // 返回商品是否已发放。
        },
      },
      onEvent: (event) => {
        console.log(event);

        if (event.type === 'success') {
          cleanup();
        }
      },
      onError: (error) => {
        console.error(error);
        cleanup();
      },
    });
  }, [sku]);

  useEffect(() => {
    async function fetchProducts() {
      try {
        const response = await IAP.getProductItemList();
        setProducts(response?.products ?? []);
      } catch (error) {
        console.error('获取商品列表失败：', error);
      }
    }

    fetchProducts();
  }, []);

  return (
    <List>
      {products.map((product) => (
        <ListRow
          key={product.sku}
          left={<ListRow.Image type="square" src={product.iconUrl} />}
          contents={
            <ListRow.Texts
              type="3RowTypeA"
              top={product.displayName}
              middle={product.description}
              bottom={product.displayAmount}
            />
          }
          right={
            <Button size="medium" onClick={() => handleBuy(product.sku)}>
              购买
            </Button>
          }
        />
      ))}
    </List>
  );
}

React Native

import { IAP, IapProductListItem } from '@apps-in-toss/framework';
import { Button, List, ListRow } from '@toss/tds-react-native';
import { useEffect, useState, useCallback } from 'react';

function IapProductList() {
  const [products, setProducts] = useState<IapProductListItem[]>([]);

  const handleBuy = useCallback(() => {
    const cleanup = IAP.createOneTimePurchaseOrder({
      options: {
        sku,
        processProductGrant: ({ orderId }) => {
          // 编写商品发放逻辑。
          return true; // 返回商品是否已发放。
        },
      },
      onEvent: (event) => {
        console.log(event);

        if (event.type === 'success') {
          cleanup();
        }
      },
      onError: (error) => {
        console.error(error);
        cleanup();
      },
    });
  }, [sku]);

  useEffect(() => {
    async function fetchProducts() {
      try {
        const response = await IAP.getProductItemList();
        setProducts(response?.products ?? []);
      } catch (error) {
        console.error('获取商品列表失败：', error);
      }
    }

    fetchProducts();
  }, []);

  return (
    <List>
      {products.map((product) => (
        <ListRow
          key={product.sku}
          left={<ListRow.Image type="square" source={{ uri: product.iconUrl }} />}
          right={
            <Button size="medium" onPress={() => handleBuy(product.sku)}>
              购买
            </Button>
          }
          contents={
            <ListRow.Texts
              type="3RowTypeA"
              top={product.displayName}
              middle={product.description}
              bottom={product.displayAmount}
            />
          }
        />
      ))}
    </List>
  );
}

示例响应

{
  "products": [
    {
      "sku": "sku1",
      "displayName": "移除广告",
      "displayAmount": "4,900韩元",
      "iconUrl": "https://cdn.example.com/icons/premium-monthly.png",
      "description": "移除广告并提供高级功能"
    },
    {
      "sku": "sku2",
      "displayName": "100 个金币",
      "displayAmount": "9,900韩元",
      "iconUrl": "https://cdn.example.com/icons/coin-100.png",
      "description": "可在应用内使用的 100 个金币"
    }
  ]
}

体验示例应用

apps-in-toss-examples 在仓库中 with-in-app-purchase 下载代码并试用。

发起一次性支付请求

SDK 函数： createOneTimePurchaseOrder

createOneTimePurchaseOrder 该函数会打开应用内支付弹窗，用户将继续完成支付。若支付过程中发生错误，将根据错误类型跳转到错误页面。

请参考

支付成功后 30 秒内 processProductGrant 如果未调用回调或该回调结果不为 true， {appName} 出现问题。请申请退款 页面可能会显示。

签名

function createOneTimePurchaseOrder(params: IapCreateOneTimePurchaseOrderOptions): () => void;

参数

interface IapCreateOneTimePurchaseOrderOptions {
  options: { sku: string; processProductGrant: (params: { orderId: string }) => boolean | Promise<boolean> };
  onEvent: (event: SuccessEvent) => void | Promise<void>;
  onError: (error: unknown) => void | Promise<void>;
}

interface IapCreateOneTimePurchaseOrderResult {
  orderId: string;
  displayName: string;
  displayAmount: string;
  amount: number;
  currency: string;
  fraction: number;
  miniAppIconUrl: string | null;
}

interface SuccessEvent {
  type: 'success';
  data: IapCreateOneTimePurchaseOrderResult;
}

• options · 必填

  这是应用内支付所需的选项。

  • params.sku · 必填 · string

    是要下单的商品 ID。
  • params.processProductGrant · 必填 · (params: { orderId: string }) => boolean | Promise<boolean>

    订单创建后，实际发放商品时调用。 orderId接收后将发放成功与否 true 或 Promise<true>返回为。若发放失败， false则返回。
• onEvent · 必填 · (event: SuccessEvent) => void | Promise<void>

  支付成功时调用。

  • event.type · 必填 · "success"

    是事件类型。 "success"则返回。
  • event.data · 必填 · IapCreateOneTimePurchaseOrderResult

    应用内支付完成后，会返回包含支付详情和商品信息的结果。可使用返回的信息在界面上展示已购买商品的信息。

    • event.data.orderId · 必填 · string

      是支付订单 ID。支付完成后 查询支付状态时使用。
    • event.data.displayName · 必填 · string

      是要在界面上显示的商品名称。
    • event.data.displayAmount · 必填 · string

      是包含货币单位的价格信息。
    • event.data.amount · 必填 · number

      是商品价格的数值。
    • event.data.currency · 必填 · string

      是商品价格的货币单位。
    • event.data.fraction · 必填 · number

      是用于决定显示价格时保留到小数点后几位的值。
    • event.data.miniAppIconUrl · string | null

      是迷你应用图标图片的 URL。
• onError · 必填 · (error: unknown) => void | Promise<void>

  支付过程中发生错误时调用。接收错误对象后，可以进行日志记录或执行恢复流程。

错误代码

• INVALID_PRODUCT_ID : 商品 ID 无效，或该商品不存在。请确认商品 ID。

  在商品 ID 无效或该商品不存在时发生。

返回值

• () => void

  返回 App Bridge cleanup 函数。应用内支付功能结束后，必须调用此函数释放资源。

示例

跳转到特定的应用内支付订单页

js

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

let cleanup;

function handleBuyProduct(sku) {
  cleanup = IAP.createOneTimePurchaseOrder({
    options: {
      sku,
      processProductGrant: ({ orderId }) => {
        console.log('执行商品发放逻辑：', orderId);
        return true;
      },
    },
    onEvent: (event) => {
      console.log('事件：', event);
      cleanup?.();
    },
    onError: (error) => {
      console.error('应用内支付失败：', error);
      cleanup?.();
    },
  });
}

window.addEventListener('pagehide', () => {
  cleanup?.();
});

React

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

interface Props {
  sku: string;
}

function IapCreateOneTimePurchaseOrderButton({ sku }: Props) {
  const handleBuy = useCallback(() => {
    const cleanup = IAP.createOneTimePurchaseOrder({
      options: {
        sku,
        processProductGrant: ({ orderId }) => {
          // 编写商品发放逻辑。
          return true; // 返回商品是否已发放。
        },
      },
      onEvent: (event) => {
        console.log(event);
        cleanup();
      },
      onError: (error) => {
        console.error(error);
        cleanup();
      },
    });
  }, [sku]);

  return <Button onClick={handleBuy}>购买</Button>;
}

React Native

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

interface Props {
  sku: string;
}

function IapCreateOneTimePurchaseOrderButton({ sku }: Props) {
  const handleClick = useCallback(() => {
    const cleanup = IAP.createOneTimePurchaseOrder({
      options: {
        sku,
        processProductGrant: ({ orderId }) => {
          // 编写商品发放逻辑。
          return true; // 返回商品是否已发放。
        },
      },
      onEvent: (event) => {
        console.log(event);
        cleanup();
      },
      onError: (error) => {
        console.error(error);
        cleanup();
      },
    });
  }, []);

  return <Button onPress={handleClick}>购买</Button>;
}

体验示例应用

apps-in-toss-examples 在仓库中 with-in-app-purchase 下载代码并试用。

查询未完成订单

SDK 函数： getPendingOrders

getPendingOrders 是 已完成支付但商品尚未发放的订单列表的获取函数。请确认查询到的订单信息后向用户发放商品。 createOneTimePurchaseOrder 即使函数调用后未收到结果，也可以查询该订单。

如果应用版本低于最低支持版本（Android 5.234.0、iOS 5.231.0）， undefined则返回。

签名

function getPendingOrders(): Promise<{ orders: Order[] } | undefined>;

返回值

• Promise<{ orders: Order\[] } | undefined>

  返回包含待处理订单列表（orders）的对象。如果应用版本低于最低支持版本（Android 5.234.0、iOS 5.231.0）， undefined则返回。

返回对象属性

interface Order {
  orderId: string;
  sku: string;
  paymentCompletedDate?: string;
}

• orders · 必填 · Order\[]

  是待处理订单的数组。如果没有待处理订单，则返回空数组。
• orders[].orderId · 必填 · string

  是订单的唯一 ID。
• orders[].sku · 必填 · string

  是订单商品的唯一 ID。
• orders[].paymentCompletedDate · 必填 · string

  表示支付完成的时间。

字段更新说明

• SDK 1.4.2: sku 新增了字段。该字段 仅在 Android 5.234.0 及以上、iOS 5.231.0 及以上返回。
• SDK 1.4.8: paymentCompletedDate 新增了字段。可以确认支付完成时间。

示例

js

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

async function fetchOrders() {
  try {
    const pendingOrders = await IAP.getPendingOrders();
    return pendingOrders;
  } catch (error) {
    console.error(error);
  }
}

React

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

async function fetchOrders() {
  try {
    const pendingOrders = await IAP.getPendingOrders();
    return pendingOrders;
  } catch (error) {
    console.error(error);
  }
}

React Native

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

async function fetchOrders() {
  try {
    const pendingOrders = await IAP.getPendingOrders();
    return pendingOrders;
  } catch (error) {
    console.error(error);
  }
}

完成商品发放处理

SDK 函数： completeProductGrant

completeProductGrant 该函数 用于完成待处理订单商品发放处理的函数。请向用户发放商品并 completeProductGrant 调用函数将发放状态更改为完成。

如果应用版本低于最低支持版本（Android 5.231.0、iOS 5.231.0）， undefined则返回。

签名

function completeProductGrant(params: {
  params: {
    orderId: string;
  };
}): Promise<boolean | undefined>;

参数

• { params: { orderId: string } }

  是包含已完成支付订单信息的对象。

  • params.order · Id string

    是订单的唯一 ID。用于指定要完成商品发放的订单。

返回值

• Promise<boolean | undefined>

  返回商品发放是否完成。若应用版本低于最低支持版本（Android 5.233.0、iOS 5.233.0）， undefined则返回。

示例

js

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

async function handleCompleteProductGrant(orderId) {
  try {
    await IAP.completeProductGrant({ params: { orderId } });
  } catch (error) {
    console.error(error);
  }
}

React

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

async function handleCompleteProductGrant(orderId: string) {
  try {
    await IAP.completeProductGrant({ params: { orderId } });
  } catch (error) {
    console.error(error);
  }
}

React Native

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

async function handleCompleteProductGrant(orderId: string) {
  try {
    await IAP.completeProductGrant({ params: { orderId } });
  } catch (error) {
    console.error(error);
  }
}

查询已完成·已退款订单

SDK 函数： getCompletedOrRefundedOrders

getCompletedOrRefundedOrders 是获取通过应用内支付购买并退款的订单列表的函数。可以查询已完成支付及商品发放的订单和已退款订单。

已完成支付但商品尚未发放的订单不会被查询到。 getPendingOrders通过函数 orderId查询后，向用户发放商品并 completeProductGrant通过函数将商品发放处理标记为完成。

如果应用版本低于最低支持版本（Android 5.231.0、iOS 5.231.0）， undefined则返回。

分页

• 每页最多 50 个 订单会被返回。
• 当存在下一页时， hasNext为 true并且响应中的 nextKey作为下一次调用的 key 参数传递后继续查询。

签名

function getCompletedOrRefundedOrders(params?: {
  key?: string | null;
}): Promise<CompletedOrRefundedOrdersResult | undefined>;

返回值

• Promise<{ CompletedOrRefundedOrdersResult } | undefined>

  返回包含分页的订单列表对象。如果应用版本低于最低支持版本（Android 5.231.0、iOS 5.231.0）， undefined则返回。

返回对象属性

interface CompletedOrRefundedOrdersResult {
  hasNext: boolean;
  nextKey?: string | null;
  orders: {
    orderId: string;
    sku: string;
    status: 'COMPLETED' | 'REFUNDED';
    date: string;
  }[];
}

• hasNext · 必填 · boolean

  是否有下一页。 `true`如果是，则还有更多订单。
• nextKey（可选） · string | null · null

  用于查询下一页的游标键。上一条响应的 nextKey 使用该值。首次调用时可省略或 null传入。
• orders · 必填 · Array

  包含订单信息的数组。每个元素表示一笔订单。
• orders[].orderId · 必填 · string

  是订单的唯一 ID。
• 示例
• 订单状态查询 API

• 可以通过 API 在服务器端直接查询应用内支付订单状态。即使未收到批准或退款响应，也可以使用。
• 请参考

  使用支付状态查询 API 之前，请先进行 Toss 登录 集成。
• Content-type: application/json
• Method: POST
• URL: /api-partner/v1/apps-in-toss/order/get-order-status
• 请求头
• 如果不包含该头部，则会返回所有订单。
• 在头部中 x-toss-user-key 包含该值时，只会返回对应 userKey 的订单。
• 请求参数
• {
    "orderId": "13c9a1ff-2baa-4495-bbfa-a0826ba8c7c0"
  }

• 响应
• status (enum)
• 响应示例
• {
    "resultType": "SUCCESS",
    "success": {
      "orderId": "13c9a1ff-2baa-4495-bbfa-a0826ba8c7c0",
      "sku": "ait.0000010000.af647449.3bd55cfd00.0000000475",
      "statusDeterminedAt": "2025-09-12T16:57:12",
      "status": "PAYMENT_COMPLETED",
      "reason": "支付已完成。"
    }
  }

• {
    "resultType": "SUCCESS",
    "success": {
      "orderId": "13c9a1ff-2baa-4495-bbfa-0000000000",
      "sku": "ait.0000010000.af647449.00000000000.0000000475",
      "statusDeterminedAt": "2025-09-12T16:57:12",
      "status": "PURCHASED",
      "reason": "这是已完成的订单。"
    }
  }

• 沙盒测试

• 上线前务必 沙盒应用环境请测试其中的应用内支付是否正常运行。在沙盒中不会发生真实支付（扣费），所有支付都会按测试场景处理。
• 请参考

  目前沙盒测试 一次性支付仅支持。订阅支付的沙盒测试目前不支持。
• 1. 在沙盒中查询商品列表时的行为
• 在沙盒应用中 getProductItemList()调用时，在控制台中注册的应用内支付商品中 展示状态为 ON的商品才会被查询到。
• 实际在控制台注册的商品列表会原样返回。
• 在控制台中 展示 OFF的商品在沙盒应用中也看不到。
• 2. 必须测试的场景
• 在沙盒中，下面 3 种测试必须分别执行。请确认应用在每个场景下是否正确响应。
• ① 支付成功测试
• 成功回调(event.type: success)是否能正常传递。
• 不会发生真实支付（扣费）。
• 在 SDK 1.1.3 及以上版本中，合作方的 连商品发放逻辑也成功后，才算最终成功处理。
• 需要确认的项目

  • orderId, amount 等 event.data 是否正常返回
  • 内部发放逻辑是否正常运行
  • 发放完成后屏幕/UI 更新
• [观看视频](../../../../resources/development/iap/iap_sandbox_test_1.mp4)
• ② 支付成功（服务器失败）测试
• 虽然支付成功，但合作方服务器的发放逻辑失败的情况必须测试。
• 应用需要支持以下处理：
• 发放完成后 completeProductGrant 调用
• 应用重新启动时 getPendingOrders恢复未完成订单
• 向用户提示发放失败
• 这是在正式服务中也很可能发生的场景，因此必须测试。
• [观看视频](../../../../resources/development/iap/iap_sandbox_test_2.mp4)
• ③ 错误测试
• 请提前模拟支付过程中发生错误的各种情况。
• 需要测试的典型场景

  • 网络错误
  • 用户取消支付
  • 内部错误
  • 合作方商品发放失败
• [观看视频](../../../../resources/development/iap/iap_sandbox_test_3.mp4)
• 3. 测试检查清单
• 常见问题

测试项目	必填	确认要点
商品列表展示	✔️	控制台中注册的商品是否能正常返回
支付成功测试	✔️	event.data 处理、发放逻辑、UI 处理
支付成功 + 服务器发放失败（订单恢复）	✔️	未完成订单恢复及重新发放处理
错误测试	✔️	错误 UI、错误处理、重试流程
订单状态查询 API	推荐	服务器验证及一致性确认

状态	说明	详细说明
PURCHASED	订单完成	应用内支付和商品发放都已完成的状态
PAYMENT_COMPLETED	支付完成	在 SDK 1.1.3 及以上版本中，支付已完成但商品发放失败的状态
FAILED	订单失败	支付失败的情况
REFUNDED	订单已退款	已完成退款的情况
ORDER_IN_PROGRESS	订单进行中	订单已创建，但支付/发放处理尚未完成的情况
NOT_FOUND	无订单	找不到对应订单号的情况
MINIAPP_MISMATCH	商品不匹配	所订购的商品不是该应用的商品的情况
ERROR	内部错误	发生系统内部错误时

名称	类型	说明
orderId	String	请求的订单号
sku	String	所订购的商品 ID
statusDeterminedAt	String	订单完成时间（yyyy-MM-dd'T'HH🇲🇲ss，固定为 KST） status为 REFUNDED时为退款完成时间
status	String	订单状态（enum）
reason	String	状态说明

名称	类型	必填	说明
orderId	String	Y	支付创建后获取的订单号（uuid v7）

名称	类型	是否必填	说明
x-toss-user-key	string	N	通过 Toss 登录 获取的 userKey 值