Add a routing rule
Define provider routing rules to control which payment providers you serve your players and in what order.
Read time 3 minutesLast updated 16 days ago
To activate a payment provider, you need to define the provider routing rules. Routing rules let you control which payment providers you offer to each player. You can target players by platform or country, and define the order in which providers appear. You can also use rollout percentages to gradually introduce a new provider to a subset of players before a full rollout.
Note
Routing rules are evaluated at runtime, so you can change provider routing without the requirement of a client update or new app release.
Important
When you save a routing rule, the rule becomes active immediately, and activates your configured payment providers. Don't add a rule until you're ready.
- Open In App Purchases > Payment Providers.
- Under Provider routing, select Add routing rule.
- Enter a name for your rule.
- Select a Priority number for the rule that defines the order in which rules apply to players. Refer to Rule priority for more information.
- Enter the following configuration options:
Configuration option
Description
Platform attributes Select each platform that you want this rule to apply to. Country attributes Select each country that you want this rule to apply to. Apply to webshops Select this option if you want the rule to apply to your webshops. Provider order If you have multiple connected payment providers, drag the payment provider you want to be the primary provider to the top of the list. Select Disabled on a payment provider to ensure that you don't offer that provider to any players that match this rule. Rollout Define the percentage of players that match this rule that you want the rule to apply to. For more information, refer to Rollout functionality. - Select Save to make the rule active.
Rule priority
Assign each rule a priority number: the lower the number, the higher the priority. When multiple rules match a player, all of them apply: the player is eligible for every provider across all matching rules. Priority determines which provider Unity IAP selects by default when you don't explicitly specify one in code — the highest-priority matching rule wins.Use distinct priorities
We recommend you assign each rule a distinct priority. With full control over priority, you don't need to rely on tie-breaking behavior, and distinct priorities keep routing predictable.Rollout functionality
Use the rollout setting to control what percentage of players that match a rule's conditions the rule actually applies to. Assignment is deterministic per player, which means that the same player is consistently included or excluded across sessions. Players that fall outside the rollout percentage are treated as if the rule doesn't match them. IAP then evaluates and applies any remaining rules by priority, or applies the default fallback behavior if none apply.Note
If you change the rollout percentage after launch, the change takes effect per player the next time their targeting is recalculated. This typically occurs on app restart, or at a point you have specifically instrumented in your game.
Fallbacks if no rule matches a player
Payment providers are a stand-alone store. If no rule matches the player, or a rule matches but none of its configured payment providers are available, the player can't complete the purchase through external payments. Whether the player can instead complete the purchase through the native store (Apple App Store or Google Play Store) is up to you, and is subject to the terms of the external purchase program in the player's region. For a webshop purchase, if there are no rules that match the player, Unity IAP defaults to a graceful failure and the purchase is blocked. For information on how to configure a specific fallback provider, refer to Set a fallback payment provider.Override routing in code
By default, routing decisions are made server-side based on the rules you configure in the Dashboard. No client-side changes are required for routing to work. If you need more control, Unity IAP provides two optional APIs:- : Returns the list of payment providers the current player is eligible to use, in priority order (highest first). An empty list means no provider is eligible and external payments are unavailable.
IPaymentProvidersExtendedService.GetEligiblePaymentProviders() - : Overrides the server-side routing decision and forces a specific payment provider for subsequent purchases. The override still respects which providers are available to the player.
IPaymentProvidersExtendedPurchaseService.SetPaymentProviderOverride(string)