In-app purchase validation

In-app purchases (IAP) are a key monetization tool for games, enabling purchases for unlocks, consumables, subscriptions, and more. However, without proper validation, IAP implementations are vulnerable to fraud and abuse. Nakama provides secure server-side validation for Apple App Store, Google Play, and Huawei purchases.

This guide explains how Nakama’s IAP validation works, how to prevent common attacks like replay attacks and receipt sharing, and how to handle purchase state changes through real-time notifications.

Why validate purchases server-side #

Client-side IAP validation is vulnerable to several common attacks:

• Feeding the client fake purchase responses which indicate success.
• Replaying a valid purchase response multiple times.
• Sharing a purchase response with another client, so multiple players can receive the reward from a single purchase.

For in-app purchases, you need a trusted source of truth. Nakama checks and tracks purchases and purchase history, solving a significant set of possible vulnerabilities and pain points:

How IAP validation works #

The validation flow is initiated by your game client, but all verification happens server-side in Nakama:

1. Client makes purchase: The player completes a purchase using the platform SDK (Apple, Google, or Huawei).
2. Client receives receipt: The platform SDK returns a receipt in a platform-specific format.
3. Client sends receipt to Nakama: Your game sends the receipt to Nakama’s validation endpoint.
4. Nakama validates with provider: Nakama contacts the provider’s API (Apple, Google, or Huawei) to verify the receipt is authentic.
5. Nakama stores the result: After validation, Nakama normalizes the response and stores it in the database, attached to the user.
6. Game grants reward: Based on the validation response, your game logic grants the appropriate rewards or access.

This flow ensures that all payments are verified by the actual payment provider on the server before your game grants any rewards.

Replay attack prevention #

Every validated purchase and subscription is stored in Nakama’s database. When you validate a receipt, Nakama checks if it’s been validated before and returns a seenBefore boolean flag.

• seenBefore: false: This is the first time this receipt has been validated - it’s safe to grant rewards.
• seenBefore: true: This receipt has already been validated - it may be a replay attack or legitimate re-validation.

This mechanism prevents players from using the same receipt multiple times to receive rewards repeatedly.

Purchases vs subscriptions #

Nakama supports two distinct entities for IAP validation:

Purchases #

One-time purchases for consumables, unlocks, or permanent items. Key characteristics:

• Single validation: Once validated, the purchase is recorded.
• Seen before tracking: Nakama tracks if a receipt has been used before to prevent double-spending.
• Refund notifications: You can receive notifications when purchases are refunded.

Subscriptions #

Recurring purchases that grant access for a period of time. Key characteristics:

• Time-based access: Subscriptions have expiry times and active status.
• State changes: Subscriptions can be renewed, expired, cancelled, or refunded.
• Real-time updates: Nakama automatically updates subscription state based on provider notifications.
• Ongoing tracking: Subscription status is continuously monitored through the validation period.

Handling refunds and subscription changes #

Payments and refunds are handled entirely by the platform providers (Apple, Google, Huawei). Nakama never sees payment information directly. However, providers offer notification systems to inform your server about changes.

Real-time notifications #

Both Apple and Google support real-time server-to-server notifications for:

• Purchase refunds: When a player requests and receives a refund.
• Subscription renewals: When a subscription auto-renews successfully.
• Subscription cancellations: When a player cancels their subscription.
• Subscription expirations: When a subscription reaches its expiry time without renewing.

Once you configure Nakama to receive these notifications, it automatically updates the purchase or subscription state in the database.

Notification types #

Apple and Google send many different notification types with various subtypes. Nakama simplifies these by normalizing them into 5 categories that track expiry time changes, subscription state, and refund status.

This normalization makes it easier to handle notifications consistently across providers.

If you need access to the original provider notification data for custom processing, it’s available in the providerPayload parameter passed to your notification hooks. This contains the complete raw notification from Apple or Google.

Notification hooks #

You can register callback functions i.e., hooks, to respond to notifications. Your hooks execute after Nakama has updated the purchase or subscription state in the database.

Use notification hooks to:

• Revoke player access when subscriptions expire or are refunded.
• Send re-engagement messages when subscriptions are cancelled.
• Update analytics or tracking systems.
• Trigger in-game rewards or notifications.

For purchases, only refund notifications are available. For subscriptions, you’ll receive notifications for all state changes.

Understanding validation results #

When you validate a receipt, Nakama returns a validation result containing a list of validated purchases.

Apple receipts #

Because Apple receipts can contain multiple purchases in a single receipt, each validated purchase in the resulting list will contain only the purchases which have been validated and a boolean value to indicate if it’s been seen before. If a purchase has already been validated by Nakama previously, the “seen before” value will be true, letting you discriminate new purchases from repeated validations and protect against replay attacks.

Google and Huawei receipts #

For Google and Huawei, each validation corresponds to a single purchase, which is included in the validation response list. Like Apple, each purchase also has a “seen before” value to prevent replay attacks.

Response contents #

Each validated purchase includes:

• User ID: The user who made the purchase
• Product ID: The SKU or product identifier
• Transaction ID: Unique identifier for the transaction
• Store: The platform (Apple, Google, Huawei, or Facebook)
• Purchase time: When the purchase was made
• Seen before: Boolean indicating if this receipt was previously validated
• Provider response: The raw response from the provider, in case you need it for custom processing
• Environment: Whether the purchase was made in production or sandbox
• Refund time: Set if the purchase was refunded

For subscriptions, the response includes additional fields:

• Original transaction ID: The ID of the original subscription (not renewals)
• Expiry time: When the subscription expires
• Active: Whether the subscription is currently active
• Provider notification: Raw provider notification data

Error handling #

If the purchase or receipt is invalid, the validation fails for any reason, or the provider is unreachable, you’ll receive an error. Your game should handle these errors gracefully and not grant rewards when validation fails.

Supported platforms #

Apple App Store #

• Single product purchases
• Subscription purchases
• Real-time server notifications for refunds and subscription changes
• iOS 7+ receipts supported

Set up Apple validation →

Google Play #

• Single product purchases
• Subscription purchases
• Real-time developer notifications for refunds and subscription changes
• Requires Google Cloud Service Account with Play Console permissions

Set up Google validation →

Huawei AppGallery #

Nakama validates Huawei purchases against their IAP validation service. As suggested by Huawei, the validity of the purchase data is also checked against the provided signature before contacting the Huawei service. If the data is invalid for any reason, the purchase is rejected before validation with Huawei’s validation service.

Validate purchase #

To validate a Huawei purchase, you’ll need both the purchase data and its signature from the Huawei IAP SDK. Nakama first verifies the signature locally, then validates the purchase with Huawei’s servers.

1
2
3

curl "http://127.0.0.1:7350/v2/iap/purchase/huawei \
  --user 'defaultkey:' \
  --data '{"purchase":"json_encoded_purchase_data","signature":"purchase_data_signature"}'

1

-- Huawei purchases are not yet supported by https://defold.com/extension-iap/

1
2
3
4
5
6
7

string huaweiReceipt = "<receipt>";
string huaweiSignature = "<signature>";
var response = await client.ValidatePurchaseHuaweiAsync(session, huaweiReceipt, huaweiSignature);
foreach (var validatedPurchase in response.ValidatedPurchases)
{
    System.Console.WriteLine("Validated purchase: " + validatedPurchase);
}

1
2
3
4
5
6
7
8

let huaweiReceipt = "<receipt>"
let huaweiSignature = "<signature>"

let response = try await client.validatePurchaseHuawei(session: session, receipt: huaweiReceipt, signature: huaweiSignature)

for purchase in response.validatedPurchases {
    print("Validated purchase: \(purchase)")
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

const huaweiReceipt = "<receipt>";
const huaweiSignature = "<signature>";
const result = await client.validatePurchaseHuawei(
  session,
  huaweiReceipt,
  huaweiSignature
);
result.validatedPurchases.forEach((validatedPurchase) => {
  console.info("Validated purchase:", validatedPurchase);
});

1
2
3
4
5
6
7
8

var huawei_receipt = "<receipt>"
var huawei_signature = "<signature>"
var result : NakamaAPI.ApiValidatePurchaseResponse = yield(client.validate_purchase_huawei_async(session, huawei_receipt, huawei_signature), "completed")
if result.is_exception():
    print("An error occurred: %s" % result)
    return
for p in result.validated_purchase:
    print("Validated purchase: %s" % p.validated_purchase)

1
2
3
4
5
6
7
8

var huawei_receipt = "<receipt>"
var huawei_signature = "<signature>"
var result : NakamaAPI.ApiValidatePurchaseResponse = await client.validate_purchase_huawei_async(session, huawei_receipt, huawei_signature)
if result.is_exception():
    print("An error occurred: %s" % result)
    return
for p in result.validated_purchase:
    print("Validated purchase: %s" % p.validated_purchase)

1
2
3
4
5
6
7
8
9

POST /v2/iap/purchase/huawei
Host: 127.0.0.1:7350
Accept: application/json
Content-Type: application/json
Authorization: Bearer <session token>
{
  "purchase":"json_encoded_purchase_data",
  "signature":"purchase_data_signature"
}

Refer to the function reference page for the provided runtime purchase validation functions.

Facebook Instant Games #

Nakama supports validating purchases made for products on Facebook Instant Games.

Validate purchase #

To validate a Facebook Instant Games purchase, you’ll send the signed request from the Facebook SDK to Nakama. The signed request contains the purchase information that Nakama will verify with Facebook’s servers.

1
2
3
4

var signedRequest = "<signedRequest>";
var response = await client.ValidatePurchaseFacebookInstantAsync(session, signedRequest);

System.Console.WriteLine("Validated purchase: " + response.ValidatedPurchase);

1
2
3
4

const signed = "<signedRequest>";
const response = await client.validatePurchaseFacebookInstant(session, signed);

console.info("Validated purchase:", response.validatedPurchase);

Unity IAP #

If you’re using Unity IAP in your game, you can still validate purchases through Nakama. Unity IAP provides a unified interface for integrating with most popular app stores, including Apple and Google, and Nakama can validate the receipts it generates.

Unity IAP purchase receipts contain the following information:

Validate purchase #

When validating Unity IAP purchases, you’ll extract the payload from the Unity receipt and route it to the appropriate platform validation endpoint based on the store type. Here’s how to handle Unity IAP receipts in your server-side code:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

type unityIAP struct {
	  Payload       string `json:"Payload"`
	  Store         string `json:"Store"`
	  TransactionID string `json:"TransactionID"`
}

switch unityIAP.Store {
    case "GooglePlay":
        validatedReceipt, err = nk.PurchaseValidateGoogle(ctx, userID, wrapper.Payload)
    case "AppleAppStore":
        validatedReceipt, err = nk.PurchaseValidateApple(ctx, userID, wrapper.Payload)
    default:
        logger.Warn("Unrecognised store type in Unity IAP.")
        return ErrBadInput
}
if err != nil {
    logger.WithField("err", err).Error("Receipt validation error.")
    return err
}

if validatedReceipt.SeenBefore {
    // Handle already seen receipt.
    logger.Warn("Receipt replay attack.")
}

Subscriptions #

In addition to validation of purchases and subscriptions, you can also get subscriptions by specific product ID or list all subscriptions for a given user.

Get subscription #

After validating a subscription, you can retrieve its current state at any time using the product ID. This is useful for checking subscription status, expiry times, and renewal information without revalidating the receipt.

1
2
3
4

string productId = "<productId>";
var response = await client.GetSubscriptionAsync(session, productId);

System.Console.WriteLine("Subscription: " + response);

1
2
3
4
5

let productId = "<productId>"

let response = try await client.getSubscription(session: session, productId: productId)

print("Subscription: \(response)")

1
2
3
4
5
6
7
8

var product_id = "..."
var response : NakamaAPI.ApiValidatedSubscription = yield(client.get_subscription_async(session, product_id), "completed")

if response.is_exception():
    print("An error occurred: %s" % response)
    return

print("Validated subscription: %s" % response)

1
2
3
4
5
6
7
8

var product_id = "..."
var response : NakamaAPI.ApiValidatedSubscription = yield(client.get_subscription_async(session, product_id), "completed")

if response.is_exception():
    print("An error occurred: %s" % response)
    return

print("Validated subscription: %s" % response)

1
2

curl "http://127.0.0.1:7350/v2/iap/subscription/{productId} \
  -H 'Authorization: Bearer <session token>'

1
2
3
4
5

GET /v2/iap/subscription/{productId}
Host: 127.0.0.1:7350
Accept: application/json
Content-Type: application/json
Authorization: Bearer <session token>

1
2
3

local product_id = "<productId>";
local response = client.get_subscription(product_id)
pprint("Subscription:", response)

1
2
3

const productId = "<productId>";
const response = await client.getSubscription(session, productId);
console.info("Subscription:", response);

Refer to the function reference page for the provided runtime subscription validation functions.

List user subscriptions #

You can retrieve all subscriptions for a user, which is useful for displaying their current subscription status in your game or managing multiple active subscriptions. The list supports pagination for users with many subscriptions.

1
2
3
4
5
6
7

string userId = "<userId>";
var response = await client.ListSubscriptionsAsync(userId);

foreach (var validatedSubscription in response.ValidatedSubscriptions)
{
    System.Console.WriteLine("Subscription: " + validatedSubscription);
}

1
2
3
4
5

let response = try await client.listSubscriptions(session: session, limit: 20)

for subscription in response.validatedSubscriptions {
    print("Subscription: \(subscription)")
}

1
2
3
4
5
6
7
8

var response : NakamaAPI.ApiSubscriptionList = yield(client.get_subscription_list(session), "completed")

if response.is_exception():
    print("An error occurred: %s" % response)
    return

for p in result.validated_subscriptions:
    print("Validated subscription: %s" % p.validated_subscription)

1
2
3
4
5
6
7
8

var response : NakamaAPI.ApiSubscriptionList = await client.get_subscription_list(session)

if response.is_exception():
    print("An error occurred: %s" % response)
    return

for p in result.validated_subscriptions:
    print("Validated subscription: %s" % p.validated_subscription)

1
2

curl "http://127.0.0.1:7350/v2/iap/subscription/limit=<limit>&cursor=<cursor>" \
  -H 'Authorization: Bearer <session token>'

1
2
3
4
5

GET /v2/iap/subscription/limit=<limit>&cursor=<cursor>
Host: 127.0.0.1:7350
Accept: application/json
Content-Type: application/json
Authorization: Bearer <session token>

1
2
3
4

local response = client.list_subscriptions()
for i,subscription in ipairs(response.validatedSubscriptions) do
  pprint("Subscription:", response)
end

1
2
3
4

const response = await client.listSubscriptions(session, limit: 20)
response.validatedSubscriptions.forEach(validatedSubscription => {
  console.info("Subscription:", validatedSubscription)
});

Refer to the function reference page for the provided runtime subscription validation functions.

See also #

• Validate Apple App Store purchases
• Validate Google Play purchases
• Purchases function reference