Facebook Game Cards are available in over 20 countries and in approximately 130,000 retail locations worldwide. They enable players to redeem a Game Card for an equivalent Facebook stored balance which can be used to purchase in-game currency and goods. |
Facebook Game Cards are a popular way of purchasing items within games. In addition to redeeming the value of a Game Card via the Facebook Game Card website, developers can also opt to offer their own in-app redemption flow. This enables players to redeem the full value of any Facebook Game Card straight into a game’s in-app currency. Through this direct in-app redemption, developers can use Game Cards as a new payment option, taking advantage of incremental gifting opportunities and cash-based purchases.
This guide describes how to implement your own customized in-app Game Card redemption flow in just a few simple steps and outlines the user experience including recommended best practices.
Below you can see the 3 stages of the standard in-app redemption flow.
First, the player clicks a "Redeem Game Card" button, provided by the developer, which is usually placed on the games' shop window. It's up to the developer to either use a basic link to invoke the Game Card Dialog or to design their own button:
When the Game Card dialog is initiated, a Facebook Dialog is invoked, prompting the player to enter their Game Card PIN.
Then the player selects the in-app currency.
Your app needs to be live to see the list of available in-app currency options.
This section will take you through the process of enabling players to redeem Game Cards directly in your game.
Please follow the steps outlined in the payments tutorial to set up your in-game currency. The pricing of your og:product
can be static or dynamic.
As we don't know the Game Card's value upfront, the Open Graph object instance created needs to represent a single unit of in-game currency. Based on the Game Card stored value we'll alter the quantity based on your in-game currency definition.
Game Cards are usually denominated as a whole number (e.g.: 10, 15, 20, ...) so it's best to have a low unit price which can be a multiple of those common denominations.
For example, with a US$10 Game Card redeemed in the below example, the player will be granted 50 units of the $0.20 currency.
As a game can define multiple different in-app currencies, you need to specify which ones are meant to be enabled for in-app redemption of Game Cards explicitly. To register a product for in-app redemption, you'll need to issue a POST
to the Graph API endpoint /APP_ID/payment_currencies
with the currency_url
and access_token
(app access token).
POST https://graph.facebook.com/APP_ID/payment_currencies?currency_url=URL_TO_OG_OBJECT&access_token=APP_ACCESS_TOKEN
Parameter | Description | Required |
---|---|---|
| The URL to your Product Open Graph object. | Yes |
| An app access token. | Yes |
You can verify your App mapping by issuing a GET request to the same /APP_ID/payment_currencies
with your app access_token
(app access token).
GET https://graph.facebook.com/APP_ID/payment_currencies?access_token=APP_ACCESS_TOKEN
Note that you can add multiple currencies per app by issuing a POST request as described above for each currency product URL that you would like to support. If an app supports more than one currency the player will be able to select which one he would like to use in the currency selection dialog during the checkout flow.
If a currency is no longer needed you can remove it from the app by issuing a DELETE request to the same /APP_ID/payment_currencies
endpoint with the currency_url
and access_token
(app access token).
DELETE https://graph.facebook.com/APP_ID/payment_currencies?currency_url=CURRENCY_URL&access_token=APP_ACCESS_TOKEN
Parameter | Description | Required |
---|---|---|
| The URL to your Product Open Graph object. | Yes |
| An app access token. | Yes |
To enable players to redeem Game Cards directly from your game, you'll need to render the Game Card dialog using the JS SDK. The below sample can be used to render the Game Card redemption flow. The only major difference between this and the standard Pay Dialog is the additional parameter of action: redeem
.
FB.ui({ method: 'pay', action: 'redeem', request_id: 'sra93zd8em' //Optional, unique per transaction }, callback );
Notice that you can also use the optional request_id
parameter for extra security and payment tracking.
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.
{ "product":"URL_TO_THIS_WEBPAGE", "quantity":"", "user_currency":"USD", "method":"payments_get_item_price", "request_id":"sra93zd8em", "signed_request":"lFd_bGdvcml0aG0iOiJITUFDLVNIQTI1Ni..." }
Decoding the signed_request reveals extra information about the initiated order including the product URL, the preferred currency of the player, the player's user_id and locale and so on.
Specifically to Game Card redemption, the parameter giftcard
is added which contains the Game Card's amount
and currency
.
{ "algorithm":"HMAC-SHA256", "expires":1370898000, "issued_at":1370893836, "oauth_token":"CAAGCibe0BykBAMD8dSKnzIQUNS1PTORgIuegrIC1EJu495cZASCfvlQlCZBeOyFnKyuAZDZD", "payment": { "product":"URL_TO_THIS_WEBPAGE", "quantity":"", "user_currency":"USD", "request_id":"sra93zd8em", "giftcard": { "amount":"10", "currency":"USD" } }, "user": { "country":"us", "locale":"en_US", "age": { "min":21 } }, "user_id":"12355545545212" }
If no in-app currency options are mapped to your game, the value of the Game Card is redeemed into the player's balance. In this case the JavaScript callback will return the following object:
{status="redeemed_to_balance"}
If the player cancels the redemption flow, your JavaScript callback will be passed the following error object:
{error_code=1383010, error_message="User canceled the order."}
You can generate test Pins using the "Retrieve Gift Card Test Pins" button on the payments tab of your app dashboard:
A collection of Pins will be generated supporting both USD
and EUR
. Each Pin can be used multiple times but it takes up to ten minutes until the same Pin can be used again.
Test redemption doesn't transfer real value to the app and will return an extra parameter "test": true
in the JavaScript callback.
{ "payment_id":378600162255784, "quantity":100, "status":"completed", "test":true, "request_id":"sra93zd8em", "signed_request":"dA_3cu5yZsdfwJJuGIqmtMupE3zJR06UNw.eyJhbGdvcml0aG0iOiJITUFDLVNIQTI1NiIsImlzc3VlZF9hdCI6MTM3MTA4MTM1NywicGF5bWVudF9pZCI6Mzc4NjAwMTYyMjU1Nzg0LCJxdWFudGl0eSI6Nywic3RhdHVzIjoiY29tcGxldGVkIn0" }
A prominent placement of the Game Card option is crucial to drive adoption of Game Card redemptions in your game. It is recommended to include the redemption option on the games' shop window to make potential payers aware that they can redeem Game Cards directly in your game.
The game Top Eleven Be A Football Manager is a great example for how Game Cards can be part of the shop window:
When you're starting to offer Game Card redemption within your game it's a good idea to make players aware of this new option. This can be done, for example, by presenting players with a landing page or banner, which provides extra context on the new payment option.
It's also recommended to use your associated App Page to post about the launch of in-game Game Card redemption.
Providing players with a small reward for using Game Cards to pay for in-game items have been very effective driver of payer conversions. This can range from giving away ex. free energy, lives or desirable in-game items to offering exclusive items to Game Card payers only.