Payments Tutorial

Facebook Payments is a payment system that offers users a safe, easy and fast way to pay for digital and virtual goods, in games and apps across Facebook. It also offers an easy way for developers to be paid, along with a set of tools to streamline your business operations.

What makes Facebook Payments a great choice for developers and users?

• Facebook users trust the Facebook brand, and feel comfortable storing their payment information with Facebook and buying with their Facebook credentials.
• Facebook Payments is available internationally and supports 80+ payment methods in 50+ countries around the world, all via one simple API. And we're always actively working to expand our global footprint.

Developers already building on Facebook Platform can use the Graph API and Dialogs to integrate with our payments APIs. This API enables developers to focus on building great apps, while Facebook takes care of all the overhead of processing payments and mitigating fraud.

In this document, we'll walk through six steps you can take to use Facebook Payments to turn your app into a sustainable business.

• Step 1: Register your company
• Step 2: Set up your callbacks
• Step 3: Invoke the Pay dialog
• Step 4: Display prices in local currency
• Step 5: Access orders created via Graph API to ensure orders are created properly
• Step 6: Download reports from API

Step 1: Register your company

We'll begin by assuming you've set up your app to run on Facebook Canvas, and you're ready to enable payments. Once your app has been created you can follow the steps in our tutorial showing how to register your company.

Step 2: Set up your callbacks

You'll need to implement a Payments callback - a RESTful, web-facing service providing two functions. One,

1. payments_get_items, allows us to query your server for details of the specific item that the user wishes to purchase.
2. payments_status_update, allows us to tell your server when a payment is complete, and that you should award the user the item purchased.

By having you host this component on your server, and by signing all traffic to it, we are able to prevent malicious users from manipulating the request. Detailed documentation on the callback, including complete PHP code for a simple implementation, can be found in the payment callback docs.

At this point, you can start building a catalog of items and their prices (in Facebook Credits), and build out a storefront to sell them within your app.

Once you've written and deployed the callback, you can configure your app to use it on the "Payments" tab of the "Settings" page by providing its URL. This would also be a convenient time to configure yourself as a Payments Tester, which will allow you to make test purchases in your app without being charged (or paid, of course). Enter your Facebook user ID, and that of anyone else you'd like to designate, in the "Payments Testers" field and click "Save Changes".

You may want to test the complete payment flow with real money later; simply remove your user ID from the field and save.

Step 3: Invoke the Pay dialog

Within your app's store, you'll need to display a control that allows users to buy each item, typically a button. Your next step will be to invoke Facebook's pay dialog, which shows the user the item they're going to buy and its price, allows them to choose a payment method, gets purchase confirmation, and finally sends out either an order ID, or an indication that the purchase was canceled.

To bring up the dialog, implement and configure your Payments callback as described above (otherwise, the dialog will display an error message), then call the function FB.ui() from the Facebook Javascript SDK, passing in a dictionary with properties method, action, and order_info, plus a function which will be called with either the order ID on completion. Note that although the JS callback is a good way to find out when the user has finished interacting with the dialog, it's not a good idea to rely on it in delivering your virtual goods. You should use the payment_status_update callback, to deliver your virtual goods to the user.

FB.ui(
  {
    method: 'pay',
    action: 'buy_item',
    // order_info can be anything you want; it will be passed to your 
    // Payments callback's payments_get_items function, which should 
    // be able to process and respond to this data.
    order_info: {'item_id': '1a'}, // Maximum of 31 chars
  },
  callback_function
)

The resulting dialog, showing the item's name, description, image, and price in Facebook Credits, looks like this.

The Pay Dialog documentation has a fuller explanation, including additional options for displaying the dialog and usage notes.

Step 4: Display prices in local currency

Once you have implemented the basic purchase flow, you should consider displaying prices in a user's preferred real-world currency, rather than Facebook Credits. Apps that take this extra step show improved monetization, and the experience is clearer and more familiar for users.

There are three things you need to do: first, get the user's currency data; second, convert your app's prices from Credits into that currency, and display the result; third, invoke the Pay dialog with a flag to indicate that it should do the same.

To get the user's currency preferences, call the Graph API function GET https://graph.facebook.com/USER_ID?fields=currency. You'll get an object containing the name of the user's local currency, the number of decimal places to display, and the exchange rate to and from Facebook Credits. For example, it might look like this.

{ "currency":  {
    "user_currency":"EUR",
    "currency_exchange":12.363417,
    "currency_exchange_inverse":0.080883788,
    "currency_offset":100
  },
  "id": 221987449
}

Next, convert all of your app's prices into user_currency by multiplying the price in credits by currency_exchange_inverse, rounding to the nearest 1/currency_offset. You may also want to translate the ISO-4217-3 currency code into a friendly representation (in this case, "€") and use a locale-appropriate decimal separator.

In Javascript, you might write a function taking a Credits price and the object from the Graph API, and returning a localized price, like this.

function convertPrice(price, currencyData) {
var currmap = {
        USD: '$',
        EUR: '€', //... cover whichever currencies are relevant to your app
    }
    var currency = currmap[currencyData.currency.user_currency]
        || currencyData.currency.user_currency, // in case the map doesn't cover it
    rate = currencyData.currency.currency_exchange_inverse,
    offset = currencyData.currency.currency_offset;

    // JS Math.round only rounds to int, so work around that
    var localPrice = String(Math.round(price * rate * offset)); 

    // Using string operations - you could also use floor(division) and mod
    offset = {1:0, 10:-1, 100:-2, 1000: -3}[offset];
    var minorUnits = localPrice.substr(offset),
        majorUnits = localPrice.substring(0, localPrice.length + offset) || "0",
        separator = (1.1).toLocaleString()[1]; // use the locale-correct decimal

    var displayPrice = currency + String(majorUnits) +
        (minorUnits ? separator + minorUnits : '');
    return displayPrice;
}

Finally, invoke the Pay dialog with an additional parameter, dev_purchase_params: {'oscif': true}, to signal that it should use local currency representations of prices as well.

FB.ui(
  {
    method: 'pay',
    action: 'buy_item',
    order_info: {'item_id': '1a'}, // Maximum of 31 chars
    dev_purchase_params: {'oscif': true}
  },
  callback_function
)

The resulting dialog will look like this.

Complete details are available in the Local Currency documentation.

Step 5: Access orders created via Graph API to ensure orders are created properly

If a user completes an order, the server receives a status update (to placed) which includes a field called order_id , which identifies an order object in the Graph API. You can read the details of an order by making a request to the Graph API using your app access token, at GET https://graph.facebook.com/ORDER_ID. The result looks like this.

{
  "data": [
    {
      "id": "0000000000000",
      "from": 1111111111,
      "to": 1111111111,
      "amount": 6,
      "status": "settled",
      "application": {
        "name": "Agar Man",
        "namespace": "agarman",
        "id": "104191753063425"
      },
      "created_time": "2012-09-01T02:11:49+0000",
      "updated_time": "2012-09-01T02:11:53+0000"
    }
  ],
  "paging": {
    "previous": "https://graph.pprabhu.dev3442.facebook.com/1697818070/payments?limit=1000&since=1346465513",
    "next": "https://graph.pprabhu.dev3442.facebook.com/1697818070/payments?limit=1000&until=1346465513"
  }
}

The server can use this data to verify the current state of an order, or to look up its details after the fact. By calling POST /ORDER_ID with an app token, the server can also update certain properties of the order - this is how, for instance, you should refund a purchase. For more, check the Graph API Order documentation.

Step 6: Download reports from API

Facebook Payments can help you streamline your business processes by integrating with your billing and reconciliation systems, via our Reporting API. This feature gives you a convenient, flexible, reliable, and secure way to download digest-level or detailed reports of transactions in your apps, including purchases, refunds, and chargebacks.

If you go to your account preferences in the upper right hand corner of the App Dashboard, assuming you've set up your company using the instructions in step 1, you’ll find a “Company Settings” tab. There, you can see and edit your company information. One piece of information displayed there is your company’s credentials, an ID and a secret, which are required to access the Reporting API.

To begin, you'll need to generate a company access_token.

Issue the Graph API request

GET https://graph.facebook.com/oauth/access_token?client_id=COMPANY_ID&client_secret=COMPANY_SECRET&grant_type=client_credentials

and save the access_token field from the response. Assuming your company secret doesn't change (which can happen when you rotate the secret), the token will not expire.

Once you have the token, you can issue a request for a report. To get a detailed report - one record per transaction, for all apps associated with your company - use the following request with your company access_token:

GET https://paymentreports.facebook.com/234599349987627/report?date=YYYY-MM-DD&type=detail

Similarly, to get a digest report - one record per app, across your company, per transaction type - use the following request with your company access_token:

GET https://paymentreports.facebook.com/234599349987627/report?date=YYYY-MM-DD&type=digest

In either case, you'll received a ZIP-compressed CSV file as the output.

Reports are generated daily. They contain metadata describing their structure, which you should use rather than hardcoding the field orders for a report section, as the exact specification of any given report section may change. A complete explanation is available via the Reports API documentation.

Congratulations!

Your app is now payment-enabled. You've got a lot of good options for your next step; we recommend that you consider implementing In-App Currency Offers, Payer Promotion, and Subscriptions to add new revenue opportunities to your app. Also, you should follow our Developers blog for feature announcements, case studies, tech talks, and ecosystem news.

Happy hacking!