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 get started, ensure you’ve completed the following steps:
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.
First call the Appcharge Create Checkout Session API from your server.
Include the following in the request:
Appcharge returns the following:
Parameter | Type | Description |
---|---|---|
checkoutSessionToken | String | A unique token that identifies and validates the checkout session. |
purchaseId | String | A unique ID to track the transaction. |
url | URL | The base URL for the Appcharge checkout page. |
Next, return the session data to the game client.
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.
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.
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:
Parameter | Type | Description |
---|---|---|
status | String | Indicates 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:
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.
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.
For a reference implementation, see our sample Unity app, which demonstrates the recommended process for integrating payment links into an iOS game.