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 7 days 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:
- Configure your environment in the Unity Editor
- Create your Remote Catalog
- Initialize services to handle the start up sequence
- Fetch your Remote Catalog
- Configure a webhook or Cloud Code module for purchase fulfillment (optional)
- Configure your Payment Provider
- Configure your routing rules
- Fulfill purchases
- 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.
- Install IAP v5.4.
- For more information, refer to upgrade to IAP version 5.
- If you use Unity 2022.3 to build for Android, refer to Troubleshooting In-App Purchasing 5.4.0 Android builds on Unity 2022.3 for the required build configuration.
- Install and configure Unity Authentication to manage player identities.
- Install the Deployment package to deploy your product catalogs.
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:- In the Unity Editor, select Edit > Project Settings > Services > Environments.
- 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:- Create your Unity IAP product catalog.
- Upload your catalog to the Remote Catalog service.
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 theStoreControllerConfigure 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 (fulfill) 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.
Method | When to use | Solution outcome |
|---|---|---|
| Through the SDK | Your 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 SDK | Your 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 |
| Through the backend API | Your 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 module | Your 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 theOnPurchasePendingConfirmPurchaseImportant
For Payment Providers, you must specify the store name () when you call the or . specifies Direct-to-Consumer provider integration and does not return the display name of the provider.
PaymentProvider.NameUnityIAPServicesStoreControllerPaymentProvider.NameFulfill 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 (SetComplianceCheckFeature support
IAP doesn't currently support the following features:- Subscriptions through D2C payment providers.
- Unity Analytics support for D2C transactions.
- Managed entitlements for native Apple and Google purchases.
- Alternative billing choice for users.
- WebGL builds. D2C payment providers are primarily targeted at mobile platforms (iOS and Android).