Initiate a purchase
Start a purchase from your application and let players choose how to pay with the Purchase Options UI.
Read time 4 minutesLast updated 19 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:
- Create and fetch your Remote Catalog.
- Initialize the IAP services and connect to the store.
- To surface D2C options, connect at least one payment provider and add a routing rule that applies to the player.
Start a purchase from your application
To start a purchase and show the Purchase Options UI, call on with the of the listing you want to sell. The identifies the specific listing the player buys. If you haven't defined more than one listing for a product, the matches the product's SKU. For more information, refer to Products and catalog listings.
ShowPurchaseOptionIPaymentOptionProvidercatalogListingIdcatalogListingIdcatalogListingIdObtain the from by calling , or if your project uses UI Toolkit.
IPaymentOptionProviderIPaymentProvidersExtendedServiceGetPaymentOptionProviderUGUI()GetPaymentOptionProviderUITK()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 callback so you can fulfill the order. For information on how to fulfill and confirm purchases, refer to Fulfill purchases through the SDK.
OnPurchasePendingWhile the purchase is in flight, 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 , the purchase fails.
falseTo avoid this, call on first. If the player isn't eligible, call to process the purchase through the native store instead of showing the UI:
IsUserEligibleForPurchaseIPaymentProvidersExtendedServicePurchaseProductvar 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
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 Unity 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.
Provider memory
After a player completes a successful purchase, the SDK records the provider they used on that device. On subsequent purchases, the UI presents that provider as the default action, while keeping the other eligible providers available. The player can always select a different provider.
Note
Provider memory is per player, per device. It doesn't persist across devices or app reinstalls. A player who reinstalls your app receives the standard first-time UI.
Disable the UI for a build
Even when you call , 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.
ShowPurchaseOptionBuild 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 to get the ordered list of providers the player is eligible for.
IPaymentProvidersExtendedService.GetEligiblePaymentProviders() - Call to force a specific provider for the purchase.
IPaymentProvidersExtendedPurchaseService.SetPaymentProviderOverride(string)
For more information, refer to Override routing in code.
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: