Roku Developer Help - In-Channel Purchase / Roku Pay

Using In-Channel Purchasing (also known as "Roku Pay") with your Roku Channel

This Instant TV Channel Help article applies only to Custom SDK Roku channels. Roku does not support In-Channel Purchasing in Direct Publisher channels yet.

The In-Channel Purchase feature allows a Roku channel to support one-time and subscription purchases entirely within a Roku channel. Product selection and payment authorization are all performed on-screen using the Roku remote control. All payments are processed through Roku Billing Services, and Roku deposits sales revenue directly to your PayPal account. Each product offered for purchase in a Roku channel has a unique Product Identifier configured in your Roku Developer Account. Products can be individual videos, groups of videos, or entire channels. During the purchase process the viewer is prompted to enter their Roku PIN number to authorize a one-time or recurring credit card charge. If the purchase is successful, then any product in the channel (or any channel in the same Roku Developer Account) with the corresponding Product Identifier will be available to the viewer.

• In order to use the In-Channel Purchase feature with your Roku channel, you must be enrolled in the Roku Partner Payouts Program. Visit the Roku Partner Payouts Program page at developer.roku.com/developer/billing for additional information.
• Your Instant TV Channel account Developer Mode must be set to Advanced in order to view or change In-Channel Purchase related settings. You can change the Developer Mode from the Instant TV Channel Account page.
• To add Purchase buttons to the Springboard page you must enable Springboard Button Editing ("Show Custom Springboard Buttons") on the Instant TV Channel Account page.
• Your channel must be a Commercial channel type. Free and Unlimited channel types do not include support for In-Channel Purchasing.

Products available for purchase with the In-Channel Purchase feature currently include:

ad removal - Remove video ads from a specific content item or items.
content - Allow a specific content item or items to be played, with or without video ads. This is the most commonly used option.
content without video ads - Allow a specific content item or items to be played with the video ads removed.
quality - Allow access to HD bitrate streaming for a specific content item or items. (Streams are tagged as HD within Instant TV Channel by setting the Stream Quality parameter to "True".)
quality without video ads - Allow access to HD bitrate streaming for a specific content item or items with the video ads removed.
other - Allow a purchase to be made that has no effect on what content item can be played. For example a donation or contribution.

Purchase Types are determined by the Product settings in your Roku Developer Account. Each Product has a single Purchase Type. Available Purchase Types currently include:

One-Time Purchase - A one-time non-recurring purchase.
One-Time Purchase, Consumable - Allows multiple purchases of the same Product. Not typically used for video content.
Monthly Subscription - A monthly recurring purchase. This is the most commonly used option.
Yearly Subscription - A yearly recurring purchase.

More than one product can be purchased for a single content item. For example a content item might have two separate product purchase buttons, one for ad removal and another for HD quality. The two products, ad removal and HD quality, could be purchased separately or purchased together:

Example Content Item with 2 Products
Product Purchased	Services Available	Services Not Available
None	SD video streaming.	HD video streaming, video ad removal.
"Ad Removal" Only	SD video streaming, video ad removal.	HD video streaming.
"Quality Content" Only	SD and HD video streaming.	Video ad removal.
Both "Ad Removal" and "Quality Content"	SD and HD video streaming, video ad removal.

Below is a complete matrix of all possible purchase combinations. Note that the availability of one product can affect the services provided by another product. For example, if the "content" product is offered by itself, the viewer has both HD and SD streams available after purchasing the product. But if the "quality content without video ads" product is offered along with the "content" product, then the "content" product only provides an SD stream, and the viewer must purchase the additional "quality content without video ads" product in order to view the HD stream.

In-Channel Purchase Matrix If multiple Product Purchase Types are available for a single content item:
Product Purchase Type	Purchased			Available But Not Purchased
Product Purchase Type	Remove Ads	Allow HD	Allow SD	Remove Ads	Allow HD	Allow SD
ad removal	yes
content			yes		no, if not already yes	no, if not already yes
content without video ads	yes		yes		no, if not already yes	no, if not already yes
quality content		yes	yes		no, if not already yes
quality content without video ads	yes	yes	yes		no, if not already yes
other
If neither yes nor no after all available Product Purchase Types for a Content Item are considered:
	Remove Ads		Allow HD		Allow SD
Default Settings	no		yes		yes

Walkthrough

Let's walk through the steps required to set up a single video content item with both an "ad removal" product and a "quality content" (HD) product. This will provide the viewer with 4 choices for watching the content item:

Don't purchase anything and watch the stream in SD with video ads.
Purchase just the "ad removal" product and watch the stream in SD without video ads.
Purchase just the "quality content" product and watch the stream in HD with video ads.
Purchase both products and watch the stream in HD without video ads.

The walkthrough will consist of several parts:

Add Products to your Roku Developer Account
Add a Test User to your Roku Developer Account (optional)
Add Purchase Buttons and Products to your Instant TV Channel Videos
Set up an S3 Transaction Bucket (optional)

Add Products to your Roku Developer Account

Log into your Roku Developer Account and click "Manage My In-Channel Products". This should display the "Manage My In-Channel Products" page.
If you not see the "Manage My In-Channel Products" link then you'll need to sign up for Roku Billing Services. There should be a link on the main page of your Roku Developer Account that allows you to sign up, or visit the Roku Billing Services page at www.roku.com/billing.
On the "Manage My In-Channel Products" page, click the "Add a Product" button. This should display the "Add an In-Channel Product" page.
From the list of channels, select the channel or channels to which you wish to add this product.
Enter a Product Name of "View without Ads", or choose your own Product Name if you'd like. Once this name has been entered it cannot be changed. The Product Name will be shown on the receipt that Roku emails to a purchaser, and it can optionally be used in the on-screen receipts in your Roku channel. The same Product Name can be used for multiple products.
Enter an Identifier of "AD-1", or choose your own Identifier if you'd like. This is an order code that will be used in your Roku channel to identify this specific product. If you have multiple In-Channel Products, each product must have a unique Identifier. The Identifier is not visible to the purchaser.
Enter a Purchase Type. The following types are available:
- One-Time Purchase - This Purchase Type is used to allow a subscriber to make a one-time non-recurring purchase.
- One-Time Purchase, Consumable - This Purchase Type allows the subscriber to make multiple purchases. It is not usually used for products such as video content or ad removal, but it could be used for donations or contributions.
- Monthly Subscription - This Purchase Type causes the subscriber's account to be charged each month on a recurring basis. It is often used for subscription-based video content.
- Yearly Subscription - This Purchase Type causes the subscriber's account to be charged each year on a recurring basis.
Leave Quantity set at the default value of "1"
Leave Internet Connection Required at the default setting of "Yes"
Leave Requires Additional Purchase at the default setting of "No"
Change Cleared for Sale to "Yes"
Select a Price Tier for the product. This is the amount that each subscriber will be charged when purchasing your product. If your channel is available in multiple geographic regions then several different local currencies may be displayed for each tier.
Click the "Create" button. This should return you to the "Manage My In-Channel Products" page.
Click "Submit for review" for the product that you just created.
Repeat each of the above steps to create another In-Channel Product, except this time use a Product Name of "View in HD" and an Identifier of "HD-1".

Add a Test User to your Roku Developer Account

A test account is used so that you can make on-screen test purchases from your Roku channel without charges being applied to your credit card.

• Setting up a test user is optional.
• Your In-Channel Purchases will be processed correctly even if you do not set up a test user, however any purchases that you make to test your Roku channel will result in actual credit card charges.

From the main page of your Roku Developer Account, click "Manage Test Users". This should display the "Manage Test Users" page.
Click "Add New Test User".
Enter the email address of the test user. This must be the same email address that is associated with the Roku device that you will be testing with.
Select the Roku channels in which you want to allow the user to make test purchases.
Click the "Add" button.

Add Purchase Buttons and Products to your Instant TV Channel Videos

• Video content items created in channels older than Update #285 do not have support for user-defined Springboard buttons such as the Purchase button, and will need to be re-entered as new items in order to use with In-Channel Purchasing.

From the Instant TV Channel "Content" page, select the video content item to which the Purchase buttons will be added.
Scroll down the parameter list until you see the Button parameters ("Button 1", "Button 2", etc). (If you do not see the Button parameters, you will need to visit the "Account" page and select "Yes" for Show Custom Springboard Buttons. Don't forget to click the green SAVE button on the Account page after making any changes..)
Click the New button located on the highest numbered Button parameter block. This will create a new Button parameter block.
Change the new button's Action parameter from "New" to "Purchase".
Change the "Purchase" button's Label parameter to "Remove ads for 99 cents". Instead of "99 cents" you should use whatever price tier you previously selected for ad removal in your Roku Developer Account.
Leave the Button Display parameter set at "hide if this product is purchased". This will cause the button to be hidden after a purchase has been made.
Enter a Purchase button Identifier of "AD-1", or whatever ad removal Identifier you previously entered in the In-Channel Products page of your Roku Developer Account.
Enter a Purchase button Product Name of "Ad Removal". This name can be displayed in the on-screen Receipts available to your subscribers. If Product Name is blank then the Product Name entered in the In-Channel Products page of your Roku developer account will be used for on-screen receipts.
Leave the After Purchase parameter set at "play this content item". This will cause the video to play immediately after a successful purchase. If the purchase is not successful then the Springboard screen will be redisplayed.

Editing a Purchase Button

Click the New button located on the Purchase button parameter block. This will create another new Button parameter block.
Change this new button's Action parameter from "New" to "Purchase".
Change the new "Purchase" button's Label parameter to "View in HD for 99 cents". Instead of "99 cents" you should use whatever price tier you previously selected for "View in HD" in your Roku Developer Account.
As before, leave this button's Button Display parameter set at "hide if this product is purchased".
Enter a Purchase button Identifier of "HD-1", or whatever HD Identifier you previously entered in the In-Channel Products page of your Roku Developer Account.
Enter a Purchase button Product Name of "View in HD".
As before, leave the After Purchase parameter set at "play this content item".
Optionally change the Purchase button's location relative to the other buttons by clicking the up ⇧ or down ⇩ arrows next to each button.
Scroll lower in the video's parameter list until you locate the Product block containing the Product Identifier and Product Purchase Type.
Set the Product Identifier to the same value as the Purchase button Identifier, "AD-1".
Set the Product Purchase Type to "ad removal".
The Purchase Type of "ad removal" is now tied to the "AD-1" Identifier for this video content item. If this video is played and the "AD-1" product has been previously purchased, all ads will be removed from the video.

Editing a Product

Click the Product New button to create a second Product, then repeat each of the above steps once more, except this time use a Product Identifier of "HD-1" and a Product Purchase Type of "quality content".
The Purchase Type of "quality content" is now tied to the "HD-1" Identifier for this video content item. If this video is played and the "HD-1" product has been previously purchased, all streams in this video that have the Quality parameter set to "True" will playable.

Set up an S3 Transaction Bucket

An S3 bucket can be set up which will contain a file for each In-Channel Purchase transaction. The files in the Transaction bucket can be used to reconcile the transaction information in your Roku Developer Account. If you collect user data (email and street addresses) with each purchase, the user data will be stored in the bucket as part of the purchase's transaction file. The Instant TV Channel "Roku Billing" page allows you to view the contents of the transaction files, or you can download the S3 bucket contents for processing with your own application.

• Setting up an S3 Transaction bucket is optional.
• Your In-Channel Purchases will be processed correctly even if you do not set up an S3 Transaction bucket, however no user data will be saved.
• The transaction files are written directly into the S3 Transaction bucket by each Roku device as a purchase is made, and may be missing if there are network problems at the time of the purchase that prevent the Roku device from reaching Amazon.
• Any valid purchase will always have a transaction record available in your Roku Developer Account.

Click on the "Roku Billing" link on the left side of the Instant TV Channel page.
Copy and paste the 36-character "API Key" from the "Roku Pay Web Services" page in your Roku Developer Account to the Roku API Key parameter on the Instant TV Channel "Roku Billing Settings" page.
Go to the S3 section of your AWS (Amazon Web Services) control panel and create a new S3 bucket, named something like "my-transaction-bucket". You will use the bucket name in several of the following steps.
- The bucket Region must be set to "US East (N. Virginia)".
- This should be a private bucket that is not web enabled.
- This bucket will only be used to contain transaction information for Roku In-Channel Purchases and should not be used for Instant TV Channel Configuration File or Content storage.
- Use only lower-case characters, digits, and dashes in your bucket name. Instant TV Channel does not support the use of upper-case characters or other symbols in bucket names.
  
  Good Bucket Name: transaction-bucket
  
  Good Bucket Name: transaction123
  
  Bad Bucket Name: transaction.bucket (contains unsupported period character ".")
  
  Bad Bucket Name: transaction+123 (contains unsupported plus character "+")
  
  Bad Bucket Name: Transaction-Bucket (contains upper-case characters "T" and "B")
Go to the IAM (Identity and Access Management) section of your AWS control panel.
Click the Policies link on the left side of the page.
Click the Create policy button near the top of the page.
Click the JSON tab, and erase the sample lines of JSON text.
Copy the security policy below and paste it into the JSON text box. Replace the two instances of
```
my-transaction-bucket
```
in the policy with the name of the bucket that you just created. This JSON security policy code allows files in the Transaction bucket to be both read from and written to.
```
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "s3:*"
      ],
      "Resource": [
        "arn:aws:s3:::my-transaction-bucket",
        "arn:aws:s3:::my-transaction-bucket/*"
      ]
    }
  ]
}
```
Click the Next: Tags button near the bottom of the page.
Click the Next: Review button near the bottom of the page.
Provide a new Policy Name, for example "my-transaction-policy". You may optionally also enter a Policy Description.
Click the Create policy button near the bottom of the page.
Click the User groups link on the left side of the page.
Click the Create group button near the top of the page.
Provide a new User group name, for example "my-transaction-group".
Scroll down to the list of policies, and locate the "my-transaction-policy" policy that you just created, or type the name of your newly created policy in the "Filter" box. You may need to scroll through a large number of built-in AWS policies until your policy is visible.
Check the checkbox to the left of your policy name. making sure that no other checkboxes are checked, then click the Create Group button near the bottom of the page.
Click the Users link on the left side of the page.
Click the Add Users button near the top of the page.
Provide a new User name, for example "my-transaction-user".
Click the Next button near the bottom of the page.
Check the checkbox to the left of the previously created Group name, then click the Next button near the bottom of the page.
Click the Create user button near the bottom of the page.
Click the previously created User name from the list of users. This will display a Summary page for the user.
Click the Security credentials link or tab.
Click either of the Create access key buttons.
Select Other, then click the Next button.
Click the Create access key button.
Click the Show link beneath "Secret access key" or click the Download .csv button to copy and save the Access Key ID and Secret Access Key. These keys will be used exclusively for access to your Transaction bucket. They cannot be used to access any other AWS buckets or services. Make sure that you save the keys for future use, Amazon will not display them again. If you misplace the keys you will have to create a new IAM user.
After copying the Security Credentials, click the Close button near the bottom of the page.

At this point we have a new IAM user that is a member of a new IAM group - the user has the keys and the group has the security policy. This will allow the keys to be used in the Roku channel to access the S3 bucket specified by the security policy.
Enter the name of the Transaction bucket that you just created into the Instant TV Channel Transaction Bucket Name parameter on the Instant TV Channel "Roku Billing" page.
Leave the Transaction Prefix or Folder Name parameter blank. You can use this later if you wish to set up separate folders for multiple Roku channels.
Enter the Access Key ID that you just created into the Instant TV Channel Transaction Bucket Access Key ID parameter.
Enter the Secret Access Key that you just created into the Instant TV Channel Transaction Bucket Secret Access Key parameter.
Click the TEST S3 TRANSACTION STORAGE button to verify that the bucket name and S3 keys are correct. If this test fails, do not proceed until the problem is resolved.
The default "request" setting of the User Data parameter will cause the Roku device to ask the user for permission to share their email and street address before a purchase is made. If the user agrees, the user data will be added to the transaction receipt stored in the S3 bucket. If the user does not agree to share their data the purchase will still proceed normally.
If you do not wish to ask the user for their email address and street address when making a purchase, change the User Data parameter to "none".

If you want to require the user to share their email address and street address when making a purchase, change the User Data parameter to "require". If the user does not agree to share their data then the purchase will be cancelled. This setting is not recommended, as it may result in lost sales.
Leave the Use Store Catalog setting at its default value of "True". This value only needs to be changed if you have a very large number of In-Channel Products assigned to this channel in your Roku Developer Account. If this value is changed to "False" and your are using the "%NAME" macro in any of the remaining parameters, you will need to make sure that you specify a Product Name for each Purchase button.
All remaining parameters on the Instant TV Channel "Roku Billing" page can remain at their default values. These parameters are used to customize the on-screen receipts and messages related to In-Channel Purchases.

Additional Suggestions

The same Identifier can be used in the Purchase buttons and Products in multiple video items at the same time. This allows a single Purchase button to activate the same service across many videos simultaneously. This can be used, for example, to activate HD streaming across all episodes of a series by configuring the same Product Identifier and PurchaseType in each of the episodes.
It is not necessary to have matching Identifiers for the Purchase buttons and the Products within an individual video item. For example the Purchase button Identifier in one video item could enable access to an HD stream or ad removal in a different video item that has the same Product Identifier.
Instead of a Purchase button in a Springboard, a Programmable Button can be used to complete an In-Channel Purchase. A purchase made with a Programmable Button will affect any item containing a Product Identifier that matches the Identifier used in the Programmable Button, the same way that a Springboard Purchase button would.
Configure the Success Top and Success Bottom parameters on the Instant TV Channel "Roku Billing" page so that the message displayed after a purchase accurately reflects what the viewer purchased.
The In-Channel Purchase Settings on the Instant TV Channel "Roku Billing" page can be used to specify one or two global Identifiers and Purchase Types that apply to the entire channel. This allows you to configure In-Channel Purchasing for all items in the channel without configuring the individual Product - Identifier or Product - PurchaseType parameters for each item. You can opt-out individual items from the global Identifiers and Purchase Types by setting the item's IgnoreInChannelPurchase parameter to "True".

Example Channel

The example channel contains two linear loops of video content, a Free loop, and a Premium (paid) loop. The Free loop contains content that the viewer is allowed to watch before paying and a Programmable Button that allows the viewer to make a purchase of the Premium loop. If no purchase has been made, then the Free loop is played and the Premium loop is not visible. If a purchase has been made, then the Premium loop is played and the Free loop is not visible.
The channel's top-level AutomaticPlay parameter is set to "once" so that it automatically starts running without waiting for a remote-control selection.
The channel uses a Control configured as a text macro. This allows the Product ID associated with the purchase to be configured at one location within the channel, instead of in three places. For example if the text macro contains $PID$:MY_PRODUCT_ID then MY_PRODUCT_ID will be substituted for any occurrence of $PID$ found in the channel. The substitution is done in the Roku device as the channel runs, no changes are made to the stored channel.
When using a Control macro it is necessary to nest all parts of the channel to which the macro will apply at a lower level, otherwise the macro substitions may not be applied consistently. The "List of All Items" Horizontal List serves this purpose. The "List of All Items" AutomaticPlay parameter is set to "once" so that it automatically enters the "Loop of Free Videos" or "Loop of Premium Videos" without waiting for a remote-control selection.
The "Loop of Free Videos" has its AutomaticPlay parameter set to "repeat", DoNotDisplay set to "yes if condition is true", and its Condition parameter set to purchased=$PID$. After the macro substitution this is interpreted as "do not display if MY_PRODUCT_ID has been purchased". Together the DoNotDisplay and Condition settings cause the entire Free list be be hidden if the purchase has been made.
The Programmable Button within the Free loop allows the viewer to purchase an upgrade to access the Premium loop. It is configured by setting the Function parameter to "in-channel purchase", the Identifier parameter to $PID$ (or whatever was used as the macro placeholder in the Control ), and the Purchase Success parameter to "restart channel". It is necessary to provide custom artwork via a URL for the ChannelSetupUrl parameter that describes to the viewer what they will be purchasing.
As configured in the example channel, the user will be presented with the option to make a purchase after all the videos in the Free loop have played. It may be advantageous to move the Programmable Button to the beginning of the Free loop, or to have several identical Programmable Buttons withing the Free loop.
The "Loop of Premium Videos" Horizontal list has its AutomaticPlay parameter set to "repeat", DoNotDisplay set to "yes if condition is true", and its Condition parameter set to !purchased=$PID$. The exclamation point at the beginning of the Condition negates the purchase test, and after the macro substitution causes it to be interpreted as "do not display if MY_PRODUCT_ID has not been purchased" which is the same as "do display if MY_PRODUCT_ID has been purchased". Together the DoNotDisplay and Condition settings cause the entire Premium list be be hidden if the purchase has not been made.
This example channel can be imported into your account using the Channel ID 1f71f178-64a5-45d7-bbd1-e330b9e57a8a.

This is the content tree for the example channel.

- o -

Please see this Quick 5-Minute Guide for information about how to get started with Instant TV Channel.

Suggestions, comments, or questions about this Roku tutorial can be sent to .