Skip to end of metadata
Go to start of metadata

Roku Web Services is integral to allow subscribers who signed up on Roku to use your service on other platforms. This API can be used to determine whether a subscription on Roku is still valid so the subscriber can be entitled access on a platform other than Roku. Among other features, this API provides functionality for canceling subscriptions, issuing credits, and updating billing cycles.

Table of Contents


Setting up Roku Web Services

All transaction service requests require a Roku API Key assigned to each Roku developer. The API key can be retrieved from the Web API Settings page on the Developer Dashboard.

Developers can also set a range of IP addresses transaction service requests can come from. Requests will only be valid if Roku receives it from the range of IP addresses specified. If no range is specified, requests from any IP address using your Roku API Key are valid.

Developers can also specify a URL endpoint to receive push notifications for transaction events such as: purchases, cancellations, refunds, and credits.

If the endpoint to receive push notifications fails consecutively, Roku will stop sending notifications and Stop sending billing notifications will be checked. When the endpoint is valid and can receive push notifications again, uncheck Stop sending billing notifications.

 

See Developer Dashboard for an overview of available features.

Transaction Service

These API calls are all located on https://apipub.roku.com to remove the need of having a Roku certificate to use them.

You can use either XML or JSON format for your requests. 

  • To use JSON, include the following header in the request: accept: application/json
  • To use XML, include the following header in the request: accept: text/xml

Validate Transaction

Validates a transaction that was returned from a channel or product purchase in the channel store.

Heading:

Response example: 

Validate Refund

Validates a transaction that was returned from a channel or product purchase in the channel store.

Heading: 

Response example:

Cancel Subscription

Cancels the subscription that corresponds to the transactionId. The channel associated with the transactionId must be owned by the developer associated with Roku API Key.

Heading: 

Request example:

Response example:

Refund Subscription

Refunds the subscription that corresponds to the transactionId. The channel associated with transactionId must be owned by the developer associated with Roku API Key. A refundId is returned to validate if needed at a later date.

Heading:

Request example: 

Response example: 

Update Billing Cycle

Used to update the bill cycle of a subscription with the provided transactionId. The subscription must be owned by the developer that owns the included rokuAPIkey. The newBillCycleDate must be included in an ISO-8601 format.

Heading: 

Request example: 

Response example:

Issue Service Credit

Used to issue a service credit to a particular rokuCustomerID. The channel/product must be owned by the developer that owns the included rokuAPIKey. If the service credit is for a channel, there must be an included channelID. For an in-app product, there must be both a channelID and productID. The response will include a partnerReferenceId that can be used later to find the service credit in the Roku system.

Heading:

Request example: 

Response example:

Push Notifications

There are four types of push notifications:

A sample response for each type of push notification is listed below.

Security

A few items have been implemented to ensure security. Roku sends a responseKey as shown in the examples below. The partner must return this and only this in the response content.

Before downloading the content, Roku checks to ensure that the size is equal to the size of what was sent. This prevents hackers from responding with overwhelmingly large chunks of data attempting to crash the Roku Web Service.

Additionally, you are required to send an ApiKey header with the value containing your Roku API key that was issued on the developer site and a content length of 32. When sending the notification, the subscriber cannot redirect in any way. If a redirect attempt is made, the request will fail. The requests also time out after 10 seconds.

Example Notification response:

Sale (purchase)

Cancellation

Refund

Credit

  • No labels