TinyPass Developer's Resources

Integration

Tinypass SDK implementations are currently available in the following programming languages: Java, PHP, .NET, and Ruby. These libraries are available for download here.

Don't see a match for your project? Just let us know (support@tinypass.com) and we'll see what we can do!


Creating a Publisher Account

To get started with Tinypass, you'll need to first create an account at (Tinypass Sandbox or Tinypass Production).

Tinypass offers two different environments for processing requests. The sandbox environment is used for testing and development. In the sandbox, some features have been simplified to ease testing. Additionally, all transactions are virtual and no money is processed. Our sandbox and production environments are entirely separate.

Take note of your Application AID and private key, both found on your account dashboard. You'll need these to authenticate your integration below.

Your private key should be protected and hidden from public view.


Basic Tinypass Usage

The example below shows a client that has some content on their web site which they consider premium. The client wishes to charge their users for 24-hours of access to the premium content.

Step 1 - Prerequisites

In the HEAD of your HTML page, include the tinypass.js file. For example:

<script type="text/javascript" src="https://code.tinypass.com/tinypass.js"></script>

Step 2 - Configuration

/* Include Tinypass - make sure to use the correct path */
include_once "/path/to/api/TinyPass.php";
 
TinyPass::$AID = "your_sandbox_aid";
TinyPass::$PRIVATE_KEY = "your_sandbox_private_key";
TinyPass::$SANDBOX = true;

TinyPass.SANDBOX = true;
TinyPass.AID = "your_sandbox_aid";
TinyPass.PRIVATE_KEY = "your_sandbox_private_key";

TinyPass.TP.SANDBOX = true;
TinyPass.TP.AID = "your_sandbox_aid";
TinyPass.TP.PRIVATE_KEY = "your_sandbox_private_key";

Tinypass.sandbox = true
Tinypass.aid = "your_sandbox_aid"
Tinypass.private_key = "your_sandbox_private_key"

Parameters:

  • aid - 10 character application ID ( retrieved from merchant account )
  • private_key - 40 character application private key ( retrieved from merchant account )

Step 3 - Check Access

At this point, we need to check if the user already has access to the requested resource. The Tinypass widget stores encrypted user access information in the browser cookie.

/* Include TinyPass - make sure to use the correct path */
include_once "/path/to/api/TinyPass.php"
 
/* Load the incoming request cookie header into AccessTokenStore, which will parse
 * out the user access information
 */
$rid = "unique_resource_id";
$store = new TPAccessTokenStore();
$store->loadTokensFromCookie($_COOKIE);
$token = $store->getAccessToken($rid);
if($token->isAccessGranted()) {
     //Access granted! Display requested resource to the user
} else {
     //Access denied! Proceed with the next steps and display a Tinypass button...
}

/* Load the incoming request cookie header into AccessTokenStore, which will parse
 * out the user access information
 */
String rid = "unique_resource_id";
AccessTokenStore store = new AccessTokenStore();
store.loadTokensFromCookie(request.getHeader("cookie"));
AccessToken token = store.getAccessToken(rid);
if(token.isAccessGranted()) {
     //Access granted! Display requested resource to the user
} else {
     //Access denied! Proceed with the next steps and display a Tinypass button...
}

/* Load the incoming request cookie header into AccessTokenStore, which will parse
 * out the user access information
 */
var rid = "unique_resource_id";
var store = new AccessTokenStore();
store.LoadTokensFromCookie(Request.Headers["cookie"]);
var token = store.GetAccessToken(rid);
if(token.IsAccessGranted()) {
     //Access granted! Display requested resource to the user
} else {
     //Access denied! Proceed with the next steps and display a Tinypass button...
}

# Load the incoming request cookie header into AccessTokenStore, which will parse
# out the user access information
 
rid = 'unique_resource_id'
store = Tinypass::AccessTokenStore.new
store.load_tokens_from_cookie(cookies)
if store.get_access_token(rid).access_granted?
    # Access granted! Display requested resource to the user.
else
    # Access denied! Proceed with the next steps and display a Tinypass button…
end

Step 4 - Define the Resource

/* Include TinyPass - make sure to use the correct path */
include_once "/path/to/api/TinyPass.php"
 
$resource = new TPResource("Premium-Content", "Site wide premium content access");

Resource resource = new Resource("Premium-Content", "Site wide premium content access");

var resource = new Resource("Premium-Content", "Site wide premium content access");

resource = Tinypass::Resource.new('Premium-Content', 'Site wide premium content access')

A web site can define many resources. For example, each page could be a resource with its url being a unique RID. In our case however, there's only one resource to access (access to the whole web site).

Step 5 - Create an Offer and Configure Price Options

An offer is the combination of resource information, pricing options, and other polices. The same resource could be offered under various configurations and price options.

$po1 = new TPPriceOption(".50", "24 hours");
$po2 = new TPPriceOption(".99", "1 week");
$offer = new TPOffer($resource, array($po1, $po2));

PriceOption po1 = new PriceOption(".50", "24 hours");
PriceOption po2 = new PriceOption(".99", "1 week");
Offer offer = new Offer(resource, po1, po2);

var po1 = new PriceOption(".50", "24 hours");
var po2 = new PriceOption(".99", "1 week");
var offer = new Offer(resource, po1, po2);

po1 = Tinypass::PriceOption.new('.50', '24 hours')
po2 = Tinypass::PriceOption.new('.99', '1 week')
offer = Tinypass::Offer.new(resource, po1, po2)

An offer can be configured with up to 3 Price Options.

Step 6 - Create Request And Generate Button HTML

If the user doesn't have access to the resource, the offer created in the previous step must be displayed. For a user to make a purchase, the offer must be sent to Tinypass. This is accomplished by creating a request and then generating the button HTML that can be embedded into your site.

As you can see from the code below, there is an additional line where the “generateTag” method is called. This script output generates all the necessary glue for sending your request safely and securely to Tinypass.

//create a request and generate an HTML button
$purchaseRequest = new TPPurchaseRequest($offer);
$buttonHTML = $purchaseRequest->generateTag();

//create a request and generate an HTML button
PurchaseRequest purchaseRequest = new PurchaseRequest(offer);
String buttonHTML = purchaseRequest.generateTag();
 
// or this can be combined into a single line
String buttonHTML = new PurchaseRequest(offer).generateTag();

//create a request and generate an HTML button
var purchaseRequest = new PurchaseRequest(offer);
var buttonHTML = purchaseRequest.GenerateTag();
 
// or this can be combined into a single line
var buttonHTML = new PurchaseRequest(offer).GenerateTag();

purchase_request = Tinypass::PurchaseRequest.new(offer)
button_html = purchase_request.generate_tag
 
# or this can be combined into a single line
button_html = Tinypass::PurchaseRequest.new(offer).generate_tag

Once buttonHTML is inserted into the page, it will render a Tinypass button:


Defining a Callback Listener

You can a define a custom function that is called when access is granted or denied on a specific resource. The listener is declared using the following line:

$purchaseRequest->setCallback("myFunction");

purchaseRequest.setCallback("myFunction");
 
// the full syntax for creating a button with a callback
String buttonHTML = new PurchaseRequest(offer).setCallback("myFunction").generateTag();

PurchaseRequest.SetCallback("MyFunction");
 
// the full syntax for creating a button with a callback
String ButtonHTML = new PurchaseRequest(offer).SetCallback("myFunction").GenerateTag();

purchase_request.callback = 'myFunction'
 
# the full syntax for creating a button with a callback
button_html = Tinypass::PurchaseRequest.new(offer).callback('myFunction').generate_tag

It is NOT required to define a javascript callback listener. By default, the Tinypass API will automatically perform a page reload in the event of a state change.

Be aware that you can only set the callback method prior to calling the “generateTag” function (in step 6).

<script type="text/javascript">
    function myFunction(status) {
        if (status.state == 'granted') {
              //reload or perform any other logic based on the state
              window.location.reload();
        }
    }
</script>

where status is an object containing the following properties:

  • aid (application id)
  • uid (user id)
  • rid (resource id)
  • state (granted/denied)
  • user_ref (user reference or uid)

Full Example

Following is the full integration in one file:

// Embed tinypass.js in the HTML header
echo "<script type='text/javascript' src='http://code.tinypass.com/tinypass.js'></script>";
 
/* Include TinyPass - make sure to use the correct path */
include_once "/path/to/api/TinyPass.php"
 
// configure Tinypass
TinyPass::$SANDBOX = true;
TinyPass::$AID = "sandbox_aid";
TinyPass::$PRIVATE_KEY = "sandbox_private_key";
 
$rid = "unique_resource_id";
$store = new TPAccessTokenStore();
$store->loadTokensFromCookie($_COOKIE);
$token = $store->getAccessToken($rid);
if($token->isAccessGranted()) {
    //Access granted! Display requested resource to the user
 
} else {
    //Access denied! Proceed with the next steps and display a Tinypass button...
 
    $resource = new TPResource($rid, "Site wide premium content access");
 
    $po1 = new TPPriceOption(".50", "24 hours");
    $po2 = new TPPriceOption(".99", "1 week");
    $offer = new TPOffer($resource, array($po1, $po2));
 
    $request = new TPPurchaseRequest($offer);
    $buttonHTML = $request->setCallback("myFunction")->generateTag();
 
    //output button HTML in the place where Tinypass button is supposed to be rendered
    echo $buttonHTML;
}

// Embed tinypass.js in the HTML header
out.println(
  "<script type='text/javascript' src='http://code.tinypass.com/tinypass.js'></script>"
);
 
// configure Tinypass
TinyPass.SANDBOX = true;
TinyPass.AID = "sandbox_aid";
TinyPass.PRIVATE_KEY = "sandbox_private_key";
 
String rid = "unique_resource_id";
AccessTokenStore store = new AccessTokenStore();
store.loadTokensFromCookie(request.getHeader("cookie"));
if(store.getAccessToken(rid).isAccessGranted()) {
    //Access granted! Display requested resource to the user
 
} else {
    //Access denied! Proceed with the next steps and display a Tinypass button...
 
    Resource resource = new Resource(rid, "Site wide premium content access");
 
    PriceOption po1 = new PriceOption(".50", "24 hours");
    PriceOption po2 = new PriceOption(".99", "1 week");
    Offer offer = new Offer(resource, po1, po2);
 
    String buttonHTML = new PurchaseRequest(offer).setCallback("myFunction").generateTag();
 
    //output button HTML in the place where Tinypass button is supposed to be rendered
    out.println(buttonHTML);
}

// Embed tinypass.js in the HTML header
// <script type='text/javascript' src='http://code.tinypass.com/tinypass.js'></script>
 
// configure Tinypass
TinyPass.TP.SANDBOX = true;
TinyPass.TP.AID = "sandbox_aid";
TinyPass.TP.PRIVATE_KEY = "sandbox_private_key";
 
var rid = "unique_resource_id";
var store = new AccessTokenStore();
store.LoadTokensFromCookie(Request.Headers["cookie"]);
if(store.GetAccessToken(rid).IsAccessGranted()) {
    //Access granted! Display requested resource to the user
 
} else {
    //Access denied! Proceed with the next steps and display a Tinypass button...
 
    var resource = new Resource(rid, "Site wide premium content access");
 
    var po1 = new PriceOption(".50", "24 hours");
    var po2 = new PriceOption(".99", "1 week");
    var offer = new Offer(resource, po1, po2);
 
    var buttonHTML = new PurchaseRequest(offer).SetCallback("myFunction").GenerateTag();
 
    //output button HTML in the place where Tinypass button is supposed to be rendered
    Response.Write(buttonHTML);
}

# Embed tinypass.js in the HTML header
# <script type='text/javascript' src='http://code.tinypass.com/tinypass.js'></script>
 
# Configure Tinypass
Tinypass.aid = "your_sandbox_aid"
Tinypass.private_key = "your_sandbox_private_key"
Tinypass.sandbox = true
 
rid = 'unique_resource_id'
store = Tinypass::AccessTokenStore.new
store.load_tokens_from_cookie(cookies)
if store.get_access_token(rid).access_granted?
    # Access granted! Display requested resource to the user.
else
    # Access denied! Proceed with the next steps and display a Tinypass button…
 
    resource = Tinypass::Resource.new(rid, 'Site wide premium content access')
 
    po1 = Tinypass::PriceOption.new('.50', '24 hours')
    po2 = Tinypass::PriceOption.new('.99', '1 week')
    offer = Tinypass::Offer.new(resource, po1, po2)
 
    purchase_request = Tinypass::PurchaseRequest.new(offer)
    purchase_request.callback = 'myFunction'
    button_html = purchase_request.generate_tag
end


Web Site With Registered Users

Lets look at another use case. The same publisher is running a web site with its own user base. Every user is required to create an account and login in order to purchase access. Every user in the system has a unique username.

It is possible to “tag” every purchase request with the username of a logged in user. Once a purchase is completed, the granted access will be associated with that username. Publishers will be able to use REST API to query Tinypass for:

  • user access information
  • revoke access and issue refunds

While integrating with Tinypass, there are a few questions each publisher will have to answer:

  1. Do I want to take full advantage of Tinypass widget or simply redirect users to Tinypass with a “return URL”?
  2. Where do I want to store user access information:
    • Encrypted user's browser cookie
    • Local database
    • Always query Tinypass

Tinypass Widget

The Tinypass Widget is something that makes the Tinypass experience smooth for end users and easy for publishers to implement. In the simplest terms, here's what happens:

  1. A Tinypass button is generated and shown on publisher's page
  2. Users clicks on the button and completes purchases in the popup
  3. There's an event once the purchase is completed
  4. Encrypted user access information is stored in the browser cookie
  5. When the page is reloaded, Tinypass client parses the browser cookie and is able to tell if access is granted

In some cases however, the publisher might want to have more control over the workflow and not use browser cookies for storage. Tinypass can let you do that.

Instead of step 6 of the integration process, publisher can generate a URL and redirect users directly to Tinypass to complete the purchase.

$purchaseRequest = TPPurchaseRequest($offer);
 
//set user reference (username in this case)
$purchaseRequest->setUserRef($username);
 
$link = $purchaseRequest->generateLink("publisher_return_url", "publisher_cancel_url");

PurchaseRequest purchaseRequest = new PurchaseRequest(offer);
 
//set user reference (username in this case)
purchaseRequest.setUserRef(username);
 
String link = purchaseRequest.generateLink("publisher_return_url", "publisher_cancel_url");

var purchaseRequest = new PurchaseRequest(offer);
 
//set user reference (username in this case)
purchaseRequest.SetUserRef(username);
 
var link = purchaseRequest.GenerateLink("publisher_return_url", "publisher_cancel_url");

purchase_request = Tinypass::PurchaseRequest.new(offer)
 
#set user reference (username in this case)
purchase_request.user_ref = username
 
link = purchase_request.generate_link('return_url', 'cancel_url')

Once the purchase is completed, the user will be redirected back to the provided return url. The return url will be appended with additional parameters:

  • aid (application ID)
  • rid (resource ID)
  • user_ref (user reference)

At this point the publisher should validate user access with the following REST call:

$accessDetails = TinyPass::fetchAccessDetail(array("rid"=>$rid, "user_ref"=>$user_ref));
 
if($accessDetails->isAccessGranted()) {
    //Access is granted! Store access information and/or simply display requested resource
}

AccessDetails accessDetails = TinyPass.fetchAccessDetail(rid, userRef);
 
if(accessDetails.isAccessGranted()) {
    //Access is granted! Store access information and/or simply display requested resource
}

var accessDetails = TinyPass.TP.FetchAccessDetail(rid, userRef);
 
if(accessDetails.IsAccessGranted()) {
    //Access is granted! Store access information and/or simply display requested resource
}

access_details = Tinypass.fetch_access_detail('my_rid', 'my_user_ref')
 
if access_details.access_granted?
    # Access is granted! Store access information and/or simply display requested resource
end

Access Information

Publishers can choose to store user access information in the local database, in any other type of storage (like browser cookies or session), or to simply query Tinypass via REST API.

Storing access information locally has obvious performance benefits. However, the publisher has to keep in mind that the user access state might change in the future. For example, the publisher might revoke access via the Tinypass dashboard. The best approach to solve synchronization issues like that is to query Tinypass whenever the user logs into the publisher's site.

//Get all user access(s)
$params = array("user_ref" => username);
$ads = TinyPass::fetchAccessDetails($params);
 
//store access details locally...

//Get all user access(s)
HashMap<String,Object> params = new HashMap<String, Object>();
params.put("user_ref", username);
PagedList<AccessDetails> ads = TinyPass.fetchAccessDetails(params);
 
//store access details locally...

//Get all user access(s)
var parameters = new Dictionary<string, object>();
parameters.Add("user_ref", username);
var ads = TinyPass.TP.FetchAccessDetails(parameters);
 
//store access details locally...

#Get all user access(s)
params = {user_ref: 'username'}
ads = Tinypass.fetch_access_details(params)
 
#Store access details locally

Purchase Request Options

Publishers can change the look of the Tinypass button and ticket screens. Currently the following options are available:

  • btn.size - change the size of the Tinypass button (0 - small (default), 1 - medium, 2 - large)
  • tkt.img - the URL of an image displayed on the left side of the first ticket screen (the screen that a user sees after clicking on the Tinypass button). The URL should be hosted on HTTPS
  • tkt.upsell.img - the URL of an image displayed on the left side of the upsell ticket screen. The URL should be hosted on HTTPS

$ticketoptions = array();
$ticketoptions["btn.size"] = "2";
$purchaseRequest = new TPPurchaseRequest($offer, $ticketoptions);

PurchaseRequest purchaseRequest = new PurchaseRequest(offer);
purchaseRequest.getOptions().put("btn.size", "2");

PurchaseRequest purchaseRequest = new PurchaseRequest(offer);
purchaseRequest.GetOptions().set("btn.size", "2");

purchase_request = Tinypass::PurchaseRequest.new(offer, ticket_options)
ticket_options = {btn_size: "2"}

Interested in using a custom image as a subscribe button in lieu of our standard blue ticket? Simply embed the $buttonHTML variable in a hidden div, embed your image as a standard HTML image, and use jQuery to bind that image to the hidden $buttonHTML as a click event.

<script type="text/javascript">
$(function(){
    $("#subscribe-button").click(function(){
        $("#tp_button_unique_resource_id").click();
    })
})
</script>

Dedicated Login Button

If you would like to have a dedicated login button in addition to the Tinypass-generated subscribe button, simply use the following tag:

<tp:login text='Login Here'></tp:login>