Stash Pay Opt-In

Stash Pay Opt-In allows users to choose Stash Pay as their preferred payment method instead of using their platform's native in-app purchase (IAP) system. When users opt-in, they gain access to exclusive rewards, bonuses, and a unified payment experience across games.

How It Works

When a user initiates a purchase and hasn't set a payment channel preference, they see a channel selection screen where they can choose:

• Stash Pay: Enables Stash Pay for future purchases (opt-in)
• Native IAP: Continues using platform's default payment method

Once a user opts in, they bypass the selection screen and go directly to Stash Pay checkout for future purchases.

Behavior and Effects

When Opt-In is Enabled (Stash Pay Selected)

• Users skip the channel selection screen on future purchases
• All purchases go through Stash Pay checkout flow
• Users can earn Stash Pay rewards and bonuses
• Payment methods available: Cards, Apple Pay, Google Pay, PayPal (if configured)
• Unified payment experience across games using Stash Pay

When Opt-In is Not Enabled (Native IAP Selected)

• Users continue using platform's native payment system
• Platform-specific payment methods (e.g., App Store, Google Play)
• No Stash Pay rewards or bonuses
• Standard platform purchase flow

Changing Preferences

Users can change their preference at any time:

• If they previously selected Native IAP, they'll see the channel selection screen again on their next purchase
• If they previously selected Stash Pay, you can manually change it in the Payment Channels table

Requirements

Prerequisites

• Stash Pay Enabled: Your shop must have Stash Pay enabled and configured
• Payment Processing: Stripe or Adyen must be configured
• Studio Access: You need admin access to Studio for your shop
• Feature Flag: The Payment Channels feature must be enabled (contact Stash support if you don't see it)

Configure Channel Selection

Reward Image Best Practices

• Use high-quality images that clearly show rewards or bonuses
• Keep file sizes reasonable for fast loading (< 500KB recommended)
• Ensure text on images is readable at the recommended size
• Test the image appearance on both light and dark themes
• Show tangible rewards users will receive
• Use crisp, professional images
• Preview on both mobile and desktop views
• Refresh images to keep content current

Customization

The opt-in experience can be customized through the Appearance settings. All customization options are found under Stash Pay → Appearance:

Channel Selection Reward Image

Location: Stash Pay → Appearance → Channel Selection

Configure the reward image displayed on the channel selection screen. This is separate from the checkout banner image.

Recommended size: 333px width × 135px height
Format: PNG, JPG, or WebP

Customization Limitations

What Cannot Be Customized:

• Channel selection screen layout and structure
• Button text and messaging (standardized for consistency)
• Screen flow and navigation
• Font families and typography (uses system fonts)
• Spacing and positioning of elements

What Can Be Customized:

• ✅ Reward image on channel selection screen (333×135px)
• ✅ All color values (background, text, buttons, cards) - configured in Checkout Appearance
• ✅ Banner image in checkout flow - configured in Checkout Appearance
• ✅ Visual branding elements

The channel selection screen layout and messaging are standardized to ensure a consistent, accessible user experience across all games. Visual customization (colors and images) allows you to brand the experience while maintaining usability.

View and Manage User Opt-Ins

You can view and manage which users have opted in to Stash Pay through the Payment Channels page.

Navigation: Stash Studio → Stash Pay → Payment Channels

Payment Channels Table

The table shows:

• User ID: The external user ID from your game
• Channel: Current payment channel preference (Stash Pay or Native IAP)
• Date Updated: When the preference was last updated

Edit User Preference

1. Navigate to Stash Pay → Payment Channels
2. Click on a user in the table
3. Select the desired payment channel (Stash Pay or Native IAP)
4. Click Save

The user's preference will be updated immediately.

Unity SDK Implementation

For the opt-in flow to work, your game must integrate the Stash SDK. This section covers Unity-specific implementation.

Opening an Opt-in Popup

Use OpenPopup() to display payment channel selection opt-in dialogs. Always handle the OnOptinResponse event:

using StashPopup;

void ShowPaymentChannelSelection()
{
    // Subscribe to opt-in response
    StashPayCard.Instance.OnOptinResponse += OnChannelSelected;
    
    StashPayCard.Instance.OpenPopup(
        "https://your-site.com/payment-channel-selection",
        dismissCallback: () => {
            // Unsubscribe when popup closes
            StashPayCard.Instance.OnOptinResponse -= OnChannelSelected;
        }
    );
}

void OnChannelSelected(string channel)
{
    // Receives "native_iap" or "stash_pay"
    string paymentMethod = channel.ToUpper();
    
    // Save user preference
    PlayerPrefs.SetString("PaymentMethod", paymentMethod);
    PlayerPrefs.Save();
    
    Debug.Log($"User selected: {paymentMethod}");
}

Configuring Popup Size

OpenPopup() supports optional custom size configuration. By default, it uses platform-specific default sizing. You can customize the size using PopupSizeConfig:

var customSize = new PopupSizeConfig
{
    portraitWidthMultiplier = 0.9f,      // 90% of base width in portrait
    portraitHeightMultiplier = 1.2f,     // 120% of base height in portrait
    landscapeWidthMultiplier = 1.4f,     // 140% of base width in landscape
    landscapeHeightMultiplier = 0.85f    // 85% of base height in landscape
};

StashPayCard.Instance.OpenPopup(
    url,
    dismissCallback: OnDismiss,
    customSize: customSize
);

Note: The popup automatically adjusts its size when the device rotates between portrait and landscape orientations. Custom multipliers are applied relative to the calculated base size (which depends on device type and screen dimensions).

Unity SDK API Reference

OpenPopup(string url, Action onDismiss = null, Action onSuccess = null, Action onFailure = null, PopupSizeConfig? customSize = null)

Opens Stash opt-in and other remote Stash dialogs in a centered modal popup. Size can be customized using PopupSizeConfig. If not provided, uses platform-specific default sizing.

OnOptinResponse (event Action<string>)

• Fired when user selects a payment channel in opt-in popup. Receives "native_iap" or "stash_pay".

PopupSizeConfig (struct)

• portraitWidthMultiplier (float) - Width multiplier for portrait orientation
• portraitHeightMultiplier (float) - Height multiplier for portrait orientation
• landscapeWidthMultiplier (float) - Width multiplier for landscape orientation
• landscapeHeightMultiplier (float) - Height multiplier for landscape orientation

Note: Each platform (iOS and Android) has its own default sizing. When customSize is not provided, the platform-specific defaults are used.

Troubleshooting

Users Can't Opt-In

Problem: Users click "Enable Stash Pay" but nothing happens

Solutions:

1. Verify SDK method is available (StashSdk.hasSetPaymentChannel())
2. Check browser/console for errors
3. Verify API connectivity
4. Check Payment Channels table to see if preference was saved

Reward Image Not Displaying

Problem: Reward image doesn't appear on channel selection screen

Solutions:

1. Verify image is uploaded in Channel Selection settings
2. Check image URL is valid
3. Clear browser cache
4. Re-upload the image if necessary

Best Practices

User Communication

• Ensure users understand what Stash Pay offers
• Emphasize rewards and bonuses
• Make it clear users can change their preference
• Provide support contact for questions

Monitoring

• Track opt-in rates via Payment Channels table
• Periodically review user preferences
• Test different reward images to optimize conversion
• Collect feedback on the opt-in experience