跳至主要内容

Checkout Links

Integrate the Aghanim to start accepting payments for your game items online through a prebuilt checkout page. A lightweight, portal-based integration used when full API or SDK implementation would be excessive. Though you will need some coding.

Web Links Checkout
Web Links Checkout

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.

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.

Every Checkout Link is a deep link and associated with a player and an item, they are crucial for the Checkout to work. In a Checkout Link, you can use only the items that are already added to the Dashboard. And all players that aren’t in the Dashboard will be created once the Checkout Link is opened.

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

Add an item to the Dashboard so you can use it in a Checkout Link:

  1. Go to SKU Management → Items.
  2. Click Add Item. The site will open the Add Item page.
  3. Enter the item name New item.
  4. Enter the item SKU new-item-199.
  5. In the Price block:
    1. Select the Fiat price type for a real money item.
    2. Enter the price 1.99.
  6. Click Add item.

For integration purposes, we have shortened an item setup. Before going live, use every suitable feature while adding items to the Dashboard.

Each Checkout Link is created for one item:

  1. Go to Integration → Checkout Links.
  2. Click Add Checkout Link. The site will open the Add Checkout Link window.
  3. In the general block, enter and select the SKU new-item-199.
  4. Click Save changes.

To complete the Checkout Link, copy it and replace the player ID placeholder with the value.

https://pay.aghanim.com/link/lnk_eHriLMNNvUxvbFHm?player_id={player_id}

Redirect your player to Checkout page

Add a checkout button to your game and embed in it the created Checkout Link. Once the player clicks it, they will be redirected to the payment form in their browser.

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.

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

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.

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.

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.

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.
# 使用以下示例代码来处理您集成环境中的 Webhook 事件。
#
# 1. 将此代码复制到新创建的 `server.py` 文件中。
#
# 2. 安装必要的依赖项：
#    python -m pip install fastapi[all]
#
# 3. 在 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>"  # 请替换为您的实际 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:
    # 用于处理事件和添加商品的示例占位代码。
    # 在实际应用中，此函数将与您的数据库或库存管理系统进行交互。
    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:
    # 用于处理事件和移除商品的示例占位代码。
    # 在实际应用中，此函数将与您的数据库或库存管理系统进行交互。
    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)

When the webhook handling is ready, add the endpoint to the Dashboard 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.

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

需要技术支持？
联系我们的集成技术团队： integration@aghanim.com

On this page