This is the fourth tutorial of our series on implementing in-app purchases into an app. Today, I’m going to discuss server-side purchase validation for iOS. I recommend you read the other ones as well:
Server validation (server-side receipt validation) is a way to verify the purchase’s authenticity. Unlike device-based validation, server validation occurs — wait for it — on the server side. Validation signifies that the device or the server makes a request to Apple’s servers to find out whether the purchase actually occurred and whether it was valid.
It should be noted that server validation isn’t mandatory — in-app purchases will still work without it. It grants some advantages, though:
Speaking from our experience, the first advantage alone is enough to set up server purchase processing.
In general, the process of receipt validation on iOS looks like this:
To send a request of payment validation, you have to include the shared secret to authorize the request. You can generate one in App Store Connect.
Shared secret can be created for a specific app (app-specific secret) or for all apps in the account (primary secret).
To generate an app-specific secret, open the app’s page in App Store Connect, go to In-App Purchases → Manage and click App-Specific Shared Secret. In the window that opens, you’ll be able to generate a new token or copy the existing one.
To receive the secret for all apps in your account, open the Users and Access page and select the Shared Secret tab.
Once you receive the shared secret, you can send receipts to get validated on Apple servers. This is done via the verifyReceipt request. You have to send a POST request to https://buy.itunes.apple.com/verifyReceipt. In the JSON body of the request, pass the shared secret in the password field and the receipt in the receipt-data field. There’s also the optional exclude-old-transactions parameter. If it has the true value, then for each auto-renewable subscription, you’ll receive the last transaction only instead of the full renewal history.
Here’s the payload of the purchase validation request:
If you’re working in Sandbox environment — that is, you’re testing purchases — then send validation requests to https://sandbox.itunes.apple.com/verifyReceipt. The shared secret, as well as the payload and the response formats stay the same.
It’s important to note that you won’t be able to validate a receipt created in Sandbox environment on a Production server, and vice versa. That’s why in real-world systems, the best practice is to direct the first request to the Production server and redirect it to the Sandbox server in case the status key returned the 21007 error code. This behavior is a must during app review, since it allows Apple employees to test purchases while also allowing your app’s real users to make them.
Among other errors to note, there’s the 21004 error code that means we’re using the wrong secret. It’s important to keep track of, since it has an impact on both user experience and analytics accuracy. In the worst-case scenario, the app can be removed from the App Store if the user is never granted access to the premium features after they pay for these.
If the validation was successful (status=0), the response will contain the details of the user’s transactions.
Here’s the payment validation request response:
The response is quite cumbersome and was simplified in the App Store Server API new version, but the current implementation isn’t that hard to get hold of.
To find out whether the user has access to the app’s premium features, you need a way to determine their subscription status. There’s no dedicated request for retrieving subscription status in the current version of the API, so you’ll need to work with transaction history in any case.
The latest_receipt_info array, by default, contains all in-app purchase transactions of a particular user, except for consumable products that are completed on the app side. This way, you can retrieve the user’s entire purchase history. That’s quite useful for both analytics and determining the current subscription status.
It seems that transactions always come already sorted newest first. To be sure, though, I still recommend implementing your own by-date sorting for transactions.
The transaction payload:
To check the current subscription status, it’s enough to retrieve the latest transaction of the chain and look at the expires_date property. The exception to that would be the grace period, which we’ll discuss a bit later.
For analytics purposes, I recommend saving the following properties:
Apple has announced on WWDC 2021 that they’re planning to add an appAccountToken field to transaction info. It will contain the user’s identifier in your system. This identifier must be in the UUID format and is defined on the app side when the purchase gets initialized. If defined, it will be returned in all transactions of this chain (subscription renewals, billing issues, etc.), which means it’ll be easy for you to understand which user made the purchase.
You should also keep track of the subscription_group_identifier parameter. If the user previously had any transactions with active trials or intro offers, then they shouldn’t have access to these for the same group of subscriptions. This should be tracked on the server side.
The pending_renewal_info array stores the subscription renewal data. It allows to understand what is to happen to the subscription in the next billing period. For example, if you discovered the user opted out of auto renewal, you can suggest they switch to a different plan or present them with a promo offer. These events can be handily tracked with server notifications, which I’ll discuss soon.
Subscription renewal data:
If the user has no auto-renewable products, the latest_receipt_info and the pending_renewal_info keys won’t be returned. In this case, transactions can be found in receipt → in_app. The transaction format is similar to auto-renewable transactions but has no fields for expiry, renewals, offers, and other properties exclusive to auto-renewable transactions only.
It should be noted that receipt → in_app will arrive for auto-renewable transactions as well, but the better practice is to use latest_receipt_info, as the subscription data it contains will be the most up to date.
Some time ago you’d have to devise a complex system to track subscription status changes. For example, to understand whether or not the subscription was renewed, you’d have to send a subscription status request to Apple servers every hour starting 24 hours before the subscription expiry. Apple was adding more and more server notifications over time, and these now cover virtually all important events that have to do with subscriptions. That’s highly useful: once there are any changes on Apple’s side, you’ll get notified about it on your own server. That is, you’ll be notified about new purchases, subscription renewals, billing issues, etc. This allows you to collect much more accurate analytics, as well as makes managing the subscription status much easier.
You can enable server notifications in App Store Connect. Open the app’s page and go to General -> App information. Next, put the link into the URL for App Store Server Notifications field and save your changes.
The server notification format is similar to the payment validation response. The transaction details are stored in unified_receipt → latest_receipt_info. The password key stores the shared secret for your app, allowing you to verify the request’s authenticity. The notification_type key stores the event type. In my opinion, the most useful of these are:
Server validation can supercharge your analytics for the data you collect from your app. It also makes it harder for fraudsters to access your premium content, as well as allowing you to make your subscriptions cross-platform. At the same time, implementing server validation can take quite a lot of time, especially if you need highly accurate data. This would require taking lots of side cases into account: subscription upgrade, subscription crossgrade, trial periods, promo/intro offers, grace periods, refunds, family subscriptions, etc. You also have to know of and account for various nuances, e.g. Apple having a policy of lowering the commission from 30% to 15% for subscriptions that get regularly renewed for over a year.