Upgrading to TrialPay Direct Offer Integrations

On September 12th, 2013, Facebook will deprecate Facebook Credits, so you must change your offer integrations to work directly with TrialPay. You must make these changes even if you are already issuing your own game's currency on the Facebook platform. To do this:
  • update any existing DealSpot and Offer Wall code snippets
  • set up a new og:product object for your in-app currency on Facebook
  • set up a payment script that we can call whenever a customer completes an offer

1. Create a Merchant Account

Your TrialPay merchant account is where you will be able to access reporting, testing, and customization for your integrations. Your merchant account is also where we store your payment information and post your payment history. It only takes 5 minutes to get started! Create your account now! You will only need one merchant account for all of your Facebook apps.

2. Set up your currency on Facebook

Replace your existing currency object (fbpayment:currency) with an og:product object instance. Follow these Facebook instructions to set up the new object: https://developers.facebook.com/docs/howtos/payments/definingproducts/#ogproduct_currency Notes:
  • We do not support dynamic pricing. If your existing currency already uses dynamic pricing, create a new currency object with static pricing for offers.
  • Be sure to use Facebook’s object debug tool to verify that your object has been set up correctly.
  • Please make sure that one of the prices that you list is USD as that is what TrialPay will use

3. Update your existing code snippets

The code snippets aren't changing too much. If you've already integrated our code snippets, you only need to make the following changes:
  • Change the "mode" parameter value from "fbpayments" to "fbdirect"
  • Add a new "tp_vendor_id" parameter with your TrialPay developer ID as its value (available in your account's notification preferences).
  • Add a “callback_url” parameter with your payment script URL as its value
Refer to the DealSpot and Offer Wall sections below for details.

3.1 DealSpot in-swf integrations

Replace any existing in-swf DealSpot code snippets with the new code snippet below.
https://s-assets.tp-cdn.com/static3/swf/dealspot.swf?mode=<mode>&app_id=<app_id>&tp_vendor_id=<tp_vendor_id>&callback_url=<callback_url>&currency_url=<currency_url>&sid=<sid>

Required Parameters

Parameter names are case-sensitive. All values must be URL encoded.
Placeholder Sample Value Description
<mode> fbdirect This should always be fbdirect.
<app_id> abcDEF123 Your Facebook app ID.
<tp_vendor_id> abcDEF123 Your TrialPay vendor ID (available in your account's notification preferences).
<callback_url> http%3a%2f%2fwww.acmesoft.com %2ftastymorsels%2fcallback.php The payment script's URL.
<currency_url> https%3a%2f%2fwww.acmesoft.com %2fvc%2fcoins.php The URL to your Facebook currency OpenGraph object.
<sid> abcDEF123 Your customer's Facebook third-party-ID (not the FB UID).

Optional Parameters

Parameter names are case-sensitive. All values must be URL encoded. Refer to the "Using the Optional Parameters" section for more details about some of these parameters.
Parameter Sample Value Description
onTransact my_ontransact An object you can use to tell when a customer completes an offer.
onOfferAvailable offer_available The name of your own JavaScript function that DealSpot will call if there are one or more offers to show the customer.
onOfferUnavailable alternative_promo The name of your own JavaScript function that DealSpot will call if there are no offers to show the customer.
touchpoint 1 Identifies individual DealSpot integrations. This is required if you are integrating more than one DealSpot into your game or app.
onOpen overlay_opened The name of your own JavaScript function that DealSpot will call when a customer clicks the in-game icon.
onClose overlay_closed The name of your own JavaScript function that DealSpot will call when a customer closes the offer overlay.
width 300 Overrides the SWF’s width (default is 100). Only do this if you are using custom in-game icons.
height 250 Overrides the SWF’s height (default is 100). Only do this if you are using custom in-game icons.
position_top 250 Positions the offer overlay X pixels from the top edge of your swf’s host page.
position_left 250 Positions the offer overlay X pixels from the left edge of your swf’s host page.
zIndex 5 Displays the overlay in the specified stack order.
order_info %7b%22item+id%22+%3a+%221a%22%7d Your own custom parameters. This can be any string. We will pass this back to you when we call your payment callback script. Character limit = 100.

3.2 DealSpot out-of-swf integrations

Replace any existing out-of-swf DealSpot code snippets with the new code snippet below:
<span id="<DOM_ID>"></span>
<script type="text/javascript">
  window.trialpayAsync = window.trialpayAsync || [];
  window.trialpayAsync.push(function() {
    TRIALPAY.social.render_dealspot_swf( {
      "id" : "<DOM_ID>",
      "mode" : "<mode>",
      "app_id" : "<app_id>",
      "tp_vendor_id" : "<tp_vendor_id>",
      "callback_url" : "<callback_url>",
      "currency_url" : "<currency_url>",
      "sid" : "<sid>"
    });
  });

  var script = document.createElement("script");
  script.type = "text/javascript";
  script.src = "//s-assets.tp-cdn.com/static3/js/api/payment_overlay.js";
  document.getElementsByTagName("body")[0].appendChild(script);
</script>

Required Parameters

Placeholder Sample Value Description
<DOM_ID> trialpay_dealspot A unique HTML DOM ID you've chosen for this DealSpot touchpoint.
<mode> fbdirect This should always be fbdirect.
<app_id> abcDEF123 Your Facebook app ID.
<tp_vendor_id> acdDEF123 Your TrialPay vendor ID (available in your account's notification preferences).
<callback_url> http://www.acmesoft.com/tastymorsels/callback.php Your payment script's URL.
<currency_url> http://www.acmesoft.com/vc/coins.php The URL to your Facebook currency OpenGraph object.
<sid> abcDEF123 Your customer's Facebook third-party-ID (not the FB UID).

Optional Parameters

Refer to the "Using the Optional Parameters" section for more details about some of these parameters.
Parameter Sample Value Description
onTransact my_ontransact An object you can use to tell when a customer completes an offer.
onOfferAvailable offer_available The name of your own JavaScript function that DealSpot will call if there are one or more offers to show the customer.
onOfferUnavailable alternative_promo The name of your own JavaScript function that DealSpot will call if there are no offers to show the customer.
touchpoint 1 Identifies individual DealSpot integrations. This is required if you are integrating more than one DealSpot in your game or app.
onOpen overlay_opened The name of your own JavaScript function that DealSpot will call when a customer clicks the in-game icon.
onClose overlay_closed The name of your own JavaScript function that DealSpot will call when a customer closes the offer overlay.
width 300 Overrides the SWF’s width (default is 100). Only do this if you are using custom in-game icons.
height 250 Overrides the SWF’s height (default is 100). Only do this if you are using custom in-game icons.
position_top 250 Positions the offer overlay X pixels from the top edge of your swf’s host page.
position_left 250 Positions the offer overlay X pixels from the left edge of your swf’s host page.
zIndex 5 Displays the overlay in the specified stack order.
order_info {"item id" : "1a"} Your own custom parameters. This can be any string. We will pass this back to you when we call your payment callback script. Character limit = 100.

3.3 Offer Wall

Replace any existing Offer Wall code snippets with the new code snippet below.
<a href="#" onclick="tp_earn(); return false;">Earn Currency</a>

<script type="text/javascript">
  function tp_earn() {
    TRIALPAY.fb.show_overlay("<app_id>",
                             "<mode>",
                             {
                               tp_vendor_id: "<tp_vendor_id>",
                               callback_url: "<callback_url>",
                               currency_url: "<currency_url>",
                               sid : "<sid>"
                             });
  }

  var script = document.createElement("script");
  script.type = "text/javascript";
  script.src = "//s-assets.tp-cdn.com/static3/js/api/payment_overlay.js";
  document.getElementsByTagName("body")[0].appendChild(script);
</script>

Required Parameters

Placeholder Sample Value Description
<app_id> abcDEF123 Your Facebook app ID.
<mode> fbdirect This should always be fbdirect.
<tp_vendor_id> abcDEF123 Your TrialPay vendor ID (available in your account's notification preferences).
<callback_url> http://www.acmesoft.com/tastymorsels/callback.php Your payment script's URL.
<currency_url> http://www.acmesoft.com/vc/coins.php The URL to your Facebook currency OpenGraph object.
<sid> abcDEF123 Your customer's Facebook third-party-ID (not the FB UID).

Optional Parameters

Refer to the "Optional Parameters" section for more details about some of these parameters.
Parameter Sample Value Description
onTransact my_ontransact An object you can use to tell when a customer completes an offer.
touchpoint 1 Identifies individual Offer Wall integrations. This is required if you are integrating more than one Offer Wall into your game or app.
onOpen overlay_opened The name of your own JavaScript function that the Offer Wall will call when a customer clicks the in-game icon.
onClose overlay_closed The name of your own JavaScript function that the Offer Wall will call when a customer closes the offer overlay.
order_info {"item id" : "1a"} Your own custom parameters. This can be any string. We will pass this back to you when we call your payment callback script. Character limit = 100.
zIndex 5 Displays the overlay in the specified stack order.

4. Set up a payment callback script

Currently, when a customer completes an offer, we call Facebook who then calls your payment callback script. After the transition, we will call your payment script directly. In order for this to work, you must set up a script that can receive a FORM POST request from us (it will come from the IP range 54.183.233.157, 54.183.231.95, 70.42.249.1 – 70.42.249.255, and 199.68.156.0 - 199.68.159.255). Whenever we call the script, you must:
  1. validate the request,
  2. issue the reward to the customer, and
  3. respond to the request and indicate success or failure.

4.1 POST body contents

The POST body will contain a single URL encoded string comprised of the following variables:
Key Sample Value Description
app_id AaBb1234 Your Facebook app ID.
sid CcDd5678 Your customer's Facebook third-party-ID.
oid abcd1234 A unique ID that identifies the transaction in our system.
reward_amount 100 The amount of currency to issue the customer.
callback_url http%3a%2f%2fwww.acmesoft.com%2ftastymorsels %2fcallback.php Your payment script's URL.
currency_url https%3a%2f%2fwww.acmesoft.com %2fvc%2fcoins.php The URL to your Facebook currency OpenGraph object.
order_info %7b%27item_id%27%3a+%271a%27%7d Custom, game-specific information you pass to us when you first launch DealSpot or the Offer Wall.

4.2 Validating the request

We will sign the POST body string with an HMAC-MD5 hash using the string and your notification key and assign the hash to the "TrialPay-HMAC-MD5" header. You must validate this hash before responding our request. To validate the hash:
  1. Plug the POST body string and your notification key into an HMAC-MD5 hashing function. You can get your notification/secret key by accessing your account's notification preferences.
  2. Generate your own hash from the above.
  3. Compare the two hashes.
If the keys match, the request is valid and you should issue the customer the reward and respond to the request indicating success. If they keys do not match, the request is invalid, so you should not issue a reward. Respond to our request and indicate failure. For sample validation code, please refer to this help article.

4.3 Responding To The Request

After you attempt to issue the customer credits, you must respond to our request and indicate if you succeeded or failed.

Indicating Success

To indicate success, respond with success code 200 and the number 1 in the body. For example:
HTTP/1.0 200 OK
Date: Sat, 04 Apr 2009 23:59:59 GMT
Content-length: 8

1

Indicating Failure

To indicate failure, respond with success a 400- or 500-level status code and any human readable text that indicates the nature of the failure. For example:
HTTP/1.0 400 ERROR
Date: Sat, 04 Apr 2009 23:59:59 GMT
Content-length: 90

Duplicate Transaction

5. Using the optional parameters

If you are implementing our code snippets for the first time, or have not used these features before, use the following instructions to listen for various events. If you are already taking advantage of our event listening features, you can disregard this section (nothing changed).

onOfferAvailable/onOfferUnavailable

These parameters can only be used with DealSpot. Before the in-game icon appears we check if there are any offers to show the customer. You can listen for the result and call your own functions by assigning the functions to the onOfferAvailable or onOfferUnavailable optional parameters (alternatively you can use ActionScript and listen for the trialpayOfferAvailable or trialpayOfferUnavailable events). For example, let’s say you want to display an alternative promotion if there are no offers to show the customer. You create a function named alternative_promo, which you define somewhere in your game/page, and assign it to the onOfferUnavailable optional parameter:
<span id="<DOM_ID>"></span>
<script type="text/javascript">
  function alternative_promo()
  {
    // code to show alternative promo
  }

  window.trialpayAsync = window.trialpayAsync || [];
  window.trialpayAsync.push(function() {
    TRIALPAY.social.render_dealspot_swf( {
      "id" : "<DOM_ID>",
      "app_id" : "<app_id>",
      "tp_vendor_id" : "<tp_vendor_id>",
      "mode" : "<mode>",
      "callback_url" : "<callback_url>",
      "sid" : "<sid>",
      "onOfferUnavailable" : "alternative_promo"
    });
  });

  var script = document.createElement("script");
  script.type = "text/javascript";
  script.src = "//s-assets.tp-cdn.com/static3/js/api/payment_overlay.js";
  document.getElementsByTagName("body")[0].appendChild(script);
</script>

onTransact

You can tell when a customer completes an offer by adding the onTransact parameter and object to the code snippet. For example, in DealSpot:
<span id="<DOM_ID>"></span>
<script type="text/javascript">  function my_ontransact(obj)
  {
    alert('my_ontransact. completions: ' + obj.completions + ". vc_amount: " + obj.vc_amount + ". vc_name: " + obj.vc_name);
  }

  window.trialpayAsync = window.trialpayAsync || [];
  window.trialpayAsync.push(function() {
    TRIALPAY.social.render_dealspot_swf( {
      "id" : "<DOM_ID>",
      "app_id" : "<app_id>",
      "tp_vendor_id" : "<tp_vendor_id>",
      "mode" : "<mode>",
      "callback_url" : "<callback_url>",
      "sid" : "<sid>",
      "onOfferUnavailable" : "<offer_unavailable>",
      "onTransact" : "my_ontransact"
    });
  });

  var script = document.createElement("script");
  script.type = "text/javascript";
  script.src = "//s-assets.tp-cdn.com/static3/js/api/payment_overlay.js";
  document.getElementsByTagName("body")[0].appendChild(script);
</script>
When a customer completes an offer we’ll call the my_ontransact function and you can retrieve the following properties:
  • completions — number of completions (e.g., 1).
  • vc_amount — amount of virtual currency rewarded (e.g. 15)
  • vc_name — the name of the virtual currency rewarded (e.g. Gold Coins).
Note that if we timeout while waiting for a completion notification from the advertiser, we’ll call the function anyway and set both completion and vc_amount to zero.

onOpen/onClose

You can call your own function whenever a customer opens or closes the offer overlay by including the onOpen or onClose parameters in the code snippet. For example, in DealSpot:
<span id="<DOM_ID>"></span>
<script type="text/javascript">
  function overlay_closed()
  {
    // code to execute when customer closes overlay
  }

  window.trialpayAsync = window.trialpayAsync || [];
  window.trialpayAsync.push(function() {
    TRIALPAY.social.render_dealspot_swf( {
      "id" : "<DOM_ID>",
      "app_id" : "<app_id>",
      "tp_vendor_id" : "<tp_vendor_id>",
      "mode" : "<mode>",
      "callback_url" : "<callback_url>",
      "sid" : "<sid>",
      "onClose" : "overlay_closed"
    });
  });

  var script = document.createElement("script");
  script.type = "text/javascript";
  script.src = "//s-assets.tp-cdn.com/static3/js/api/payment_overlay.js";
  document.getElementsByTagName("body")[0].appendChild(script);
</script>

6. Testing your integration

6.1 Add private apps to our system

To test TrialPay on your private apps, you will need to manually add your private App IDs to our system.
  • Log into your Merchant Account and add your app in your account's Test Settings.
  • If you see "Error: Your App ID already exists in our platform" there is no need to manually add your App ID into our system.
  • You are now ready to integrate TrialPay on your private app!

6.2 Whitelisting your Facebook account for our test offer

We can whitelist your Facebook account's HID for our test offer, which can simulate an offer completion. To find your HID:

6.3 Viewing failed callback notifications

You must respond to our callback with an HTTP status code of 200 and a body of 1. You can view all failed responses in your Merchant Account under Failed Notifications