RVS for Consumables and Entitlements
The Receipt Verification Service (RVS) for the Appstore Billing Compatibility SDK lets you validate purchases made by your app's users. For an overview of RVS, see Receipt Verification Service Overview.
RVS for the Appstore Billing Compatibility SDK has two REST APIs, one for verifying consumable and entitlement purchases, and another for verifying subscription purchases. This page describes the requests and responses of the REST API used for consumable and entitlement purchases.
- purchases.products.get API request
- purchases.products.get API response
- Response codes and error messages
- Response fields for successful transactions
- Unsupported fields for purchases.products.get API
- Related topics
purchases.products.get API request
Use the purchases.products.get API to verify the receipts of consumable or entitlement purchases made through the Appstore Billing Compatibility SDK. Upon successful purchase of an item, the Appstore Billing Compatibility SDK returns a Purchase
object. To perform a server-side validation of the purchase, extract the purchase token from this object and pass it, along with the app package name, the product ID (the SKU value you used to create the in-app item), and your shared secret to the RVS server. For security, when you make a request from your server, you must pass a shared secret to confirm your identity.
The request uses the following format:
https://appstore-sdk.amazon.com/version/{operation-version-number}/get/developer/{shared-secret}/applications/{package-name}/purchases/products/{product-id}/tokens/{token}
The curly brackets contain placeholders for the request parameters. In your request, replace the placeholders with the values from the transaction you want to verify. The following table lists descriptions of the request parameters.
Request parameter | Description |
---|---|
operation-version-number | Version number of the purchases.products.get operation. This version number is independent of the Appstore Billing Compatibility SDK version number. The current purchases.products.get version number is "1.0". |
shared-secret | Shared secret used to identify the developer issuing the request. Your shared secret can be found on the Shared Key page in the Developer Console: https://developer.amazon.com/sdk/shared-key.html. |
package-name | The package name of the application in which the in-app product was sold. For example, 'com.amazon.sample.iap.consumable'. You can get the package name from your app by calling getApplicationContext().getPackageName() or you can find it in the AndroidManifest.xml file. |
product-id | The in-app product SKU that you created for your app in the Developer Console. For example 'iapsamplev2.gold_medal'. For a subscription product, use the term SKU. You can fetch the product ID from the Purchase object using the Purchase.getSkus() .get(0) method. |
token | Unique ID for the purchase obtained from the Purchase object's getPurchaseToken() method. |
purchases.products.get API response
The purchases.products.get API provides a RESTful JSON API interface. As a best practice, use a JSON parser class, such as OkHttp or Apache HttpClient, for reading the JSON responses from the RVS server.
After you make a request to the RVS server to verify a transaction, the RVS server returns a response code indicating if the request was successful. If successful, the returned JSON response includes information about the transaction.
The following example shows a successful response:
{
"cancelDate": null,
"cancelReason": null,
"kind": "androidpublisher#productPurchase",
"parentProductId": null,
"productId": "com.amazon.iapsamplev2.expansion_set_1",
"productType": "ENTITLED",
"purchaseState": 0,
"purchaseTimeMillis": "1399070753509",
"purchaseToken": "mINy5VRd1FqjVOz-WBtTqw9FBGWhnuVx07kzTBMR600=:2:11",
"purchaseType": null,
"quantity": 1,
"testTransaction": false
}
Response codes and error messages
The Receipt Verification Service responds with one of the following codes, which indicate the result of the validation check.
HTTP response code | Description |
---|---|
200 | The purchase is valid. |
400 | The purchase token or product ID is invalid. |
401 | The developer secret is invalid or doesn't match the given purchase token. |
404 | The package name is invalid or doesn't match the given purchase token. |
410 | The transaction represented by this receiptId is no longer valid. Treat it as a canceled receipt. |
429 | The request was throttled. Reduce your calling rate and retry after some time. |
500 | There was an Internal Server Error. |
Response fields for successful transactions
The following table describes the fields included in a purchases.products.get response for a successful transaction. Some fields have the same name and data type as Google's purchases.products.get API. Those fields are listed under Fields that match Google's purchases.products.get API. Fields listed under Additional fields are different from Google APIs and present purchase details provided by the Amazon Appstore.
Field | Data type | Description |
---|---|---|
Fields that match Google's purchases.products.get API | ||
kind |
String | Represents a ProductPurchase object in the androidpublisher service. |
purchaseTimeMillis |
String | The time the product was purchased, in milliseconds since the epoch (Jan 1, 1970). |
purchaseState |
Integer | The purchase state of the order. Possible values:0 - Purchased1 - Canceled |
purchaseType |
Integer | The type of purchase of the in-app product. This field is set only if this purchase wasn't made using the standard in-app purchase flow. Possible value:0 - Test (purchased from a license testing account). |
purchaseToken |
String | Unique identifier for the purchase. |
productId |
String | The SKU that you defined for this item in your app. |
quantity |
Integer | Quantity purchased. Always null or 1. |
Additional fields | ||
parentProductId |
String | Null. Reserved for future use. |
productType |
String | Type of product purchased. Valid product types are CONSUMABLE and ENTITLED . |
cancelDate |
Long integer | The date the purchase was canceled. Time is in milliseconds. In a valid receipt, the cancel date contains the null value. If the cancel date field is not null, it contains the date that Amazon customer service canceled the purchase. |
cancelReason |
Integer | Indicates why a product was canceled. Possible values are null , 0 , 1 , or 2 , where each integer represents a cancellation reason: null - The purchase was not canceled. 0 - The cancel reason is currently unavailable and will render at a later time. 1 - Your customer canceled the order. 2 - The purchase was canceled by Amazon's system. This code is also returned if Amazon customer support canceled the order at the request of a customer. |
testTransaction |
Boolean | Indicates whether this purchase was made as a part of Amazon's publishing and testing process. |
Unsupported fields for purchases.products.get API
The following fields that are available in the Google Play Developer API, aren't supported in the Appstore Billing Compatibility RVS API.
consumptionState
regionCode
orderId
developerPayload
acknowledgementState
obfuscatedExternalAccountId
obfuscatedExternalProfileId
Related topics
- RVS for Subscriptions
- RVS Production Setup for Appstore Billing Compatibility
- RVS Examples for Appstore Billing Compatibility
Portions of this page are modifications based on work created and shared by Google and used according to terms described in the Creative Commons 4.0 Attribution License. Sources: https://developers.google.com/android-publisher/api-ref/rest/v3/purchases.products/get, https://developers.google.com/android-publisher/api-ref/rest/v3/purchases.products.
Last updated: May 22, 2024