Payments Best Practices

The Local Currency Payments system allows the developer complete flexibility to price goods in any region specific local currency, at arbitrary price-points. The system simplifies the purchase experience for users, maximizes the performance of the payment flow, and makes it easy for developers to price virtual goods for a global audience.

This guide details some best implementation practices for the Local Currency Payments system, including detail on how to offer an optimal user experience and extract the most value from common scenarios surrounding the system.

For a technical outline of the product, see How-to: Local Currency Payments.

Order Fulfillment and RTUs

The Local Currency Payments system exposes several methods to ensure that a user has processed a transaction successfully in your game or application. After the user completes the purchase flow, you need to check the payment status, fulfill the order if the payment was successful and inform the user that they have received the product they purchased.

The primary method used for order fulfillment is through the JavaScript SDK, via the order confirmation callback. This method is preferable as it completes instantly and creates a responsive user experience. However, a common issue not covered via this method is the ability to fulfill asynchronous payment methods when the completion of a payment is not performed in realtime. Furthermore, when a user's connectivity to your application is unreliable, the callback may never be triggered. A common scenario where this may occur is if the user loses connection to the internet mid-flow or closes their browser.

It is therefore mandatory that you also subscribe to Realtime Updates for payments in your application.

Real-time Updates will notify your server whenever a transaction is completed or disputed. Moreover, if a user elects to pay via an asynchronous payment method, this is the only way that you will be notified that the transaction was fulfilled. Be aware, it is perfectly possible in some situations that an asynchronous payment transaction may take several days to complete.

Realtime Updates will not be sent until the developer subscribes to the actions and disputes fields for the payment object. To read more about order fulfillment and Real Time Updates, see Realtime Updates for Payments

International Pricing

The Local Currency Payments system allows for separate, distinct price points to be specified for the same item in any of the supported local currencies. While Facebook will automatically generate prices for every one of the supported currencies by converting from the first currency you specify, the ability to explicitly define price points for each currency gives you a number of benefits:

Charge users in a currency they're familiar using. This helps the user get a feel of the value of the item they're purchasing.
You can specify evenly rounded prices for each region. For example, in the diagram below, the 'Friend Smash Starter Pack' is available at £3.50 GBP. This is a nicely rounded number that British users are familiar seeing, as opposed to an automatic conversion from the initially specified $4.99 USD, which would for example convert to an uglier £3.31 GBP.
You can target each region with a different pricing strategy. Certain regions of the world may monetize better or worse than others. Take advantage of this market knowledge by pricing appropriately and tailoring your products to your audience.

The Open Graph og:product object which implements the example shown above would be defined as:

<head prefix=
   "og: http://ogp.me/ns# 
    fb: http://ogp.me/ns/fb# 
    product: http://ogp.me/ns/product#">
   <meta property="og:type"                   content="og:product" />
   <meta property="og:title"                  content="Friend Smash Starter Pack" />
   <meta property="og:image"                  content="http://www.friendsmash.com/images/pack_50.png" />
   <meta property="og:description"            content="A pack of items to give you a smashing start!" />
   <meta property="og:url"                    content="http://www.friendsmash.com/og/pack.html" />
   <meta property="product:price:amount"      content="4.99"/>
   <meta property="product:price:currency"    content="USD"/>
   <meta property="product:price:amount"      content="3.99"/>
   <meta property="product:price:currency"    content="EUR"/>
   <meta property="product:price:amount"      content="3.50"/>
   <meta property="product:price:currency"    content="GBP"/>
   <meta property="product:price:amount"      content="9.50"/>
   <meta property="product:price:currency"    content="TRY"/>
   <meta property="product:price:amount"      content="35.00"/>
   <meta property="product:price:currency"    content="SEK"/>
</head>

Use Insights to analyze your users

While it would be ideal to be able to specify pricing information explicitly for every region globally, it is probably an unreasonable maintenance task to continually monitor and respond to market conditions and the expectations of users in each of the dozens of currencies Facebook supports. It makes sense therefore to optimize the purchase experience for regions based on the popularity of your app. The demographic breakdown of your users is available under the 'Users' section of App Insights, under the subsection titled 'Demographics - Total Users'. By analysing this data, you can quickly see where your app is proving most popular and implement optimized payment experiences for users in the currency related to that region. In the diagram below, the darker shaded regions (United States, United Kingdom, Poland, India) are proving popular regions for a sample app, therefore the currencies attached to those regions, (Dollars, Pound Sterling, Zlotys, Rupees) receive explicit price points.

The Open Graph og:product object which implements the example shown above would be defined as:

<head prefix=
   "og: http://ogp.me/ns# 
    fb: http://ogp.me/ns/fb# 
    product: http://ogp.me/ns/product#">
   <meta property="og:type"                   content="og:product" />
   <meta property="og:title"                  content="Friend Smash Starter Pack" />
   <meta property="og:image"                  content="http://www.friendsmash.com/images/pack_50.png" />
   <meta property="og:description"            content="A pack of items to give you a smashing start!" />
   <meta property="og:url"                    content="http://www.friendsmash.com/og/pack.html" />
   <meta property="product:price:amount"      content="4.99"/>
   <meta property="product:price:currency"    content="USD"/>
   <meta property="product:price:amount"      content="15.00"/>
   <meta property="product:price:currency"    content="PLN"/>
   <meta property="product:price:amount"      content="3.50"/>
   <meta property="product:price:currency"    content="GBP"/>
   <meta property="product:price:amount"      content="300.00"/>
   <meta property="product:price:currency"    content="INR"/>
</head>

In-Game Currency

The Local Currency Payments system enforces pricing restraints for mobile price points in certain circumstances. This limitation can reduce your pricing flexibility and may cause difficulty when determining the price of virtual items within your app.

It is therefore recommended that you create a virtual currency within your app, and price virtual items within that currency, rather than directly in the user's local currency.

When a user purchases a virtual currency, they typically obtain a given quantity of that currency, as opposed to a single unit of a virtual item. Allowing Facebook to be flexible with the quantity you wish to sell to a user can help handle the pricing restriction mentioned above. Full details on how this works is described in the Handling Price Jumping section of the How-to: Local Currency Payments - User Payment Flow doc.

As a developer, you manage the balance of the user's virtual currency through your server. They can then exchange this currency for virtual items, with no pricing limitations caused by payment instruments.

Implementing a virtual currency also has the additional benefit of allowing the user to store extra funds in your system. Typically this allows you to maximize the conversion of each purchase event and up-sell the user to purchase higher priced items.

Up-sell currency packages by providing incremental promotions

The Local Currency Payments system supports the ability for developers to provide a quantity parameter when invoking the Pay Dialog in order to control the amount of a given item that will be sold to a user. Facebook will multiply the cost of a single unit of the item with the given quantity to reach the final cost of the goods. This feature will typically be coupled with a virtual-currency, providing you with full flexibility to sell any quantity of the currency at any given time.

As Facebook derives the price for the good through a simple multiplication, it logically follows that the quantity of the currency offered to the user will scale linearly with the price. This is not always an ideal pricing strategy, as it offers no incentive for a user to purchase more than the absolute minimum they require at any given time.

It is recommended therefore, that you consider the creation of currency packages, which sell a fixed quantity of the virtual currency at a discounted price. You can then offer incremental incentives for a user to purchase a higher quantity of your currency at any given time. These incentives can boost player loyalty, offer improved value for highly engaged players and positively impact revenue. Upsell bundles

An example of how this might look in an in-game store is below:

Display a confirmation on purchase completion

A key design decision behind the Local Currency Payment system was to optimise for the speed and efficiency of the user checkout experience. As part of this design, there is no confirmation dialog displayed to the user after a purchase. Instead, as soon as a purchase is confirmed by the user, the Pay Dialog closes, calling the JavaScript callback specified by the developer and returning control to the app. It is therefore incumbent on the developer to implement a purchase confirmation UI experience, letting the player know the status of the transaction.

This confirmation may not be necessary in the case that the user cancels out of the payment flow, but should certainly be shown when a transaction completes successfully and the user receives their virtual currency or item, or in the case of an error, to inform the user they did not receive their item.

Important Note - Be aware that in the case of Price Jumping, the quantity of a given item that you are selling to the user has the potential to change during the purchase flow. This means, if you provided a quantity_min or quantity_max parameter when invoking the Pay Dialog you cannot assume that the quantity passed into the FB.ui() method will be the same as the quantity returned in the JavaScript callback. In these circumstances, it is important you parse the JavaScript object returned to the callback and use the final quantity value reported to display your confirmation and fulfill the order for the user.

Full details on how to construct this callback, and what data you are provided is detailed here.

Create a mobile store

In certain regions of the world, mobile carrier billing, either direct to the user's phone bill, or via SMS are the most common form of payment mechanism. In these locations it is valuable to optimize the payment flow for users of this type. There are two primary ways in which you can optimize the user experience for paying with mobile, Mobile Price Points and Mobile Shortcutting.

Mobile Price Points

Users paying through mobile payment methods are subject to carrier specific fixed price points, limiting the prices available for them at which to purchase. Facebook provides the developer the ability to query the user for their supported mobile price points ahead of time, allowing for the presentation of virtual goods and currency packages that match what the user is able to pay. For more information, please see the Mobile Price Points API Reference doc.

A simple HTTP GET call to the Graph API is all that is needed to fetch the mobile price points for a given user.

GET https://graph.facebook.com/me?fields=payment_mobile_pricepoints&amp;access_token=USER_ACCESS_TOKEN

Given these constraints, we encourage you to create a 'Buy with Mobile' or similar button in your app which links to a mobile specific purchase experience. Within this mobile specific store, developers should adjust the quantity and price of virtual item and currency packages to reflect the fixed price points available for that user.

If you do not implement this, the user is likely to encounter a situation where they attempt to purchase an item at a price unavailable to them through their mobile payment instrument. In this circumstance, Facebook is forced to round up the price to the nearest available mobile price point, with the difference between the item's original price and the user's price point being collected by Facebook as an additional fee. This is known as Price Jumping, and has the potential to create a confusing and inefficient user experience. For more information, please see the How-to: Local Currency Payments - Handling Price Jumping doc.

However, if you explicitly create a mobile pricing table, which only displays currency or items for sale at the established mobile price points for the given user, you can avoid price jumping altogether. This creates a purchase experience which offers the most value to the end-user per transaction, and minimizes the potential for user confusion during the purchase flow.

Mobile Shortcutting

In addition to providing the developer with the available mobile price points for a given user, Facebook also improves the purchase experience for mobile payment through Mobile Shortcutting.

Mobile Shortcutting allows the developer to 'shortcut' the payment flow and present the user with an immediate ability to pay with mobile, reducing the number of clicks, and therefore friction involved with making the purchase. If you follow the best practice above and implement a mobile store, you can safely choose to enable Mobile Shortcutting for users within this store, as they have already elected to pay with their mobile.

Mobile Shortcutting is enabled by providing an additional parameter when invoking the Pay Dialog. You must include the parameter pricepoint_id with the value set to the corresponding id found in the Graph API return data for the user's mobile price point you want to charge at. You are required to provide a specific, valid mobile-price point in order to shortcut to the mobile payment flow.

FB.ui(
  "method": "pay",
  "action": "purchaseitem",
  "product": "http://www.friendsmash.com/og/coins.html",
  "pricepoint_id": "x1b2dedt",
);

On invoking the Pay Dialog with Mobile Shortcutting enabled, the user is taken straight to the mobile purchase flow.

Learn more about the API specification here

Use the A/B Testing API

The monetization of virtual goods is a complex and nuanced topic, often requiring incremental improvements in order to reach optimal performance. A common tactic used to iterate, measure and evolve conversion rates and bottom line revenue generated from a given app is the A/B test. Typically you will run an experiment, exposing two or more variants of your product to a group of users. After some time you can establish, typically through statistical analysis, which variant performed best and with what confidence. This information then influences future product decisions as you incrementally improve the product.

To help facilitate this process, Facebook has created a simple API that segments users into 1 of 10 rollout groups.

When you query the API, we will return a payment_test_group value between 1 and 10. We have taken steps to ensure this segmentation is truly random and will generate reliable results with little to no demographic, economic or social biases.

To check which payment_test_group a user is in, you can query the graph API as below, with a user or app access token.

GET https://graph.facebook.com/USER_ID?fields=payment_test_group&amp;access_token=ACCESS_TOKEN

Response An integer value between 1 and 10.

Once you have this information, you can choose which variant of your product to show, be it purchase flow, item price point, or something else, to each segment of users. For example, if you wanted to run an A/B test with two variants, you would provide all users with a payment_test_group of 5 or less with experience 'A', and all users with a payment_test_group of 6 or more with experience 'B'.

Consider Sales and Events

Sales can be an effective means to increase revenue for a limited timespan. When coupled with the Local Currency Payments system, you can target sales to specific groups of users within your app. You may choose to target all users, users in a specific region, highly-engaged players, non-highly engaged players, even down to the individual user level, for loyalty discounts or birthday offers, etc.

It is important to note that sales on premium goods can shift revenue forward without actually increasing overall payment volume. It is common for sales to dip after a sale period has ended, as users with a fixed budget, who would previously have paid in the post-sale period were incentivized to spend sooner. You therefore need to be cautious of creating too many sales or offers. Users very quickly learn that sales happen and may choose to delay a purchase at full price while they wait for a sale. Payer conversion is critically important to the ultimate success of an app, and so while sales are very powerful, they should be used judiciously.

Events and tournaments are a great way to create an incredibly engaged base of players around a set of new content. When events and tournaments are structured effectively, you can create demand around time sensitive content and increase your monetization. Discounts offered during a crucial moment of an event or tournament are proven to be highly effective. Using Facebook's social channels, such as App Notifications, can help amplify new content, tournaments and events to increase engagement and retention, which can ultimately lead to an increase in monetization.

Offer Subscriptions

Using Facebook's Subscriptions feature, you can create a recurring revenue stream, enabling new kinds of seller experiences. You can use Subscriptions to implement game rental, a VIP club or extra premium features and unlockables within you app. Subscribed users tend to be more engaged, thereby sharing more and creating an additional source of organic user acquisition. Subscriptions are an incremental revenue opportunity, since you run them alongside the traditional sale of virtual goods.

A subscription's recurrence period is set by the developer, providing the flexibilty to offer features on an ongoing basis that best suits your app. A monthly or weekly subscription cycle is typical, but any length is supported. Facebook additionally supports a free trial of a subscription, providing the user with 'try-before-you-buy' reassurance.

Plan your virtual goods catalog

There are several kinds of goods that are common across a wide range of game types. Here, we'll discuss three paradigmatic cases: vanity items, which are in-game collectibles; functional items, which include consumable play enhancements ("buffs") as well as durable ones; and session extenders, such as energy packs or arcade tokens.

Vanity Items

Vanity Items are in game virtual goods that have no direct effect on game play. Generally these are cosmetic items that can be used to enhance a players visible avatar, house, base, town, etc.

An important motivator for purchasing vanity items is scarcity or uniqueness. This can be enhanced by implementing limited time sales or limiting the quantity of an item sold. Should the item prove to be popular it can be re-introduced into the ecosystem at later points in the games lifecycle as a slight variant on the original item, so as to preserve the uniqueness of the original purchasers item.

Functional Items and Buffs

Functional Items are the opposite of Vanity Items. These are items that can be purchased in-game that have a direct effect on gameplay - a faster car or more powerful weapon.

Buffs are consumable items (limited number of uses) that can be applied to a player’s game state, increasing their ability to perform certain tasks. For example a Match Three game can sell an item that can be used once and increases a combo multiplier for the current session, allowing the player to achieve a greater score.

It is important to think carefully about how to use Buffs in your game if you are building a skill-based game. It is important that buffs don't become the way to cheat, or "buy your way to victory", but are an integral part of game play.

Session Extensions (Speed Ups and Energy Packs)

These are items commonly sold in Social Games that increase session length or decrease the amount of down time between sessions.

A common mechanic is to limit session length by introducing a limited use but recharging resource. All actions performed in the game require some amount of this resource, and once the player runs out, they will need to wait for it to recharge, which happens slowly over time. As an alternative to waiting, players can purchase items that give a quick boost of energy, allowing them to keep playing without leaving the current session.

Another common mechanic is to have the passage of real time affect the completion of activities. This is usually found in city management or empire building games, where players need to train troops or construct buildings. The activity requires X amount of time to complete. If players want to expedite the construction, they can do so by spending a certain amount of virtual currency.

Setting a fixed number of moves or plays per session is another method to throttle player consumption of content and allow for monetization opportunities. This is similar to tokens in a real world arcade. Each day the player receives X tokens. Once these tokens have been spent the player must return the following day, or purchase additional tokens to keep playing.

Implement Facebook Game Card In-App Redemption

Facebook Game Cards are available in over 20 countries and in approximately 130,000 retail locations worldwide. With the new local currency payments system, you are now be able to implement the Game Card Dialog to directly redeem the full value of any Facebook Game Card straight into your game’s in-app currency or item . Through this direct in-app redemption, developers can utilize gift cards as a new payment option, taking advantage of incremental gifting opportunities and cash-based purchases.

You can find more information on how to implement in-app gift card redemption on the Facebook redeeming Game Cards in Local Currency guide.