Facebook Payments Overview

Facebook's Payments system allows the developer complete flexibility to price goods in any region specific local currency, at arbitrary price-points. This new system simplifies the purchase experience for users, improves the performance of the payment flow, and makes it easier for developers to price virtual goods for a global audience.
This document details the key product features of the Facebook Payments system, including developer features, user experience and common usage scenarios.

Payment Features

There are two common product offerings that developers make available within their app store, both of which are supported by the payments system:

Virtual Currency

The recommended model is for developers to sell their own in-app virtual currency, such as 'coins', through our payments system. This currency can then be used within the game in exchange for virtual goods. When selling an in-app currency, you provide Facebook with a quantity parameter, dictating the amount of currency you are selling to the user at a given time. Facebook will then render the payment dialog, showing that amount, before your currency's name.

In-app Items

Alternatively, you may choose to sell individual, discrete products in your game at a set price. A simple example of this approach might be offering a 'starter pack', which contains a number of goods at a discounted price. By omitting a quantity parameter during the payment flow, Facebook assumes you are selling a single unit of your item.
The Facebook Payments system has no concept of a stored balance. This means users will directly, atomically, purchase items or virtual currencies at set price-points, with no ability to 'over pay' and store remaining funds with Facebook. Each transaction within your app will directly bill the user. The only exception to this is Facebook gift cards, which will provide users with a store of funds from which they can make purchases.

Static and Dynamic Pricing

In addition to the two types of product you can specify, payment products can be priced in two different ways.

Static Pricing

The simplest method for pricing a product is Static Pricing. You specify a fixed price for the item in any number of local currencies. Specifying the price up-front allows Facebook to cache the pricing data, enabling the ability to instantly display the Pay Dialog, with no delay to the user.
The ability to provide a price for the item in multiple currencies means you have complete flexibility to target each region with different pricing strategies, and specify appropriately rounded prices that users are familiar seeing. If you do not define a price point for a particular local currency, users of that currency will have their price automatically calculated based upon the current exchange rate between the first currency you specify and that target currency.
This architecture provides the flexibility to price goods appropriate to each region in which you're selling, but gives the assurance that if you do not provide specific pricing detail for a given region, Facebook will generate and charge an appropriate price for you.

Dynamic Pricing

While Static Pricing is straightforward to implement and provides users with a fast, efficient payment experience, it can sometimes be valuable to gain additional pricing flexibility by dynamically controlling the price of an item at the time of purchase. A common example of the utility of this feature is when implementing a flash sale, where you temporarily reduce the cost of items within your app by a small percentage, or when A/B testing different price-points to optimize conversion. Alternatively, it can be valuable to price goods specifically to individual users, allowing you to implement loyalty discounts.
As with Static Pricing, Facebook will cache the product information provided (title, image etc) to improve the performance of the checkout experience for the user. Additionally however, Facebook will contact your server for pricing information at the point of purchase. Using dynamic pricing introduces a blocking call that must be made to your server during the purchase flow, which slows down the display of the initial pay dialog for users. Whenever possible, it is recommended that you use static pricing. Dynamic pricing should only be used in scenarios where the additional pricing flexibility is required.

Fulfillment

Facebook has streamlined the order fulfillment process to avoid all blocking requests required before the pay dialog is closed and a purchase completed. This makes the user experience of purchasing a virtual item more responsive, leading to higher conversion rates.
There are two primary methods through which you are notified of the outcome of the purchase, and a further method by which you can verify any payment information.
Firstly, Facebook will return details of the order via a JavaScript callback. The data sent to this callback includes:
  • payment_id, which uniquely identifies the transaction.
  • quantity, which indicates the amount of the item which was sold.
  • request_id, optionally, the developer can provide their own unique identification for the transaction when calling the Facebook SDK for Javascript to render the payment dialog. This value is then returned upon purchase completion.
  • status, which indicates the current state of the transaction, i.e. 'pending', 'completed', 'failed' etc.
Secondly, Facebook will issue a realtime update notifying the developer that a new order has completed. The developer can subscribe to the payment_object callback to track order completions, using the payment_id as the unique identity parameter for each transaction.
Thirdly, at any time, the payment_id can be used to verify details of a transaction via the Graph API. Details such as the associated user_id, updated_time and amount can be queried, using thepayment_id. The Graph API will also allow you to access further details including any refunds or disputes associated with the transaction.
If for some reason both the JavaScript callback and the realtime update fail and you do not receive thepayment_id, we also allow you to query the Graph API using the optional request_id parameter, which can be specified by the developer when invoking the Facebook payment dialog.
More details around fulfillment can be found in this section.

User Experience

Buying Currency and Items

Users only pay for the item being purchased and will not have a stored balance after the transaction. The Pay Dialog reflects this by showing the amount billable to the user with each transaction. The only exceptions to this rule, where an existing balance might have cause to be displayed, are a one-time credits migration, or gift cards.
In this first example, the user is purchasing an in-app currency, 'Friend Smash Coins'. A quantity of 100 has been provided, which is reflected in the dialog.
Alternatively, when selling an individual item or bundled package, the quantity you wish to sell will typically always be 1. Therefore, if you either specify a quantity of 1, or omit the quantity parameter altogether, Facebook will not display a quantity figure when rendering the dialog leaving only the product title. This is illustrated in the 'Friend Smash Bomb' example below.

Pricing Items in Specific Currencies

Items may be priced specifically in different currencies, enabling full flexibility with pricing strategies across multiple regions. The example below is another item, the 'Friend Smash Starter Pack', priced specifically for a British audience.
Below the same item is offered, this time aimed at American users, paying in US Dollars.
Although these values are not equal in each currency, the ability to price the item specifically for each region allows you to provide a price point users are familiar seeing (with no strange rounding), and to target different countries with different monetization strategies.

Dynamic Pricing for Different Situations

Items can be priced dynamically, allowing for more control over pricing in real time. Some examples are frequent price changes, A/B testing, sales or loyalty bonuses. In the example below, still for a 'Friend Smash Starter Pack', a user is being charged in Euros.
The user below has attempted to purchase the same item, but under sale conditions. The price can be fetched from the developer at the time of purchase, and the sale can be rendered in the dialog.

Paying with Different Methods

Facebook payments will will always display prices in the user's preferred currency, customising the experience for international users.

Credit Card

If a user chooses to purchase with a credit card, and they have previously purchased on Facebook with a credit card, they are given the option to continue with their previous credit card details, or register a new card.
For the case where the user wishes to purchase with a credit card, but does not have one on file with Facebook, they will see a dialog prompting them to enter new credit card details.
Once they continue with this flow, Facebook will open a new secure window for the user to enter their credit card credentials similar to the one below.

PayPal

If a user chooses to pay through a Paypal account, and already have their PayPal details on file with Facebook, they will see their email below the PayPal option.
Once they click okay, their email address will be automatically entered into the Paypal login window as seen below.
If the user elects to use their Paypal account, but does not have one associated with Facebook already, they will first select the Paypal option as seen below.
Then they will see a new window, prompting them to create a new Paypal account. Finally, they will be returned to complete the purchase.

Mobile

In most regions, users can additionally choose to pay via their mobile carrier, where the charge will appear as part of their monthly carrier bill, either via a direct charge or via SMS.
If the user has not previously entered mobile details with Facebook, they will be prompted to enter that information before the transaction can continue.
In order to confirm the mobile is valid, a code will be sent via SMS to the number the user provides. The user is required to respond to the SMS to complete the registration process.
While our payment partners finish the transaction, the user will see a progress dialog similar to the following before the dialog closes upon completion.
The dialog will close once Facebook has successfully charged the user's Mobile Phone.

Alternate Payment Methods

We also support alternate payment methods such as Western Union and MoneyGram which vary from country to country. You can find more information on what alternate payment methods are supported in each country here.

Mobile Price points and Price Jumping

Certain payment methods, including mobile carrier billing and some alternative pay methods have limitations on the price points available for a user. As a result, sometimes the price the user wishes to pay may not be available. Since the payments system has no concept of a stored balance, Facebook will instead round up the price to the closest price point available that still covers the cost of the item. Such scenarios will result in an additional 'fee' field that reflects the difference between the price of the item and the mobile price point at which the user must be charged.
We use the term "price jumping" to explain this scenario when Facebook is forced to apply this fee to users because the price point they wish to pay is not supported by the selected payment instrument.Read more about price jumping, and how to optimize the cost of items within your app to maximize user value.
In the example above, the item was priced at £10.00 GBP, but that price point was not available to the user looking to make the purchase through their mobile. The closest price point available above the £10.00 GBP cost of the item is at £12.00 GBP, thus, the user sees a 'fee' of £2.00, to cover the difference.
Optimizing Quantity
If the user wishes to purchase a quantity (greater than 1) of an item or currency in your app, then we allow you to specify whether Facebook should attempt to optimize the quantity of the item or currency that the user receives, to yield the maximum value for a given fixed payment price point.
To best illustrate this in action, take the following example:
  • We define a virtual currency, the 'Friend Smash Coin' to be worth $0.05 USD each.
  • The user is prompted to purchase 151 of them, coming to a total cost of $7.55 USD.
  • There is no price point available to the user at $7.55 USD. The closest price points are $7.50 USD ($0.05 below the target price), and $10.00 USD ($2.45 above the target price).
  • If a minimum and maximum quantity are not specified, Facebook is forced to round the price upward to the nearest price point that covers the cost of the item. Therefore the user will be charged $10.00 USD, including a fee of $2.45.
  • However, if a minimum quantity is specified, say at 100, you are giving Facebook permission to round to the lower price point and alter the quantity to match. In this instance Facebook will reduce the quantity to the price point at $7.50 USD. The user will be offered to purchase 150 'Friend Smash Coins' at a flat $7.50 USD, with no fee applied.
It's important to note, this is only possible if you inform Facebook you are flexible with the quantity of the virtual item sold. This often is perfectly acceptable for a virtual currency, but not for a virtual item (where you only wish to sell a single unit). We therefore recommend that developers price their virtual items in their virtual currency rather than directly in a local currency, as much as possible.
Mobile Store and Shortcut
The recommended way to handle price jumping is to create a mobile store where items and currency bundles are priced at the mobile price-points available for the user in that country. We provide an API for you to easily query the price-points for the user, as well as shortcut the user directly into the mobile flow. Using these APIs you can create a great mobile paying experience for users where they never have to experience price jumping or unnecessary fees. See the documentation on Mobile Price Points and Shortcutting for more information.

Getting Started

Developers can start integrating with Facebook Payments right away.
Was this document helpful?