ROKU In-App purchases

The InPlayer system integrates with native apps (the Roku app in this case) on the end-users’ TV devices, as a way to support the in-app payment process. For that purpose, in our merchant panel you will be provided a UI for specifying the required parameters for integrating the Roku ecosystem.

You can find the dedicated integration page here.

For a more detailed and visual representation of the integration set-up, click here.

Once the integration is set up and you have your merchant offers created, you can then proceed with the implementation of the in-app payment process.

Application Development Steps#

As an InPlayer Merchant, you should refer to our API services for the purposes of the application development. You can find the technical references of our API services here.

The APIs provide you with the necessary endpoints for given functionalities and enable the communication between the application and our system. These specific functionalities include authentication, in-app payment, and subscription.

Authentication#

Whenever an end-user registers using the [POST] /accounts endpoint, the process ends with an 'access token' that our system returns to authenticate the account.

Example:

curl https://services.inplayer.com/accounts \
-d full_name="John Doe" \
-d email="john@example.com" \
-d password="foobar123" \
-d password_confirmation="foobar123" \
-d type="consumer" \
-d merchant_uuid="507d866c-4e33-445d-b027-f163d0099f54" \
-d metadata[phone]="555-1234-6789"

On the other hand, if the user already exists, then the [POST] /accounts/authenticate endpoint is invoked.

Example:

curl https://services.inplayer.com/accounts/authenticate \
-d client_id="528b1b80-5868-4abc-a9b6-4d3455d719c8" \
-d grant_type="password" \
-d client_secret="password"

For signing out the user invoke the [GET] /accounts/logout request.

In-app Payment#

The in-app payment is a separate functionality and should be implemented independently, by your app developers.

To begin with, the value of your offers (= payment options) is vital in making the payment process work. An offer ID should be created both in our platform and in the native app ecosystems, whereas for the Roku implementation, each offer is called a 'product' which equals to an 'access fee' (= price) in the InPlayer system. When you create products in the native ecosystem, make sure to have the product IDs constructed in the following format:

<asset id>_<access fee id>

According to this product/access fee correlation, by purchasing one product from a native ecosystem, the end-users are in fact purchasing one price from our system. As a merchant, first, you need to make sure that you have entered the accurate value as a product ID. Second, to enable in-app payments, ensure that your app communicates the payment information with the InPlayer system. The in-app payment process ends with a receipt generated by the native Roku system which you should forward to our system by firing the [POST]/v2/external-payments/roku/validate.

Example for [POST] /v2/external-payments/roku/validate

curl https://services.inplayer.com/v2/external-payments/roku/validate \
-H "Authorization: <token>" \
-d receipt="<receipt>" \
-d item_id=256 \
-d access_fee_id=128

That way we can have both the payment and access records entered in our system correctly.

Once our system receives this payment information, as a protection measure, it engages into validating that the receipt is both existing and valid in the native ecosystem (the communication with the native ecosystem is done via the parameters entered during the initial integration process).

Next, your Roku app should communicate to our API by invoking the checkAccess endpoint for two reasons:

  1. To ensure that the payment validation process has been completed and recorded to our system successfully;
  2. To ensure that access to the respective product has been granted and the premium content is fetched, ready to be displayed.

After the validity of the receipt and the entitlement of the asset are confirmed, our system will create and store all the relevant information regarding the in-app payment. More precisely information for:

  • one-time payments - for which our system will store transaction records;
  • subscription payments - where for initial payments, our system will create a subscription record and store a transaction record concerning that subscription;
  • access records - regardless of the type of payment, the final step in the process is granting and writing access records in our system (these access records determine the duration period of an access entitlement for the purchased premium content to the paying customer).

The purchase process is completed once the account is authenticated, payment has been validated and recorded, and the checkAccess endpoint has fetched the premium content making it available for the entitled end-user.

Subscription Recurring Charges#

When subscription is created via in-app purchase, our back-end communicates with the native ecosystem to check and confirm whether a rebill has been successfully issued and paid. This is done independently from the native application and all the rebill transaction and access records related to them will be automatically created by our system.

Reporting and Management Functionalities#

In addition to the support for implementing payments, the InPlayer system features additional reporting and management functionalities, related to the payment actions that our system offers.

Reporting#

Our system provides payment reports, subscription reports and asset access reports that you can generate as a merchant. Each report renders details for each record. During the in-app payments, these records are being stored in our system, therefore, you have the reports available for usage.

Regarding the type of records that concern you, proceed to the following link(s):

Management#

In the case of in-app payments, the actions to be taken depend on the ecosystems themselves and the extent to which they allow external control over payments and subscriptions created in their systems. At the moment, there are two supporting functionalities in play i.e. subscription cancellation and refund. You can cancel subscription for your users and refund others, directly from the InPlayer dashboard.

As part of the management section of the platform, our system supports a specific type of voucher called in-app voucher. To learn more of the in-app voucher, please refer to the following guide:

In-app Voucher

Edit this page