Skip to end of metadata
Go to start of metadata


The following are the web service APIs you can use to connect to the Channel Store. These API calls are all located on apipub (https://apipub.roku.com/) to remove the need of having a Roku certificate to use them. Each of the APIs is documented below in its own section with a heading in the form of apiname.svc.

You can use either XML or JSON format for your requests (the examples below use one or the other). 

To use JSON, pass the following header in the request:

accept: application/json

To use XML, pass the following header in the request:

accept: text/xml

BaseResponseData

All responses to all services derive from BaseReponseData. The base response is structured as follows:

<result>
  <status>{Success|Failure}</status>
 
<errorMessage>error_message</errorMessage>
 
<errorDetails>error_details</errorDetails>
 
<errorCode>non-localized_function_error_code</errorCode>
</result>

transaction-service.svc

The transaction service allows developers to validate transactions and modify channel state remotely. All requests require a developer ID to validate which can be retrieved from the owner site.

/listen/transaction-service.svc/validate-transaction/{webApiKey}/{transactionid}

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

Response Example

<result>

  <transactionId>{transactionid}</transactionId>

  <purchaseDate>2012-07-22T14:59:50</purchaseDate>

  <channelName>123Video</channelName>

  <productName>123Video Monthly Subscription</productName>

  <productId>NETMONTH</productId>

  <amount>9.99</amount>

  <currency>USD</currency>

  <quantity>1</quantity>

  <rokuCustomerId>abcdefghijklmnop</rokuCustomerId>

  <expirationDate>2012-08-22T14:59:50</expirationDate>

  <originalPurchaseDate>2010-08-22T14:59:50</originalPurchaseDate>

  <status>Success</status>

  <errorMessage>error_message</errorMessage>

</result>

/listen/transaction-service.svc/validate-refund/{webApiKey}/{refundId}

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

Response Example

<result>
 
<transactionId>{transactionid}</transactionId>
 
<purchaseDate>2012-07-22T14:59:50</purchaseDate>
 
<channelName>123Video</channelName>
 
<productName>123Video Monthly Subscription</productName>
 
<productId>NETMONTH</productId>
 
<amount>9.99</amount>
 
<currency>USD</currency>
 
<quantity>1</quantity>
 
<expirationDate>2012-08-22T14:59:50</expirationDate>
 
<originalPurchaseDate>2010-08-22T14:59:50</originalPurchaseDate>
 
<status>Success</status>
 
<errorMessage>error_message</errorMessage>
</result>

/listen/transaction-service.svc/cancel-subscription

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

Request Example

<cancel>
 
<partnerAPIKey>{apikey}</partnerAPIKey>
 
<transactionId>{transactionId}</transactionId>
 
<cancellationDate>2012-08-22T14:59:50</cancellationDate>
 
<partnerReferenceId>{partnerReferenceId}</partnerReferenceId>
</cancel>

Response Example

<result>
 
<status>Success</status>
 
<errorMessage>error_message</errorMessage>
</result>

/listen/transaction-service.svc/refund-subscription

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

Request Example

<cancel>
 
<partnerAPIKey>{apikey}</partnerAPIKey>
 
<transactionId>{transactionId}</transactionId>
 
<amount>2.99</amount>
 
<partnerReferenceId>{partnerReferenceId}</partnerReferenceId>
 
<comments>Customer was not impressed</comments>
</cancel>

Response Example

<result>
 
<status>Success</status>
 
<errorMessage>{error message goes here}</errorMessage>
 
<refundId>{refundId}</refundId>
</result>

/listen/transaction-service.svc/update-bill-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 partnerAPIkey. The newBillCycleDate must be included in an ISO-8601 format.

Request Example

POST https://apipub.roku.com/listen/transaction-service.svc/update-bill-cycle HTTP/1.1
content-type: application/json
accept: application/json

{"partnerAPIKey":"02E763BE3642C0459CF79F5E011CB1CE5642","newBillCycleDate":" 2014-03-28","transactionId":"1C63E500EF094DB4A83CA2CF00B7EB4E"}

Response Example

 {"errorCode":null,"errorDetails":null,"errorMessage":"","status":0}

/listen/transaction-service.svc/issue-service-credit

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

Request Example

POST https://apipub.roku.com/listen/transaction-service.svc/issue-service-credit HTTP/1.1
accept: application/json
content-type: application/json

{"partnerAPIKey":"02E763BE3642C0459CF79F5E011CB1CE5642","amount":5.00,"channelId":"10081","comments":"This is sample json","partnerReferenceId":" ","productId":" ","rokuCustomerId":"AC4D2FD61F624451A61AQ2CF00A766A1"}

Response Example

 {"errorCode":null,"errorDetails":null,"errorMessage":"","status":0,"ReferenceId":"1409"}

Push Notifications

Four types of push notifications are available if you subscribe to receive them: Sales, Cancellation, Credit, Refund. When a qualifying event occurs, Roku attempts to send the notification every few seconds. If the notification is not successfully delivered within a reasonable time period, Roku removes it.

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 body. 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 system. Additionally, you are required to send an ApiKey header with the value containing your Roku API key that was issued on the developer site. 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:

HTTP/1.1 200 OK
ApiKey: [roku api key value in dev portal]
Content-Length: 32

659a9e3f6b1649f681a408f1beeb2766

Example Notifications

Credit

{"customerId": "bbd2d8c616cc4802989da2d800cf2b81","transactionType": "Credit","transactionId": "1243","channelId": "484","channelName": "StwzAbNxMbX779Ia","productCode": "f478e3a9d68d4ff390bb","productName": "Monthly Sub","price": 5.00,"total": 5.00,"currency": "usd","partnerReferenceId": "prefid","comments": "Service Credit Test","eventDate": "2014-02-20T20:34:21.1781901Z","responseKey":"659a9e3f6b1649f681a408f1beeb2766"}

Sale

{"customerId":"ac4d2fd61f624451a61aa2cf00a766a1","transactionType":"Sale","transactionId":"aa3f3a2479ea4e0c88d9a2d500f33e74","channelId":"26558","productCode":"testProd123","price":0.99,"tax":0.00,"total":0.99,"currency":"usd","comments":"New order processed.","eventDate":"2014-02-17T22:45:37.496125Z","responseKey":"659a9e3f6b1649f681a408f1beeb2766"}

Refund

{"customerId":"ac4d2fd61f624451a61aa2cf00a766a1","transactionType":"Refund","transactionId":"970625d44a544b78964ba2d6011231bd","channelId":"26558","productCode":"testProd123","price":-0.99,"tax":0.00,"total":-0.99,"currency":"usd","originalTransactionId":"dccc31583aa1441e8c76a2d600b28716","originalPurchaseDate":"2014-02-18T18:49:59","partnerReferenceId":"test","comments":"test","eventDate":"2014-02-19T00:38:20.231375Z","responseKey":"c1a73677590948e68215586dfa9455b5"}

Cancellation

{"customerId": "6a4d984e7aee47d18975a2d800cb707b","transactionType": "Cancellation","transactionId": "260a7b6d8e4a4e7b8b0ba2d800cb7142","channelId": "445","productCode": "fb435917cefc4f66b36c","productName":"Monthly Sub","expirationDate": "2014-02-20T20:20:42.6473452Z","originalTransactionId": "a82e4abdab0247fb9a2ca2d800cb712d","originalPurchaseDate": "2014-02-20T20:20:42","partnerReferenceId": "CANCELTESTNOTIFICATION","comments":"Cancellation for Monthly Sub","eventDate": "2014-02-20T20:20:42.6903495Z","responseKey":"c1a73677590948e68215586dfa9455b5"}

  

  • No labels