In-App Purchases

It’s a one-time payment SDK used for products completed with a single purchase, such as consumables and non-consumables. For an introduction to the service and how to set up the console, In-app Purchase introduction documentplease refer to.

BaseURL

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

mTLS certificate is required for server-to-server communication

The in-app purchase order status inquiry API is server-to-server communication called from the partner server to the Apps in Toss server. For security, set up an mTLS certificate on your server before making the call. For how to issue a certificate, refer to the mTLS certificate issuance guide.

Follow the sequence below for the integration flow.

1. Get product list — getProductItemList
2. Request payment — createOneTimePurchaseOrder
3. Restore pending orders — getPendingOrders, completeProductGrant
4. Check order status — getCompletedOrRefundedOrders or Order status inquiry API

Please note

• SDK version 1.1.3 or laterPlease use it.

  • Starting from SDK version 1.1.3, the product grant completion processwas added, changing the function interface.
• SDK version 1.2.2and later, purchase restoration featurewas added.
• Be sure to integrate it so in-app purchase products remain granted even if the user's device changes.

  • Use the native storage feature.
  • Use Toss Login integration and the in-app purchase status inquiry API.
• To use the in-app purchase status inquiry API, you must first integrate Toss Login.

---

IAP object

IAPis an object that contains in-app purchase-related functions.

Please note

Supported from Toss app version 5.219.0. In versions that do not support in-app purchases, undefinedis returned.

Signature

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

Properties

• getProductItemListtypeof getProductItemList

  This is a function that retrieves the list of products that can be purchased with in-app purchases. For details, getProductItemListPlease refer to it.
• createOneTimePurchaseOrdertypeof createOneTimePurchaseOrder

  This is a function that requests an in-app purchase. For details, createOneTimePurchaseOrderPlease refer to it.
• getPendingOrderstypeof getPendingOrders

  It retrieves the list of pending orders. For details, getPendingOrders refer to the document.
• getCompletedOrRefundedOrderstypeof getCompletedOrRefundedOrders

  It retrieves the list of orders purchased or refunded through in-app purchases. For details, getCompletedOrRefundedOrders refer to the document.
• completeProductGranttypeof completeProductGrant

  It sends a message to the app that product grant processing has been completed. For details, completeProductGrant refer to the document.

View product list

SDK function: getProductItemList

getProductItemList This is a function that contains the list of products purchasable with in-app purchases. Use it to display the product list on screen.

Signature

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

Return value

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

  Returns an object containing the product list. If the app version is lower than the minimum supported version (5.219.0), undefinedis returned.

Properties

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

• IapProductListItem

  This is an object containing information about a single product that can be purchased with in-app purchases. Use it to display the product list on screen.
• sku · Required · string

  The product's unique ID. IAP.createOneTimePurchaseOrderused when calling productIdhas the same value as.

Example

Get purchasable in-app purchase product list

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 }) => {
          // Write the product grant logic.
          return true; // Return whether the product was granted.
        },
      },
      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('Failed to get the product list:', 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)}>
              Buy
            </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 }) => {
          // Write the product grant logic.
          return true; // Return whether the product was granted.
        },
      },
      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('Failed to get the product list:', 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)}>
              Buy
            </Button>
          }
          contents={
            <ListRow.Texts
              type="3RowTypeA"
              top={product.displayName}
              middle={product.description}
              bottom={product.displayAmount}
            />
          }
        />
      ))}
    </List>
  );
}

Example response

{
  "products": [
    {
      "sku": "sku1",
      "displayName": "Remove ads",
      "displayAmount": "4,900 won",
      "iconUrl": "https://cdn.example.com/icons/premium-monthly.png",
      "description": "Remove ads and premium features"
    },
    {
      "sku": "sku2",
      "displayName": "100 coins",
      "displayAmount": "9,900 won",
      "iconUrl": "https://cdn.example.com/icons/coin-100.png",
      "description": "100 coins usable in the app"
    }
  ]
}

Try the sample app

apps-in-toss-examples from the repository with-in-app-purchase Download the code and try it out.

Request a one-time payment

SDK function: createOneTimePurchaseOrder

createOneTimePurchaseOrder This function opens the in-app purchase payment sheet and the user proceeds with payment. If an error occurs during payment, the app navigates to an error page depending on the error type.

See

Within 30 seconds after successful payment, processProductGrant if the callback is not called or the result of that callback is not true, {appName} has encountered a problem. Please request a refund the page may be displayed.

Signature

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

Parameters

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 · Required

  This is a required option for in-app purchases.

  • params.sku · Required · string

    The ID of the product to order.
  • params.processProductGrant · Required · (params: { orderId: string }) => boolean | Promise<boolean>

    Called when actually granting the product after the order is created. orderIdreceives it and returns whether the grant succeeded as true or Promise<true>If granting fails, returns falseis returned.
• onEvent · Required · (event: SuccessEvent) => void | Promise<void>

  Called when payment succeeds.

  • event.type · Required · "success"

    This is the event type. "success"is returned.
  • event.data · Required · IapCreateOneTimePurchaseOrderResult

    When the in-app purchase is completed, it returns the payment details and product information. You can use the returned information to display the purchased product information on screen.

    • event.data.orderId · Required · string

      This is the payment order ID. Used to query payment status after payment is completed. query the payment statuswhen needed.
    • event.data.displayName · Required · string

      The product name to display on screen.
    • event.data.displayAmount · Required · string

      The price information including the currency unit.
    • event.data.amount · Required · number

      The numeric value of the product price.
    • event.data.currency · Required · string

      The currency unit of the product price.
    • event.data.fraction · Required · number

      The value that determines how many decimal places to show when displaying the price.
    • event.data.miniAppIconUrl · string | null

      URL of the mini app icon image.
• onError · Required · (error: unknown) => void | Promise<void>

  Called when an error occurs during payment. You can receive the error object to log it or run recovery steps.

Error code

• INVALID_PRODUCT_ID : The product ID is invalid, or the product does not exist. Please check the product ID.

  Occurs when the product ID is invalid or the product does not exist.

Return value

• () => void

  Returns the App Bridge cleanup function. When the in-app purchase feature ends, you must call this function to release resources.

Example

Go to a specific in-app purchase order page

js

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

let cleanup;

function handleBuyProduct(sku) {
  cleanup = IAP.createOneTimePurchaseOrder({
    options: {
      sku,
      processProductGrant: ({ orderId }) => {
        console.log('Running product grant logic:', orderId);
        return true;
      },
    },
    onEvent: (event) => {
      console.log('Event:', event);
      cleanup?.();
    },
    onError: (error) => {
      console.error('In-app purchase failed:', 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 }) => {
          // Write the product grant logic.
          return true; // Return whether the product was granted.
        },
      },
      onEvent: (event) => {
        console.log(event);
        cleanup();
      },
      onError: (error) => {
        console.error(error);
        cleanup();
      },
    });
  }, [sku]);

  return <Button onClick={handleBuy}>Buy</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 }) => {
          // Write the product grant logic.
          return true; // Return whether the product was granted.
        },
      },
      onEvent: (event) => {
        console.log(event);
        cleanup();
      },
      onError: (error) => {
        console.error(error);
        cleanup();
      },
    });
  }, []);

  return <Button onPress={handleClick}>Buy</Button>;
}

Try the sample app

apps-in-toss-examples from the repository with-in-app-purchase Download the code and try it out.

View pending orders

SDK function: getPendingOrders

getPendingOrders is the list of orders for which payment has been completed but the product has not yet been grantedRetrieve it and grant the product to the user. createOneTimePurchaseOrder You can query the order even if you did not receive a result after calling the function.

If the app version is lower than the minimum supported version (Android 5.234.0, iOS 5.231.0), undefinedis returned.

Signature

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

Return value

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

  Returns an object containing the list of pending orders (orders). If the app version is lower than the minimum supported version (Android 5.234.0, iOS 5.231.0), undefinedis returned.

Returned object properties

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

• orders · Required · Order\[]

  An array of pending orders. Returns an empty array if there are no pending orders.
• orders[].orderId · Required · string

  The order's unique ID.
• orders[].sku · Required · string

  The unique ID of the ordered product.
• orders[].paymentCompletedDate · Required · string

  Indicates when the payment was completed.

Field update guide

• SDK 1.4.2: sku This field has been added. This field is returned only on Android 5.234.0 or later and iOS 5.231.0 or later. Android 5.234.0 or later, iOS 5.231.0 or lateronly.
• SDK 1.4.8: paymentCompletedDate This field has been added. You can check when the payment was completed.

Example

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);
  }
}

Complete product grant processing

SDK function: completeProductGrant

completeProductGrant The function that completes product grant processing for pending ordersfor pending orders. Grant the product to the user and completeProductGrant call the function to change the grant status to completed.

If the app version is lower than the minimum supported version (Android 5.231.0, iOS 5.231.0), undefinedis returned.

Signature

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

Parameters

• { params: { orderId: string } }

  This is an object containing order information for which payment has been completed.

  • params.order · Id string

    The order's unique ID. Use it when specifying the order whose product grant should be completed.

Return value

• Promise<boolean | undefined>

  Returns whether the product grant has been completed. If the app version is lower than the minimum supported version (Android 5.233.0, iOS 5.233.0), undefinedis returned.

Example

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);
  }
}

View completed/refunded orders

SDK function: getCompletedOrRefundedOrders

getCompletedOrRefundedOrders It retrieves the list of orders purchased and refunded through in-app purchases. You can query orders with completed in-app purchase payment and product grant, as well as refunded orders.

Orders whose payment is complete but whose product has not yet been granted are not retrieved. getPendingOrdersThrough the function orderIdquery it and grant the product to the user, then completeProductGrantcomplete product grant processing using the function.

If the app version is lower than the minimum supported version (Android 5.231.0, iOS 5.231.0), undefinedis returned.

Pagination

• Up to 50 orders are returned per page.
• When there is a next page, hasNextis trueand the response's nextKeypass it as a parameter to the next call key and continue querying.

Signature

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

Return value

• Promise<{ CompletedOrRefundedOrdersResult } | undefined>

  Returns an order list object including pagination. If the app version is lower than the minimum supported version (Android 5.231.0, iOS 5.231.0), undefinedis returned.

Returned object properties

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

• hasNext · Required · boolean

  Indicates whether there is a next page. `true`If `true`, there are more orders remaining.
• nextKey optional · string | null · null

  This is the cursor key for fetching the next page. Use the nextKey value from the previous response. On the first call, omit it or nullpass it.
• orders · Required · Array

  An array containing order information. Each element represents one order.
• orders[].orderId · Required · string

  The order's unique ID.
• Example
• Order status inquiry API

• You can directly query in-app purchase order status via the API from the server. You can use it even if you did not receive an approval or refund response.
• See

  To use the payment status inquiry API, please first set up Toss Login integration.
• Content-type: application/json
• Method: POST
• URL: /api-partner/v1/apps-in-toss/order/get-order-status
• Request headers
• If the header is not included, all orders are returned.
• In the header, x-toss-user-key if you include the value, only orders for that userKey are returned.
• Request parameters
• {
    "orderId": "13c9a1ff-2baa-4495-bbfa-a0826ba8c7c0"
  }

• Response
• status (enum)
• Response example
• {
    "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": "The payment has been completed."
    }
  }

• {
    "resultType": "SUCCESS",
    "success": {
      "orderId": "13c9a1ff-2baa-4495-bbfa-0000000000",
      "sku": "ait.0000010000.af647449.00000000000.0000000475",
      "statusDeterminedAt": "2025-09-12T16:57:12",
      "status": "PURCHASED",
      "reason": "This is a completed order."
    }
  }

• Sandbox test

• Before release, be sure to sandbox app environmenttest whether in-app purchases work properly. In Sandbox, no actual payment (billing) occurs, and all payments are handled as test scenarios.
• See

  Currently, Sandbox testing one-time paymentsare supported only. Sandbox testing for subscription payments is not currently supported.
• 1. Behavior when checking the product list in Sandbox
• In the Sandbox app, getProductItemList()when called, among the in-app purchase products registered in the console, only those with display status ONare retrieved.
• The list of products registered in the actual console is returned as is.
• In the console, display OFFproducts are not visible in the Sandbox app either.
• 2. Required test scenarios
• In Sandbox, you must perform the following three tests individually. Please check whether the app responds correctly in each scenario.
• ① Payment success test
• Success callback (event.type: success) is delivered correctly.
• No actual payment (billing) occurs.
• In SDK 1.1.3 or later, the partner's the item delivery logic must also succeed for the final successto be treated as successful.
• Items to check

  • orderId, amount etc. event.data Whether it is returned normally
  • Whether the internal delivery logic works properly
  • Screen/UI update after delivery completion
• [Watch video](../../../../resources/development/iap/iap_sandbox_test_1.mp4)
• ② Payment success (server failure) test
• You must test the case where payment succeeds but the partner server's delivery logic fails.
• The app must support the following handling:
• After delivery completion completeProductGrant call
• When the app is relaunched getPendingOrdersrestore pending orders with
• Notify the user of delivery failure
• This is a scenario that can occur frequently in production as well, so be sure to test it.
• [Watch video](../../../../resources/development/iap/iap_sandbox_test_2.mp4)
• ③ Error test
• Simulate various situations where errors occur during payment in advance.
• Typical scenarios to test

  • Network error
  • User cancels payment
  • Internal error
  • Partner item delivery failure
• [Watch video](../../../../resources/development/iap/iap_sandbox_test_3.mp4)
• 3. Test checklist
• Frequently asked questions

Test item	Required	Checkpoints
Product list display	✔️	Whether the products registered in the console are returned properly
Payment success test	✔️	event.data Processing, delivery logic, UI handling
Payment success + server delivery failure (order restoration)	✔️	Pending order restoration and re-delivery handling
Error test	✔️	Error UI, error handling, retry flow
Order status inquiry API	Recommended	Server validation and consistency checks

Status	Description	Detailed description
PURCHASED	Order completed	State where both in-app payment and item delivery are complete
PAYMENT_COMPLETED	Payment completed	In SDK 1.1.3 or later, payment is complete but item delivery failed
FAILED	Order failed	When payment fails
REFUNDED	Order refunded	When the refund is complete
ORDER_IN_PROGRESS	Order in progress	When the order has been created but payment/delivery processing is not complete
NOT_FOUND	No order	When the corresponding order number cannot be found
MINIAPP_MISMATCH	Product mismatch	When the ordered product is not a product for the app
ERROR	Internal error	When an internal system error occurs

Name	Type	Description
orderId	String	Requested order number
sku	String	Ordered product ID
statusDeterminedAt	String	Order completion date/time (yyyy-MM-dd'T'HH🇲🇲ss, fixed to KST) statusis REFUNDEDIf so, refund completion date/time
status	String	Status for the order (enum)
reason	String	Description of the status

Name	Type	Required	Description
orderId	String	Y	Order number acquired after payment creation (UUID v7)

Name	Type	Whether required	Description
x-toss-user-key	string	N	userKey value obtained through Toss Login