This article explains how to set up a payment link in your app using the Appcharge API. To implement payment links with the SDK, refer to the iOS Mobile Checkout SDK.

​
Before you begin

Before you get started, ensure you’ve completed the following steps:
  1. Develop and expose a webhook to receive player transaction updates from Appcharge, following the Player Order Reporting Webhook schema.
  2. Enter your webhook URL in the Publisher Dashboard under Settings -> Integration.

​
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

First 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 (a universal link that brings the player back to the game)
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.
Next, return the session data to the game client.

​
Step 3 | Build and open the checkout URL

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.
Important: The cot parameter is required, and without it, the checkout page will not load correctly.
Your checkout URL should look something like this: https://appcharge-checkout-url.com/eb02bb412ccb47948f7d62667a7774b1?cot=0b2b42ab8a3d491ba76b6b8919d8e0ee Next, open this URL in the browser. Note: 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 Player Order Reporting Webhook 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 iOS device will display a Return to game button. Players can tap this button to be redirected back to your game. 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 URL: 
    https://www.my-game.com/?status=success
    Note: The redirect uses a Universal Link, which may trigger a confirmation dialog on iOS. Learn how to remove it and send players straight back into the game.

    ​
    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 Player Order Reporting Webhook. If the purchase is valid, apply the corresponding items to the player’s account.

    ​
    Example

    For a reference implementation, see our sample Unity app, which demonstrates the recommended process for integrating payment links into an iOS game.