How to Purchase Items from the Game Client Using Aghanim

This guide provides a step-by-step process for purchasing items from the in-game hub via a game client using the Aghanim API.

Prerequisites

• API Key: Required for authenticating your API requests.
• Integrated item.add Webhook: Ensure that the item.add webhook is integrated to handle purchased items.

Step 1: Create an Order on the Game Server

When a user clicks the "Buy" button in the game client, the client should send a message to the game server's backend to create an order. This is done by sending a POST request to the Create Order endpoint using the Server-to-Server (S2S) API.

Request schema

The POST request payload must include the following fields:

Field	Type	Description	Required
player_id	string	The unique ID of the player making the purchase.	Yes
items	Item[]	A list of items that the player intends to buy.	Yes
ip_address	string	The IP address of the player making the purchase.	No
user_agent	string	The user agent of the player making the purchase.	No
locale	string	The locale of the player making the purchase.	No
country	string	The country of the player making the purchase.	No

The Item object schema

Each item in the items array should adhere to the following schema:

Field	Type	Description	Required
id	string	The unique ID of the item.	Yes
sku	string	The Stock Keeping Unit (SKU) of the item.	Yes
name	string	The name of the item.	Yes
price	number	Item price in minor currency units.	Yes
currency	string	Item price currency.	Yes
image_url	string	The URL of the item image.	No
description	string	The description of the item.	No
quantity	number	The quantity of the item to be purchased.	No
discount_percent	number	The discount applied to the item in %age.	No
bonus_percent	number	The bonus applied to the item in %age.	No

Example request

Here’s an example of how to create an order using a POST request with curl:

curl -X POST https://api.aghanim.com/s2s/v1/orders \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -d '{
        "player_id": "2D2R-OP3C",
        "items": [
          {
            "id": "093431513412",
            "sku": "crystals",
            "name": "Crystals",
            "price": 9499,
            "currency": "USD",
            "image_url": "https://example.com/crystals.png",
            "description": "Reign supreme over your rivals with this massive crystal treasure.",
            "quantity": 480000
          }
        ]
    }'

Example response

On successfully creating the order, the server will respond with an order_id:

{"order_id": "ord_eCacpFwavzi"}

Step 2: Open the Checkout Dialog in the Game Client

Once the order is created, you can open the purchase dialog in the game client by invoking the JavaScript function aghanim.purchase(orderId).

Example function call

aghanim.purchase('ord_eCacpFwavzi');

This function triggers the in-game purchase flow, allowing the player to complete the transaction.

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