Table of Contents

This list of best practices for Roku Pay is a good checklist to review your implementation. Most advice is easy to implement, and will help optimize your user acquisition funnel, provide better feedback to your customer base, and prevent production issues like double billing.

Providing a meaningful company name

Your company name will be on your customer's credit card statement. Be sure to enter a name that will be meaningful to the customer.

1. Login to your Roku developer account and go to your Developer Dashboard. Select "Developer information".
   You will see the field "Company Name" on the screen. This field displays on a user's credit card statement when they subscribe to a product on your channel. 
2. Update "Company Name" to something that helps the user associate your product with the purchase on their bank statement. In this example, you would replace "XYZ Co." in the Company Name field with the company name you want your customers to see on their credit card statements. 

Providing a meaningful product name

Your in-channel product name is displayed to the user as part of the purchasing or sign-up flow on a device, as well as in all subscription emails that are sent by Roku. Be sure to enter a name that will be meaningful to the customer.

1. Login to your Roku developer account and go to your Developer Dashboard. 
2. Select "Manage my in-channel products" under "My channels."
3. Scroll to the product you want to edit and click "Edit". 
4. On the "Edit in-channel product" screen, update "Product Name" to something that the user will be able to associate with their purchase.

For more details on how to setup your product correctly, please refer to: Monetization in Developer Dashboard.

Using Roku's Validate Transaction API for entitlement checks and dunning

Dunning is the process of methodically communicating with the users about their subscription expiration status and repeatedly attempting a charge to their MOPs to ensure collection of payment. This process validates a transaction that was returned from an SVOD product purchased in the Channel Store and returns subscription information required for implementing entitlement.

To determine a user’s subscription eligibility, the validate-transaction API now returns a new parameter, isEntitled, a simple Boolean value.  Previously, Roku asked partners to use a hard-coded grace period of 4 days to approximate the Roku dunning cycle. This made for fragile and overly complex code. Roku's new recommendation is to remove this code asap and replace it with this process:

The entitlement service that the channel has should run a nightly sync with the Roku Channel Store channel in which it iterates all expired subscriptions and calls validate-transaction, passing the stored transaction ID for the subscription.

The entitlement service then needs to read the returned parameter isEntitled. If isEntitled is false, then Roku has completed the dunning cycle and canceled the subscription. Therefore the user should no longer be entitled to the SVOD subscription. 

Not only does the entitlement service cancel the entitlement, it can put the account in an "unsubscribed" state so that it does not need to call validate-transaction anymore for that user.

None of the other parameters that validate-transaction returns have been removed, so that more detailed account status can also be tracked in the entitlement service. This table shows the detailed account subscription states:

More details at: Web Service API.

Using the Channel Store object correctly

In an implementation of a channel, because DoOrder() and SetOrder() need to read the product type returned by GetCatalog(), only one instance of roChannelStore should ever be used for a complete purchase flow. For example, you should never create a separate roChannelStore object to complete a purchase that was initiated by a different instance of roChannelStore.

Avoiding double billing

Make sure your channel's UI follows the best practice of not allowing a user to accidentally sign-up for a product that they have already purchased.

The channelStore service protects against purchasing an SVOD product more than once, returning an error in DoOrder()/SetOrder() if an attempt is made to purchase an SVOD product the user is already subscribed to. However, it is the channel's responsibility to protect against purchasing different SVOD products. A common pattern where this occurs is offering a free subscription SVOD product to users that have never had a free subscription and a non-free subscription product for those who have not. 

The way to provide this protection is to call GetPurchases(), which returns transactions for active subscriptions and protects against purchasing multiple, mutually-exclusive SVOD products.