RVS for IAP Apps - Amazon Vega Docs

The Receipt Verification Service (RVS) enables validation of purchases made by your app’s users. In the preview release, you can use RVS in sandbox mode. This page introduces you to RVS and shows the syntax of RVS requests and responses.

RVS overview

The following image shows the purchase workflow with receipt verification. RVS starts after the IAP API completes the purchase and returns the purchase receipt to the app.

The steps in the following table match the callouts in the diagram above:

Step	Component	Task
1	IAP API	IAP API interacts with the user to complete the purchase. IAP API returns a purchase receipt to the App.
2	App	App forwards the purchase receipt to the App Server.
3	App server	App server sends a request to RVS server for validation of the receipt.
4	RVS server	RVS server confirms that the receipt is valid.
5	App server	App server makes the content available to the user.

You can also use RVS to enable access to a subscription purchased on another platform, such as your website, as long as the purchase was made through Amazon. The following scenario describes this workflow:

Your app’s user purchases a subscription through Amazon via your company’s website.
Your app receives a receipt for the purchased subscription
To enable access, your app then sends information from the receipt to your server. Finally, your server validates this transaction by querying RVS.

RVS request syntax

Use RVS to validate the PurchaseResponse object, or the PurchaseUpdatesResponse object. From these response objects, you can extract a UserId, which denotes a unique identifier of the user. The PurchaseResponse object contains a ReceiptId, which is used in conjunction with the UserId to perform an out-of-band server-side validation of the purchase. Requests from your server require a shared secret to be passed to confirm your identity for security. These requests use the following format:

<Protocol>//<Server>[/<sandbox>]/version/<Operation_version_number>/verifyReceiptId/developer/<Shared_Secret>/user/<UserId>/receiptId/<ReceiptId>

The terms in angle brackets are the request parameters, replace them with the following values for the transaction being verified:

Protocol: Protocol being used to communicate with the server or sandbox, such as https:.
Server: URL for the RVS server that you are communicating with.
sandbox: Use the value “sandbox”.
Operation_version_number: Version number of the verifyReceiptId operation. This version number is independent of the IAP version number. The current verifyReceiptId 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 for your developer account with the Amazon Appstore: https://developer.amazon.com/sdk/shared-key.html. For the RVSSandbox, the Shared Secret can be any non-empty string.
UserId: ID representing a distinct Amazon customer for your Appstore app: PurchaseResponse.getUserData().getUserId().
ReceiptId: Unique ID for the purchase: PurchaseResponse.getReceipt().getReceiptId() or PurchaseUpdatesResponse.getReceipts() → Receipt.getReceiptId().

RVS response syntax

RVS provides a RESTful JSON API interface. As a best practice, use a JSON parser class for reading the JSON responses from the RVS server. After making a request to verify a transaction, the RVS server or sandbox 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:

{
 "autoRenewing":false,
 "betaProduct":false,
 "cancelDate":null,
 "cancelReason":null,
 "freeTrialEndDate":null,
 "gracePeriodEndDate":null,
 "parentProductId":null,
 "productId":"com.amazon.iapsamplev2.gold_medal",
 "productType":"CONSUMABLE",
 "promotions": null,
 "purchaseDate":1399070221749,
 "purchaseMetadataMap":null,
 "quantity":1,
 "receiptId":"wE1EG1gsEZI9q9UnI5YoZ2OxeoVKPdR5bvPMqyKQq5Y=:1:11",
 "renewalDate":null,
 "term":null,
 "termSku":null,
 "testTransaction":true
 }

RVS response codes

The Receipt Verification Service responds with one of the following codes, which indicate the result of the validation check:

Response Code	Description
HTTP 200	Success: The Receipt ID, User ID, and shared secret are all valid. Product Type is one of: “ENTITLED”, “CONSUMABLE”, or “SUBSCRIPTION”
HTTP 400	The transaction represented by this `receiptId` is invalid, or no transaction was found for this `receiptId`.
HTTP 410	The transaction represented by this `receiptId` is no longer valid. Treat it as a canceled receipt.
HTTP 429	The request was throttled. Reduce your calling rate and retry after some time.
HTTP 496	Invalid `sharedSecret`
HTTP 497	Invalid User ID
HTTP 500	There was an Internal Server Error

RVS response fields for successful transactions

The following table lists and describes the fields included in an RVS response for a successful transaction:

Field	Data Type	Description
`autoRenewing`	Boolean	Indicates if customer’s subscription will auto renew.
`betaProduct`	Boolean	Indicates whether the product purchased is a Live App Testing product.
`cancelDate`	Long integer	The date the purchase was canceled, or the subscription expired. The field is null if the purchase was not canceled. Time is in milliseconds.
`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. For example, a customer purchases a subscription with an invalid payment and the purchase could not be completed in the grace period. This code is also returned if Amazon customer support canceled the order at the request of a customer.
`freeTrialEndDate`	Long integer	Indicates that the subscription is in a free trial. Provides the free trial end date of the subscription in epoch (milliseconds). The field is null if the subscription is not in a free trial period.
`gracePeriodEndDate`	Long integer	Indicates that the subscription is in grace period. Provides the grace period end date of the subscription in epoch (milliseconds). The field is null if the subscription is not in a grace period.
`parentProductId`	String	Null. Reserved for future use.
`productId`	String	The SKU that you defined for this item in your app.
`productType`	String	Type of product purchased. Valid product types are CONSUMABLE, SUBSCRIPTION, and ENTITLED.
`promotions`	List	Details of the promotional pricing of subscription purchase. Null if there is no promotion.
`purchaseDate`	Long integer	The date of the purchase, stored as the number of milliseconds since the epoch. For subscription items, `purchaseDate` represents the initial purchase date, not the purchase date of subsequent renewals.
`quantity`	Integer	Quantity purchased. Always null or 1.
`receiptId`	String	Unique identifier for the purchase.
`renewalDate`	Long integer	The date that a subscription purchase needs to be renewed. The date is stored as the number of milliseconds since the epoch.
`term`	String	Duration that a subscription IAP will remain valid (the term starts on the date of purchase). The term consists of a number and a time period (Day, Week, Month, Year), such as 1 Week or 2 Months.
`termSku`	String	Unique SKU that corresponds to the subscription term.
`testTransaction`	Boolean	Indicates whether this purchase was made as a part of Amazon’s publishing and testing process.

Cancel date and renewal date

The renewalDate field contains the date that an auto-renew subscription purchase next needs to be renewed. This field applies to subscription purchases only. If a customer has a monthly subscription, the subscription renews monthly on the same date the customer first subscribed. In the case where the next month does not include the exact date, the renewal date is the closest prior date. For example:

If a customer subscribed on January 2, the next three renewal dates are February 2, March 2, and April 2.
If a customer subscribed on January 31, the next three renewal dates are February 28 (or February 29 if it is a leap year), March 31, and April 30.

The cancelDate field contains the date that a subscription purchase expired or that Amazon customer service canceled the purchase. The cancel date represents the date when the customer lost access to the content. When a customer cancels their subscription by turning off auto-renew, the cancel date is when the renewal date would have been. The renewalDate and cancelDate fields are stored as time in milliseconds. You can use java.util.Date(timeInMillis) to convert the value into a date object. Consumable or entitlement purchase In a valid receipt, the cancel date and renewal date both contain the null value. If the cancel date field is not null, it contains the date that Amazon customer service canceled the purchase. Subscription purchase In a valid subscription receipt, the cancel date is null. If the cancelDate field is not null, it contains the date that the subscription expired, or that Amazon customer service canceled the purchase. The renewalDate field contains the date that an auto-renew subscription purchase next needs to be renewed. The field value will be null if the subscription is not set to auto-renew. In the following example, the user has a subscription that was canceled:

The subscription was active from 2016/01/01 – 2016/03/01. In this receipt, the purchaseDate for this subscription is set to 2016/01/01, and the cancelDate is set to 2016/03/01.
If this subscription is subsequently reactivated on 2016/04/01, the subscription will have a second receipt. The second receipt will show a purchaseDate of 2016/04/01 and a cancelDate of null.

RVS Cloud Sandbox

To set up RVS in sandbox mode, see Use RVS Cloud Sandbox.

​RVS overview

​RVS request syntax

​RVS response syntax

​RVS response codes

​RVS response fields for successful transactions

​Cancel date and renewal date

​RVS Cloud Sandbox