Tutorial: Roku In-App Purchase

Prerequisites

For Roku in-app purchases to be connected to Cleeng's system, the following steps must be completed:

  1. Create a Roku customer account
  2. Enroll as a Roku developer
  3. Register for Roku Partner Payouts Program
  4. Configure in-app products for your Roku channel app

    • Note: Each Roku Product ID should match its Cleeng Offer ID with one minor exception–– becasue the _ (underscore) character is not supported, you must use a - (dash) instead:

      Cleeng Offer ID | Roku Product ID
      ----------------|-------------------
      S123123123_US   | S123123123-US
      
  5. Set your Roku push notification URL to this Cleeng endpoint: https://cleeng.com/roku/push-notification/publisher_id

    Push notification URL

  6. Contact Cleeng to finalize Roku in-app purchase setup.

This tutorial assumes that the user is already authenticated and has a customerToken stored in the app. For reference see our authentication tutorial.

Purchase Flow

The Roku channel app is responsible for displaying the “buy" button to initiate the payment. Once successful payment is completed through Roku Billing, the Cleeng receipt endpoint must be notified.

Receipt Endpoint

Endpoints:

  • Production URL: https://cleeng.com/roku/payment
  • Sandbox URL: https://sandbox.cleeng.com/roku/payment

Request:

  1. Request method: POST
  2. Required headers:

    • Content-Type: application/json
    • X-Publisher-Token: publisher_token
    • Authorization: Basic auth_token - token provided by Cleeng
  3. Json payload example:

    {
      customerToken: customer_token,
      offerId: offer_id,
      order: {
        amount: amount_number,
        code: product_code,
        purchaseId: purchase_id,
        qty: qunatity,
        total: total_amount,
      },
      ipAddress: "192.168.1.1"
    }
    
  4. Parameters describe

    • customerToken - token identyfing customer account on Cleeng (eg. ZAP8dgKPIEgBulSZZBdyv1O0wzg1pucyHf8gUGg2X6ZhdRaH)
    • offerId - identifier for Cleeng offer (eg E123123123_US)
    • amount - Price of each purchased item
    • code - Product code, this corresponds to the product identifier that the developer assigns to the specific in-app purchase product
    • purchaseId - Contains the unique transaction ID of the transaction, channels often use this value to entitle users to purchased subscriptions, etc. in their back end systems
    • qty - Quantity of the specific product purchased
    • total - Total purchase amount (including taxes) in the local currency
    • ipAddress - viewer ip address, optional parameter
  5. Example json response:

    {
      "message": "OK"
    }
    
  6. Response describe

    • message - processing result
  7. HTTP status codes

    • 400 - Invalid parameters
    • 401 - Invalid authentication // broadcaster and viewer
    • 422 - Unprocessable entity
    • 200 - OK
    • 500 - Internal Server Error

Validate Access

Payment processing is asynchronous and may take up to 1-2 minutes between purchase and validation in Cleeng. Because of this, the app should grant temporary access to the user while the transaction is processed. However, every time after the inital purchase, the middleware will be the source of truth to check the user's access status.

Note: If this is not completed within 1-2 minutes, the app should assume that the payment failed and notify the user.

Roku purchase flow

End User Registration and In-App Purchase Diagram

Roku registration & purchase