Initiate a purchase

Start a purchase from your application and let players choose how to pay with the Purchase Options UI.

Read time 4 minutes

Last updated 16 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

ShowPurchaseOption

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.

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

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

The Purchase Options UI titled "How would you like to pay?", that shows a webshop option with a +200 bonus badge, a Pay with Stripe button, a Google Pay button, and a "Remember my preference" checkbox.

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

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.

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 providersReturn to the Integrate D2C payment providers with IAP workflow page.

Fulfill purchases through the SDKProceed to the next step in the workflow to fulfill the purchases your players make.

Documentation

Development

User Acquisition

Monetization

Industry