Pay Dialog

Overview

Related Topics

On Facebook, payments are handled via the Pay Dialog, which is rendered as an overlay over your Canvas title. Developers integrating this dialog enable their users to pay for virtual items or currency via a variety of payment methods, including credit-card, Paypal and mobile carrier billing.

The Pay Dialog is invoked via the Facebook SDK for JavaScript. When launched, the Pay Dialog will show the user the item they're going to buy, its price, and various methods of payment available to the user. After the user has chosen a payment method and confirmed the purchase, the dialog will indicate, via a JavaScript callback that the purchase was either completed or cancelled.

Additional notes:

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 = "//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

ParameterRequiredDescription

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:

ParameterDescription

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"
}
ParameterDescription

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:

  1. 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.

  2. 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.