Reminder: By Aug 31, 2025, all new apps and updates to existing apps must use Billing Library version 7 or newer. If you need more time to update your app, you can request an extension until Nov 1, 2025. Learn about Play Billing Library version deprecation.
با مجموعهها، منظم بمانید
ذخیره و طبقهبندی محتوا براساس اولویتهای شما.
محصولات یکبار خرید چرخه عمر ساده تری نسبت به محصولات اشتراکی دارند، اما هنوز چندین حالت و رویداد انتقالی وجود دارد که باطن شما باید بتواند به درستی از عهده آنها برآید.
شکل 1 وضعیت های چرخه حیات و رویدادهای انتقال برای خریدهای یکباره.
خرید یک بار محصول جدید
پس از تکمیل جریان صورت‌حساب توسط کاربر، برنامه شما می‌تواند اطلاعات خرید جدید را به یکی از روش‌های زیر ببیند:
Real-time developer notifications را تنظیم کنید و Get all notifications for subscriptions and one-time products را فعال کنید تا به‌روزرسانی‌های وضعیت خریدها را دریافت کنید.
برای دریافت خودکار به‌روزرسانی‌های خرید، رابط PurchasesUpdatedListener از BillingClient پیاده‌سازی کنید.
هنگامی که کاربری یک محصول یک بار مصرف را خریداری یا لغو می کند، Google Play یک پیام OneTimeProductNotification ارسال می کند. برای به‌روزرسانی وضعیت خرید باطن خود، از رمز خرید ارائه شده در شی OneTimeProductNotification برای فراخوانی روش purchases.productsv2.getproductpurchasev2 استفاده کنید. این روش آخرین وضعیت خرید و مصرف را با یک توکن خرید ارائه می دهد.
وقتی یک پیش‌سفارش انجام شد و وضعیت خرید آن به PURCHASED تغییر کرد، یک RTDN برای مشتری شما ارسال می‌شود. پس از دریافت RTDN، خرید پیش‌سفارش را همانطور که در فرآیند خرید یکبار محصول در باطن خود توضیح داده شده است، پردازش کنید.
شما باید RTDN های مربوط به تراکنش را در باطن امن خود مدیریت کنید.
انجام معاملات تکمیل شده
وقتی کاربر یک بار خرید محصول را تکمیل می‌کند، Google Play یک پیام OneTimeProductNotification با نوع ONE_TIME_PRODUCT_PURCHASED ارسال می‌کند. وقتی این RTDN را دریافت کردید، خرید را همانطور که در فرآیند خریدهای یکبار محصول در باطن خود توضیح داده شده است، پردازش کنید.
رسیدگی به تراکنش های لغو شده
وقتی خرید یکبار محصول لغو می‌شود، Google Play یک پیام OneTimeProductNotification با نوع ONE_TIME_PRODUCT_CANCELED می‌فرستد، اگر برای دریافت اعلان‌های برنامه‌نویس هم‌زمان پیکربندی کرده باشید. برای مثال، اگر کاربر پرداخت را در بازه زمانی لازم انجام ندهد، یا اگر خرید توسط توسعه‌دهنده یا درخواست مشتری لغو شود، ممکن است این اتفاق بیفتد. هنگامی که سرور بک‌اند شما این اعلان را دریافت کرد، با روش purchases.productsv2.getproductpurchasev2 تماس بگیرید تا آخرین وضعیت خرید را دریافت کنید، سپس باطن خود را بر اساس آن، از جمله حقوق کاربر، به‌روزرسانی کنید.
اگر یک بار خرید محصول در حالت Purchased بازپرداخت شود، با استفاده از API خریدهای باطل نیز مطلع خواهید شد.
خرید یک بار محصول را در باطن خود پردازش کنید
خواه خرید جدیدی را با استفاده از ONE_TIME_PRODUCT_PURCHASED RTDN شناسایی کرده باشید یا از طریق PurchasesUpdatedListener در داخل برنامه مطلع شده باشید یا به صورت دستی خریدها را در روش onResume() برنامه خود واکشی کنید، باید خرید جدید را پردازش کنید. توصیه می کنیم برای امنیت بهتر، پردازش خرید را در باطن خود انجام دهید.
این مراحل را برای پردازش یک خرید یک بار جدید دنبال کنید:
برای دریافت آخرین وضعیت خرید یک بار محصول، از نقطه پایانی purchases.productsv2.getproductpurchasev2 پرس و جو کنید. برای فراخوانی این روش برای خرید، به purchaseToken مربوطه از برنامه خود یا از ONE_TIME_PRODUCT_PURCHASED RTDN نیاز دارید.
با getPurchaseState() تماس بگیرید و مطمئن شوید که وضعیت خرید PURCHASED است.
به کاربر اجازه دسترسی به محتوا را بدهید. حساب کاربری مرتبط با خرید را می‌توان با فیلد obfuscatedExternalAccountId از purchases.productsv2.getproductpurchasev2 شناسایی کرد، در صورتی که در هنگام خرید با استفاده setObfuscatedAccountId() تنظیم شده باشد.
در صورت مصرفی بودن کالا، با فراخوانی روش purchases.products.consume کالا را به عنوان مصرف شده علامت بزنید تا کاربر پس از مصرف مجدد کالا را خریداری کند. این روش خرید را نیز تایید می کند.
همچنین روش‌های تأیید خرید و مصرف در «کتابخانه صورت‌حساب Play» موجود است که به شما امکان می‌دهد خریدها را از برنامه خود پردازش کنید، اما توصیه می‌کنیم اگر برای اجرای ایمن‌تر، پردازش را در پشتیبان خود انجام دهید.
محتوا و نمونه کدها در این صفحه مشمول پروانههای توصیفشده در پروانه محتوا هستند. جاوا و OpenJDK علامتهای تجاری یا علامتهای تجاری ثبتشده Oracle و/یا وابستههای آن هستند.
تاریخ آخرین به‌روزرسانی 2025-07-29 بهوقت ساعت هماهنگ جهانی.
[[["درک آسان","easyToUnderstand","thumb-up"],["مشکلم را برطرف کرد","solvedMyProblem","thumb-up"],["غیره","otherUp","thumb-up"]],[["اطلاعاتی که نیاز دارم وجود ندارد","missingTheInformationINeed","thumb-down"],["بیشازحد پیچیده/ مراحل بسیار زیاد","tooComplicatedTooManySteps","thumb-down"],["قدیمی","outOfDate","thumb-down"],["مشکل ترجمه","translationIssue","thumb-down"],["مشکل کد / نمونهها","samplesCodeIssue","thumb-down"],["غیره","otherDown","thumb-down"]],["تاریخ آخرین به‌روزرسانی 2025-07-29 بهوقت ساعت هماهنگ جهانی."],[],[],null,["# One-time purchase lifecycle\n\nOne-time purchase products have a simpler lifecycle than subscription products,\nbut there are still several states and transition events that your backend needs\nto be able to handle properly.\n**Figure 1** Lifecycle states and transition events for one-time purchases.\n\nNew one-time product purchases\n------------------------------\n\nAfter the user completes the billing flow, your app can see information about\nthe new purchase in one of the following ways:\n\n- Setup [`Real-time developer notifications`](/google/play/billing/getting-ready#enable-rtdn \"Real-time developer notifications\") and enable `Get all\n notifications for subscriptions and one-time products` to receive updates on the status of purchases.\n- Implement the [`PurchasesUpdatedListener`](/reference/com/android/billingclient/api/PurchasesUpdatedListener) interface from `BillingClient` to automatically receive purchase updates.\n- Call the [`BillingClient.queryPurchasesAsync()`](/reference/com/android/billingclient/api/BillingClient#queryPurchasesAsync(com.android.billingclient.api.QueryPurchasesParams,%20com.android.billingclient.api.PurchasesResponseListener)) method.\n\nAfter receiving the new purchase, use the\n[`getPurchaseState`](/reference/com/android/billingclient/api/Purchase#getPurchaseState()) method or\n[`purchases.productsv2.getproductpurchasev2 in Play Developer API`](https://developers.google.com/android-publisher/api-ref/rest/v3/purchases.productsv2/getproductpurchasev2 \"purchases.productsv2.getproductpurchasev2 in Play Developer API\")\n\nto determine the payment state of the new purchase.\n\n### Real-time developer notifications\n\n| **Note:** One-time purchase real-time developer notifications are only published if you have [opted into them while configuring real-time developer\n| notifications](/google/play/billing/getting-ready#enable-rtdn \"Real-time developer notifications\").\n\nWhen a user purchases or cancels the purchase of a one-time product, Google Play\nsends a [`OneTimeProductNotification`](/google/play/billing/rtdn-reference#one-time) message.\nTo update your backend purchase state, use the purchase token provided in the\n`OneTimeProductNotification` object to call the\n[`purchases.productsv2.getproductpurchasev2`](https://developers.google.com/android-publisher/api-ref/rest/v3/purchases.productsv2)\nmethod. This method provides the latest purchase and consumption status given a\npurchase token.\n\nWhen a pre-order is fulfilled and its purchase state changes to PURCHASED, an\nRTDN is sent to your client. After receiving the RTDN, process the pre-order\npurchase as described in [Process one-time product purchases in your\nbackend](#process).\n\nYou should handle transaction-related RTDNs in your secure backend.\n\n### Handle completed transactions\n\nWhen a user completes a one-time product purchase, Google Play sends a\n`OneTimeProductNotification` message with the type `ONE_TIME_PRODUCT_PURCHASED`.\nWhen you receive this RTDN, process the purchase as described in [Process\none-time product purchases in your backend](#process).\n\n### Handle canceled transactions\n\nWhen a one-time product purchase is canceled, Google Play sends a\n`OneTimeProductNotification` message with the type `ONE_TIME_PRODUCT_CANCELED`\nif you have configured to receive real-time developer notifications. For\nexample, this can occur if the user doesn't complete payment within the required\ntimeframe, or if the purchase is revoked by the developer or by customer\nrequest. When your backend server receives this notification, call the\n[`purchases.productsv2.getproductpurchasev2`](https://developers.google.com/android-publisher/api-ref/rest/v3/purchases.productsv2)\nmethod to get the latest purchase state, then update your backend accordingly,\nincluding user entitlements.\n\nIf a one-time product purchase in `Purchased` state gets refunded, you will also\nbe made aware using the [Voided Purchases API](https://developers.google.com/android-publisher/voided-purchases).\n\nProcess one-time product purchases in your backend\n--------------------------------------------------\n\nWhether you have detected a new purchase using a `ONE_TIME_PRODUCT_PURCHASED`\nRTDN\nor you have been made aware in-app through\n[`PurchasesUpdatedListener`](/reference/com/android/billingclient/api/PurchasesUpdatedListener) or [manually fetching\npurchases](/google/play/billing/integrate#fetch) in your app's `onResume()` method, you must process\nthe new purchase. We recommend that you handle purchase processing in your\nbackend for better security.\n\nFollow these steps to process a new one-time purchase:\n\n1. Query the [`purchases.productsv2.getproductpurchasev2`](https://developers.google.com/android-publisher/api-ref/rest/v3/purchases.productsv2) endpoint to obtain the latest one-time product purchase status. To call this method for a purchase, you need the corresponding `purchaseToken` either from your app or from the `ONE_TIME_PRODUCT_PURCHASED` RTDN.\n2. Call [`getPurchaseState()`](/reference/com/android/billingclient/api/Purchase#getPurchaseState()) and make sure that the purchase state is `PURCHASED`.\n3. [Verify the purchase](/google/play/billing/security#verify).\n4. Give the user access to the content. The user account associated with the purchase can be identified with the [`obfuscatedExternalAccountId`](https://developers.google.com/android-publisher/api-ref/rest/v3/purchases.productsv2#ProductPurchaseV2) field from `purchases.productsv2.getproductpurchasev2`, if one was set using [`setObfuscatedAccountId()`](/reference/com/android/billingclient/api/BillingFlowParams.Builder#setObfuscatedAccountId(java.lang.String)) when the purchase was made.\n 1. For non-consumable product purchases, acknowledge delivery of the content by calling the [`purchases.products.acknowledge`](https://developers.google.com/android-publisher/api-ref/rest/v3/purchases.products/acknowledge) method. Make sure that the purchase hasn't been previously acknowledged by checking the [`acknowledgementState`](https://developers.google.com/android-publisher/api-ref/rest/v3/purchases.productsv2) field.\n 2. If the product is consumable, mark the item as consumed by calling the [`purchases.products.consume`](https://developers.google.com/android-publisher/api-ref/rest/v3/purchases.products/consume) method so that the user can buy the item again after they have consumed it. This method also acknowledges the purchase.\n\n| **Note:** If you don't acknowledge a purchase within three days, the user automatically receives a refund, and Google Play revokes the purchase.\n\nThere are also purchase acknowledgement and consume methods available in the\nPlay Billing Library that allow you to process purchases from you app, but we\nrecommend that you handle processing in your backend if you have one for a more\nsecure implementation."]]
