Skip to main content
This article explains how to migrate your Payment Links integration from the Link Out flow to the Payment Links SDK flow. With the SDK, Appcharge handles more of the checkout handoff for supported mobile platforms, so your app can rely less on custom redirect logic. Use this article alongside the Payment Links SDK for your specific platform. It focuses on what changes from an existing Link Out integration, including return link configuration, checkout session creation, checkout launch, and purchase result handling. The SDK supports Android, iOS, and Unity. If your app uses another engine or platform, contact your account manager to scope a custom bridging plan before migrating.
CapabilityLink Out (API Only)Payment Links SDK
Checkout launchThe app opens parsedUrl in a browser.The app passes purchaseId and parsedUrl to the SDK, and the SDK opens checkout.
Return URL setupredirectUrl is required when creating a checkout session.SDK configuration defines the return link. Don’t pass redirectUrl in the Create Checkout Session API request.
Redirect handlingThe app receives the redirect URL and parses ?status=success, ?status=fail, or ?status=cancel.The app passes incoming URLs to the SDK. The SDK completes transaction handling and triggers success or failure callbacks.
Success and failure callbacksThe app infers the result from the URL status parameter.The SDK returns onPurchaseSuccess and onPurchaseFailed callbacks.
Purchase validationThe application backend validates against the Grant Award Callback before fulfillment.No change. The application backend still validates against the Grant Award Callback before fulfillment.
Browser type awarenessN/AThe SDK handles internal and external flows.
Supported platformsAny platform with manual implementation.iOS, Android, Unity.
MaintenanceManaged by the application team.Managed by Appcharge.
Server-side checkout, validation, and fulfillment on the application side stay the same. Before migrating, make sure the Link Out integration already validates purchases with the Grant Award Callback and can look up purchase state by purchaseId.
SDK callbacks are client-side signals, not proof of payment. Use the purchaseId from the SDK callback as a lookup key, then validate and fulfill the purchase on the application backend using the Grant Award Callback data.

​
Migration process

Follow the SDK documentation for your platform to implement the SDK. Use the steps below to identify the Link Out-specific changes you need to make during that implementation. For the full end-to-end SDK implementation, see the Payment Links SDK flow.

​
Step 1 | Implement and configure the SDK

First, import, configure, and initialize the Payment Links SDK for your platform. During setup, move your return handling from the Link Out redirectUrl API field into the SDK configuration.
If your Link Out flow already uses a universal link for iOS, you can use the same universal link in the SDK configuration. If your Link Out flow uses a deep link for Android, you need to update the deep link scheme in the SDK configuration.
Complete these SDK pages:
  1. Import the SDK.
  2. Set Up Your Project.
  3. Initialize the SDK.
During setup, add the URL scheme acnative-$(PRODUCT_BUNDLE_IDENTIFIER), set the associated domain to your Link Out universal link domain using applinks:{YOUR_DOMAIN}, and pass the universal link you created in the Link Out flow as redirectUrl in the iOS SDK ConfigModel.
Complete these SDK pages:
  1. Setup.
  2. Initialize the SDK.
During setup, add the SDK checkout activity to your manifest and add the deep link scheme <data android:scheme="acnative-{IDENTIFIER}"/>. Replace {IDENTIFIER} with the last sequence of your package name, as described in the Android setup guide.Reuse your existing Link Out app link handling, but set the SDK return scheme to acnative-{IDENTIFIER}. If your existing scheme is different, add the SDK scheme and pass incoming URLs to the SDK.
Complete these SDK pages:
  1. Import the Unity SDK.
  2. Configure the SDK.
  3. Initialize the SDK.
  4. For iOS builds, Integrate with iOS.
  5. For Android builds, Integrate with Android.

​
Step 2 | Remove redirectUrl from checkout session requests

In the non-SDK flow, you passed redirectUrl in the body of the Create Checkout Session API request. The browser used this URL to redirect the player back to your app after payment. With the SDK, the player is redirected using the link configured in your SDK setup file, so you must remove the redirectUrl parameter from your API request. 
{
  "offerName": "Coin Pack 500",
  "offerId": "offer_abc123",
  "items": ["..."],
  "playerCountry": "US",
  "redirectUrl": "https://www.my-game.com/"
}
The Appcharge response stays the same. You still receive purchaseId and parsedUrl. In the next step, you’ll use the parsedUrl to launch the checkout.

​
Step 3 | Open checkout through the SDK

The checkout session response still includes values such as purchaseId and parsedUrl. Return the session response to your client, then pass those values to the SDK instead of opening parsedUrl directly in a browser:
  • Native iOS: Call ACBridgeAPI.openCheckout(purchaseId, parsedUrl). See Launch the Checkout.
  • Native Android: Call BridgeAPI.openCheckout(purchaseId, parsedUrl). See Launch the Checkout.
  • Unity: Call PaymentLinksController.Instance.OpenCheckout(purchaseId, parsedUrl). See Launch the Checkout.
The session response values must be passed exactly as received. Modifying purchaseId, parsedUrl, or other session values may cause checkout to fail.

​
Step 4 | Replace URL status parsing with SDK callbacks

Remove client code that parses the returned URL for ?status=success, ?status=fail, or ?status=cancel. After the player returns to your app through the SDK-configured return link, pass the incoming URL to the SDK and handle the SDK callbacks instead: Use these callbacks to replace the purchase status you parsed from the returned URL:
Native callbackUnity callbackWhen it fires
onPurchaseSuccessOnPurchaseSuccessPurchase completed successfully.
onPurchaseFailedOnPurchaseFailedCheckout was closed, canceled, failed, or a server-to-server error occurred during purchase handling.
When onPurchaseSuccess or OnPurchaseSuccess fires, use the returned OrderResponseModel to identify the purchase. The model includes purchaseId, orderId, customerId, purchased items, price, currency, and related order data. The purchaseId is a lookup key, not proof of payment, so you must validate the purchase with the game server before fulfillment. The application backend should match the purchase against the Grant Award Callback data before granting items to the player.

​
Step 5 | Test the migrated flow

Before you move to production, test the full purchase flow in your sandbox environment:
  1. Create a checkout session from the game server without redirectUrl.
  2. Open checkout through the SDK.
  3. Complete a successful purchase and verify that the success callback fires.
  4. Close or cancel checkout and verify that the failure callback fires.
  5. Confirm the application backend receives the Grant Award Callback.
  6. Confirm the application backend validates and fulfills only valid purchases.
  7. Test player return behavior for internal and external browser modes that your app supports. ​

​
Migration checklist

  1. Import and configure the SDK for your platform.
  2. Configure the deep link/universal link in the SDK config file:
    • iOS: uses a .plist file.
    • Android: uses a manifest file.
    • Unity: uses an Appcharge config file.
  3. Initialize the SDK in your app.
  4. Implement callback methods, including onPurchaseSuccess and onPurchaseFailed.
  5. Remove redirectUrl from the Create Checkout Session API call.
  6. Configure your app to pass incoming URLs to the SDK.
  7. Remove manual URL status parsing from the game client.
  8. Test the full purchase flow in a sandbox environment.

Payment Link Flow (SDK)

Review the full Payment Links SDK integration flow.

iOS SDK Setup

Import and configure the Payment Links SDK for native iOS.

Android SDK Setup

Set up and configure the Payment Links SDK for native Android.

Unity SDK Setup

Import and configure the Payment Links SDK for Unity.

Troubleshooting

Resolve common issues with Payment Links SDK integrations.

Grant Award Callback

Review the callback used to validate and fulfill completed purchases.