Mobile Shortcutting

Overview

To optimize the mobile payment experience, mobile price points available to a given person can be queried via the Graph API. You can then use these price points to make a mobile store available to people. When you know that someone wants to purchase at a specific mobile price point, it's also possible to shortcut them to the mobile payment flow, bypassing all other payment methods.

Implementation

Typically, the price points available through mobile payments will differ from the ideal pricing you'd choose within your app. The recommended workaround for this issue is to build 2 pricing tables and flows within your store:

• A flow for credit-card, PayPal etc., as detailed in the User Payment Flow guide
• A flow for mobile that depends on the player's carrier price points

Querying for mobile price points

You can query the mobile price points available for people playing your game by making an HTTP GET request to the Graph API endpoint /me?fields=payment_mobile_pricepoints with a user access_token.

GET https://graph.facebook.com/USER_ID?fields=payment_mobile_pricepoints&access_token=USER_TOKEN

Your app has to be Payments enabled and the player has to authenticate your app for this call to succeed. The return data varies based on the amount of information we have about the player:

In the case that no mobile price points are available for that person, the pricepoints array won't be present. In this case, you shouldn't display the option to pay with mobile within your payment dialog.

Description of fields in the pricepoints array

Every request to read payment_mobile_pricepoints from the Graph API will result in a unique set of pricepoint_id's being returned. As such you must not cache these values, rather requesting them each time people load your game.

If mobile price points are returned, you must render a pricing table displaying the pricing options available for mobile payment. How to approach this scenario depends on how much information we're able to return on behalf of people playing your game.

If the mobile_country field is present, it means that the player has paid with mobile before or registered a phone number with Facebook. As such, the available mobile price points for people in their country will be returned. A sample Graph API response is below:

{
  "payment_mobile_pricepoints": {
    "user_currency": "EUR",
    "mobile_country": "DE",
    "phone_number_last4": "5489",
    "pricepoints": [
      {
        "pricepoint_id": "x1b2dedt...", // encoded pricepoint id
        "payer_amount": "2.00",         // user pays 2.00 EUR
        "payout_base_amount": "1.40",   // dev gets EUR 1.40 * 70% rev share
        "currency": "EUR",
        "country": "DE"
      },
      {
        "pricepoint_id": "x1b2dedt...",
        "payer_amount": "4.00",
        "payout_base_amount": "2.80",
        "currency": "EUR",
        "country": "DE"
      },

      …, // other price points in DE
    ]  
  }
}

For first-time mobile payers, the user_currency field will still be returned. The pricepoints array will contain a list of the price points in all countries that accept this currency.

If there's only one country returned in the pricepoints array, then you should use these prices. Facebook will ensure that the set of price points returned are supported by all known carriers within that country. This ensures that any price point selected will be valid for any player paying with mobile within that country.

If multiple countries are returned, you must render a drop-down menu or other appropriate interface element to let people choose the country that applies to them. Once people select a country, you can price your items according to the available price points in that country and currency.

If the predicted_mobile_country field is present, it represents the country we think the player's mobile phone is most likely registered in, based on currently detected locale. We recommend that you preselect this country for the player, and provide a drop-down menu or other interface element so the player can change country. That's because it's possible that predicted_mobile_country is inaccurate.

Here's a sample Graph API response:

{
  "payment_mobile_pricepoints": {
    "user_currency": "EUR",
    "predicted_mobile_country": "DE",       // may not be supplied
    "pricepoints": [
      {
        "pricepoint_id": "x1b2dedt...",     // encoded pricepoint id
        "payer_amount": "2.00",             // user pays 2.00 EUR
        "payout_base_amount": "1.40",       // developer get EUR 1.40 * 70% rev share
        "currency": "EUR",
        "country": "DE"
      },
      {
        "pricepoint_id": "x1b2dedt...",
        "payer_amount": "4.00",
        "payout_base_amount": "2.80",
        "currency": "EUR",
        "country": "DE"
      },
      …,   // other price points from DE

      {
        "pricepoint_id": "...",
        "payer_amount": "1.00",
        "payout_base_amount": "0.60",
        "currency": "EUR",
        "country": "FR"
      },
      {
        "pricepoint_id": "...",
        "payer_amount": "3.00",
        "payout_base_amount": "1.80",
        "currency": "EUR",
        "country": "FR"
      },

      …,   // other price points from FR

      …,   // price points from other countries

    ]  
  }
}

Enable mobile shortcutting

Once people select to pay with mobile and choose to purchase at a specific price point, you can shortcut them directly to the mobile purchase flow when invoking the Pay dialog. To do this, include the pricepoint_id parameter with the value set to the corresponding id from the Graph API return data for the price point you wish to charge.

FB.ui({
    method: "pay",
    action: "purchaseitem",
    product: "http://www.friendsmash.com/og/coins.html",
    quantity: 20,
    pricepoint_id: "x1b2dedt..."
  },
  callback
);

When shortcutting people to the mobile flow in this way, the payer_amount from the price point specified will override the price specified in the Open Graph product object.

The payer_amount from the mobile price point also has to be larger than the product:price:amount of the associated product URL multiplied by the quantity. If this isn't the case the following error will be returned:

{
   "error_code": 1353037,
   "error_message":"The amount you specified is invalid. Please verify that it is a valid positive amount, has the same currency as the payment and is supported by its currency in terms of decimal offset."
}

It's possible for people to change their payment method within the purchase flow and revert to paying with a non-mobile method. In this case, the price from your Open Graph product object will be used. We recommend that you set the price in your Open Graph product to reflect the payout_base_amount.

Handling Expired price points

The price points returned via the Graph API are provided by mobile carriers and can change from time to time. So it's possible that the price point used when invoking the Pay dialog is no longer valid, and an error will be returned:

{
   "error_code":1383104,
   "error_message":"The pricepoint ID that you have passed in is no longer valid. You can get an updated one by querying the Graph API."
}

If you receive this error, query the Graph API for the player's available mobile price points again and update the prices and quantities offered in your game's mobile store appropriately.