Pay Dialog

Overview

Invoking the Pay Dialog

The following simple JavaScript example demonstrates invoking the FB.ui method using the JavaScript SDK to open a Pay Dialog, accepting payment in a local currency (e.g. USD).

You are required to pass in the URL of a og:product object, which represents the product you are selling. For an example of the markup required to produce the product object, please see the How-to: Local Currency Payments - Defining Products guide, and the Product Object reference material.

<!DOCTYPE HTML>
<html>
  <head>
    <meta http-equiv="content-type" content="application/xhtml+xml; charset=UTF-8" />
    <title>My Sample Payment App</title>
  </head>
  <body>

    <h2>Purchase a product:</h2>
    <button id="pay">Buy Product</button>
    <div class="returndata" id="output"></div>


    <script type="text/javascript">
      window.fbAsyncInit = function() {
        FB.init({
          appId      : 'YOUR_APP_ID',
          status     : true,
          cookie     : true,
          xfbml      : true
        });

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

          FB.ui(obj, function(data) {
              console.log(data);
            });
        }

        document.getElementById('pay').onclick = function() {buy()};
      };

      // Load the SDK Asynchronously
      (function(d){
        var js, id = 'facebook-jssdk', ref = d.getElementsByTagName('script')[0];
        if (d.getElementById(id)) { return; }
        js = d.createElement('script'); js.id = id; js.async = true;
        js.src = "https://connect.facebook.net/en_US/all.js";
        ref.parentNode.insertBefore(js, ref);
      }(document));
    </script>
  </body>
</html>

The example above shows the Pay Dialog being invoked with the three required parameters: method, action and product. There are further parameters you can pass to the dialog, detailed below.

Properties

Parameter	Required	Description
method	✓	Should always be 'pay'.
action	✓	Should always be 'purchaseitem'.
product	✓	The absolute URL of your `og:product` object that the user is looking to purchase. For a full description on how to construct this product object, please see the How-to: Local Currency Payments - Defining Products guide, and the Product Object reference material.
quantity	✗	The amount of this item the user is looking to purchase - typically used when implementing a virtual currency purchase. If this parameter is omitted, it defaults to 1.
quantity_min	✗	The minimum quantity of the item the user is able to purchase. This parameter is important when handling price jumping to maximize the efficiency of the transaction.
quantity_max	✗	The maximum quantity of the item the user is able to purchase. This parameter is important when handling price jumping to maximize the efficiency of the transaction.
request_id	✗	The developer defined unique identifier for this transaction, which becomes attached to the payment within the Graph API. Learn more.
pricepoint_id	✗	Used to shortcut a mobile payer directly to the mobile purchase flow at a given price point. Full details can be found in the Optimizing for Mobile Payments doc.
test_currency	✗	This parameter can be used during debugging and testing your implementation to force the dialog to use a specific currency rather than the current user's preferred currency. This allows you to rapidly prototype your payment experience for different currencies without having to repeatedly change your personal currency preference settings. This parameter is only available for admins, developers and testers associated with the app, in order to minimize the security risk of a malicious JavaScript injection. Provide the 3 letter currency code of the intended forced currency. The list of supported currency codes is available here

Return Data

Upon completion, either in a succeeded or failed case, the dialog will call the provided callback function with data about the order. The return data is a JavaScript object, passed into the JavaScript callback function specified when you invoked FB.ui.

Below is an example JavaScript object that would be returned in the case of a successful purchase completion.

{
  payment_id: "495869257196092",
  amount: "5.00",
  currency: "USD",
  quantity: "1", 
  request_id: "60046727",
  status: "completed", 
  signed_request: "7QYHzKqKByA7fjiqJUh2bxFvEdqdvn0n_y1zYiyN6tg.eyJhbGCJxdWFudGl0eSI6IjEiLCJzdGF0dXMiOiJjb21wbGV0ZWQifQ"
}

The following data is returned:

Parameter	Description
payment_id	The Facebook-generated unique identification number for this payment. Use this to query additional details about the transaction through the Payment Graph API
amount	The total amount paid by the user.
currency	The currency in which the payment was made.
quantity	The quantity of the item the user purchase. Important Note - Due to Price Jumping it is possible the `quantity` provided when invoking the Pay Dialog is not the same as the final quantity purchased. Always be sure to handle this case.
request_id	(Optional) The developer-generated unique identifier for the transaction. This is only returned if it has been passed to the Pay Dialog at the point of purchase.
status	The current status of the order. This is typically either `initiated` or `completed` at the time the callback is invoked. For full detail on this parameter, please refer to the Payment API Reference.
signed_request	Contains additional, cryptographically secured information about the purchase. For more information on handling the signed request, please refer to the How-to: Local Currency Payments - Order Fulfillment doc.

The decoded signed_request contains the following data:

{
   "algorithm":"HMAC-SHA256",
   "amount":"5.00",
   "currency":"USD",
   "issued_at":1387285426,
   "payment_id":495869257196092,
   "quantity":"1",
   "request_id":"60046727",
   "status":"completed"
}

Parameter	Description
algorithm	The algorithm used to generate the signed request. Can be safely ignored.
amount	The total amount paid by the user.
currency	The currency in which the payment was made.
issued_at	The UNIX timestamp at which the signed request was generated. Can be safely ignored.
payment_id	As above. The Facebook generated unique identification number for this payment. Use this to query additional details about the transaction through the Payment Graph API
quantity	As above. The quantity of the item the user purchase. Important Note - Due to Price Jumping it is possible the `quantity` provided when invoking the Pay Dialog is not the same as the final quantity purchased. Always be sure to handle this case.
request_id	(Optional) The developer-generated unique identifier for the transaction. This is only returned if it has been passed to the Pay Dialog at the point of purchase.
status	As above. The current status of the order. This is typically either `initiated` or `completed` at the time the callback is invoked. For full detail on this parameter, please refer to the Payment API Reference.

Below is an example JavaScript object that would be returned in the case of a failed purchase completion. A transaction can fail for a number of reasons, usually for the simple reason that the user exits out of the dialog before purchase completion.

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

The complete list of error codes related to Local Currency Payments is available here.

Request ID

There may be some circumstances in which you may want to provide your own identification mechanism for querying orders. We therefore support passing in an optional request_id parameter when invoking the Pay Dialog. This ID must be alpha-numeric, no greater than 256 characters in length, and must be unique for each order made within your app. Facebook then associates this request_id to the order being completed by the user, and allows you to use it going forward to query information regarding the order.

Providing a request_id is recommended as it proves particularly useful in two circumstances:

Firstly, you can use the request_id to further verify the order's authenticity via a query to the Payment Graph API. This can ensure any information returned to your server from the client matches with the information Facebook has stored regarding that order, and has not been tampered with during transmission via the client.
Secondly, in the event the JavaScript callback fails to return a payment_id, the request_id can be used to verify the purchase, again via a query to the Payment Graph API. Note: if you have subscribed to Realtime Updates you should still receive a payment_id for an order, even if the order is completed and the JavaScript callback fails, however, having a request_id provides you additional flexibility when handling these rare error cases.

Please see the Payment Graph API reference doc for full detail on how to use the request_id to obtain transaction information.