Facebook Credits is the easiest way for people to buy digital goods and services on Facebook. As announced in January and on our Developer Roadmap, we will require canvas game developers on Facebook to process all payments through Facebook Credits starting July 1st, 2011. Below we’ve outlined how to easily implement Facebook Credits into your app.
Step 1: Register your app
To get started with using Facebook Credits in your canvas app, register your company on the ‘Credits’ tab found in the Developer App (shown below). After your company is registered, select the company in the ‘Company Name’ dropdown menu and click ‘Save Changes.’ Your app is now ready receive credits.
Step 2: Generate the pay dialog with the JavaScript SDK
Within your app, prompt the user to buy directly in Facebook Credits. In this preferred integration, Ravenwood Fair prices its premium items directly in Facebook Credits and non-premium items in their experience currency (earned by users when taking in-app actions):
The following example shows how to render a simple form that submits the appropriate item information to Facebook:
<html>
<head>
<title>Facebook Credits sample
</head>
<body>
<form name ="place_order" id="order_form" action="#">
<img src="http://www.facebook.com/images/gifts/21.png">
<input type="hidden" name="item_id" value="1a" id="item_id">
<img src="http://developers.facebook.com/attachment/credits_sm.png"
height="25px">
<a onclick="placeOrder(); return false;">
<img src="https://www.facebook.com/images/credits/paybutton.png">
</a>
</form>
<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});
function placeOrder() {
var item_id = document.getElementById('item_id').value;
// Assign an ID - usually points to a db record
// found in your callback
var order_info = item_id;
// calling the API ...
var obj = {
method: 'pay',
order_info: order_info,
purchase_type: 'item'
};
FB.ui(obj, callback);
}
var callback = function(data) {
if (data['order_id']) {
// Success, we received the order_id. The order states can be
// settled or cancelled at this point.
return true;
} else {
//handle errors here
return false;
}
};
</script>
</body>
</html>
Enter your appId in the FB.init method and assign an ID to the variable order_info which will be used in your callback to construct your item before payment (e.g., we assigned the value of the item_id as “1a”).
Step 3: Build callback.php
After setting up the client-side code, you must also write the code to process the order. An overview of the order flow is shown below:
When your app submits the order, Facebook sends a request to the payments_get_items method to construct your item information before the user purchase.
As shown in the example below, check for the method payments_get_items from the $_REQUEST, look for the unique order_info (e.g., ‘1a’), and assign the required item parameters. Facebook then prompts a modal dialog containing the item's title, description, its price in Credits, and an image of the item.
Once the user clicks to purchase, Facebook will make a second call to your callback with the method payments_status_update, which is where you process the purchase and change the status of the user’s order from placed to settled.
<?php
// Enter your app information below
$api_key = 'YOUR_API_KEY';
$secret = 'YOUR_APP_SECRET';
// prepare the return data array
$data = array('content' => array());
// parse signed data
$request = parse_signed_request($_REQUEST['signed_request'], $secret);
if ($request == null) {
// handle an unauthenticated request here
}
$payload = $request['credits'];
// retrieve all params passed in
$func = $_REQUEST['method'];
$order_id = $payload['order_id'];
if ($func == 'payments_status_update') {
$status = $payload['status'];
// write your logic here, determine the state you wanna move to
if ($status == 'placed') {
$next_state = 'settled';
$data['content']['status'] = $next_state;
}
// compose returning data array_change_key_case
$data['content']['order_id'] = $order_id;
} else if ($func == 'payments_get_items') {
// remove escape characters
$order_info = stripcslashes($payload['order_info']);
$item_info = json_decode($order_info, true);
//Per the credits api documentation,
//you should pass in an item reference
// and then query your internal DB for the proper
//information. Then set the item
//information here to be returned to facebook
//then shown to the user for confirmation.
if ($item_info == "1a") {
$item['title'] = 'BFF Locket';
$item['price'] = 1;
$item['description']='This is a BFF Locket...';
$item['image_url']='http://www.facebook.com/images/gifts/21.png';
$item['product_url']='http://www.facebook.com/images/gifts/21.png';
}
//for url fields, if not prefixed by http:,
//prefix them
$url_key = array('product_url', 'image_url');
foreach ($url_key as $key) {
if (substr($item[$key], 0, 7) != 'http://') {
$item[$key] = 'http://'.$item[$key];
}
}
$data['content'] = array($item);
}
// required by api_fetch_response()
$data['method'] = $func;
echo json_encode($data);
?>
Step 4: Set the location of your callback
Once you have constructed both files, input the location of your callback file in the ‘Credits’ tab found in the Developer App as shown below:
Step 5: Complete a transaction
Now you are ready to test your first Facebook Credits transaction! Navigate to the location of your Facebook Canvas App and trigger the FB.ui call:
Click “Pay Now” to see the pay dialog:
Click “Buy BFF Locket” to see the confirmation dialog:
Please reference our Credits API documentation for more info.
Tune in to Facebook Live to ask questions
If you still have questions on how to implement Facebook Credits, we are hosting a session covering this information following by live Q&A at 11AM PST.
We recommend canvas game developers begin the migration process now, as this will provide you with time to optimize your implementation and receive support from the Facebook Credits Support Team, if needed.
Daniel is excited to see new developers using credits in innovative ways.