Pay Dialog

Dialogs

We are moving from Facebook Credits to local currency pricing, and plan to migrate all game developers on Facebook.com in the third quarter this year. We want to provide ample time for you to review the new documentation. After launch, developers will have a minimum of 90 days to implement the updated payments infrastructure to continue accepting payments. For now, we continue to support Facebook Credits. In the coming weeks, we will provide further updates on when developers can begin integration. Learn more in our local currency FAQs and overview

Overview

The Pay Dialog prompts users to initiate Facebook Credits orders. Developers integrating this dialog can enable their users to pay for digital goods and to earn virtual currencies.

Additional notes:

Only apps on Facebook can open the this dialog.
This dialog only supports desktop display modes: page.
This dialog only supports mobile display mode: touch.
Use of this dialog does not require extended permissions.
Before integrating the Pay Dialog, developers must register their company information and implement the server-side Credits Callbacks. The contents of the Pay Dialog depend on it's use and on how the developer implements the Credits Callbacks if applicable.

JavaScript Example

The following simple JavaScript example demonstrates invoking the FB.ui method using the JavaScript SDK to open a Pay Dialog for item purchases priced in local currency (e.g. USD).

For buy_item orders,

The Pay Dialog only opens if you've responded to the Credits Callback payments_get_items request.
The order_info parameter and value are passed back to your Credits Callback URL when Facebook issues a payments_get_items request. Use this information to determine your payments_get_items response. Note that there is a limit of 31 characters for the order_info parameter.

For other usages, click here.

<html xmlns="http://www.w3.org/1999/xhtml"
      xmlns:fb="http://www.facebook.com/2008/fbml">
  <head>
    <title>Facebook Credits Demo</title>
  </head>
  <body>
    <h2>Buy something...</h2>
    <button onclick="buy()">Buy</button>
    <div id="fb-ui-return-data"></div>
    <div id="fb-root"></div>

    <script src="http://connect.facebook.net/en_US/all.js"></script>
    <script> 
      FB.init({appId: "YOUR_APP_ID", status: true, cookie: true});

      // The dialog only opens if you've implemented the
      // Credits Callback payments_get_items.
      function buy() {
        var obj = {
          method: 'pay',
          action: 'buy_item',
          // You can pass any string, but your payments_get_items must
          // be able to process and respond to this data.
          order_info: {'item_id': '1a'},
          dev_purchase_params: {'oscif': true}
        };

        FB.ui(obj, js_callback);
      }

      // This JavaScript callback handles FB.ui's return data and differs
      // from the Credits Callbacks.
      var js_callback = function(data) {
        if (data['order_id']) {
          // Facebook only returns an order_id if you've implemented
          // the Credits Callback payments_status_update and settled
          // the user's placed order.

          // Notify the user that the purchased item has been delivered
          // without a complete reload of the game.
          write_callback_data(
                    "<br><b>Transaction Completed!</b> </br></br>"
                    + "Data returned from Facebook: </br>"
                    + "Order ID: " + data['order_id'] + "</br>"
                    + "Status: " + data['status']);
        } else if (data['error_code']) {
          // Appropriately alert the user.
          write_callback_data(
                    "<br><b>Transaction Failed!</b> </br></br>"
                    + "Error message returned from Facebook:</br>"
                    + data['error_code'] + " - "
                    + data['error_message']);
        } else {
          // Appropriately alert the user.
          write_callback_data("<br><b>Transaction failed!</b>");
        }
      };

      function write_callback_data(str) {
        document.getElementById('fb-ui-return-data').innerHTML=str;
      }
    </script>
  </body>
</html>

Direct URL Example

You can also open a Pay Dialog by issuing an HTTP GET request to the /dialog/pay endpoint.

For buy_item orders,

The Pay Dialog only opens if you've responded to the Credits Callback payments_get_items request.
The order_info parameter and value are passed back to your Credits Callback URL when Facebook issues a payments_get_items request. Use this information to determine your payments_get_items response.

For other usages, click here.

https://www.facebook.com/dialog/pay?app_id=YOUR_APP_ID&
                                    redirect_uri=YOUR_REDIRECT_URI&
                                    action=buy_item&
                                    order_info={"item_id":"1a"}&
                                    dev_purchase_params={"oscif":true}

Usage Notes

The Pay Dialog can be used for the following circumstances:

Buy item priced in local currency (e.g. USD).
Buy item priced in credits as a currency.
Buy credits priced in local currency (e.g. USD).
Earn credits by completing advertiser offers.
Earn in-app currency by completing advertiser offers.

Buy item priced in local currency (e.g. USD).

To prompt users to purchase an item priced in local currency (e.g. USD), developers should invoke FB.ui with the following properties and values.

Note that Facebook considers app currency (e.g. Fred's App's Cash) to be an item.

The contents of the dialog depend on how the developer has implemented the Credits Callback payments_get_items request and it's processing of order_info.

If Facebook's return data to the app's JavaScript callback contains an order_id, please notify the user that the purchased item has been delivered without a complete reload of the game.

function buy() {
  var obj = {
    method: 'pay',
    action: 'buy_item',
    order_info: SOME_DEV_JS_OBJECT_ORDER_INFO,
    dev_purchase_params: {'oscif': true}
  };

  FB.ui(obj, js_callback);
}

The JavaScript example demonstrates this dialog.

Developers can also open this dialog by direct URL by issuing an HTTP GET request to the /dialog/pay endpoint.

https://www.facebook.com/dialog/pay?app_id=YOUR_APP_ID&
                                    redirect_uri=YOUR_REDIRECT_URI&
                                    action=buy_item&
                                    order_info=SOME_DEV_JSON_ORDER_INFO&
                                    dev_purchase_params={"oscif":true}

The direct URL example demonstrates this dialog.

Buy item priced in credits as a currency.

To prompt users to purchase an item priced in credits, developers should invoke FB.ui with the following properties and values.

Note that Facebook considers app currency (e.g. Fred's App's Cash) to be an item.

The contents of the dialog depend on how the developer has implemented the Credits Callback payments_get_items request and it's processing of order_info.

If Facebook's return data to the app's JavaScript callback contains an order_id, please notify the user that the purchased item has been delivered without a complete reload of the game.

function buy() {
  var obj = {
    method: 'pay',
    action: 'buy_item',
    order_info: SOME_DEV_JS_OBJECT_ORDER_INFO
  };

  FB.ui(obj, js_callback);
}

Developers can also open this dialog by direct URL by issuing an HTTP GET request to the /dialog/pay endpoint.

https://www.facebook.com/dialog/pay?app_id=YOUR_APP_ID&
                                    redirect_uri=YOUR_REDIRECT_URI&
                                    action=buy_item&
                                    order_info=SOME_DEV_JSON_ORDER_INFO

Buy credits priced in local currency (e.g. USD).

To prompt users to purchase credits priced in local currency (e.g. USD), developers should invoke FB.ui with the following properties and values.

Since the user is purchasing credits from Facebook,

There are no items to get from the developer, and therefore Facebook will not issue a Credits Callback payments_get_items request.
There is no placed order with the developer, and therefore Facebook will not issue a Credits Callback payments_status_update request.

Since there's no placed order with the developer, an order_id is never returned to the app's JavaScript callback. The app's callback only receives the return data parameter error_code with value 1383010 indicating that the user has closed the Pay Dialog. While it's possible that the user purchased credits from Facebook, it's not possible for the developer to determine the number of credits purchased.

function buy() {
  var obj = {
    method: 'pay',
    action: 'buy_credits'
  };

  FB.ui(obj, js_callback);
}

Developers can also open this dialog by direct URL by issuing an HTTP GET request to the /dialog/pay endpoint.

https://www.facebook.com/dialog/pay?app_id=YOUR_APP_ID&
                                    redirect_uri=YOUR_REDIRECT_URI&
                                    action=buy_credits

Earn credits by completing advertiser offers.

For more details, visit the Credits Offers documentation.

To prompt users to earn credits, developers should invoke FB.ui with the following properties and values.

Since the user is earning credits from Facebook,

There are no items to get from the developer, and therefore Facebook will not issue a Credits Callback payments_get_items request.
There is no placed order with the developer, and therefore Facebook will not issue a Credits Callback payments_status_update request.

Since there's no placed order with the developer, an order_id is never returned to the app's JavaScript callback. The app's callback only receives the return data parameter error_code with value 1383010 indicating that the user has closed the Pay Dialog. While it's possible that the user earned credits from Facebook, it's not possible for the developer to determine the number of credits earned.

function earn() {
  var obj = {
    method: 'pay',
    action: 'earn_credits'
  };

  FB.ui(obj, js_callback);
}

Developers can also open this dialog by direct URL by issuing an HTTP GET request to the /dialog/pay endpoint.

https://www.facebook.com/dialog/pay?app_id=YOUR_APP_ID&
                                    redirect_uri=YOUR_REDIRECT_URI&
                                    action=earn_credits

Earn in-app currency by completing advertiser offers.

For more details, visit the In-app Currency Offers documentation.

To prompt users to earn in app currency, developers should invoke FB.ui with the following properties and values.

Facebook will not issue a Credits Callback payments_get_items request, but will issue a Credits Callback payments_status_update request. For details, visit the In-App Currency Offers payments_status_update documentation.

If Facebook's return data to the app's JavaScript callback contains an order_id, please notify the user that the earned app currency has been delivered without a complete reload of the game. It’s possible for a user to complete multiple offers in a single Pay Dialog. Facebook only returns the last completed order_id.

To test various app currency object instances, select an object instance to pass when invoking the Pay Dialog.

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

function earn() {
  var obj = {
    method: 'pay',
    action: 'earn_currency',
    product: 'URL_TO_APP_CURR_WEBPAGE'
  };

  FB.ui(obj, js_callback);
}

Developers can also open this dialog by direct URL by issuing an HTTP GET request to the /dialog/pay endpoint.

https://www.facebook.com/dialog/pay?app_id=YOUR_APP_ID&
                                    redirect_uri=YOUR_REDIRECT_URI&
                                    action=earn_currency&
                                    product=URL_TO_APP_CURR_WEBPAGE

Properties

`method`	The value `pay`. If using a direct URL, this property and value are not required because the `pay` value is retrieved from the HTTP GET request to the `/dialog/pay` endpoint.
`app_id`	The developer's app id. If using the JavaScript SDK, this property and value are provided when initing the JavaScript SDK.
`redirect_uri`	After the user interacts with the Pay Dialog, redirect the browser to this URI. If using the JavaScript SDK, the value is supplied by the JavaScript SDK.
`action`	One of the values `buy_item`, `buy_credits`, `earn_credits`, `earn_currency`.
`order_info`	Developer provided data containing order information and is passed from the user's client to the developer's server via Facebook's `payments_get_items` request. Note not all usages result in Facebook issuing `payments_get_items` requests. If using the JavaScript SDK, the data format is a JavaScript object. If using a direct URL, the data format is a JSON string.
`dev_purchase_params`	Configures whether the Pay Dialog displays prices in local currency (e.g. USD). If `{'oscif': true}` is provided using the JavaScript SDK or `{"oscif": true}` is provided is provided using a direct URL, the Pay Dialog displays prices in local currency. If using the JavaScript SDK, the data format is a JavaScript object. If using a direct URL, the data format is a JSON string. You can also set a `shortcut` parameter here to shortcut directly to a payment flow. Acceptable values - `{shortcut: mobile}`. Learn more in mobile shortcut docs.
`product`	A url to an app currency object instance used for `earn_currency` orders.

Return Data

After a developer settled order, the following data is returned.

`order_id`	A Facebook order id.
`status`	The value `settled`.

After an error, the following data is returned.

`error_code`	An error code identifying the error.
`error_message`	An error message describing the error.

If you're using the JavaScript SDK, the return data is a JavaScript object. This object is passed into the JavaScript callback function specified when you invoked FB.ui.

An example JavaScript object returned for a settled order.

{
  order_id: 9006529929647,
  status: 'settled'
}

An example JavaScript object returned for an error.

{
  error_code: 1383010,
  error_message: 'User canceled the order.'
}

If you're using a direct URL, the return data is appended as query parameters to the provided redirect_uri.

An example redirect_uri with the appended query parameters for a settled order.

http://example.com/response?order_id=9006529936904&status=settled

An example redirect_uri with the appended query parameters for an error.

http://example.com/response?error_code=1383010&
                            error_message=User+canceled+the+order.

A complete list of client error codes and messages can be found here.

Updated about an hour ago

Dialogs

Pay Dialog

Overview

JavaScript Example

Direct URL Example

Usage Notes

Buy item priced in local currency (e.g. USD).

Buy item priced in credits as a currency.

Buy credits priced in local currency (e.g. USD).

Earn credits by completing advertiser offers.

Earn in-app currency by completing advertiser offers.

Properties

Return Data