Skip to main content

Checkout for web games

For the web games distributed on the desktop screen, use this page to integrate the Aghanim Checkout via the API and start accepting payments for your game items online through a prebuilt checkout page.

Desktop Checkout
Desktop Checkout

Register with Aghanim and link your game

First, register for an Aghanim account. At the end of registration, add the link to your mobile game. It should be published in Apple App Store or Google Play Store.

Set up environment

If you want to make real payments, you are all set as the live mode is used as default. Otherwise, use a sandbox, an isolated test environment, to simulate the Aghanim events to test payments without real money movement. To turn on the sandbox mode, set the Sandbox toggle to the active position.

While integrating, you will need an S2S key to authenticate requests to the Aghanim. Keep in mind that the sandbox and live modes have different keys. Find the S2S key in Integration → API keys.

Redirect your player to Checkout page

Add a checkout button to your game that calls the server-to-server endpoint to create an Order. An Order is the programmatic representation of what the player sees when they’re redirected to the payment form in their browser.

Create Order

Every Order is associated with a player and items, they are crucial for the Checkout to work. You can use the existing players and items from your game or create them now with any data.

When passing items, each should have its SKU, a unique identifier for the item within your game backend. You can add their prices, currency, sale configuration, and more.

Orders expire 24 hours after creation.

To have a quick result of the integration, create an Order for any arbitrary set of data. Here, you need to fill in just your S2S key.

curl -X POST https://api.aghanim.com/s2s/v1/orders \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <YOUR_S2S_KEY>' \
  -d '{
    "player_id": "r2d2-c3po",
    "items": [
      {
        "sku": "CRS-82500",
        "name": "Magic Crystals",
        "description": "Magic Crystals."
      }
    ],
    "price_decimal": 29.99,
    "currency": "USD"
  }'

OptionalPrefill player data

If you’ve already collected the player email address, pass it into the Order so the Aghanim will prefill it in the payment form. Fewer steps for the player, more respect for you.

curl -X POST https://api.aghanim.com/s2s/v1/orders \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <YOUR_S2S_KEY>' \
  -d '{
    "player_id": "r2d2-c3po",
    "items": [{"sku": "CRS-82500"}],
    "email": "pixel_warrior77@gmail.com"
  }'

OptionalReturn player back to game

To make the interaction between your game and the Checkout smoother, set a deep link to return the player to after they complete the payment.

curl -X POST https://api.aghanim.com/s2s/v1/orders \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <YOUR_S2S_KEY>' \
  -d '{
    "player_id": "r2d2-c3po",
    "items": [{"sku": "CRS-82500"}],
    "back_to_game_url": "<YOUR_GAME_DEEP_LINK>"
  }'

Finally redirect player

When an Order is created, receive a URL of the payment form and redirect the player to it.

{
  "order_id": "ord_eCacpFwavzi",
  "checkout_url": "https://pay.aghanim.com/order/ord_eCacpFwavzi"
}

Make payment

Make a payment. If you have set the sandbox mode, use the test card below. In the sandbox, you can make payments only with the test cards. They accept any digits as CVV and any future date as expiry date. Don’t forget to fill in an email address to check the receipt is sent and any postal code as a billing address.

Successful payments

After you complete the payment, you will receive a receipt sent to the specified email address and a transaction record in Aghanim Dashboard → Transactions.

Card BrandCard NumberCVVExpiry dateCountry
VISA (credit)
4242 4242 4242 4242
Any 3 digitsAny future dateGB

Unsuccessful payments

Make unsuccessful payment just in case you are curious. You will see the transaction in Aghanim Dashboard → Transactions as well.

NumberCVVExpiry dateResponse codeDescription
4832 2850 6160 9015
Any 3 digitsAny future date16Payment declined

OptionalAll payment methods

For the live mode, you can find all supported payment methods in Company settings → Payment methods. Turn on or off those you see suitable. Some payment methods are available globally by default. You can’t disable Credit cards, Apple Pay, Google Pay, and PayPal.

In Checkout, the Aghanim evaluates the currency and any restrictions, then dynamically presents only the payment methods available to the player based on evaluation.

OptionalSaving payment method

When you use the live mode, the payment form shows to the player a setting to save their payment method so they can make a one-click payment in the future.

Handle post-payment events

To complete the Checkout, handle items’ granting and chargebacks on your game backend. To do so, implement a webhook system that accepts the item.add and item.remove webhooks. See the code example with the implementation.

Comply with the Aghanim requirements for these webhooks:

  • Use HTTPS schema for the single POST webhook endpoint.
  • Check that webhooks are generated and signed by the Aghanim.
  • Handle the idempotency_key field in the webhook payload to prevent processing duplicate webhooks.
  • Respond with the HTTP status codes:
    • 2xx for successfully processed webhooks.
    • 4xx and 5xx for errors.

Grant items to player

The Aghanim sends the item.add webhook to let you know about the purchased items and ask for your permission to grant them to the player.

When the Aghanim has your 2xx answer, it can complete the checkout logic and redirect the player to a deep link if provided.

Support refunds and chargebacks

The Aghanim sends the item.remove webhook when a bank or payment system reverses the transaction, or you have requested refund in Aghanim Dashboard → Transactions. Partial refunds are not supported.

Use suggested implementation

The suggested implementation handles the webhooks mentioned before:

  • item.add for granting items. You need it for integration.
  • item.remove for refunds and chargebacks. You might need it for integration.
# Use this sample code to handle webhook events in your integration.
#
# 1. Paste this code into a new file `server.py`.
#
# 2. Install dependencies:
#    python -m pip install fastapi[all]
#
# 3. Run the server on http://localhost:8000
#    python server.py

import fastapi, hashlib, hmac, json, typing 

app = fastapi.FastAPI()

@app.post("/webhook")
async def webhook(request: fastapi.Request) -> dict[str, typing.Any]:
    secret_key = "<YOUR_S2S_KEY>"  # Replace with your actual webhook secret key

    raw_payload = await request.body()
    payload = raw_payload.decode()
    timestamp = request.headers["x-aghanim-signature-timestamp"]
    received_signature = request.headers["x-aghanim-signature"]

    if not verify_signature(secret_key, payload, timestamp, received_signature):
        raise fastapi.HTTPException(status_code=403, detail="Invalid signature")

    data = json.loads(payload)
    event_type = data["event_type"]
    event_data = data["event_data"]

    if event_type == "item.add":
        add_item(event_data)
        return {"status": "ok"}

    if event_type == "item.remove":
        remove_item(event_data)
        return {"status": "ok"}

    raise fastapi.HTTPException(status_code=400, detail="Unknown event type")

def verify_signature(secret_key: str, payload: str, timestamp: str, received_signature: str) -> bool:
    signature_data = f"{timestamp}.{payload}"
    computed_hash = hmac.new(secret_key.encode(), signature_data.encode(), hashlib.sha256)
    computed_signature = computed_hash.hexdigest()
    return hmac.compare_digest(computed_signature, received_signature)

def add_item(event_data: dict[str, typing.Any]) -> None:
    # Placeholder logic for processing the event and adding item.
    # In a real application, this function would interact with your database or inventory system.
    player_id = event_data["player_id"]
    for item in event_data["items"]:
      sku = event_data["sku"]
      print(f"Item {sku} have been credited to player's {player_id} account.")

def remove_item(event_data: dict[str, typing.Any]) -> None:
    # Placeholder logic for processing the event and removing item.
    # In a real application, this function would interact with your database or inventory system.
    player_id = event_data["player_id"]
    for item in event_data["items"]:
      sku = event_data["sku"]
      print(f"Item {sku} have been removed from player's {player_id} account.")

if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app, host="0.0.0.0", port=8000)

Add webhook endpoint to Aghanim

When the webhook handling is ready, add the endpoint to the account so the Aghanim could start sending the events.

  1. Go to Integration → Webhooks.
  2. Click New Webhook. The site will open the Create new webhook window.
  3. Cope and paste the URL https://<YOUR_DOMAIN>/webhook.
  4. Click Select events. The site will open the Select events to send window.
  5. Expand the Main class and select the Item add, Item remove checkboxes.
  6. Click Apply.
  7. Click Add. The site will redirect you to the webhook page.
  8. Click Back.

Test your integration

After you have handled the webhooks, check that the purchased items are in your inventory. That’s all.

Next steps

Need help?
Contact our integration team at integration@aghanim.com

On this page