Offers with Payments

Facebook Payments enables users to earn in-app currency by completing engaging advertiser offers. By integrating this feature, developers gain access to an additional revenue channel targeted towards users who are not yet willing to pay for virtual currency. Note: This functionality is not available when an app has sandbox mode turned on.

Facebook has partnered with TrialPay to provide developers with the following implementation types:

• Offerwall. This implementation enables your app to open a Facebook dialog containing an interactive list of compelling advertiser offers. Learn more about TrialPay’s offers here.

• TrialPay's DealSpot. This implementation enables your app to spotlight one offer in-game. Learn more about TrialPay’s DealSpot here.

For both Offerwall and DealSpot implementation types, developers can choose:

• In-app Currency Offers. Offers are denominated in the app's in-game currency.
• Credits Offers. Offers are denominated in credits.

We highly recommend that developers implement the In-app Currency Offers as they tend to convert much better unless developers are using Credits as their in-game currency.

Note: Users can dispute offer orders and that the normal Dispute Flow applies. If a developer refunds a disputed offer order, the user is credited with the credits_amount for the refunded order. It's impossible to reverse completed offers.

---

In-App Currency Offers

This feature allows users to earn app currency by completing advertiser offers. First, you should read the documentation for In-App Currency Orders and implement the steps there. Then:

• Implement an Offerwall or TrialPay's DealSpot which utilizes an in app currency Open Graph object instance.
• Test your integration to make sure it works correctly.

 

Implement an Offerwall or TrialPay's Dealspot.

Offerwall

A best practice is to spotlight offers independently from payment methods in some distint UI element (e.g. a tab). It's important to clearly articulate to users that offers provide an opportunity to earn virtual currency which is distinctly different than paying for virtual currency using a payment method.

To implement an Offerwall containing In-app Currency Offers, you simply need to invoke the Pay Dialog with the following parameters.

1. An object containing the following required attributes:

   Name	Type	Value	Required
   method	String	pay	Yes
   action	String	earn_currency	Yes
   product	String	URL to the app currency Open Graph object instance	Yes

2. A callback pointing to a function which handles Facebook’s response. If Facebook responds with an order_id, please display the user’s updated app currency balance without a complete reload of the game.

Additional notes:

• It’s possible for a user to complete multiple offers in a single Facebook offerwall dialog. Facebook only returns the last completed order_id.

• If you’d like to test various app currency object instances, you can determine which object instance to pass when you invoke the Pay Dialog.

• Facebook uses the data associated with our last scape of the passed app currency object instance.

An example code snippet using Facebook's JavaScript SDK,

function earn_currency() {
  var obj = {
    method: 'pay',
    action: 'earn_currency',
    product: 'URL_TO_APP_CURR_WEBPAGE'
  };
 
  FB.ui(obj, js_callback);
}
 
var js_callback = function(data) {
  if (data['order_id']) {
    // Display the user's updated app currency balance.
  } else if (data['error_code']) {
    // Handle error.
  } else {
    // Handle unknown error.
  }
};

TrialPay's DealSpot

To implement DealSpot refer to TrialPay's DealSpot documentation.

To implement Payer Promotion only DealSpot refer to TrialPay's Payer Promotion DealSpot Documentation.

The pay dialog that users will see when they click on the Payer promotion looks something like this.

The title, image and description you provide for your in-app currency in this Open Graph object will be shown to the user at time of purchase. We highly recommend that you specify a good image, title and description of the currency.

For example in the above dialog, the description of Farmcash is "Use Farm Cash to get premium animals, trees and farm aides for your farm".

Note: The more you can make the description suggest the value that users can get by buying that currency, the more likely the user will redeem the promotion.

 

Test In-app Currency Offers integration.

Setup your app with TrialPay. Please refer to TrialPay's Developer Help Center for more information. If you have further questions, contact your TrialPay account manager or send an email to merchantsupport@trialpay.com.

Note that In-app Currency Offers are unavailable for:

• Users are Platform Test Users.

• Users are listed in the App Dashboard as Edit Settings -> Payments -> Payments Testers.

---

Credits Offers

This feature allows your users to earn credits by completing advertiser offers.

Offerwall

A best practice is to spotlight offers independently from payment methods in some distint UI element (e.g. a tab). It's important to clearly articulate to users that offers provide an opportunity to earn app currency which is distinctly different than paying for app currency using a payment method.

To implement an Offerwall containing Credits Offers, you simply need to invoke the Pay Dialog with the following parameters.

1. An object containing the following required attributes:

   Name	Type	Value	Required
   method	String	pay	Yes
   action	String	earn_credits	Yes

2. A callback pointing to a function which handles Facebook’s response. Since the user is earning credits from Facebook, an order_id is never returned to your JavaScript callback. Your callback only receives the return data parameter error_code with value 1383010 indicating that the user has closed the Offerwall. While it's possible that the user completed an offer, it's not possible for you to determine the number of credits earned.

An example code snippet using Facebook's JavaScript SDK,

function earn_credits() {
  var obj = {
    method: 'pay',
    action: 'earn_credits'
  };
 
  FB.ui(obj, js_callback);
}
 
var js_callback = function(data) {
  if (data['order_id']) {
    // For earn credits orders, Facebook never returns an order id.
  } else if (data['error_code']) {
    // Handle error.
  } else {
    // Handle unknown error.
  }
};

TrialPay's DealSpot

To implement DealSpot refer to TrialPay's DealSpot documentation.

To implement the Payer Promotion only Dealspot refer to TrialPay's Payer Promotion DealSpot Documentation..