Skip to main content
This article explains how to link out players from your app to a web checkout for both Android and iOS. To do this using our SDK, refer to the Payment Link Flow.

​
Before you begin

Before you get started, ensure you’ve completed the following steps:
  1. Develop and expose a an API endpoint to receive player transaction updates from Appcharge, following the Grant Award Callback schema.
  2. Enter your API endpoint URL in the Publisher Dashboard under Settings -> Integration.
  3. Configure a redirectURL to return players to your app after a successful payment:

​
Step 1 | Send item details to your game server

When a player selects an offer in your game, such as a coin pack or a character skin, send the item details from the game client to your game server.

​
Step 2 | Call the Create Checkout Session API

Follow the steps below to create the checkout session:
  1. Call the Appcharge Create Checkout Session API from your server. Include the following in the request:
    • Offer name and ID
    • Item list and images
    • Item prices
    • Redirect URL (Universal Link or Deep Link that returns the player to the app)
    • Player country code in ISO-3166 alpha-2 format. If not provided, Appcharge determines the customer’s country from the player’s IP address.
      Setting a country manually will affect the applicable tax jurisdiction and rates. It’s your responsibility to ensure that any country values provided via the API align with your regulatory and business requirements.
  2. Appcharge returns the following:
    ParameterTypeDescription
    checkoutSessionTokenStringA unique token that identifies and validates the checkout session.
    purchaseIdStringA unique ID to track the transaction.
    urlURLThe base URL for the Appcharge checkout page.
  3. Return the session data to the game client.

​
Step 3 | Build and open the checkout URL

Follow the steps below to build and open the checkout URL:
  1. In the game client, build the checkout URL using this format: 
    {$url}/{$checkoutSessionToken}?cot={$Checkout_Public_Key}
    • You can find the Checkout Public Key in the Publisher Dashboard under Settings -> Integration -> Checkout Public Key.
    • The cot parameter is required, and without it, the checkout page will not load correctly.
  2. Your checkout URL should look something like this: 
    https://appcharge-checkout-url.com/eb02bb412ccb47948f7d62667a7774b1?cot=0b2b42ab8a3d491ba76b6b8919d8e0ee
  3. Open this URL in the browser. You may want to notify players that they’ll briefly leave the app to complete their purchase securely in a mobile browser.

​
Step 4 | Receive checkout transaction data if relevant

The player selects a payment method and completes the purchase on the Appcharge checkout page. The Grant Award Callback is triggered, and your game server receives a POST request with the complete transaction data. If the player doesn’t complete the purchase, the checkout session will automatically expire after 1 hour or when the player actively closes the checkout page. To cancel an open checkout session at any time, such as when multiple checkout tabs are open, call the Cancel Checkout Session API. You can listen for order events that are triggered based on different checkout outcomes.

​
Step 5 | Redirect player to the game

Once the payment is processed, the browser will display a Return to game button. Players can tap this button to be redirected back to your app. Appcharge handles the redirection using the redirectUrl you provided in the Create Checkout Session API request. The URL includes the following query parameter:
ParameterTypeDescription
statusStringIndicates the result of the payment process.
One of:
  • ?status=success: The purchase was completed successfully.

  • ?status=fail: An error occurred during the purchase process, or the player closed the checkout window.

  • ?status=cancel: The player actively canceled the purchase.
    •
    Example iOS URL: 
    https://www.my-game.com/?status=success
    Example Android URL: 
    my-prefix-my-game://action?status=success
    The redirect URL may trigger a confirmation dialog.

    ​
    Step 6 | Validate the purchase and fulfill the order

    After the player returns to your game via the redirectUrl, parse the URL to extract the status. If status=success, send this data to your game server to validate the transaction against the data received from the Grant Award Callback. If the purchase is valid, apply the corresponding items to the player’s account.