Automatic Payment Refunds

Aghanim supports automatic payment refunds when your game server rejects a purchase due to expired promotions, insufficient player requirements, or other business logic. This feature allows your webhook to instruct Aghanim to automatically process refunds without manual intervention, improving player experience and reducing support overhead.

Overview

When a player attempts to purchase an item but your game server determines the purchase should be rejected (for example, a promotion has expired), your item.add webhook can respond with a declined error code. If your team has configured automatic refunds in Aghanim, the payment will be automatically refunded.

This prevents players from being charged for items they cannot receive and eliminates the need for manual refund processing.

info

Automatic refunds must be configured by the Aghanim team. Please contact our integration team to enable automatic refunds for purchases rejected with code="declined".

How It Works

1. Player initiates purchase - A player attempts to buy an item through the game hub
2. Payment processed - Aghanim processes the payment through the payment provider
3. Webhook sent - Aghanim sends an item.add webhook to your game server
4. Game server validates - Your server checks business rules (promotion validity, player eligibility, etc.)
5. Purchase declined - If the purchase should be rejected, your server responds with code="declined"
6. Automatic refund - If configured, Aghanim automatically processes the refund through the payment provider

Prerequisites

• Configured item.add webhook endpoint
• HTTPS endpoint capable of processing webhook requests
• Business logic to validate purchases against current promotions and requirements

Implementation

Standard Success Response

For successful purchases, respond with a 200 status code:

{
  "status": "ok"
}

Purchase Rejection

To reject a purchase, respond with a 400 status code:

{
  "status": "error",
  "code": "declined",
  "message": "Purchase rejected: promotion has expired"
}

Error Response Schema

Key	Type	Description	Required?
status	string	Must be "error" for rejected purchases.	Yes
code	string	Error code indicating the reason for the error.	Yes
message	string	Human-readable error message.	Yes

Available Error Codes

Standard Error Codes

• not_found: The account/player not found
• invalid_signature: The signature was invalid
• validation_error: The request data was invalid
• banned: The account/player is banned
• declined: The request was declined due to business rules or restrictions

warning

Only code="declined" will trigger automatic refunds when this feature is enabled by the Aghanim team. Other error codes will not trigger refunds.

Common Rejection Scenarios

Expired Promotion

{
  "status": "error",
  "code": "declined",
  "message": "Purchase rejected: Black Friday promotion ended at midnight"
}

Insufficient Player Level

{
  "status": "error", 
  "code": "declined",
  "message": "Purchase rejected: player must be level 10 or higher"
}

Item No Longer Available

{
  "status": "error",
  "code": "declined",
  "message": "Purchase rejected: item is no longer available"
}

Daily Purchase Limit Exceeded

{
  "status": "error",
  "code": "declined",
  "message": "Purchase rejected: daily purchase limit exceeded"
}

Regional Restrictions

{
  "status": "error",
  "code": "declined",
  "message": "Purchase rejected: item not available in player's region"
}

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