Skip to content

Purchases

Jump to bottom
Oren Kosto edited this page Mar 15, 2017 · 14 revisions

The Bamboo Video Platform supports creation and management of purchases, whether the purchases are made using the platform itself, or via a 3rd party service, while only using Bamboo for storing the purchase metadata.

The API calls related to purchases are explained in the Bamboo API reference.

The purchase API offers 2 major services - Purchasing and Validating existing purchases.

Purchasing

The purchasing service allows end users to purchase content and finalize it using the Bamboo platform. Purchases and payments can be done directly with Bamboo (using the supported payment gateways), or using 3rd party services, while using Bamboo only to store information about who purchased what. Purchases can also be assigned to end users manually by an administrator using the API directly. The purchase metadata will be stored and associated with the end user on Bamboo.

Prerequisites

  • To purchase using Bamboo, the end user must be registered and logged in to Bamboo.
  • To assign purchases manually to an end user, we must be logged in as an administrator.

Usage

If you are an administrator assigning a purchase to a different end user, you must first try to retrieve the end user to ensure it exists on Bamboo. If the end user does not exist on Bamboo, we must create it. After creation, we'll need to login using the end user's credentials, or an administrator user. Perform the Add Purchase API request The request URL should look something like:

http://mywebsite.bamboo-video.com/api/user/newuser@email.com/purchase?format=json

If we are logged in as the end user, we can also use:

http://mywebsite.bamboo-video.com/api/user/0/purchase?format=json

The request body should contain the purchase metadata. It should look something like:

{
  "type": 1, //the object type. 1 is a media entry.
  "objectId": "<ENTRY_ID>", // the id of the purchased object.
  "service": 2, //the service used for the purchase. 2 is Bamboo, also used for storing purchases made by 3rd party services.
  "price": "<ENTRY_PRICE>", //the amount of money that was charged for the purchase. This value can be formatted with the currency symbol (i.e. $4.99). Bamboo will use USD by default of no currency symbol was provided.
  "info": { //additional info about the purchase. Used to store sensitive information like the receipt hash string.
    "<INFO_KEY>": "<INFO_VALUE>"
  }
}

When finalizing a purchase done on Bamboo, the info field should contain all the necessary metadata needed for validating the purchase. Examples include the purchase ID assigned by the payment service that was used, and the receipt string. To ensure the privacy and protection of sensitive information stored on Bamboo, This field will never be returned in any API call, with the exception of content packages. If the payment was done via a 3rd party service, there is no need for the info field. Just make sure to use 2 (Bamboo) under the service field to indicate that the payment was not done with Bamboo.

Upon purchase, if the purchase was made directly by the end user using Bamboo, Bamboo also performs a validation process to ensure that only valid purchases are assigned and stored. When using a 3rd party service, the validation service will always pass and the purchase will be stored immediately.

The API response should indicate whether the purchase object was successfully assigned to the user. The response should look something like:

{
  "result": true
}

Listing Existing Purchases

The Bamboo API can be used to retrieve all of the purchases that are registered to an end user. This is useful for presenting a list of available/purchased content to the end user.

Prerequisites

Usage

Perform the Purchase List API request. The request URL should look something like:

http://mywebsite.bamboo-video.com/api/user/0/purchase?format=json

The API response should contain all of the purchase objects currently registered to the end user. Packages will be displayed as package items, and not the content items associated with the packages. The response should look something like:

[
  {
    "type": 1, //the object type. 1 is a media entry
    "objectId": "<ENTRY_ID>", // the id of the purchased object.
    "service": 2 //the service used for the purchase. 2 is Bamboo, also used for storing purchases made by 3rd party services.
  },
  {...}
]

Validating Purchases

Purchase validation checks whether a user has a valid purchase for an object (or a content package that includes the object) with a given ID. This is useful for when the user wishes to consume certain content. Before allowing the consumption of the content, we will want to check if the end user has access to it by having a valid purchase of that content.

Prerequisites

Usage

Given an object ID (i.e. a media entry with the ID: 0_9jfo2eoo), Perform the Validation API request for the ID. The request URL should look something like:

http://mywebsite.bamboo-video.com/api/user/0/purchase/0_9jfo2eoo?format=json

The API response should indicate whether the end user has access to the content, or a content package that includes the content. The response should look something like:

{
  "result": true
}
Clone this wiki locally