Validate Apple App Store purchases

This guide shows you how to set up and validate Apple App Store purchases and subscriptions with Nakama.

Before you begin #

Make sure you have:

• An Apple Developer account with access to App Store Connect
• An iOS app configured for in-app purchases in App Store Connect
• Nakama v3.37.0 or later if using StoreKit 2

How Apple validation works #

Nakama sends Apple purchase receipts to Apple for validation. Following Apple’s recommendations, it uses both Production and Sandbox servers to validate receipts.

Apple receipts can contain multiple purchases. Nakama validates all of them and stores them as individual purchase records. Nakama only supports validating iOS 7+ receipts.

StoreKit 1 and StoreKit 2 #

Nakama supports both StoreKit 1 (legacy) and StoreKit 2 receipts through the same validation API. The receipt type your app sends depends on which version of the Apple SDK your client uses.

If you set the shared secret in Nakama, it’s used only for StoreKit 1 receipts. StoreKit 2 receipts are validated using PKI regardless of whether the shared secret is set.

Configure Apple App Store credentials #

If you’re using StoreKit 2 exclusively, skip this section as no Nakama configuration is required. If you’re using StoreKit 1 or need to support both receipt formats, configure the shared secret as follows.

1. From App Store Connect, go to General > App Information and find the App-Specific Shared Secret section:

2. Select Manage and in the dialog that appears, select Generate:

3. Record your shared secret for use in your Nakama configuration:

4. Set Nakama’s iap.apple.shared_password configuration flag to the shared secret value:

1
2
3

iap:
  apple:
    shared_password: "your-shared-secret-here"

Validate a purchase #

To validate an Apple purchase, send the receipt data in the appropriate format to Nakama’s validation endpoint. Nakama verifies the receipt with Apple’s servers and returns a list of validated purchases. Each purchase includes a “seen before” flag to help you detect and prevent replay attacks.

1
2
3

curl "http://127.0.0.1:7350/v2/iap/purchase/apple \
  --user 'defaultkey:' \
  --data '{"receipt":"base64_encoded_receipt_data"}'

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

local function validate_receipt(receipt)
  local result = client.validate_purchase_apple(receipt)
  if result.error then
    print(result.message)
    return
  end
  pprint(result)
end

-- Use https://defold.com/extension-iap/
iap.set_listener(function(self, transaction, error)
  if not error then
    validate_receipt(transaction.receipt)
  end
end)
iap.buy("com.defold.nakama.goldbars-10")

1
2
3
4
5
6

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

1
2
3
4
5
6
7

let appleReceipt = "<receipt>"

let response = try await client.validatePurchaseApple(session: session, receipt: appleReceipt)

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

1
2
3
4
5

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

1
2
3
4
5
6
7

var apple_receipt = "<receipt>"
var result : NakamaAPI.ApiValidatePurchaseResponse = yield(client.validate_purchase_apple_async(session, apple_receipt), "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

var apple_receipt = "<receipt>"
var result : NakamaAPI.ApiValidatePurchaseResponse = await client.validate_purchase_apple_async(session, apple_receipt)
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

POST /v2/iap/purchase/apple
Host: 127.0.0.1:7350
Accept: application/json
Content-Type: application/json
Authorization: Bearer <session token>
{
  "receipt": "base64_encoded_Apple_receipt_payload"
}

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

Validate a subscription #

Subscription validation works similarly to purchase validation, but returns subscription-specific information like expiry time and active status. Send the same receipt in the appropriate format to the subscription validation endpoint.

1
2
3
4

string appleReceipt = "<receipt>";
var response = await client.ValidateSubscriptionAppleAsync(session, appleReceipt);

System.Console.WriteLine("Validated subscription: " + response.ValidatedSubscription);

1
2
3
4
5

let appleReceipt = "<receipt>"

let response = try await client.validateSubscriptionApple(session: session, receipt: appleReceipt)

print("Validated subscription: \(response.validatedSubscription)")

1
2
3
4
5
6
7
8

var apple_receipt = "..."
var response : NakamaAPI.ApiValidateSubscriptionResponse = yield(client.validate_subscription_apple_async(session, apple_receipt), "completed")

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

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

1
2
3
4
5
6
7
8

var apple_receipt = "..."
var response : NakamaAPI.ApiValidateSubscriptionResponse = await client.validate_subscription_apple_async(session, apple_receipt)

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

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

1
2
3

curl "http://127.0.0.1:7350/v2/iap/subscription/apple \
  --user 'defaultkey:' \
  --data '{"receipt":"base64_encoded_receipt_data"}'

1
2
3
4
5
6
7
8

POST /v2/iap/subscription/apple
Host: 127.0.0.1:7350
Accept: application/json
Content-Type: application/json
Authorization: Bearer <session token>
{
  "receipt": "base64_encoded_Apple_receipt_payload"
}

1
2
3
4
5

local apple_receipt = "<receipt>";
local response = client.validate_purchase_apple(receipt)
for i,purchase in ipairs(response.validated_purchase) do
  pprint("Validated purchase: ", purchase)
end

1
2
3

const appleReceipt = "<receipt>";
const result = await client.validateSubscriptionApple(session, appleReceipt);
console.info("Validated subscription:", result.validatedSubscription);

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

Handle refunds and subscription changes #

The Apple App Store supports Server Notifications to monitor IAP state changes in real time. Configuring server notifications is optional since your receipts and subscriptions validate correctly without it. However, enabling notifications is recommended: it lets Nakama automatically track subscription renewals, expirations, cancellations, and refunds, and allows you to register runtime hooks to trigger custom code when these events occur.

Set up notification callbacks #

To activate the callback URL, set the notifications_endpoint_id configuration, which creates the following endpoint path: /v2/console/apple/subscriptions/<notifications_endpoint_id>.

The <notifications_endpoint_id> is an arbitrary string you define. It becomes the path segment Nakama listens on for incoming notifications.

Configure this URL in App Store Connect for both production and sandbox environments. Apple requires App Store Server Notifications v2.

Automatic state updates #

Once you’ve configured the callback URL, Nakama automatically updates the state of any purchase or subscription that was previously validated through the validation APIs. This keeps subscription expiry times, active status, and other metadata synchronized with the App Store.

Notification types #

Nakama normalizes Apple’s notifications into five simplified types:

These normalized types make it easier to handle notifications consistently across both Apple and Google platforms.

Implement notification hooks #

Register custom code to respond to notifications for purchases and subscriptions. Hooks fire after Nakama has automatically updated the purchase or subscription state in the database.

Use these hooks to implement your own business logic when IAP states change — like revoking player access when a subscription expires, sending analytics events, or triggering in-game rewards for renewals.

Purchase notifications #

Register a hook to handle purchase refunds. The purchase parameter contains the validated purchase data. See Response contents for available fields.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

if err := initializer.RegisterPurchaseNotificationApple(func(ctx context.Context, logger runtime.Logger, db *sql.DB, nk runtime.NakamaModule, notificationType runtime.NotificationType, purchase *api.ValidatedPurchase, payload *runtime.AppleNotificationData) error {
    logger.Info("Apple purchase notification: %s", notificationType.String())

    // For purchases, notificationType will always be REFUNDED since that's the only
    // purchase notification Apple sends.
    if notificationType == runtime.IAPNotificationRefunded {
        // Handle refund - e.g., revoke access, update analytics
        logger.Info("Purchase refunded for user: %s, product: %s", purchase.UserId, purchase.ProductId)

        // payload contains detailed Apple notification data if needed for custom processing
    }

    return nil
}); err != nil {
    return err
}

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

let registerPurchaseNotificationApple: nkruntime.RegisterPurchaseNotificationAppleFunction =
  function (
    ctx: nkruntime.Context,
    logger: nkruntime.Logger,
    nk: nkruntime.Nakama,
    notificationType: nkruntime.NotificationType,
    purchase: nkruntime.ValidatedPurchase,
    payload: nkruntime.AppleNotificationData,
  ) {
    logger.info("Apple purchase notification: %s", notificationType);

    if (notificationType == nkruntime.NotificationType.REFUNDED) {
      logger.info(
        "Purchase refunded for user: %s, product: %s",
        purchase.userId,
        purchase.productId,
      );
      // Handle refund logic
    }
  };

initializer.registerPurchaseNotificationApple(
  registerPurchaseNotificationApple,
);

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

local function purchase_notification_apple(context, logger, nk, notification_type, purchase, payload)
    logger.info(("Apple purchase notification: %s"):format(notification_type))

    if notification_type == "REFUNDED" then
        logger.info(("Purchase refunded for user: %s, product: %s"):format(purchase.user_id, purchase.product_id))
        -- Handle refund logic
    end
end

nk.register_purchase_notification_apple(purchase_notification_apple)

Subscription notifications #

Register a hook to handle all subscription state changes. The subscription parameter contains the validated subscription data — see Response contents for available fields.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

if err := initializer.RegisterSubscriptionNotificationApple(func(ctx context.Context, logger runtime.Logger, db *sql.DB, nk runtime.NakamaModule, notificationType runtime.NotificationType, subscription *api.ValidatedSubscription, payload *runtime.AppleNotificationData) error {
    logger.Info("Apple subscription notification: %s", notificationType.String())

    switch notificationType {
    case runtime.IAPNotificationSubscribed:
        logger.Info("New subscription: %s", subscription.ProductId)
        // Handle new subscription - e.g., grant access, send welcome message

    case runtime.IAPNotificationRenewed:
        logger.Info("Subscription renewed: %s", subscription.ProductId)
        // Handle renewal - e.g., extend access, update analytics

    case runtime.IAPNotificationExpired:
        logger.Info("Subscription expired: %s", subscription.ProductId)
        // Handle expiration - e.g., revoke access, send re-engagement message

    case runtime.IAPNotificationCancelled:
        logger.Info("Subscription cancelled: %s", subscription.ProductId)
        // Handle cancellation - e.g., schedule access revocation, send feedback survey

    case runtime.IAPNotificationRefunded:
        logger.Info("Subscription refunded: %s", subscription.ProductId)
        // Handle refund - e.g., immediately revoke access, update analytics
    }

    // The subscription object already contains updated state (expiry time, etc.)
    // payload contains detailed Apple notification data for custom processing if needed

    return nil
}); err != nil {
    return err
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

let registerSubscriptionNotificationApple: nkruntime.RegisterSubscriptionNotificationAppleFunction =
  function (
    ctx: nkruntime.Context,
    logger: nkruntime.Logger,
    nk: nkruntime.Nakama,
    notificationType: nkruntime.NotificationType,
    subscription: nkruntime.ValidatedSubscription,
    payload: nkruntime.AppleNotificationData,
  ) {
    logger.info("Apple subscription notification: %s", notificationType);

    switch (notificationType) {
      case nkruntime.NotificationType.SUBSCRIBED:
        logger.info("New subscription: %s", subscription.productId);
        break;
      case nkruntime.NotificationType.RENEWED:
        logger.info("Subscription renewed: %s", subscription.productId);
        break;
      case nkruntime.NotificationType.EXPIRED:
        logger.info("Subscription expired: %s", subscription.productId);
        break;
      case nkruntime.NotificationType.CANCELLED:
        logger.info("Subscription cancelled: %s", subscription.productId);
        break;
      case nkruntime.NotificationType.REFUNDED:
        logger.info("Subscription refunded: %s", subscription.productId);
        break;
    }
  };

initializer.registerSubscriptionNotificationApple(
  registerSubscriptionNotificationApple,
);

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

local function subscription_notification_apple(context, logger, nk, notification_type, subscription, payload)
    logger.info(("Apple subscription notification: %s"):format(notification_type))

    if notification_type == "SUBSCRIBED" then
        logger.info(("New subscription: %s"):format(subscription.product_id))
    elseif notification_type == "RENEWED" then
        logger.info(("Subscription renewed: %s"):format(subscription.product_id))
    elseif notification_type == "EXPIRED" then
        logger.info(("Subscription expired: %s"):format(subscription.product_id))
    elseif notification_type == "CANCELLED" then
        logger.info(("Subscription cancelled: %s"):format(subscription.product_id))
    elseif notification_type == "REFUNDED" then
        logger.info(("Subscription refunded: %s"):format(subscription.product_id))
    end
end

nk.register_subscription_notification_apple(subscription_notification_apple)

See also #

• About in-app purchase validation
• Validate Google Play purchases
• Purchases function reference