Troubleshooting

This guide addresses common questions and issues when integrating Stash Pay's mobile SDK (iOS/Android Unity integration).

Success Callback Not Firing

Problem

The successCallback in your Unity integration doesn't fire after a successful purchase, even though the payment completed.

Common Causes

Verifying Purchases When Callbacks Fail

Always implement server-side purchase verification as your primary method. Client-side callbacks should only be used for immediate UI feedback.

void OnPaymentSuccess()
{
    // Show immediate feedback to user
    ShowSuccessMessage("Payment processing...");
    
    // Always verify on server - don't grant items here
    StartCoroutine(VerifyPurchaseOnServer());
}

IEnumerator VerifyPurchaseOnServer()
{
    // Query your server to verify the purchase
    // Your server should check webhooks or query Stash API
    var request = UnityWebRequest.Get($"https://your-server.com/verify-purchase/{orderId}");
    yield return request.SendWebRequest();
    
    if (request.result == UnityWebRequest.Result.Success)
    {
        // Server confirmed purchase - now grant items
        GrantItemsToPlayer();
    }
    else
    {
        // Purchase not yet confirmed - show pending message
        ShowPendingMessage("Verifying purchase...");
    }
}

How Do I Know If a Purchase Worked?

Verifying Successful Purchases

Use multiple verification methods to ensure purchase completion:

GET https://api.stash.gg/sdk/server/payment/<payment_id>

Is This a Real Charge?

App Backgrounding During Checkout

What Happens When App Backgrounds

If a user backgrounds your app during checkout (switches to another app, receives a phone call, etc.), the checkout flow continues in the browser or dialog. When the user returns:

• Browser Mode: User returns via deep link after completing purchase
• Dialog Mode: Dialog may be dismissed or may persist depending on system behavior

Handling Deep Link Returns

When using browser mode, implement deep link handling to detect when users return after purchase:

void OnEnable()
{
    // Unity's deep link event
    Application.deepLinkActivated += OnDeepLinkActivated;
}

void OnDeepLinkActivated(string url)
{
    // Check if this is a purchase return
    if (url.Contains("purchase") || url.Contains("checkout"))
    {
        // Query server to verify purchase status
        VerifyPurchaseOnServer();
    }
}

void OnDisable()
{
    Application.deepLinkActivated -= OnDeepLinkActivated;
}

Best Practices

1. Always verify on return - When the app resumes, check for pending purchases
2. Use webhooks as source of truth - Don't rely on deep link parameters alone
3. Handle timeout scenarios - Purchases may complete after the user returns to the app

Low-RAM Device Considerations

Performance Best Practices

On low-RAM devices, consider the following:

void OnApplicationPause(bool pauseStatus)
{
    if (pauseStatus)
    {
        // App is being backgrounded - save state
        SaveCheckoutState();
    }
    else
    {
        // App resumed - check for completed purchases
        CheckForPendingPurchases();
    }
}

Common Integration Issues

Deep Link Not Working

Symptoms: App doesn't return after browser checkout, or callbacks don't fire.

Solutions:

1. Verify deep link schema is registered in Unity project settings
2. Confirm deep link is configured in Stash Studio
3. Test deep link manually: your-app-scheme://test
4. Check platform-specific deep link requirements (iOS Info.plist, Android manifest)

Webhook Not Receiving Events

Symptoms: Purchases complete but webhooks never arrive.

Solutions:

1. Verify webhook URL is accessible from the internet
2. Check webhook signature verification is working
3. Review webhook logs in Stash Studio
4. Ensure webhook endpoint returns 200 status code
5. Check firewall/network configuration

Purchase Verification Fails

Symptoms: Purchase completes but server verification fails.

Solutions:

1. Verify API keys are correct for the environment (test vs production)
2. Check payment ID is being passed correctly
3. Ensure server is querying the correct Stash API endpoint
4. Verify authentication headers are included in API requests

Getting Help

If you're still experiencing issues:

1. Check logs - Review Unity console logs and server logs for error messages
2. Verify configuration - Double-check API keys, deep links, and webhook URLs
3. Test in isolation - Test each component (callbacks, webhooks, deep links) separately
4. Contact support - Reach out to Stash support with:
   • Error messages from logs
   • Steps to reproduce the issue
   • Environment details (test vs production)
   • Payment IDs or order IDs for failed transactions