In-App Purchases

Generate revenue with in-app purchases (IAP) which allow users to buy digital goods and virtual currency within your application. There are two IAP methods that you can set up:

• TikTok Beans: Virtual currency used for one-time, non-subscription purchases
• Subscriptions: Recurring charges for packages within your mini drama

Prerequisites

Before setting up in-app ads for your mini game or mini drama, you must have completed the following:

• Enabled in-app purchases for your mini game or mini drama

Virtual currency and pricing tiers

TikTok Beans

Beans are in-app virtual credits that can be used to unlock or access content within your mini app. Beans can be converted into any virtual currency that's exclusively used within your mini app.

If you need to display the number of Beans consumed in the game, you can use the following image as the icon for Beans.

Pricing tiers

TikTok Beans exist in fixed pricing tiers. Refer to this pricing tiers chart for more information on the packages available.

IAP setup for TikTok Beans

This flow allows users to make purchases within your mini game using Beans, the virtual currency of TikTok. This requires users to complete the login process first.

Step 1: Create an order

First, create an order by calling TikTok's Payment API:

POST https://open.tiktokapis.com/v2/minis/trade_order/create/

POST https://open.tiktokapis.com/v2/minis/trade_order/create/
curl --location 'https://open.tiktokapis.com/v2/minis/trade_order/create' \
--header 'Authorization: Bearer {access token}' \
--header 'Content-Type: application/json' \
--data '{
    "token_type": "BEANS", // Required
    "token_amount": 100, // Required
    "order_info": {
        "order_id": "external_order_id_003", // Required
        "product_name": "Wake up dad! wedding time", // Required; displayed on the user's order list page

        "order_url": "/profile/order_history/external_product_id",
        "quantity": 1,
        "quantity_unit": "relive", // Pass the unit of the item being sold as appropriate; e.g., "episode" is the unit for a series
        "iamge_url": "https//your.domain/pics/wake_up_dad.jpg"
    }
}'

The server creates a payment order through the open API and obtains the order's trade_order_id:

response:
{
    "data": {
        "trade_order_id": "xxxx"
    },
    "error": {
        "code": "ok",
        "message": "",
        "log_id": "20241125114034036EE8AEADBAF91D5E93"
    }
}

Step 2: Call the TikTok Minis SDK payment endpoint

Call the TikTok Minis SDK payment endpoint to initiate the payment process:

TTMinis.game.pay({
  trade_order_id: "{your_trade_order_id}",
  success: () => {
  // Do something if succeeded
  },
  fail: (error) => {
  // Do something if failed
  },
  complete: () => {
  // Do something if completed
  }
})

Step 3: Register a callback URL for payment completion

Register a webhook URL in the Developer Portal so that after the order is successfully paid, the result will be sent through a webhook postback.

If you need to verify the source of webhooks, refer to the webhook verification documentation.

{
    "client_key": "your_client_key",
    "event": "minis.trade_order.redeem.success",
    "create_time": 1615338610,
    "user_openid": "",
    "content": "{\"trade_order_id\":\"TOID667700996\",\"order_id\":\"order_id_as_in_your_system\",\"is_sandbox\":true}"
}

{
  "client_key": "your_client_key",
  "event": "minis.trade_order.redeem.refund_traceback",
  "create_time": 1744946518,
  "user_openid": "",
  "content": "{\"trade_order_id\":\"TOID2157c5ba03\",\"order_id\":\"order_id_as_in_your_system\",\"is_sandbox\":true,\"refund_amount\":80}"
}

For more information, refer to the TikTok Minis SDK IAP APIs or Payment APIs from TikTok Minis.

IAP setup for subscriptions

Configuring subscriptions for your mini drama requires you to use methods from both TikTok Minis SDK and TikTok Minis Server API. You can complete two methods:

• Create a new subscription
• Renew an existing subscription

Create a new subscription

To create a new subscription, you must first query whether or not the user has a subscription. Subsequently, your platform will display a subscription tier list and then create a subscription order according to the package the user chooses. Optionally, you can provide coupons to first-time subscribers.

Step 1: Query user's subscription status

Call https://open.tiktokapis.com/v2/minis/subscription/get_active_list/ to retrieve the user's subscription status.

• If the return value is empty, then the user has no valid subscription. Proceed to step two.
• If the return value is not empty, this indicates that the user has a subscription.

If a user has a subscription, their status may be active, cancel, or onhold. Two key fields that determine the subscription's state:

• is_subscription_rights_valid: Whether the user currently has active subscription benefits.
• is_renewal_normal: Whether auto-renewal is active and functioning normally.

When a subscription payment fails, TikTok sends a minis.subscription.onhold webhook. This onhold status lasts 1-2 months.

During this time, the following rules apply:

• User action required: Users cannot create a new subscription. Use a toast notification to remind them to resolve their current subscription (either renew or cancel) in the Apple or Google Store.
• Active benefits: An onhold status does not mean the user's benefits have expired, because auto-renewals are attempted one day before expiration. To verify if benefits are still active, check the expiration date or the is_subscription_rights_valid field.
• Resolution webhooks: Once the status is resolved, TikTok will send minis.subscription.renew (if successfully renewed) or minis.subscription.expire (if the subscription becomes entirely inactive).

Step 2: Show surface coupon

To offer introductory discounts to first-time subscribers, use showSurfaceCoupon to display the promotion to the user before they view your products.

Step 3: Show tier list

Display your product page with the available subscription tier list on your frontend. Your promotion from the surface coupon will be displayed as a banner at the top of the screen.

Let the user choose their target tier then subsequently create the subscription order.

Step 4: Create subscription order

To create a subscription for a user:

1. Your server calls the subscription creation API to generate a trade_order_id.
2. Your client calls TTMinis.createSubscription with the trade_order_id to open the payment screen.
3. After the user completes payment, TikTok sends a minis.subscription.create webhook to your server to confirm activation.

Reactivate subscription

Step 1: Query user's subscription status

Call https://open.tiktokapis.com/v2/minis/subscription/get_active_list/ to retrieve the user's subscription status.

If a user has a subscription, their status may be active, cancel, or onhold. Two key fields that determine the subscription's state:

• is_subscription_rights_valid: Whether the user currently has active subscription benefits.
• is_renewal_normal: Whether auto-renewal is active and functioning normally. Subscriptions can only be reactivated if this value is false.

When a subscription payment fails, TikTok sends a minis.subscription.onhold webhook. This onhold status lasts 1-2 months.

During this time, the following rules apply:

• User action required: Users cannot create a new subscription. Use a toast notification to remind them to resolve their current subscription (either renew or cancel) in the Apple or Google Store.
• Active benefits: An onhold status does not mean the user's benefits have expired, because auto-renewals are attempted one day before expiration. To verify if benefits are still active, check the expiration date or the is_subscription_rights_valid field.
• Resolution webhooks: Once the status is resolved, TikTok will send minis.subscription.renew (if successfully renewed) or minis.subscription.expire (if the subscription becomes entirely inactive).

Step 2: Allow user to reactivate subscription

A user can reactivate their subscription only if they don't already have an active subscription.

Step 3: Reactivate subscription

To create a subscription for a user:

1. Your server calls the subscription reactivation API to generate a trade_order_id.
2. Your client calls TTMinis.reactivateSubscription with the trade_order_id to open the payment screen.
3. After the user completes payment, TikTok sends a minis.subscription.reactivate webhook to your server to confirm activation.

Test subscriptions with sandbox

Before going live, test your subscription integration using the provided sandbox tier IDs. The following concepts apply when testing integrations with sandbox tier IDs:

• No real payments: Sandbox subscriptions will not trigger the payment panel. We assure you that you will receive notifications and webhooks just like in the production environment
• Automatic renewals: Subscriptions renew every 5 minutes (12 times total). After 12 renewals or cancellation, an expiry event will be triggered.
• Same webhooks: You'll receive the same notifications as production.
• Blocked reactivations: You may not reactivate within 2 minutes of renewal. In production, this period is typically one day.
• In the sandbox, these actions can be executed: create, change, cancel, reactivate, onhold, onhold recover.

Sandbox tier IDs

When calling subscription APIs, use the following tier IDs in your request body parameters. This will automatically trigger sandbox mode: