> ## Documentation Index
> Fetch the complete documentation index at: https://docs.appcharge.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Migrate to the Payment Links SDK
This article explains how to migrate your Payment Links integration from the [Link Out flow](./link-out-without-sdk) 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.
## Link Out vs Payment Links SDK
| Capability | Link Out (API Only) | Payment Links SDK |
| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| Checkout launch | The app opens `parsedUrl` in a browser. | The app passes `purchaseId` and `parsedUrl` to the SDK, and the SDK opens checkout. |
| Return URL setup | `redirectUrl` 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 handling | The 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 callbacks | The app infers the result from the URL status parameter. | The SDK returns `onPurchaseSuccess` and `onPurchaseFailed` callbacks. |
| Purchase validation | The application backend validates against the [Grant Award Callback](../../api-reference/checkout/awards/grant-award-callback) before fulfillment. | No change. The application backend still validates against the Grant Award Callback before fulfillment. |
| Browser type awareness | N/A | The SDK handles internal and external flows. |
| Supported platforms | Any platform with manual implementation. | iOS, Android, Unity. |
| Maintenance | Managed 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](../../sdks/payment-links/payment-link-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.](../../sdks/payment-links/ios/import-payment-links-sdk)
2. [Set Up Your Project.](../../sdks/payment-links/ios/set-up-your-project)
3. [Initialize the SDK.](../../sdks/payment-links/ios/initialize-the-ios-payment-links-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.](../../sdks/payment-links/android/setup)
2. [Initialize the SDK.](../../sdks/payment-links/android/initialize-the-android-payment-links-sdk)
During setup, add the SDK checkout activity to your manifest and add the deep link scheme ``. 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.](../../sdks/payment-links/unity/import-payment-links-sdk)
2. [Configure the SDK.](../../sdks/payment-links/unity/configure-the-sdk)
3. [Initialize the SDK.](../../sdks/payment-links/unity/initialize-the-payment-links-sdk)
4. For iOS builds, [Integrate with iOS](../../sdks/payment-links/unity/integrate-with-ios).
5. For Android builds, [Integrate with Android](../../sdks/payment-links/unity/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.
```json Before with Link Out theme={"system"}
{
"offerName": "Coin Pack 500",
"offerId": "offer_abc123",
"items": ["..."],
"playerCountry": "US",
"redirectUrl": "https://www.my-game.com/"
}
```
```json After with SDK theme={"system"}
{
"offerName": "Coin Pack 500",
"offerId": "offer_abc123",
"items": ["..."],
"playerCountry": "US"
}
```
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](../../sdks/payment-links/ios/launch-the-checkout).
* **Native Android:** Call `BridgeAPI.openCheckout(purchaseId, parsedUrl)`. See [Launch the Checkout](../../sdks/payment-links/android/launch-the-checkout).
* **Unity:** Call `PaymentLinksController.Instance.OpenCheckout(purchaseId, parsedUrl)`. See [Launch the Checkout](../../sdks/payment-links/unity/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:
* **Native iOS:** Implement the [Callbacks](#native-ios-sdk-setup).
* **Native Android:** Implement the [Callbacks](../../sdks/payment-links/android/implement-the-callbacks).
* **Unity:** Implement the [Callbacks](../../sdks/payment-links/unity/implement-callbacks).
Use these callbacks to replace the purchase status you parsed from the returned URL:
| Native callback | Unity callback | When it fires |
| ------------------- | ------------------- | ----------------------------------------------------------------------------------------------------- |
| `onPurchaseSuccess` | `OnPurchaseSuccess` | Purchase completed successfully. |
| `onPurchaseFailed` | `OnPurchaseFailed` | Checkout 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.
## Related articles
Review the full Payment Links SDK integration flow.
Import and configure the Payment Links SDK for native iOS.
Set up and configure the Payment Links SDK for native Android.
Import and configure the Payment Links SDK for Unity.
Resolve common issues with Payment Links SDK integrations.
Review the callback used to validate and fulfill completed purchases.