In-App Currency Orders

This document describes how you can define a currency for your app and support fulfillment of in-app currency orders. At the end of the purchase flow, the value of the purchase is immediately redeemed into your app currency. In-app currency orders can be used with In-app currency Offers as well as payer promotions.

It is necessary to implement the following steps to ensure proper settlement of such orders:

Create an app currency Open Graph object instance which contains the conversion rate from credits to your in-app currency.
Update your payment_status_update callback to support fulfillment of in-app currency orders.
Associate your application with its Open Graph currency object, using the Graph API

In-app currency orders are currently supported via Offers and Payer Promotions.

1. Create an app currency Open Graph object instance

The app currency Open Graph object describes your in-app currency and specifies the conversion rate from credits to your app currency. It must be hosted on a web-accessible URL. Here is an example of the Open Graph meta tags for the app currency object instance.

<head prefix="og: http://ogp.me/ns#
              fb: http://ogp.me/ns/fb#
              fbpayment:http://ogp.me/ns/fb/fbpayment#">
     <meta property="fb:app_id"      content="YOUR_APP_ID" >
     <meta property="og:type"        content="fbpayment:currency" >
     <meta property="og:url"         content="URL_TO_THIS_WEBPAGE" >
     <meta property="og:title"       content="CURRENCY_PLURAL_NAME" >
     <meta property="og:description" content="CURRENCY_DESCRIPTION" >
     <meta property="og:image"       content="IMAGE_URL_200x200px" >
     <meta property="fbpayment:rate" content="CURRENCY_FX_RATE" >
</head>

The Open Graph meta property fbpayment:rate is a decimal representing the number of app currency per one credit. For example, fbpayment:rate = 0.5 if 1 app currency = 2 credits => 1 / 2 = 0.5.

The following equation is used to determine the app currency value of an order:

[app currency value] = fbpayment:rate * [credits value]

Consider the following scenarios:

If the app currency value is >= 1, values are rounded down to the nearest app currency unit. For example, assume an app currency exchange rate of 0.3333 and a order with value = 11 credits so 0.3333 * 11 = 3.6665 = round down (3.6665) = 3 app currency.
If the app currency value is between 0 and 1, values are rounded up to one app currency unit. For example, assume the same exchange rate from above and a order with value = 1 credit so 0.3333 * 1 = 0.3333 = round up (0.3333) = 1 app currency.

Facebook does not support customized rounding rules, but you may cancel the order if you are unhappy with rounding applied to a specific order.

Additional notes:

You must create an Open Graph object instance for each app currency. For example if an app has two currencies, the app should have two app currency Open Graph object instances. You may create additional app currency object instances for purposes like testing various exchange rates. Each app currency object instance must have a unique URL.
Facebook only supports plural app currency titles. For example assume your app currency is “coin”, then the og:title must be “coins”. As a result, users may see orders worth “1 coins”.
Facebook supports internationalization of your app currency object instances. Facebook determines the locale of the user and displays the appropriate content.
You can force a scrape by entering your app currency object instance into Facebook’s Debugger Tool. Please resolve all debugging errors/warnings. If you need to update your app currency object instance, you can force a re-scrape using the tool describe above or via API. For example,

POST https://graph.facebook.com?id=URL_TO_APP_CURR_WEBPAGE&scrape=true

Your app currency object instance is public so please ensure it’s something you’d be proud to surface to users.

2. Update `payments_status_update` to support in-app currency orders.

You also need to update your Credits Callback payment_status_update to support fulfillment of in-app currency orders. The payments_status_update request contains a JSON encoded item-level data element called modified. This element name is reserved for Facebook purposes.

The modified element contains the following information:

product: A URL to the app currency object instance which the user is purchasing.
product_title: The title of your app currency.
product_amount: The integer amount of app currency to deposit into the user’s balance.
credits_amount: The integer credits amount which will be paid to the developer for fulfilling and settling the order.

For example a JSON encoded value for the payments_status_update POST parameter order_details,

{"order_id":9006316682257,"buyer":409697,"app":107032282669135,"receiver":409697,
"amount":1,"time_placed":1322622026,"update_time":1322622027,"data":"",
"items":[{"item_id":"0","title":"7 Golden Coins","description":"Super coins to buy amazing things!",
"image_url":"http:\/\/external.ak.fbcdn.net\/safe_image.php?d=AQDldsPcWsejAJdC&url=http\u00253A\u00252F\u00252Fwww.etftrends.com\u00252Fwp-content\u00252Fuploads\u00252F2011\u00252F10\u00252Fcurrency-trading.jpg",
"product_url":"","price":1,"data":"{\"modified\":{\"product\":\"URL_TO_APP_CURR_WEBPAGE\",
\"product_title\":\"Golden Coins\",\"product_amount\":3,\"credits_amount\":1}}"}],"status":"placed"}

JSON decoding order_details into an array, you’ll notice that the items element contains the 0 element which contains the data element which contains the JSON encoded modified order information. For example,

Array (
  [order_id] => 9006316682257
  [buyer] => 409697
  [app] => 107032282669135
  [receiver] => 409697
  [amount] => 1
  [time_placed] => 1322622026
  [update_time] => 1322622027
  [data] =>
  [items] => Array (
               [0] => Array (
                        [item_id] => 0
                        [title] => 7 Golden Coins
                        [description] => Super coins to buy amazing things!
                        [image_url] => http://external.ak.fbcdn.net/safe_image.php?d=AQDldsPcWsejAJdC&url=http%3A%2F%2Fwww.etftrends.com%2Fwp-content%2Fuploads%2F2011%2F10%2Fcurrency-trading.jpg
                        [product_url] =>
                        [price] => 1
                        [data] => {"modified":{"product":"URL_TO_APP_CURR_WEBPAGE","product_title":"Golden Coins","product_amount":7,"credits_amount":1}}
                      )
             )
  [status] => placed
)

JSON decoding the data element yields the following array containing the modified order information. For example,

Array (
  [modified] => Array (
                  [product] => URL_TO_APP_CURR_WEBPAGE
                  [product_title] => Golden Coins
                  [product_amount] => 7
                  [credits_amount] => 1
                )
)

Developers have two options:

1. Settle the placed order by:

Depositing the product_amount of the product into the user’s app currency balance.
Responding to this payments_status_update with settled. An example developer settle response,

{"content":{"status":"settled","order_id":9006195253076},
"method":"payments_status_update"}

The developer is paid the credits_amount for the order and these transactions are represented as type S in the developer payout reports.

2. Or cancel the placed order by:

If the order is cancelled because of the order’s implicit exchange rate, developer are required to pass the parameter code and the value 131. An example developer cancel response,

{"content":{"status":"canceled","code":131,"order_id":9006203669116},
"method":"payments_status_update"}

The user’s Facebook balance is credited with the credits_amount for the canceled order.

Unlike other payment flows, developers only see the payments_status_update requests to their Credits Callback URL. Developers will not see the preceding payments_get_items requests to their Credits Callback URL. This is because there are no items to get from the developer.

Since there are no payments_get_items requests, the developer's order flow cannot rely on data passed back in the payments_get_items (e.g. order_info) requests. Previously, developers may have relied on order_info to pass custom information from the client to the server. This is not possible for app currency orders.

3. Associate your app with its Open Graph currency object

Certain features offered by Facebook may need information about your app's currency. For instance, our on-site Payer Promotion gives your Facebook Canvas game's users the opportunity to complete an offer, even when they're not playing your game at the time, and receive a reward in your game's currency. To enable that functionality, you should use this API to map a currency to your app, so we'll be able to look up the relevant data.

Currency mapping API

Set or update your app's currency mapping
Verify the currency mapping of your app
Remove a currency mapping from your app
Error code reference

Set or update your app's currency mapping

To establish or update a mapping between your app and a currency, use an app access_token and call the endpoint POST https://graph.facebook.com/APP_ID/payment_currencies, passing in the URL of your Open Graph currency object in a parameter called currency_url.

Note: Calling this endpoint with a currency URL already associated with the app has no effect; if you've changed your currency object and want Facebook to re-crawl it, you should instead view the currency object in the Open Graph debugger, or call POST https://graph.facebook.com?id=OBJECT_URL&scrape=true. You can learn more about managing Open Graph objects in the OG object documentation.

You may use the POST endpoint to map more than one currency object to your app. If you do, features that look for your app's default currency, such as the off-canvas Payer Promotion mentioned in the introduction, will use the one added most recently.

POST https://graph.facebook.com/APP_ID/payment_currencies

Parameters

currency_url: The URL of the Open Graph currency object to associate with your app

Response Values

true if the request was well-formed. This does not indicate that the the mapping was changed; perform a read to verify that.

Verify the currency mapping of your app

To check which currencies are currently mapped to your app, use the GET https://graph.facebook.com/APP_ID/payment_currencies endpoint with an app access_token. The currency which appears first in the output, which will be the one most recently added, is your app's default currency; you can call GET https://graph.facebook.com/APP_ID/payment_currencies?limit=1 to get just the default currency.

GET https://graph.facebook.com/APP_ID/payment_currencies

Response Values

A json-encoded string containing:
- data, an array of dictionaries, each of which has the properties:
  - currency_id, the Open Graph ID of the currency object
  - currency_url, the canonical URL of the currency object, from its og:url field
  - currency_title, the og:title property specified in the currency object
  - currency_description, the og:description from the currency object
  - currency_image_url, the currency's og;:image property
- paging, a dictionary that may contain next and/or previous properties (see the Pagination docs)

Sample Response

{
  "data": [
    {
      "currency_id": "10151077708687510",
      "currency_url": "http://apps.facebook.com/agarman/og/moneys.html",
      "currency_title": "Moneys",
      "currency_description": "Use Moneys to buy super-powerups in AGAR MAN",
      "currency_image_url": "http://www.freeeel.com/nagaram/og/moneys.png"
    },
    {
      "currency_id": "488916731121543",
      "currency_url": "http://apps.facebook.com/agarman/og/3moneys.html",
      "currency_title": "Moneys",
      "currency_description": "Use Newer Moneys to buy ultra-powerups",
      "currency_image_url": "http://www.freeeel.com/nagaram/og/3moneys.png"
    }
  ],
  "paging": {
    "next": "https://graph.facebook.com/104191753063425/payment_currencies?limit=25&offset=25"
  }
}

Remove a currency mapping from your app

To remove an association between your app and a currency, make a request to the endpoint DELETE https://graph.facebook.com/APP_ID/payment_currencies with an app access_token and a single parameter, currency_url, which points to the currency to disassociate. You will most commonly do this to re-arrange the order of currencies mapped to your app, or to ensure that only one currency is mapped after you change your app's default currency.

DELETE https://graph.facebook.com/APP_ID/payment_currencies

Parameters

currency_url: The URL of the Open Graph currency object to disassociate from your app

Response Values

The string true; this does not necessarily indicate that a currency mapping was deleted, only that the access token was valid and that currency_url pointed to a fbpayments:currency Open Graph object. To verify that the deletion succeeded, perform a read.

Error codes

If there is an error accessing currency_url, or it is not a valid instance of fbpayment:currency, the API will respond with the error:

{
  "error": {
    "message": "(#2) Error modifying currency information",
    "type": "OAuthException",
    "code": 2
  }
}

If you use an invalid access token, the API will respond with the error:

{
  "error": {
    "message": "(#15) This method must be called with an app access_token.",
    "type": "OAuthException",
    "code": 15
  }
}

If your app is not payments-enabled, the API will respond with the error:

{
  "error": {
    "message": "(#1151) Requires application to be payments enabled",
    "type": "OAuthException",
    "code": 1151
  }
}

Updated about 4 months ago

Getting Started

Core APIs

Local currency payments

How-Tos

Advanced

In-App Currency Orders

1. Create an app currency Open Graph object instance

2. Update `payments_status_update` to support in-app currency orders.

3. Associate your app with its Open Graph currency object

Currency mapping API

Set or update your app's currency mapping

Verify the currency mapping of your app

Remove a currency mapping from your app

Error codes

Getting Started

Core APIs

Local currency payments

How-Tos

Advanced

In-App Currency Orders

1. Create an app currency Open Graph object instance

2. Update payments_status_update to support in-app currency orders.

3. Associate your app with its Open Graph currency object

Currency mapping API

Set or update your app's currency mapping

Verify the currency mapping of your app

Remove a currency mapping from your app

Error codes

2. Update `payments_status_update` to support in-app currency orders.