Verifying receipts for in-app purchases is crucial for maintaining the integrity of transactions within your iOS app. This process ensures that the purchases made by users are legitimate, protecting your app from potential fraud. In this article, we'll cover the essential steps for verifying App Store receipts. We'll explore the process of receipt validation, best practices for secure implementation, and troubleshooting common issues.
Update: Since this guide was published, Apple announced StoreKit 2 which adds new capabilities and APIs such as Signed Transactions. StoreKit 1-style receipts and APIs will continue to be available, so we hope this article will continue to be a useful reference. If you're interested in learning more about StoreKit 2, head over here. Also, the new APIs are a major change and another and a great time to build atop Nami which abstracts away these underlying implementation details.
An App Store receipt is a digital proof of purchase generated by Apple for any transaction made within the App Store, including app purchases, in-app purchases, and subscriptions. This receipt is a critical component in ensuring the integrity and authenticity of transactions, as it contains detailed information about the purchase, such as the product ID, transaction ID, purchase date, and subscription details if applicable.
The receipt is stored on the user's device and can be retrieved and verified to confirm that the user has made a legitimate purchase. This verification process typically involves sending the receipt data to Apple's servers, where it is checked for validity and authenticity. By verifying receipts, app developers can protect their apps from fraudulent transactions and unauthorized access to premium content or features.
The receipt data provided by StoreKit is a Base64-encoded. To receive a decoded version, described in detail in this article, you need to transmit the encoded receipt to Apple’s verifyReceipt endpoint. To fully understand verifyReceipt, see this article where we code a simple Python script step-by-step that demonstrates how to send an encoded receipt and receive the decoded receipt.
Why is all of this necessary? The two most important reasons:
The mechanics of receipt validation are relatively straightforward as demonstrated in the Python script referenced early.
However, grokking the decoded receipt itself is painful. It’s not the most elegant data structure in the world, and there are all sorts of esoteric details and nuances. Our goal with this article is build upon and go beyond Apple’s documentation to help you better understand the decoded receipt and avoid common (and more exotic) pitfalls.
The first step is to obtain the receipt data from the app. This data can be retrieved using the SKReceiptRefreshRequest
class or from the receipt URL located in the app’s bundle.
if let appStoreReceiptURL = Bundle.main.appStoreReceiptURL,
FileManager.default.fileExists(atPath: appStoreReceiptURL.path) {
do {
let receiptData = try Data(contentsOf: appStoreReceiptURL, options: .alwaysMapped)
let receiptString = receiptData.base64EncodedString(options: [])
// Send receiptString to your server for verification
} catch {
print("Couldn't read receipt data with error: " + error.localizedDescription)
}
}
Once you have the receipt data, you need to send it to your server. This step is crucial because the verification process should be performed on a secure server to prevent tampering. Your server will then forward the receipt data to Apple's verification server.
Your server should send a request to Apple’s verification server at the following URL:
https://buy.itunes.apple.com/verifyReceipt
https://sandbox.itunes.apple.com/verifyReceipt
The request should include the receipt data and your app’s shared secret for subscriptions. Here's an example using Swift's URLSession
to send the receipt data:
Apple’s response will include the status of the receipt and, if valid, the receipt’s details. Your server should parse this response and take appropriate action, such as granting the purchased content or renewing a subscription.
let requestDictionary: [String: Any] = ["receipt-data": receiptString, "password": "your_shared_secret"]
guard JSONSerialization.isValidJSONObject(requestDictionary) else { return }
do {
let requestData = try JSONSerialization.data(withJSONObject: requestDictionary, options: [])
let storeURL = URL(string: "https://buy.itunes.apple.com/verifyReceipt")!
var request = URLRequest(url: storeURL)
request.httpMethod = "POST"
request.httpBody = requestData
request.setValue("application/json", forHTTPHeaderField: "Content-Type")
let task = URLSession.shared.dataTask(with: request) { data, response, error in
guard error == nil, let data = data else {
print("Error verifying receipt: \(error?.localizedDescription ?? "No data")")
return
}
// Process the verification response
}
task.resume()
} catch {
print("JSON serialization failed: \(error.localizedDescription)")
}
The responseBody JSON payload can be daunting (example), especially if the receipt belongs to an end-user with a lengthy past purchase history.
It turns out, that there are somewhere between 3 and 7 top-level keys in the verifyReceipt responseBody JSON data structure. Here are the keys:
Some of the top-level keys are present only in certain circumstances. Here’s a summary of each top-level key, what it is, and when you should expect to see it in the responseBody:
Let’s dig into each of these top-level elements in detail, starting with response metadata keys: status, is-retryable, environment.
Upon received a response from verifyReceipt, the first thing you should do is check that status key. If the value is 0, the receipt is valid. Otherwise, an error occurred and you will need to interpret the status code to know what to do next.
ProTip: Notice that the resolution to a number of the status codes is to retry later. It’s important that your receipt validation service is robust enough to handle a wide variety of scenarios including: network timeouts, HTTP status codes such as 503, and also status codes embedded in the return payload of a HTTP 200 response. In some of these cases, you may want to to support retry logic to try again immediately. If you still failed to validate the receipt, you may want to add them to job queue for a future processing attempt.
If the Apple status value is within the range of 21100-21199, the is-retryable key should be present in the response payload. Apple’s documentation says the type is boolean, but the provided values are 0 and 1, not the proper JSON boolean values of true and false.
The environment value tells you which Apple environment the receipt was generated from.
Now let’s look beyond the metadata into the primary keys containing the responseBody’s substance: receipt, latest_receipt_info, pending_renewal_info.
The value of receipt, a key within the decoded receipt response, is a JSON object containing the decoded receipt data.
This key always exists, whether a user has made an in-app purchase or not.
In fact, if you follow the best practice and send receipt data from your app to a server you will end up storing and decoding (via receipt validation) many receipts, containing this receipt key with certain metadata even if there have be no in-app purchases.
Consider the history of the App Store. It was built atop the foundations of the iTunes Music Store. On iTunes, an email receipt was sent to the user whether the song or album cost money or was free. This lineage carried on to the App Store, where in the early days there were just two types of apps: paid and free.
Once in-app purchases were added, additional context was introduced to this data structure. In fact, it contains the full context you need to understand the purchase.
Now, with the advent of subscriptions things have gotten a bit more complicated. Some context about the subscription in-app purchase exists in this data structure, but some does not. For auto-renewable subscriptions, you will find additional context inside the latest_receipt_info and pending_renewal_info top level keys which we go into more detail later in this article.
Jump to an element-by-element breakdown of the receipt data structure.
The latest Base64 encoded app receipt. This field is only returned if the app receipts contains an auto-renewable subscriptions.
An array of JSON objects representing in-app purchase transactions for auto-renewable subscriptions. This field is only returned if the app receipts contains an auto-renewable subscriptions.
ProTip: If your verifyReceipt request includes the field exclude-old-transactions set to true, only the latest auto-renewable subscription transaction will be included in this field in the response.
Jump to an element-by-element breakdown of the latest_receipt_info data structure.
An array of JSON objects representing open (pending) or failed auto-renewable subscription renewals as identified by the product_id. This field is only returned for app receipts that contain auto-renewable subscriptions.
Jump to an element-by-element breakdown of the pending_renewal_info data structure.
Let’s take a look at all of the possible elements you may encounter in the receipt JSON object.
A unique 64-bit long integer generated by App Store Connect. This is used by the App Store to unique identify the app associated with the receipt.
In production, expect a unique identifier. In sandbox, this field will be populated with a 0.
The current version of the app installed on the user’s device at the time of the receipt’s receipt_creation_date_ms. The version number is based upon the CFBundleVersion (iOS) or CFBundleShortVersionString (macOS) from the Info.plist.
In the sandbox, the value is always “1.0”.
The bundle identifier for the app to which the receipt belongs. You provide this string on App Store Connect and it corresponds to the value of CFBundleIdentifier in the Info.plist file of the app.
A unique identifier for the app download transaction.
While not well documented by Apple, this unique value appears to be tied to the download transaction represented by original_application_version and original_purchase_date.
In production, expect a unique identifier. In sandbox, this field has been observed to be populated with a 0.
The time the receipt expires for apps purchased through the Volume Purchase Program (VPP).
See expiration_date
See expiration_date
An array containing in-app purchase receipt fields for all in-app purchase transactions.
The original version of the app installed on the user’s device. For example, if the current app version is 2.0 but the user originally had version 1.8 installed, this value would be “1.8”. For the current version installed, see application_version.
The version number is based upon the CFBundleVersion (iOS) or CFBundleShortVersionString (macOS) from the Info.plist.
In the sandbox, the value is always “1.0”.
The time of the original app purchase.
The time the user ordered the app available for pre-order. This field is only present if the user pre-orders the app.
See preorder_date
See preorder_date
The time the App Store generated the receipt.
The type of receipt generated. The value corresponds to the environment in which the App Store or VPP purchase was made.
The time the request to the verifyReceipt endpoint was processed and the response was generated.
See request_date
See request_date
An arbitrary number that identifies a revision of your app. In the sandbox, this key's value is “0”.
An array of JSON object(s) found at latest_receipt_info contains in-app purchase transactions for auto-renewable subscriptions. This field is only returned if the app receipts contains an auto-renewable subscriptions.
ProTip: If your verifyReceipt request includes the field exclude-old-transactions set to true, only the latest auto-renewable subscription transaction will be included in this field in the response.
The time of the subscription was canceled. This can happen for one of the following reasons:
The reason for a refunded transaction. When a customer cancels a transaction, the App Store gives them a refund and provides a value for this key.
The time a subscription expires or when it will renew.
See expires_date
See expires_date
Indicates whether the user is the purchaser of the product, or is a family member with access to the product through Family Sharing.
Indicates whether or not an auto-renewable subscription is in the introductory price period.
An indicator of whether a subscription is in the free trial period.
Indicates a subscription has been canceled due to an upgrade. Only present for upgrade transactions.
Check cancellation_date to determine when the cancellation occurred.
The reference name of a subscription offer that you configured in App Store Connect. Present when a customer redeemed a subscription offer code.
The time of the original auto-renewable subscription purchase.
The transaction identifier of the original purchase.
The unique identifier for the product purchased as configured for that product in App Store Connect.
The identifier of the subscription offer redeemed by the user.
The time the App Store charged the user’s account for a subscription purchase or renewal.
See purchase_date
See purchase_date
The number of consumable products purchased. Included but meaningless in the latest_receipt_info data structure, which is for auto-renewable subscriptions only. Likely an artifact from Apple internally sharing data structures between responseBody.receipt.in_app and responseBody.latest_receipt_info.
The identifier of the subscription group to which the subscription belongs.
A unique identifier for purchase events across devices, including subscription-renewal events. This value is the primary key for identifying subscription purchases.
A unique identifier for a transaction such as a purchase, restore, or renewal.
If transaction_id and original_transaction_id match, the transaction is a purchase. Otherwise, the transaction is a restore or renewal.
The array of JSON object(s) found at pending_renewal_info for open (pending) or failed auto-renewable subscription renewals includes a number of possible fields. Let’s take a look.
The product identifier for the customer’s pending subscription renewal, if the user has downgraded or crossgraded to a subscription of a different duration for the subsequent subscription period.
The renewal status for the auto-renewable subscription.
If this value is “0”, the customer is showing a likelihood to churn out of the subscription at the end of the current renewal period. A best practice is to present the user with an attractive upgrade or downgrade offer in the same subscription group.
The reason a subscription expired.
If this value is “1”, you may want to offer the user an alternative subscription or a “winback” offer.
If the value is “2”, you may want to prompt them to subscribe to the same product again since they churned involuntarily.
The time at which the grace period for subscription renewals expires.
Indicates whether the user’s auto-renewable subscription is in the billing retry period.
If the value is “1”, consider prompting the user to update their billing information.
The reference name of a subscription offer that you configured in App Store Connect. Present when a customer redeemed a subscription offer code.
The transaction identifier of the original purchase.
The price consent status for a subscription price increase.
The unique identifier for the product purchased as configured for that product in App Store Connect.
Throughout the Apple decoded receipt payload, you will find three different date formats expressed whenever a date is provided:
What is ISO 8601-like? Apple documentation refers to “a date-time format similar to the ISO 8601” and “an RFC 3339 date”. In reality it’s not strictly either. The timezone part of the string make it difficult to convert these string-based date formats into date time object using common libraries which except ISO 8601 or other common standards.
Why Apple uses this specific non-standard format is probably an esoteric story related to the origins of NeXT or WebObjects.
To dive deeper into these three formats, let’s take a look at the date found at responseBody.receipt.receipt_creation_date. This is date the receipt was created expressed in the ISO 8601-like format relative to Greenwich Meantime (GMT).
Each base date key has two modifiers: _pst and _ms with the ISO 8601-like PST and Milliseconds since Unix epoch representations.
responseBody.receipt.receipt_creation_date_pst is an ISO 8601-like date relative to Pacific Standard Time (PST). Please note, even though the timezone modifier is provided in the format America/Los_Angeles instead of a UTC offset, the date provided is indeed Pacific Standard Time. Your code needs to be careful during Pacific Daylight Time (PDT), since this value will still be a Pacific Standard Time date.
responseBody.receipt.receipt_creation_date_ms is when the receipt was created in the number of milliseconds since the Unix epoch time. The _ms modifier for all date fields in an Apple decoded receipt is the far easiest to work with. Most modern languages can convert this to a native date time object out of the box or with commonly used libraries.
VPP stands for Volume Purchase Program. It's essentially how Apple provides an App Store-like experience for educational institutions or businesses to acquire and deploy apps at scale. As it relates to this article, some receipt fields only show up or contain values for transactions that occur on the VPP store.
As this guide illustrates, understanding the decoded receipt is complicated. So is the code necessary to store, validate, and make meaning out of the decoded receipt so you can properly manage your paid customer base.
The esoteric and sometimes arcane receipt response is the result of years of change and new features bolted on to the App Store year after year. It’s incredibly complex to write rock solid code to manage receipts and leverage all the App Store ecosystem has to offer related to in-app purchase and subscription monetization.
That’s where Nami can help. We’ve built a complete service to help you sell in-app purchases or subscriptions. In addition to a variety of features, we handle all client and server side details involving the receipt. In fact, you also don't have to write a single line of StoreKit 1 or StoreKit 2 code.
Our code has encountered many of the hard to test edge cases you’ll see encounter over time if you do-it-yourself. Our service has extensive test coverage and operates at scale.
This means you can stay focused on building your app experience. If you’re interested in learning more, we’d love to chat.
No-code solutions are revolutionizing the way businesses approach software development. For a VP of Engineering, adopting a no-code solution can bring numerous benefits, including faster development time, increased collaboration, cost savings, and increased flexibility.
As the world continues to rapidly digitize, businesses are relying on technology more than ever to operate efficiently and effectively. One crucial aspect of technology is software development, which has traditionally required extensive knowledge of coding and development processes. However, with the rise of no-code solutions, companies are able to create and maintain software without needing extensive technical knowledge.
A VP of Engineering plays a crucial role in the software development process, overseeing the technical team and ensuring that the software they produce is high-quality and meets business objectives. Here are some reasons why a VP of Engineering may want to adopt a no-code solution:
No-code solutions are a powerful tool for companies looking to rapidly develop high-quality software while saving time and money. For a VP of Engineering, adopting a no-code solution can improve collaboration, reduce development time, increase flexibility, and ultimately help businesses stay competitive in an ever-changing digital landscape.
If you're a VP of Engineering responsible for a subscription-based mobile application, consider Nami's no-code paywall solution. Nami's platform enables you to monetize your content and provide personalized experiences for your users, all without requiring extensive coding knowledge. With Nami, engineering teams can quickly implement and customize paywalls, optimize the purchase experience, and track revenue metrics through a user-friendly dashboard. Plus, our platform is highly flexible, allowing you to adapt and iterate quickly as your business needs evolve. Sign up for a free trial today and experience why Nami's no-code paywall solution is loved by engineering teams.
When does Google Play payout to developers? Here's all the details on what to expect from the Play Store developer payout schedule.
When does Google Play payout to developers? Play Store developer payout occurs approximately the same time each month. Generally, it happens around the 15th of each month for the previous month’s sales.
Here’s what to expect for Google merchant payments (which include Google Play developers):
Payouts are for net proceeds less Google’s Play Store commission.
Most payouts are conducted via Electronic Funds Transfer (EFT). Funds can take 2-3 business days to arrive in your account.
In some regions, payouts are via wire transfer. Funds takes take 5-7 business days to arrive in this situation.
👉Read more: Apple Fiscal Calendar Developer Payout Schedule
Here is an online Google Play store developer payout calendar resource you can bookmark that is updated for the current fiscal year. It’s also available in an downloadable PDF format.
if(window.strchfSettings === undefined) window.strchfSettings = {};
window.strchfSettings.stats = {url: "https://nami.storychief.io/en/play-store-developer-payout-schedule?id=785881016&type=26",title: "Play Store Developer Payout Schedule",id: "51b60849-ff21-4408-b48f-9543da3cae59"};
(function(d, s, id) {
var js, sjs = d.getElementsByTagName(s)[0];
if (d.getElementById(id)) {window.strchf.update(); return;}
js = d.createElement(s); js.id = id;
js.src = "https://d37oebn0w9ir6a.cloudfront.net/scripts/v0/strchf.js";
js.async = true;
sjs.parentNode.insertBefore(js, sjs);
}(document, 'script', 'storychief-jssdk'))
👉 Accrued Revenue
Nami co-founder & CEO joined The App Growth Show to discuss turbocharging app subscription revenue.
Nami co-founder & CEO joined Jennifer Sansone, host of the The App Growth Show to talk about turbocharging in-app subscription revenue.
Here is the episode synopsis:
Hey, App Growth Community! Welcome back to the App Growth Show, where we host mobile experts to provide valuable and actionable insights on how you can grow your app. No matter where you are in your app growth journey, we are able to help you achieve your mobile growth goals. Today, we are so excited to be joined by Dan Burcaw, CEO of Nami. Nami is a unique product that lets app marketers like you to design and implement the perfect subscription model for your app and create happy subscribers. They are the easiest way to implement one solution and sell subscriptions everywhere you need to. Whether a mobile app, on your website, or even from a connected device, Nami has you covered with one unified view of your subscribers regardless of where the billing takes place.
Listen on Apple Podcasts or visit the episode page.
Announcing a new Subscriber Experience Cloud release focusing on the Accessibility & Localization needs of Enterprise Mobile App Publishers.
Nami® (PRWEB), a leading provider of comprehensive mobile subscription capabilities for enterprise mobile app publishers has released the latest version of their carrier-grade subscriber experience cloud platform featuring accessibility and localization features.
“The shift to subscriptions as a fundamental mobile app monetization strategy is a global phenomenon and to do it right and make subscribers happy, apps need the ability to speak to their users where they are and make sure everyone is able to benefit,” explains Dan Burcaw, CEO and Co-Founder of the company.
Localization is the ability to present key components like the Paywall Purchase Experience in the user’s choice of languages. The Nami platform’s Paywall Builder feature now supports all the languages available on the user’s mobile device making it easier and better for publishers to adopt the languages their subscribers use natively.
Accessibility is the way software adapts its user interface to the needs of users with different requirements, such as those who may need assistance with visual cues or input. Paywalls built with the Nami platform can now be used more easily by people of all abilities.
Both Nami’s Localization and Accessibility features are built on top of the enterprise scale and carrier-grade security capabilities that give businesses of all sizes the stability, reliability and confidence to ship their products globally.
Nami ML is an early-stage business that has built a comprehensive Mobile Subscriber Experience platform focused on creating Happy Subscribers that lets mobile app publishers focus on the unique features of their apps while managing the end-to-end subscription lifecycle from first use to customer support and renewal. To try the platform sign up for free at https://namiml.com
It’s earnings season on Wall Street and for companies in the App Economy. It's a tale of two monetization strategies plus pressure for further change.
It’s earnings season on Wall Street and for companies in the App Economy. It's a tale of two monetization strategies plus pressure creating additional uncertainty. Here are three areas to watch as companies report Q3 2021 results:
Q3 2021 is the first full quarter impacted by Apple’s iOS privacy changes. App Tracking Transparency (ATT) rolled out with iOS 14.5 on April 26, 2021. ATT shifts the iOS ID for Advertisers (IDFA) from Opt Out to Opt In.
IDFA is used to measure a user’s interaction with advertisements. IDFA is also widely used to tie mobile users to customer profiles. This allows advertisers to follow users with ads across web and mobile.
The companies most predicted to feel pressure from the ATT rollout include Facebook (NASDAQ: FB) and Snap (NYSE: SNAP). Both are part of the App Economy due to their heavy dependence on mobile advertising revenue.
While Facebook saw little impact in Q2 resulting from ATT, the company felt the pain in Q3. Facebook missed revenue targets expected by analysts which Facebook CEO Mark Zuckerberg attributed to ATT:
“As expected, we did experience revenue headwinds this quarter, including from Apple's changes”
Facebook is preparing Wall Street for a bumpy Q4 in part due to ATT:
"Our outlook reflects the significant uncertainty we face in the fourth quarter in light of continued headwinds from Apple's iOS 14 changes, and macroeconomic and COVID-related factors."
Snap also missed Q3 revenue expectations. CEO Evan Spiegal cited iOS ad tracking as the driving force:
“Our advertising business was disrupted by changes to iOS ad tracking that were broadly rolled out by Apple in June and July.”
Following the earnings report, Snap’s price per share dropped approximately 25% and hasn’t recovered after two full days of trading.
Oppenheimer analyst Jason Helfstein expects much of the digital advertising industry to face IDFA-related headwinds. Both Facebook and Snap are promising technology investments to mitigate the impact.
It remains to be seen how well companies will adapt and how aggressively advertising-centric companies look to subscriptions as a means to accelerate a return to growth.
Speaking of subscriptions, Google just announced a reduction in Play Store subscription commissions. The earnings impact for App Economy companies will take time. The change won’t take effect until January 1, 2022.
However, the market is already responding positively to the news. Shares of DuoLingo (NASDAQ: DUOL), the popular language learning app, are up ~15%:
DuoLingo isn’t alone. Shares of Bumble (NASDAQ: BMBL), the dating app, are up more than ~5%:
For subscription-based apps, the reduced commission is a feel good moment that’s likely to release some of the pressure that has been building. It’s likely temporary but will cause app publishers to pile on pressure for Apple to follow suit.
Regardless of the commission, App Economy companies will still have too much churn. These companies will need strong retention programs and they need to elevate their subscriber experience.
Apple’s advertising privacy changes put more control in the hands of the end user. In the process, they have disrupted digital advertising. At least for a while. Most users if asked would surely agree that this is a positive change. So while Apple is receiving scrutiny, it’s by the parties most dependent on advertising business models.
On the other side of the monetization coin, app publishers selling directly to consumers have long been fighting for more favorable business terms and fewer restrictions. To them, this isn't about the end user at all. Rather, about building a sustainable business.
To Apple, some of the asks such as side-loading apps, alternative app stores, or even different payment mechanisms would harm iPhone’s security and privacy models.
In the US, developers went to court and received concessions via a settlement with Apple. In Japan, the Fair Trade Commission closed an investigation into the App Store after Apple offered a different concession. Of course, the already famous Epic v. Apple lawsuit resulted in a court order followed by an appeal by Apple.
Jurisdictions around the world are examining Apple and Google for potential anti-competitive behavior. While it is not clear how this will turn out, there is no doubt uncertainty lies ahead in the App Economy.