Documentation

In-App Purchasing

Client API

SDK API

In-App Purchasing

Integrate Direct to Consumer (D2C) payment providers workflow

Follow this workflow to integrate a D2C payment provider with In-App Purchases (IAP) so that you can control how and where you provide and sell IAP products to your users.
Read time 6 minutesLast updated 5 hours ago
This guide provides an overview of the end-to-end workflow for integrating D2C payment providers with Unity In-App Purchases (IAP). The workflow covers the essential steps required to facilitate off-platform transactions, from how to configure your store via the Unity Dashboard to how to implement the necessary client-side and server-side logic. By following this sequence, you can ensure a consistent purchasing experience for your players while you also maintain secure communication between the Unity Gaming Services (UGS) environment and your chosen payment gateway. This integration uses D2C payment providers that act as the merchant of record (MoR). This means that the payment provider assumes the legal responsibility for processing payments, which includes support with tax compliance, fraud prevention, disputes, and customer support. By leveraging a payment provider as an MoR, you can significantly reduce your operational overhead and compliance burden for off-platform transactions. To integrate Unity In-App Purchases (IAP) with D2C payment providers, complete the following steps:
  1. Configure your environment in the Unity Editor
  2. Create your Remote Catalog
  3. Initialize services to handle the start up sequence
  4. Fetch your Remote Catalog
  5. Configure a webhook or Cloud Code module for purchase fulfillment (optional)
  6. Configure your Payment Provider
  7. Configure your routing rules
  8. Fulfill purchases
  9. Test your integration
Important
Apple and Google now support external web links and third-party payments in select regions. Because eligibility, fees, and technical requirements vary by platform and geographical market, it's your responsibility to adhere to the requirements of each platform and region.

Prerequisites

To integrate a D2C payment provider with IAP, you need to meet the following requirements:
  • Unity Editor 2022.3 or later installed (Unity 6.0 or later recommended), with build support modules for your target platform, for example:
    • Android Build Support
    • iOS Build Support
  • A Cloud project connected to your Unity project.
You need the following packages installed:
Important
The recommended best practice is to not use anonymous sign-in as your authentication method, because anonymous sign-in doesn't persist purchases after the session token is lost. If frictionless platform-specific providers aren't viable for your app, refer to anonymous authentication and linking.

Configure your environment in the Unity Editor

The environment you set in the Unity Editor defines where Unity IAP runs after you initialize Unity Gaming Services in code. To set your environment follow these steps:
  1. In the Unity Editor, select Edit > Project Settings > Services > Environments.
  2. Select the target environment you want IAP to run in: Development, Staging, or Production.

Create your Remote Catalog

To use Payment Providers, you need to upload your product catalog to the Unity IAP Remote Catalog service. The Remote Catalog service allows you to provide your users with the latest products without the need to install a new version. To create a Remote Catalog, do the following:
  1. Create your Unity IAP product catalog.
  2. Upload your catalog to the Remote Catalog service.
For more information, refer to Create your Remote Catalog.

Initialize services to handle the start up sequence

Create a script to initialize Unity Gaming Services (UGS) to handle the startup sequence for IAP. This startup script initializes UGS, handles Authentication events, signs the player in, and then triggers the IAP initialization. For more information and a code example, refer to Initialize services to handle the start up sequence.

Fetch your Remote Catalog

You need to create a script that connects to the 
StoreController
to explicitly fetch the Remote Catalog you deployed. Attach this script to the same GameObject as the initialization script. For more information and a code example, refer to Fetch your Remote Catalog.

Configure a webhook or Cloud Code module for purchase fulfillment (optional)

Unity IAP manages entitlements for off-platform payment providers, similar to how Apple and Google handle entitlements for their stores. If you need to sync purchases with your backend or use server-authoritative entitlements, you can optionally configure a webhook or Cloud Code module to receive purchase events. For more information, refer to Configure a webhook or Cloud Code module for purchase fulfillment.

Configure your payment provider

You can choose which supported payment provider to use for IAP based on your business requirements, such as pricing model or content type. You are responsible for the management and agreement of pricing with external payment providers. For information on content types and restrictions, refer to the documentation for specific payment providers: For more information, refer to Configure your payment provider.

Configure your routing rules

To activate a payment provider, you need to define the provider routing rules. Routing allows you to target specific player attributes to determine which payment providers you present to each player and the order in which they appear. For more information, refer to Add routing rules.

Fulfill purchases

When a player completes a purchase, Unity IAP creates an order and tracks its fulfillment status. You must confirm (fulfil) purchases after granting the player their purchase.
Important
You must always mark orders as fulfilled with Unity IAP, even if you also manage entitlements in your own backend system. For consumable products, Unity IAP prevents players from purchasing the same item again until the previous order is fulfilled.
You can mark orders as fulfilled in the following ways:

Method

When to use

Solution outcome

Through the SDKYour game grants entitlements client-side and server authority is not a priority.Your game client confirms the purchase client-side and uses the IAP service as the source of truth.
Server validation alongside the SDKYour game requires server-side verification but you want to avoid managing webhooks.Your backend uses the Order ID from the client to pull purchase status directly from the Unity IAP 
GET API
before fulfilling the order.
Through the backend APIYour game uses server-authoritative entitlements.Your backend receives webhook events, grants entitlements in your system, and calls the API to mark orders as fulfilled.
Through a Cloud Code moduleYour game uses server-side logic for entitlements and fulfillment without managing your own backend infrastructure.Your game uses a Cloud Code module and endpoint to handle purchase events server-side.

Fulfill purchases through the SDK

Confirm purchases in your game client using the same method as for Apple and Google purchases. Your client code must handle the 
OnPurchasePending
callback and call 
ConfirmPurchase
for each order after you grant the player their entitlements. This acknowledges the order and closes it out. For details, refer to the Unity IAP purchases documentation.
Important
For Payment Providers, you must specify the store name (
PaymentProvider.Name
) when you call the 
UnityIAPServices
or 
StoreController
. 
PaymentProvider.Name
specifies third-party provider integration and does not return the display name of the provider.

Fulfill purchases with both the SDK and server-side validation

If you use the IAP SDK to fulfill purchases, you can still make calls to the backend API for purchase validation to achieve a server-authoritative workflow. For more information, refer to Use server-side validation alongside the SDK.

Fulfill purchases through the backend API

If your game uses server-authoritative entitlements, implement a backend system to manage entitlements and fulfill purchases. For more information, refer to Fulfill purchases through the backend API.

Use a Cloud Code module to fulfill purchases

If your game uses server-authoritative entitlements, you can use a Cloud Code module to validate the purchase event, fulfill purchases, and call the orders API. For more information, refer to Use a Cloud Code module to fulfill purchases.

Test your integration

Test your integration to ensure that it works and that you can successfully fulfill user purchases. For more information, refer to Test your integration.

Platform compliance for external purchases

Unity doesn't perform Apple or Google platform compliance on your behalf. You're responsible for determining your eligibility and meeting each platform's requirements before you ship external purchases. Unity provides a compliance callback (
SetComplianceCheck
) and webhook transaction tokens to help you implement your own flow. For more information, refer to Comply with Apple and Google external purchase requirements.

Feature support

IAP doesn't currently support the following features:
  • Subscriptions through D2C payment providers.
  • Unity Analytics support for third-party transactions.
  • Managed entitlements for native Apple and Google purchases.
  • Alternative billing choice for users.