Integrating the Offer Wall

Our offer wall is designed to be easy to integrate. This document walks you through all the steps needed to get TrialPay's offer wall up and running in your Facebook app.

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: Set up your Open Graph Currency Object 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.
  • Use Facebook's object debug tool to verify that your object has been set up correctly.
  • Make sure that one of the prices that you list is USD. This is what TrialPay will use.
  • We do support a "product:price:amount" of less than 0.01

3. Integrate the Offer Wall

The Offer Wall appears when a customer taps an in-game touchpoint of your own design. For example, you might create an "Earn Points" tab that launches the Offer Wall, or create an "Earn Points" option in an existing payment interface. Offer Wall touchpoint After a user clicks the in-game touchpoint, the offer wall is launched. Offer Wall  

3.1 Offer Wall Code Snippet

Add the following code snippet to your game or app.
<a href="#" onclick="tp_earn(); return false;">Earn Currency</a>

<script type="text/javascript">
  function tp_earn() {
    TRIALPAY.fb.show_overlay(
      "<app_id>",
      "fbdirect", {
        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>
To display the Offer Wall, call the earnCredits() function whenever a user clicks your in-game touchpoint.

3.2 Required Parameters

Placeholder Sample Value Description
<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://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). Note: SID must not exceed 220 characters in length.

3.3 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. Character limit = 100.
zIndex 5 Displays the offer wall in the specified stack order.

4. Set up a payment callback script

To issue virtual currency or virtual items, you need to set up a payment callback directly with TrialPay. 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). To ensure transaction integrity, you must:
  • Validate the request
  • Issue the reward to the customer
  • 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:

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 (note that some languages will rename this header to "HTTP_TRIALPAY_HMAC_MD5"). You must validate this hash before responding our request. To validate the hash:
  • Plug the POST body string and your notification key (available in your account's notification preferences).
  • Generate your own hash from the above.
  • 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
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.

5.1 onTransact

You can tell when a customer completes an offer by adding the onTransact parameter and object to the code snippet. For example:
<a href="#" onclick="tp_earn(); return false;" id="<DOM_ID>">Earn Currency</a>

<script type="text/javascript">
  function my_onTransact(obj) {
    alert('my_ontransact.completions: ' + obj.completions + ". vc_amount: " + obj.vc_amount + ". vc_name: " + obj.vc_name);
  }

  function tp_earn() {
    TRIALPAY.fb.show_overlay("<app_id>", "fbdirect", {
      "tp_vendor_id" : "<tp_vendor_id>",
      "callback_url" : "<callback_url>",
      "currency_url" : "<currency_url>",
      "sid" : "<sid>",
      "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.

5.2 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:
<a href="#" onclick="tp_earn(); return false;" id="<DOM_ID>">Earn Currency</a>

<script type="text/javascript"> 
  function overlay_closed() {
    // code to execute when customer closes overlay
  }

  function overlay_opened() {
    // code to execute when customer opens overlay
  }

  function tp_earn() {
    TRIALPAY.fb.show_overlay("<app_id>",
      "fbdirect", {
      "tp_vendor_id" : "<tp_vendor_id>",
      "callback_url" : "<callback_url>",
      "currency_url" : "<currency_url>",
      "sid" : "<sid>",
      "onClose" : "overlay_closed",
      "onOpen" : "overlay_opened" 
    });
  }
  
  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 3rd Party ID for our test offer

You can whitelist your 3rd Party ID for our test offer, which can simulate an offer completion. To gain access to the test offer:
  • Log into your Merchant Account and add your 3rd Party ID/App ID pairing in your account's Test Settings.
  • You will need to add 3rd party IDs for each individual app that you are testing
  • You should now be able to see our test offer, Quick and Simple Survey, in your TrialPay placements

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.
Placeholder Sample Value Description
<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://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).
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. Character limit = 100.
zIndex 5 Displays the offer wall in the specified stack order.
Key Sample Value Description
app_id AaBb1234 Your Facebook app ID.
sid CcDd5678 Your customer's Facebook third-party-ID.
oid abcd1234 A unique TrialPay 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.
  Note: Publisher may not implement TrialPay's services or technology on applications that are directed at, or collect data from, children under the age of 13.