Documentation

In-App Purchasing

IAP Client API

IAP SDK API

Webshop Admin API

Webshop Client API

In-App Purchasing

Initiate a purchase

Start a purchase from your application and let players choose how to pay with the Purchase Options UI.
Read time 6 minutesLast updated 13 days ago
When a player chooses to buy a product, you start the purchase from your application with the Unity In-App Purchasing (IAP) SDK. It's recommended to use the Purchase Options UI, an in-game component that presents the player with the payment options they're eligible for, such as the native store, a payment provider, or your webshop.
The Purchase Options UI is the default integration path for Direct-to-Consumer (D2C) payments. To show it, you call a single method with the listing you want to sell, and the UI presents the payment options your routing rules return for that player. You don't build the interface yourself. If a project hasn't configured a payment provider, its purchase behavior doesn't change.
If you want to present your own purchase interface instead, you can build a custom UI and consume the routing output directly.

Prerequisites

Before you initiate a purchase through the Purchase Options UI, complete the following steps:

Start a purchase from your application

To start a purchase and show the Purchase Options UI, call 
ShowPurchaseOption
on 
IPaymentOptionProvider
with the 
catalogListingId
of the listing you want to sell. The 
catalogListingId
identifies the specific listing the player buys. If you haven't defined more than one listing for a product, the 
catalogListingId
matches the product's SKU. For more information, refer to Products and catalog listings.
Obtain the 
IPaymentOptionProvider
from 
IPaymentProvidersExtendedService
by calling 
GetPaymentOptionProviderUGUI()
, or 
GetPaymentOptionProviderUITK()
if your project uses UI Toolkit.
public async void BuyProduct(string catalogListingId){    // Show the Purchase Options UI with the payment options the player is eligible for.    await m_PaymentOptionProvider.ShowPurchaseOption(catalogListingId);}
When the player completes the purchase, the SDK invokes the 
OnPurchasePending
callback so you can fulfill the order. For information on how to fulfill and confirm purchases, refer to Fulfill purchases through the SDK.
When the purchase is in progress, keep the buy button's state in sync with the purchase and entitlement state that Unity IAP reports. For recommendations on managing buy button states, refer to Reflect purchase state in your UI.

Check eligibility before you show the UI

Unity doesn't evaluate your compliance or eligibility rules before it shows the Purchase Options UI. If you show the UI to a player who isn't eligible for D2C payments and your compliance check later returns 
false
, the purchase fails.
To avoid this, call 
IsUserEligibleForPurchase
on 
IPaymentProvidersExtendedService
first. If the player isn't eligible, call 
PurchaseProduct
to process the purchase through the native store instead of showing the UI:
var m_PaymentProviderStoreController = new StoreController(PaymentProvider.Name);var m_PaymentProviderStoreExtendedService = m_PaymentProviderStoreController.PaymentProviderStoreExtendedService;// Obtain the Payment Option Provider. Use GetPaymentOptionProviderUITK if your project uses UI Toolkit.var m_PaymentOptionProvider = m_PaymentProviderStoreExtendedService?.GetPaymentOptionProviderUGUI();public async void BuyProduct(string catalogListingId){    if (await m_PaymentProviderStoreExtendedService.IsUserEligibleForPurchase())    {        // Show the Purchase Options UI with the eligible payment options.        m_PaymentOptionProvider.ShowPurchaseOption(catalogListingId);    }    else    {        // The player isn't eligible for D2C payment options. Process the native purchase directly.        m_PaymentProviderStoreController.PurchaseProduct(catalogListingId);    }}

What the Purchase Options UI presents

These default options are designed to be compliant with guidelines in the US, Japan, and Brazil for both iOS and Android platforms. Please note that it is still your responsibility to ensure that you comply with regional and platform guidelines.
The Purchase Options UI on Android, titled "Choose how to check out", showing a webshop option, a Stripe option, and a Google Play option, each with a row of accepted payment method logos.
The Purchase Options UI presents between two and three payment options at a time, composed from the following sources:
  • Native (the Apple App Store or Google Play Store), which is always present.
  • A payment provider, surfaced through your routing rules. The UI displays the highest-priority eligible provider; any remaining providers act as fallbacks and aren't shown.
  • A webshop entry point, surfaced when your project has a webshop configured and a routing rule opts into in-game webshop surfacing.
The UI separates payment options, which complete the current purchase, from the webshop entry point, which prompts the player to browse more products. It supports light and dark modes and both portrait and landscape orientations.

Incentives

If you configure an incentive for a payment provider or webshop option, such as a bonus value, sale price, or time-limited offer, the Purchase Options UI displays it. Configure incentives through the SKU fields in your catalog. Where the same SKU appears both in the Purchase Options UI and in your webshop, the UI uses a consistent visual treatment so players recognize it as the same incentive.

Disable the UI for a build

Even when you call 
ShowPurchaseOption
, you can suppress the Purchase Options UI in specific contexts. When the UI is suppressed, the purchase falls back to the native store. To turn the UI off for a specific build, for example because you ship your own purchase interface, set the SDK configuration option to disable it. When you disable the UI at build time, it never executes for that build, regardless of your Dashboard settings.

Build your own purchase UI

The Purchase Options UI is optional. To present your own interface, consume the routing output directly through the SDK and skip the default UI:
  • Call 
    IPaymentProvidersExtendedService.GetEligiblePaymentProviders()
    to get the ordered list of providers the player is eligible for.
  • Call 
    IPaymentProvidersExtendedPurchaseService.SetPaymentProviderOverride(string)
    to force a specific provider for the purchase.
For more information, refer to Override routing in code.
Note
It's your responsibility to make sure your presentation conforms to the regional and platform guidelines that apply to your players.

Regional availability

The Purchase Options UI is designed for regions where platform programs permit native and D2C payment options to appear side by side, such as the US and Japan. In regions that require external-only presentation, such as the EU and Korea, disable the UI per country and handle the presentation layer yourself.
Note
At general availability, the Purchase Options UI doesn't support subscription products through D2C payment providers, and you can't customize the styling of the native button.

Next steps

This page is part of a workflow to set up Direct-to-Consumer (D2C) payment providers with IAP. To continue this workflow, choose one of the following options:
Integrate D2C payment providers
Return to the Integrate D2C payment providers with IAP workflow page.
Fulfill purchases through the SDK
Proceed to the next step in the workflow to fulfill the purchases your players make.