In App Purchases

Getting Started

In App Purchases are only available if your account has support for Branded Apps. Please get in touch with your account representative if you have any questions about enabling this feature.

Set up developer accounts

VHX Branded Apps can support In App Purchasing on the Apple, Google, and Roku platforms. You'll need to set up developer accounts will need to be set up for each platfom, and then give the VHX team access to those accounts.

Apple

How to create an Apple Developer Account

Google

How to create a Google Play Developer Account

Roku

How to create a Roku Developer Account

Using the API

To use the VHX API, you must first obtain an API key and be familiar with how to use it for authorization. Details about this are here: API Authentication

Create a Customer

After your app has collected your user's email address and some billing data from an in app purchase, submit it to the VHX API to create a customer. Below are examples for how to create customers with in app purchase data from each provider:

Create a customer with in app purchase data

curl -X "POST" "https://api.vhx.tv/customers" 
     -u example_api_key_12345: 
     -H "Content-Type: application/json" 
     -d $'{
            "name":    "Beyoncé Knowles",
            "product": "https://api.vhx.tv/products/9999",
            "email":   "someone@gmail.com",
            "billing": {
              "provider": "apple",
              "receipt":  "MIIcVgYJKoZIhv..."
            }
          }'

The "billing" object will vary based on the provider being verified. Here is what the billing object should look like for each provider:

// Apple
"billing": {
  "provider": "apple",
  "receipt":  "MIIcVgYJKoZIhv..."
}

// Google
"billing": {
  "provider": "google",
  "package_name": "tv.vhx.yourpackagename", // this value is defined in Google Play
  "subscription_id": "yearly",              // this value is defined in Google Play
  "token": "abcdefghijklmnopqrstuvwxyz"
}

// Roku
"billing": {
  "provider": "roku",
  "transaction_id": "xxxxxxxxxxxx"
}

If successful, you will receive a response with status 200. The JSON response will include the customer's ID and an oAuth 2 token that can you use to authenticate them against our API.

More information on using oAuth2 with the VHX API.

{
  "id": 1,
  "name": "Beyoncé Knowles",
  "email": "someone@gmail.com",
  "created_at": "2016-02-11T20:19:30Z",
  "updated_at": "2016-02-11T20:19:30Z",
  "_links": {
    "self":  { "href": "https://api.vhx.tv/customers/1" }
  },
  "_embedded": {
    "oauth": {
      "access_token": "xxxxxxx",
      "refresh_token": "xxxxxxx",
      "token_type": "bearer",
      "expires_in": 7200,
      "scope": "public"
    },
    "products": [
      {
        "_links": {
          "self": { "href": "http://api.crystal.dev/products/1234" },
        },
        "id": 1234,
        "name": "Your Subscription Plan",
        "description": "...",
        "thumbnail": {
          "small":  "https://...",
          "medium": "https://...",
          "large":  "https://..."
        },
        "is_active": true,
        "series_count": 1,
        "movies_count": 0,
        "playlists_count": 13,
        "sections_count": 0,
        "categories_count": 0,
        "types": ["subscription"]
      }
    ]
  }
}

Verify a Customer

If you have a customer's ID or email address, you can check whether or not they are subscribed to your product with this API call.

# Check if customer 123 is subscribed to product 9999
curl -X "GET" "https://api.vhx.tv/customers/123&product_id=9999" 
     -u example_api_key_12345:

# Check if customer with email address customer@email.com is subscribed to product 9999
curl -X "GET" "https://api.vhx.tv/customers?email=customer@email.com&product_id=9999" 
     -u example_api_key_12345:

If the customer is subscribed, you will receive this response:

{
  "_links": {
    "self":  { "href": "https://api.vhx.tv/customers?email=someone@gmail.com&product=https://api.vhx.tv/products/####" },
    "first": { "href": "https://api.vhx.tv/customers?email=someone@gmail.com&product=https://api.vhx.tv/products/####&page=1" },
    "prev":  { "href": null },
    "next":  { "href": null },
    "last":  { "href": null }
  },
  "count": 1,
  "total": 1,
  "_embedded": {
    "customers": [
      {
        "_links": {
          "self":  { "href": "https://api.vhx.tv/customers/1" }
        },
        "_embedded": {},
        "id": 1,
        "name": "Customer Name",
        "email": "customer@email.com",
        "created_at": "2014-02-25T20:19:30Z",
        "updated_at": "2014-02-25T20:19:30Z"
      }
    ]
  }
}

Find a Customer with billing data

All of our supported billing platforms have a "restore purchase" function, which will provide you with billing data when a customer has already purchased your product within the app. As a convenience, you can use this data against our API to authenticate the user.

If successful, you will receive an identical response to Create a Customer. Also note that this API call also makes use of the platform-dependent "billing" object.

curl -X "POST" "https://api.vhx.tv/customers/find_by_billing" 
     -u example_api_key_12345: 
     -H "Content-Type: application/json" 
     -d $'{
            "product": "https://api.vhx.tv/products/####",
            "billing": {
              "provider": "apple",
              "receipt":  "MIIcVgYJKoZIhv..."
            }
          }'