Skip to main content

Unity SDK reference

The Aghanim Unity SDK that allows you to use the Checkout within both your Android and iOS apps.

Android. Default browser
Android. Default browser

Android. Default browser

Integration

To integrate the SDK, see its prerequisites and the detailed instruction on Integrate → Unity.

Method reference

The SDK provides direct access to the Aghanim API through the Aghanim entity.

Get Order

To get Order details, use the GetOrder method.

Aghanim.GetOrder(
    orderId: "order_123",
    onSuccess: (order) => {
        Debug.Log($"Order ID: {order.id}");
        Debug.Log($"Player ID: {order.player_id}");
        Debug.Log($"Total price: {order.price_minor_unit} {order.currency}");
    },
    onError: (error) => {
        Debug.LogError($"Failed to get order: {error}");
    }
);
ParameterTypeRequiredDescription
orderIdstringYesUnique ID for the Order.
onSuccessAction<OrderRead>Yes if no errorCallback that is invoked on successful result.
onErrorAction<string>Yes if no successCallback that is invoked on failed result.

Get unconsumed Orders

To know what Orders have been paid for but not granted yet, use the GetUnconsumedOrders method.

Aghanim.GetUnconsumedOrders(
    onSuccess: (response) =>
    {
        // Player has paid but not granted items from orders
        var unconsumedOrderIds = response.Orders;
        // TODO: Save order IDs for further consuming and granting
    },
    onError: (debugMessage) =>
    {
        // Log debug information for troubleshooting
        Debug.LogError($"Failed to get unconsumed orders: {debugMessage}");
        // TODO: Handle error
    }
);
ParameterTypeRequiredDescription
onSuccessAction<UnconsumedOrdersResponse>Yes if no errorCallback that is invoked on successful result. Use response.Orders to access the array of order IDs.
onErrorAction<string>Yes if no successCallback that is invoked on failed result.

When to use

GetUnconsumedOrders and ConsumeOrder are designed for games without a dedicated server (serverless). They allow you to handle item granting entirely on the client side.

If your game has a server, use the item.add webhook instead — it lets your server control item granting directly. See Handle post-payment events on game server-side in the integration guide.

When to call GetUnconsumedOrders depends on the launch mode you use:

Default browser, In-app browser, Custom per platform with Native UI (Android)

For these modes, subscribe to the standard Unity callbacks OnApplicationFocus and OnApplicationPause — they fire when the player returns to the app after completing the payment:

private void OnApplicationFocus(bool hasFocus)
{
    if (hasFocus)
    {
        CheckUnconsumedOrders();
    }
}

private void OnApplicationPause(bool isPaused)
{
    if (!isPaused)
    {
        CheckUnconsumedOrders();
    }
}

private void CheckUnconsumedOrders()
{
    Aghanim.GetUnconsumedOrders(
        onSuccess: (response) =>
        {
            foreach (var orderId in response.Orders)
            {
                ConsumeAndGrantOrder(orderId);
            }
        },
        onError: (debugMessage) =>
        {
            Debug.LogError($"Failed to get unconsumed orders: {debugMessage}");
        }
    );
}

In-app browser (iOS)

On iOS, in addition to OnApplicationFocus / OnApplicationPause, the onViewClosed callback fires at the exact moment the player closes the in-app browser:

var launchMode = new LaunchMode(
    android: AndroidLaunchMode.InAppBrowser(),
    ios: IOSLaunchMode.InAppBrowser(
        onViewClosed: (e) =>
        {
            // Earliest point to check order status on iOS
            CheckUnconsumedOrders();
        }
    )
);

Consume paid Order

To let the SDK acknowledge that you have granted the items the player has purchased via an Order, use the ConsumeOrder method.

Aghanim.ConsumeOrder(
    orderId: orderId,
    onSuccess: () =>
    {
        // Paid order is marked as consumed
        Debug.Log($"Order consumed: {orderId}");
        // TODO: Grant items in order to player
    },
    onError: (debugMessage) =>
    {
        // Log debug information for troubleshooting
        Debug.LogError($"Failed to consume order: {debugMessage}");
        // TODO: Handle error
    }
);
ParameterTypeRequiredDescription
orderIdstringYesUnique ID for the Order.
onSuccessActionYes if no errorCallback that is invoked on successful result.
onErrorAction<string>Yes if no successCallback that is invoked on failed result.

When to use

Call ConsumeOrder after fetching unconsumed orders to mark them as granted. This prevents the same order from being granted again on the next GetUnconsumedOrders call.

private void ConsumeAndGrantOrder(string orderId)
{
    Aghanim.ConsumeOrder(
        orderId: orderId,
        onSuccess: () =>
        {
            Debug.Log($"Order consumed: {orderId}");
            // TODO: Grant items to player
        },
        onError: (debugMessage) =>
        {
            Debug.LogError($"Failed to consume order: {debugMessage}");
        }
    );
}

Set player ID

To set the player ID once for the current SDK instance, use the SetPlayerId method. The SDK will use the ID in all following method calls.

Aghanim.SetPlayerId(playerId);
ParameterTypeRequiredDescription
playerIdstringYesUnique ID for the player.

Get items

To retrieve items with localized prices, use the GetItems method. The method returns items created in SKU Management → Items with prices localized based on the player's region.

Aghanim.GetItems(
    skus: new List<string> { "your-item-sku" },
    onSuccess: (items) =>
    {
        foreach (var item in items)
        {
            // Use item.Name, item.Price.Display, item.ImageUrl to populate your store
            Debug.Log($"{item.Name}: {item.Price.Display}");
        }
    },
    onError: (error) =>
    {
        // Log debug information for troubleshooting
        Debug.LogError($"Failed to get items: {error}");
        // TODO: Handle error
    }
);
ParameterTypeRequiredDescription
skusList<string>YesList of item SKUs to retrieve (max 50).
localeLocaleNoLocale for price formatting. Find the full list of supported locales in Checkout → Locales.
onSuccessAction<Item[]>Yes if no errorCallback that is invoked on successful result.
onErrorAction<string>Yes if no successCallback that is invoked on failed result.

Create Checkout item

To create an item representation, use the CheckoutItem method. The item should be already created in SKU Management → Items.

var items = new List<CheckoutItem>
{
    new CheckoutItem("CRS-82500")
};
ParameterTypeRequiredDescription
skustringYesItem SKU from Dashboard.
namestringNoItem name from Dashboard.
descriptionstringNoItem description from Dashboard.
imageUrlstringNoItem image URL from Dashboard.
quantityintNoItem quantity.

Create redirect behavior

To choose the behavior of redirecting the player after they have completed the payment successfully, use the RedirectSettings method.

When the player has completed the payment, the SDK redirects them immediately to the deep link from backToGameUrl.

var redirectSettings = new RedirectSettings(
    mode: RedirectMode.Immediate
);
ParameterTypeRequiredDescription
modeRedirectModeYesRedirect mode. Possible values: Immediate, Delayed, NoRedirect.
delaySecondsintYes if DelayedDelay in seconds. For Delayed mode, default is 5.

Create UI settings

To set the appearance mode for the Checkout, use the UiSettings method.

The SDK automatically detects and applies the appropriate appearance mode based on the system setting.

var uiSettings = new UiSettings(
    mode: UiMode.Auto
);
ParameterTypeRequiredDescription
modeUiModeYesUI mode. Possible values: Auto, Dark, Light.

Create Checkout params

To create Checkout params, a representation of what the player sees on the payment form, use the CheckoutParams method.

var checkoutParams = new CheckoutParams(
    items: items,
    backToGameUrl: "https://<YOUR_DOMAIN>/checkout-complete"
);
ParameterTypeRequiredDescription
itemsList<CheckoutItem>YesList of items.
metadataDictionary<string, string>NoMetadata structured as “key-value” pairs for tracking purposes.
priceTemplateIdstringNoPrice template ID from Get Price Points for localized pricing.
localestringNoLocale for item name and description localization. Find the full list of supported locales in Checkout → Locales.
backToGameUrlstringNoDeep link URL to return player to app.
redirectSettingsRedirectSettingsNoPost-payment redirect behavior.
uiSettingsUiSettingsNoCheckout appearance settings.

Use Checkout launch mode

To launch the payment form, use the LaunchMode entity.

For Android and iOS, the In-app browser launch mode creates the seamless players’ experience via Android Custom Tabs and iOS SFSafariViewController.

LaunchMode.InternalBrowser

Start Checkout

To start the Checkout process, use the StartCheckout method. The method creates an order from the provided checkout params and opens the Checkout UI. On success, you receive the Order ID. On failure, you receive an error with debug information.

For Android and iOS, the In-app browser launch mode creates the seamless players’ experience via Android Custom Tabs and iOS SFSafariViewController.

Aghanim.StartCheckout(
    checkoutParams,
    LaunchMode.InternalBrowser,
    onSuccess: (orderId) =>
    {
        // Order is created and checkout has launched successfully
        // TODO: Save order ID for further granting or tracking
    },
    onError: (error) =>
    {
        // Log debug information for troubleshooting
        Debug.LogError($"Failed to launch Checkout: {error}");
        // TODO: Show user-friendly error message to player
    }
);
ParameterTypeRequiredDescription
checkoutParamsCheckoutParamsYesCheckout configuration.
launchModeLaunchModeYesLaunch mode for Checkout.
onSuccessAction<string>YesCallback invoked with Order ID on successful Checkout launch.
onErrorAction<string>YesCallback invoked with error message on failed Checkout launch.

Present Checkout

To present the Checkout UI for an existing order, use the PresentCheckout method. Use this when you have an order ID from server-to-server order creation or when resuming a previously abandoned checkout.

For Android and iOS, the In-app browser launch mode creates the seamless players' experience via Android Custom Tabs and iOS SFSafariViewController.

Aghanim.PresentCheckout(
    orderId,
    LaunchMode.InternalBrowser,
    onSuccess: (orderId) =>
    {
        // Checkout has launched successfully for the existing order
    },
    onError: (error) =>
    {
        // Log debug information for troubleshooting
        Debug.LogError($"Failed to present Checkout: {error}");
        // TODO: Show user-friendly error message to player
    }
);
ParameterTypeRequiredDescription
orderIdstringYesID of the existing order to open.
launchModeLaunchModeYesLaunch mode for Checkout.
onSuccessAction<string>YesCallback invoked with Order ID on successful Checkout launch.
onErrorAction<string>YesCallback invoked with error message on failed Checkout launch.

FAQ

What platforms does your Unity SDK support?

The Unity SDK is available for both iOS and Android.

Need help?
Contact our integration team at [email protected]

On this page