Overview

The Friendster Developer Platforms provide APIs to access Friendster data and seamless integration points within the Friendster web site to create compelling games for Friendster's userbase.

Platform V1 and the common integration points are described in the following sections of this page.

Platform V1 APIs provides access to Friendster data through a rich REST-style interface. These resources can be accessed using an API key and a shared secret key that is issued to every game or 'Friendster App'. The resources can be accessed at the endpoint http://api.friendster.com/v1

Information Needed for App Registration

App developers provide the following information to get listed in Friendster's Game Portal and to get an API Key and API Secret to access Friendster data:

Name The name of the app as it appears in the Game Portal.
Unique Name The app name used in the app's Canvas URL, with the format: 'http://www.friendster.com/game/<app_unique_name>'.
Description The Description of the app shown in the Game Portal.
Genre The genre of the game. Multiple genres can be selected.
Gameplay Type Various gameplay types are available. Multiple gameplay types can be selected.
Callback URL The Callback URL called by Friendster after the app gets started. This must be a complete and valid URL (e.g. http://www.mygame.com/game)
Install URL The Install URL is called the first time the user plays the game. It load this URL instead of the callback URl. If no Install URL is provided, the callback URL is used instead.
Error URL The Error URL is called when an error occurs.
Maintenance URL The Maintenance URL is called when the game is in maintenance. An app can be placed in maintenance mode from the developer dashboard. When the game is not in maintenance mode, the Callback URL or Install URL will be called instead.
Topup URL The Topup URL takes the user to the payment site. On the payment site, the user can purchase items using the Friendster wallet. This URL should be provided for Premium games.
Wallet Callback URL (Optional) The Wallet callback URL is called once the user has successfully authenticated a transaction in the wallet authentication page. This is done as a server to server background call and is useful if your app does not want to rely on the return_url which does a http redirect call.
Wall Photo 34 x 34 pixels / jpeg file / max 15kb (image should be the same as the Game Page Profile Image)
Mini Icon 20 x 20 pixels, jpeg file. The game Mini Icon will be displayed in the players’ Wall.
Profile Picture Game Profile Image. 150 x 150 pixels / jpeg file / max 30kb
Portal Banner 940 x 250 pixels / jpeg or swf file / max 125kb
Portal Mini Banner 197 x 72 pixels / jpeg file / max 25kb
Admin Email Email address that Friendster can contact for important updates or issues.
Help Email the email address which players can use to notify you of issues regarding your game.
Canvas size Size of the frame enclosing the game within the Friendster game page. Two width are available by default. The user can also choose to change the default height of 760px to fit specific game sizing requirements.

Information Provided to Developers / App Partners after App Registration

Friendster provides the following keys which are used for every API call:

API Key Unique key assigned to every app.
API Secret Secret key that is shared with Friendster. It is used to compute the request signature.

API Quick Reference

The current list of resources supported by the platform is as follows:

Resource HTTP method Description
/application_guilds GET returns information about guilds associated with your game
/application/friends GET Get friends who also installed the current game.
/assets POST Upload an asset
/event/log POST Post a game event log
/friends/:uid GET Get user's friend list.
/guilds/:gid GET or POST returns information about a guild
/message/:cid GET Get the list of messages by conversation
/messages/ GET Get the list of conversation for the current user
/messages/ POST Send a message
/messages/destroy/:mid POST Delete a message
/newmessages/ GET Gets the total number of new messages
/notification POST Post a notification
/players GET Retrieve a random list of game players
/points or /points/:uid GET Query the users' maximum points that can be awarded for the day
/points or /points/:uid POST Reward a user with points
/score GET Get a list of top scores
/score/:avatar_id POST Post a game score
/sessions/destroy POST Destroys the current session for this user. This will force the friendster platform to issue a new session_key when the user plays your game.
/shoutout/:uids GET Get shoutouts for users in :uids list.
/shoutout/ GET Get the shoutout for the current user.
/shoutout/ POST Update a user's shoutout.
/user GET or POST Get User Information for the logged in user.
/user/:uids GET or POST Get User Information for users in :uids list.
/wall POST Post a rich message to the current users' wall
Payments and Wallet APIs
/wallet/payment POST Initiate purchase of a product by getting a request token
/wallet/authenticate or /sandbox_wallet/authenticate GET The page where the user has to be redirected to in order to validate a purchase. You must allow your users to authentcate using this page before you can commit the purchase.
/wallet/commit POST API to COMMIT the wallet purchase transaction initiated by Get Payment Request
/wallet/commit/confirm POST API to acknowledge that the transaction is done
/wallet/balance GET API to query the current user's balance.

The following are the current integration points within the Friendster website:

Game Portal Games/Apps are placed in the Game Portal by categories. Friendster users can explore and start playing your game from here.
The App Playground Page The App Playground Page opens when the user "plays" your app. Users can start playing from the portal or through your game information page.
Tracker A new event is added to user's network activity when an app is added by the user or if they "fave" your app
Pending App Invitations "NEW app invitations" appears in user's notification panel when they receive app invitations from their friends. User can select it to view all their app invitations.
Pending App Notifications "NEW app notifications" appears in user's notification panel when they receive game notifications from games they've installed. User can select it to view all their game notifications.

For more information about the Friendster Developers Platform, email developersupport@friendster.com.
To register your app, click here.

API Authentication/Authorization

Every API request should have the following attributes:

api_key Unique key assigned to every app.
session_key
  • Session key given to a user on login. This session_key never expires once an instance of the app is installed in the user profile, or the user explicitly gives unlimited access to the app.
  • The session key is required for all API requests except for token and session.
nonce Unique id for every call within the same session. This number needs to be unique and incrementing (e.g. current time with milliseconds) to avoid replay attacks.
sig Signature generated by the following method:
md5(concatenate( pathinfo, request_attributes_as_name_value_pairs, secret_key))
The request attributes contains all parameters like api_key=value&session_key=value etc in alphabetical key order.
other_params Other API specific parameters.

Example:

For instance for the following request:

http://api.friendster.com/v1/user/57519?
api_key=2e37638f335f0545c3719d34f4d20ed0&
session_key=M4yZuZ4LjoJQj5BJfTkw2HnGw6MG8JyM-57519&
nonce=326233766.3425

The signature is computed as follows, shown here in PHP syntax:

md5(
  '/v1/user/57519' .
  'api_key=2e37638f335f0545c3719d34f4d20ed0' .
  'nonce=326233766.3425' .
  'session_key=M4yZuZ4LjoJQj5BJfTkw2HnGw6MG8JyM-57519' .
  '<secret_key>');

App Playground Page

The Playground Page is accessed through the Game playground URL which is a public URL which uniquely identifies your game. It accepts the game unique name:

'http://www.friendster.com/play/<app_name>'

All references within Friendster use the callback URL.

An iframe is created within this page and your game's callback_url is called with the following parameters attached:

user_id Friendster user ID.
api_key Unique key assigned to every game.
api_domain The hostname that the game should use as the endpoint.
country The IP country code of the user detected by friendster
guest This value is set to 1 if the session is a guest session, it is either not present or set to 0 otherwise.
src The source for the callback 'directory', 'profile', 'myapps' if accessed from a Friendster page, or 'canvas' if accessed from the playground URL.
session_key The session key required for all API requests.
expires The session key expiry in Unix time or 0 for unlimited. A default expiry of 24 hours is usually set. Make sure that your app uses the latest session key passed to it to ensure a fresh expiration.
lang User language setting. Currently supported languages include 'en-US', 'zh-CN', 'zh-TW' and 'es-MX'. Respectively US english, simplified chinese, traditional chinese and spanish.
nonce Unique id for every call within the same session.
sandbox This will have a value of 'true' if the app is in wallet sandbox mode it is false otherwise. Wallet sandbox mode implies that the sandbox wallet is being used instead of the real wallet.
sig Signature generated by the same method as for the API calls.
signed_keys The keys that will be used in the computation of the signature. The app should use this parameter to determine which keys to include in the computation. However, all parameters passed by Friendster (except sig) via the iframe are included here, which means that your signature computation should still work if you have already been including all keys passed by Friendster in the sig computation. This parameter can also help your app in case you have a middleware that adds its own keys.
instance_id (optional) The app instance ID which is used to differentiate multiple instances of the same app in the user profile.
parameters (optional) Any parameter present in the Canvas URL is passed through to the Callback URL.

Example:

For instance the following Canvas URL for the app 'slideshow':

http://www.friendster.com/play/avatarstore/show1?view=mostrecent&instance_id=3745

The Callback URL 'http://mydomain/apps/1445' would be called as follows within the App Canvas page:

http://mydomain/apps/1445/show1?
  view=mostrecent&
  instance_id=3745&
  user_id=57519&
  api_key=2e37638f335f0545c3719d34f4d20ed0&
  api_domain=api.friendster.com&
  sandbox=false&
  signed_keys=view,instance_id,user_id,api_key,api_domain,sandbox,signed_keys,src,session_key,expires,lang,nonce&
  src=profile&
  session_key=M4yZuZ4LjoJQj5BJfTkw2HnGw6MG8JyM-57519&
  expires=0&
  lang=en-US&
  nonce=326233766.3425&
  sig=012345678901234567890123456789012

Guest Mode

Friendster allows for users who have not registered or logged in to friendster to be able to play your game. This mode of access is called "guest mode". So what happens under guest mode?

  • During guest mode a unique user (or avatar) id is automatically created and assigned to an api session that is passed to your app.
  • To let you know that the current session is under guest mode, a guest=true flag is passed to your iframe
  • Friendster will display a notice to remind the user to register if they want to save the current game state. The uid of a user will not change once they do register.

Do note that users under guest mode are not verified by friendster, as such you may opt to put in additional security measures that would prevent guest mode accounts from abusing your game (e.g. spam etc.)

How to compute for the signature

The signature is used to verify that a http request sent to the Friendster API indeed came from your game. To start we will need use the /v1/user call as an example:

http://api.friendster.com/v1/user/3448717?
nonce=177620106727976&api_key=ae17c149bedab7ecf731075eb14934a7&
session_key=b2abf542-9a5e-168c-6b29-4978de11c772

let us also assume the following:

api key: ae17c149bedab7ecf731075eb14934a7
api secret: b93d67ad280ab7bbe6fcd0197cbbc191

In order to compute for the signature correctly you need to do the following steps:

  • Extract the path from the url, remove the protocols and the domain:

  • Extract all the parmeters including the '=' sign, also if a parameter is URL encoded they should be unencoded during this computation.

    session_key=b2abf542-9a5e-168c-6b29-4978de11c772
    api_key=ae17c149bedab7ecf731075eb14934a7
    nonce=177620106727976
  • Sort those parameters in alphabetical order

    api_key=ae17c149bedab7ecf731075eb14934a7
    nonce=177620106727976
    session_key=b2abf542-9a5e-168c-6b29-4978de11c772
  • concatenate the path and the parameters together

  • concatenate your secret key at the end and then compute for the md5

    md5(/v1/user/3448717
    api_key=ae17c149bedab7ecf731075eb14934a7
    nonce=177620106727976
    session_key=b2abf542-9a5e-168c-6b29-4978de11c772b93d67ad280ab7bbe6fcd0197cbbc191)
    resulting signature from the computation => cf0e0334e5aa4d6f16e9ba038252385a
  • URL encode all parameter values, set the value to sig and add it to your final url request.

    http://api.friendster.com/v1/user/3448717?
    nonce=177620106727976&api_key=ae17c149bedab7ecf731075eb14934a7&
    session_key=b2abf542-9a5e-168c-6b29-4978de11c772&
    sig=cf0e0334e5aa4d6f16e9ba038252385a

Examples

Sample # 1:

api key: 370d00bfb0217e651b29891d09a201b0
api_secret: 783a78da225de83c7169c32ef62193c7
sample url: http://api.friendster.com/wallet/sandbox_authenticate?
api_key=370d00bfb0217e651b29891d09a201b0&
request_token=ed836ef9e96c1466315b42ce866360&
return_url=http%3A%2F%2Fwww.friendster.com
concatenated string: "/wallet/sandbox_authenticateapi_key=370d00bfb0217e651b29891d09a201b0request_token=ed836ef9e96c1466315b42ce866360return_url=http://www.friendster.com783a78da225de83c7169c32ef62193c7"

final URL with Signature

http://api.friendster.com/wallet/sandbox_authenticate?api_key=370d00bfb0217e651b29891d09a201b0&
request_token=ed836ef9e96c1466315b42ce866360&
return_url=http%3A%2F%2Fwww.friendster.com&
sig=62a2519e7544cae6c84ed8c3422822d7

The Share App Page

Friendster has a page where you can redirect to in order to let users share your game to their friends. The URL syntax is as follows:

http://www.friendster.com/app_share/show?api_key=e59ff97941044f85df5297e1c302d260&
next=http://www.google.com

Also, when a user accepts the game invite, they will be redirected to your game play page with the referrer_uid parameter passed to your callback_url (e.g. www.friendster.com/play/mygame?referrer_uid=34245542)

The following parameters are accepted:

name type description
api_key string The api key of your app
next URL string The page to redirect to after sharing has been completed

Sample Usage:

<a target="_blank" href="http://www.friendster.com/app/share?api_key=6b9569e1a8074ebf972aa9eb2d725f9e
&next=http://smackaho.st:8080/play/avatarstore">Share this app to your friends</a>

SFML tag Reference

SFML allows games to be able to post content on the user's wall with a rich formatting while making sure that the content is secure. Similar to XHTML each tag must be properly closed, otherwise an error will be thrown if it is not.

This section describes allowable tags for APIs that accept SFML templates, like POST /v1/wall

The following HTML tags are supported, however you are not allowed to specifiy any attributes.

<p> <b> <i> <u> <br/> <hr> <h1> <center>

You can use the tool below to preview SFML markup when rendered on the user's wall.

SFML Tool
SFML tag attributes description example
fs:img serial= - The asset name of the image (see post assets on how to upload these)
size=(large|medium|small|thumb|tiny) - size of the image (default "thumb")
Displays an image asset
fs:user uid= - The uid of the user to display
link=(true|false) - Make the name linkable (default true)
viewer=(true|false) - Display the user currently viewing the wall instead of the wall owner.
Displays the name of the specified user. The name can be clicked to direct the viewer to the users profile
fs:application link=(true|false) - Make the name linkable (default true)
play=(true|false) - If true, links to the game play page instead of the game info page (default: false)
Displays the name of the game. The name can be clicked to direct the viewer to the games information page.
fs:ifowner Evaluates enclosing block if viewer is the same as the wall owner This can only be seen by the wall owner
fs:nifowner Evaluates enclosing block if viewer is not the wall owner (e.g. friends) This can only be seen by friends and/or other avatars

Get User Information

Resource URL: http://api.friendster.com/v1/user/<UID> or http://api.friendster.com/v1/user?uids=<UIDS>

Resource Methods: GET (Retrieval of user information) : POST (Retrieval of user information)

Resource Description: API to get information on one or more avatars. If no avatar ID is specified, information about current logged in avatar will be returned.

Request :

string api_key Unique API ID given to each game.
string session_key Session identifier.
string uids A comma separated list of avatar uids
string cols (optional) A comma separated list of attributes that the api will return (e.g. uid,first_name,last_name,level,location,hometown,user_type,url). All attributes are returned by default. Use this to make api responses smaller.
numeric nonce Unique ID that avoids replay attacks.
string sig Signature of the Request.
string format (optional) XML (default), JSON.

Response :

container user Individual containers for users (repeatable)
numeric uid User ID.
string first_name User's first name
string last_name DEPRECATED
integer level The avatars' level
integer guild_id A unique identifier that represents the avatars' guild. Blank if not a member of a guild
string guild_name The guild name. Blank if not a member of a guild
integer level The avatars' level
string url url link to profile page
string primary_photo_url url link to primary photo
string gender male or female
string user_type DEPRECATED
string fan_profile_type DEPRECATED
container member_since DEPRECATED
numeric * month
numeric * year
string relationship_status DEPRECATED
container interested_in DEPRECATED
string * interest DEPRECATED
container birthday Birthday
numeric * year DEPRECATED
numeric * month DEPRECATED
numeric * day DEPRECATED
container location DEPRECATED
string(2) * country DEPRECATED
string * state DEPRECATED
string * city DEPRECATED
numeric * zip DEPRECATED
string hometown DEPRECATED
comma-string occupation DEPRECATED
comma-string companies DEPRECATED
comma-string hobbies_and_interests DEPRECATED
comma-string affiliations DEPRECATED
container college_list DEPRECATED
container * college DEPRECATED
string * * name DEPRECATED
string * * region DEPRECATED
string(2) * * country DEPRECATED
numeric * * year_start DEPRECATED
numeric * * year_end DEPRECATED
string * * major DEPRECATED
container school_list DEPRECATED
container school DEPRECATED
string * * name DEPRECATED
string * * region DEPRECATED
string * * city DEPRECATED
string(2) * * country DEPRECATED
numeric * * year_start DEPRECATED
numeric * * year_end DEPRECATED
container favorites DEPRECATED
comma-string * books DEPRECATED
comma-string * movies DEPRECATED
comma-string * music DEPRECATED
comma-string * tv_shows DEPRECATED
string about_me DEPRECATED
string wantto_meet DEPRECATED
string fb_id The facebook id of the user. Games that also exist in facebook can use this field as a hint to determine if the user already has an account in the game

Error Conditions/Response :

Error Code Error Condition
1 Invalid input
2 Invalid session_id
3 Unsupported version
4 Invalid field
5 Invalid format
6 Invalid sig
7 Process failed

Example Request :

http://api.friendster.com/v1/user/57519?
    api_key=2e37638f335f0545c3719d34f4d20ed0&
    session_key=M4yZuZ4LjoJQj5BJfTkw2HnGw6MG8JyM-57519&
    nonce=326233766.3425&
    sig=012345678901234567890123456789012
http://api.friendster.com/v1/user?uids=57519&
    api_key=2e37638f335f0545c3719d34f4d20ed0&
    session_key=M4yZuZ4LjoJQj5BJfTkw2HnGw6MG8JyM-57519&
    nonce=326233766.3425&
    sig=012345678901234567890123456789012

Example Response (XML) :

<?xml version="1.0" encoding="UTF-8" ?>
<user_response xmlns="http://api.friendster.com/v1/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://api.friendster.com/v1/friendster.xsd">
    <user>
        <uid>635423412</uid>
        <first_name><![CDATA[John]]></first_name>
        <last_name><![CDATA[doe]]></last_name>
        <url>http://profiles.friendster.com/635423412</url>
        <primary_photo_url>http://photos.friendster.com:81/photos/43/09/45345/1_620223562m.jpg</primary_photo_url>
        <location>
            <country>US</country>
            <state>CA</state>
            <city>California</city>
        </location>
        <hometown><![CDATA[san francisco]]></hometown>
        <user_type>Normal</user_type>
        <fan_profile_type>None</fan_profile_type>
        <fan_profile_category>None</fan_profile_category>
        <relationship_status>Single</relationship_status>
        <gender>Male</gender>
        <member_since>
            <year>2003</year>
            <month>02</month>
        </member_since>
        <interested_in list="true">
            <interest>Friends</interest>
            <interest>Activity Partners</interest>
        </interested_in>
        <occupation><![CDATA[Programmer]]></occupation>
        <companies></companies>
        <hobbies_and_interests></hobbies_and_interests>
        <affiliations></affiliations>
        <college_list list="true">
            <college>
                <name><![CDATA[University of California - Davis]]></name>
                <region>California</region>
                <country>United States</country>
                <city></city>
                <year_start>2000</year_start>
                <year_end>2003</year_end>
                <major><![CDATA[Communications]]></major>
                <degree>127</degree>
                <course></course>
                <class_of>2002</class_of>
            </college>
        </college_list>
        <school_list list="true">
            <school>
                <name><![CDATA[Joplin High]]></name>
                <region>Missouri</region>
                <country>United States</country>
                <city>Joplin</city>
                <year_start>2000</year_start>
                <year_end>2004</year_end>
                <major></major>
                <degree>0</degree>
                <course></course>
                <class_of>2004</class_of>
            </school>
        </school_list>
        <school_other></school_other>
        <favorites>
            <books><![CDATA[Confessions of a Shopaholic]]></books>
            <movies><![CDATA[Ferris Bueller's Day Off, Friday, Goonies, Zoolander, 50 First Dates, Elf]]></movies>
            <music><![CDATA[all kinds...it just depends on the mood]]></music>
            <tv_shows><![CDATA[24 BABY!!!!!  SNL, Conan O'Brien, Friends, Reality TV...esp. American Idol,
 CSI, Nip Tuck, Chappelle's Show]]></tv_shows>
        </favorites>
        <about_me><![CDATA[I'm John Doe]]></about_me>
        <want_to_meet><![CDATA[Anyone who wants to be my friend]]></want_to_meet>
        <birthday>
            <year>1984</year>
            <month>07</month>
            <day>25</day>
        </birthday>
    </user>
</user_response>

Example Error Response :

<error_response xmlns="<http://api.friendster.com/v1/>"
    xmlns:xsi="<http://www.w3.org/2001/XMLSchema-instance>"
xsi:schemaLocation="http://api.friendster.com/v1/
http://api.friendster.com/v1/friendster.xsd">
<error_code>7</error_code>
<error_msg>Unauthorized source IP address (ip was: 10.1.2.3)</error_msg>
</error_response>


Get Friends List

Resource URL : http://api.friendster.com/v1/friends/<UID>

Resource Methods : GET (Retrieval of friends list)

Resource Description : API to get the friends list of a user. If no user ID is specified, the friends list of the current logged in user will be returned.

Request :

string api_key Unique API ID given to each game.
string session_key Session identifier.
numeric nonce Unique ID that avoids replay attacks.
string sig Signature of the Request.
string format (optional) XML (default), JSON.

Response :

container friends Individual containers for friends
int uid User ID. (repeatable)

Error Conditions/Response :

Error Code Error Condition Description HTTP status code
1 Unexpected error Unexpected internal error 500
4 Wrong Method Invalid HTTP method (must be GET) 501
6 Invalid session key Invalid session key 403
8 Disabled widget App is disabled and cannot be used 403
100 Invalid input parameter Input parameters missing or invalid 4040
101 Unknown widget API Key does not exist 404
102 Session expired The current session has expired 403
103 Request replay The request was already submitted 400
104 Invalid signature Request signature is invalid 400

Example Request :

http://api.friendster.com/v1/friends/57519?
     api_key=2e37638f335f0545c3719d34f4d20ed0&
     session_key=M4yZuZ4LjoJQj5BJfTkw2HnGw6MG8JyM-57519&
     nonce=326233766.3425&
     sig=012345678901234567890123456789012

Example Response (XML) :

<friends_response xmlns="http://api.friendster.com/v1/"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xsi:schemaLocation="http://api.friendster.com/v1/
     http://api.friendster.com/v1/friendster.xsd">
   <friends list="true">
      <uid>57519</uid>
      <uid>12989</uid>
      <uid>57908</uid>
      <uid>48999</uid>
      <uid>37529</uid>
      <uid>97510</uid>
   </friends>
</friends_response>


Post Shoutout

Resource URL :http://api.friendster.com/v1/shoutout

Resource Method : POST (Updates the shoutout for the current user)

Resource Description : This API updates the shoutout of the current logged in user. If an empty value is passed as content, the current user shoutout will be cleared.

Request :

string api_key Unique API ID given to each game.
string session_key Session identifier.
string content Content of the new shoutout.
numeric nonce Unique ID that avoids replay attacks.
string sig Signature of the Request.
string format (optional) XML (default), JSON.

Response :

status contains either "updated" (when shoutout is updated) or "deleted" (when shoutout is cleared)

Error Conditions/Response :

Error Code Error Condition Description HTTP return code
1 Unexpected error Unexpected internal error 500
4 Wrong Method Invalid HTTP method (must be POST) 501
6 Invalid Session Key Invalid session Key 403
8 Disabled widget App is disabled and cannot be used 403
100 Invalid input parameter Input parameters missing or invalid 404
101 Unknown widget API Key does not exist 404
102 Session expired The current session has expired 403
103 Request replay The request was already submitted 400
104 Invalid signature Request signature is invalid 403

Example Request :

http://api.friendster.com/v1/shoutout
::Content-Type: multipart/form-data; boundary=xxx
MIME-version: 1.0

--xxx
Content-Disposition: form-data; name="content"

Traveling to Vegas!

Example Response (XML) :

<shoutout_response xmlns="http://api.friendster.com/v1/"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://api.friendster.com/v1/friendster.xsd">
    <status>updated</status>
</shoutout_response>

Example Error Response :

<error_response xmlns="<http://api.friendster.com/v1/"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://api.friendster.com/v1/">
    <error_code>104</error_code>
    <error_msg>Invalid signature</error_msg>
</error_response>

Get Shoutout

Resource URL :http://api.friendster.com/v1/shoutout(/:user_id)

Resource Method : GET (Retrieves the shoutout of the current user if user_id is not specified. Otherwise, it gets the shoutout of the given user_id if present.)

Resource Description : This API gets the shoutout of the currently logged in user or the provided user_id if present.

Request :

string api_key Unique API ID given to each game.
string session_key Session identifier.
numeric nonce Unique ID that avoids replay attacks.
string sig Signature of the Request.
string format (optional) XML (default), JSON.

Response :

container shoutouts contains a list of individual shoutouts
string shoutout contains the shoutout
int user_id the user_id of the shoutout poster
int time timestamp when the shoutout was posted

Error Conditions/Response :

Error Code Error Condition Description HTTP return code
1 Unexpected error Unexpected internal error 500
4 Wrong Method Invalid HTTP method (must be POST) 501
6 Invalid Session Key Invalid session Key 403
8 Disabled widget App is disabled and cannot be used 403
100 Invalid input parameter Input parameters missing or invalid 404
101 Unknown widget API Key does not exist 404
102 Session expired The current session has expired 403
103 Request replay The request was already submitted 400
104 Invalid signature Request signature is invalid 403
110 Invalid User ID one or more uids passed are invalid 400

Example Request :

http://api.friendster.com/v1/shoutout/1234

Example Response (XML) :

<shoutout_response xmlns="http://api.friendster.com/v1/"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://api.friendster.com/v1/friendster.xsd">
    <shoutouts>
      <uid>1234</uid>
      <shoutout>Hello world!</shoutout>
      <time>1317277054</time>
    </shoutouts>
</shoutout_response>

Example Error Response :

<error_response xmlns="<http://api.friendster.com/v1/"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://api.friendster.com/v1/">
    <error_code>104</error_code>
    <error_msg>Invalid signature</error_msg>
</error_response>



Post Notification

Resource URL:

http://api.friendster.com/v1/notification
http://api.friendster.com/v1/notification/<uids>

Resource Method: POST (generate a notification)

Resource Description: API to generate a notification to the uids listed in the resource URL on behalf of the logged in user. If no uids are provided, the notification is generated for the logged in user. There is a limit to the number of notifications a user can receive per day from a single game. When a user receives an app notification, "NEW app notifications" displays in the notification panel in the logged in homepage. The notifications appear in the user's app notifications page as follows:



Request:

string api_key API key
string sig Signature of the request
string session_key Session identifier
int nonce Unique ID that avoids replay attacks.
string content Content of new notification. Must not be an empty string (max 300 characters) [HTML not allowed]
string subject Subject of the notification (max 80 characters) [HTML not allowed]
string label Notification label (max 50 characters) [HTML not allowed]
string type Notification type ( 2 = Notification )
string uids Comma separated list of User IDs to send the notification to
string url_fragment url fragment that will be appended to the playground URL. For eg., if the url fragment is /notifications?sender_uid=12345, then the URL will be http://apps.friendster.com/simpleapp/notifications?sender_uid=12345&nid=<notification_id>&src=app_notifications
string (optional) format XML (default), JSON

Response :

container uids uids that were successfully notified.

Error Conditions/Response :

Error Code Error Condition Description HTTP status code
1 Unexpected error Unexpected internal error 500
4 Wrong Method Invalid HTTP method (must be POST) 501
6 Invalid session key Invalid session key 403
8 Disabled application Widget is disabled and cannot be used 403
100 Invalid input parameter Input parameters missing or invalid 400
101 Unknown application API Key does not exist 404
102 Session expired The current session has expired 403
103 Request replay The request was already submitted 400
104 Invalid signature Request signature is invalid 400

Example Request:

    http://api.friendster.com/v1/notification/53642,72361,4734?type=1&
    api_key=2e37638f335f0545c3719d34f4d20ed0&content=hello%20world&
    subject=hello%20world%20app&label=click%20here&sig=fake_sig

Example Response (XML):

<?xml version="1.0" encoding="UTF-8"?>
<notifications_response
    xmlns="<%3Chttp://api.friendster.com/v1/>"xmlns:xsi="<http://www.w3.org/2001/XMLSchema-instance>"
    xsi:schemaLocation="http://api.friendster.com/v1/ <http://api.friendster.com/v1/friendster.xsd>"
    list="true">
       <uid>53642</uids>
       <uid>72361</uids>
       <uid>4734</uids>
</notifications_response>

Example Error Response (XML):

<error_response xmlns="<http://api.friendster.com/v1/>"
    xmlns:xsi="<http://www.w3.org/2001/XMLSchema-instance>"
    xsi:schemaLocation="http://api.friendster.com/v1/
    http://api.friendster.com/v1/friendster.xsd">
    <error_code>100</error_code>
    <error_msg>Missing parameters from notification</error_msg>
</error_response>

Get Game friends

Resource URL:

http://api.friendster.com/v1/application/friends

Resource Method:

GET (obtain list of friends who have played the game at least once)

Resource Description:

This API returns the list of friends who have already played the game at least once.

Request :

string api_key Unique API ID given to each widget / application.
string session_key Session identifier
int nonce Unique ID that avoids replay attacks.
string sig Request signature
string (optional) format XML (default), JSON

Response :

application_friends A list of user ids for friends who have played this game at least once

Error Conditions/Response :

Error Code Error Condition Description HTTP status code
1 Unexpected error Unexpected internal error 500
4 Wrong Method Invalid HTTP method (must be GET) 501
6 Invalid session key Invalid session key 403
8 Disabled widget Widget is disabled and cannot be used 403
100 Invalid input parameter Input parameters missing or invalid 400
101 Unknown widget API Key does not exist 404
102 Session expired The current session has expired 403
103 Request replay The request was already submitted 400
104 Invalid signature Request signature is invalid 400

Example Request:

http://api.friendster.com/v1/application/friends

Example Response (XML):

<application_friends_response xmlns="http://api.friendster.com/v1/"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://api.friendster.com/v1/friendster.xsd" list="true">
    <application_friends>
      <uid>123456</uid>
      <uid>81213123</uid>
      <uid>12310993</uid>
    </application_friends>
</application_friends_response>

Example Error Response

<error_response xmlns="http://api.friendster.com/v1/"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://api.friendster.com/v1/">
<error_code>104</error_code>
<error_message>Invalid signature</error_message>
</error_response>

Get Conversation List

Resource URL : http://api.friendster.com/v1/messages;

Resource Methods : GET (Retrieval of user conversations)

Resource Description : API to get the conversations list of a user.

Request :

string api_key Unique API ID given to each game.
string session_key Session identifier.
numeric nonce Unique ID that avoids replay attacks.
string sig Signature of the Request.
string format (optional) XML (default), JSON.

Response :

container messages List of all conversations per user
container conversation Individual containers for conversations
numeric cid Conversation ID
string latest_message_body Latest message body
numeric sender_id Avatar sender id
string sender_name Avatar sender name
numeric recipient_id Avatar recipient id
string recipient_name Avatar recipient name

Error Conditions/Response :

Error Code Error Condition Description HTTP status code
1 Unexpected error Unexpected internal error 500
4 Wrong Method Invalid HTTP method (must be GET) 501
6 Invalid session key Invalid session key 403
8 Disabled widget App is disabled and cannot be used 403
100 Invalid input parameter Input parameters missing or invalid 4040
101 Unknown widget API Key does not exist 404
102 Session expired The current session has expired 403
103 Request replay The request was already submitted 400
104 Invalid signature Request signature is invalid 400

Example Request :

http://api.friendster.com/v1/messages?
     api_key=2e37638f335f0545c3719d34f4d20ed0&
     session_key=M4yZuZ4LjoJQj5BJfTkw2HnGw6MG8JyM-57519&
     nonce=326233766.3425&
     sig=012345678901234567890123456789012

Example Response (XML) :

<message_response xmlns="http://api.friendster.com/v1/"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xsi:schemaLocation="http://api.friendster.com/v1/
     http://api.friendster.com/v1/friendster.xsd">
   <messages>
      <conversation>
        <cid>55</cid>
        <latest_message_body>Private message test reply</latest_message_body>
        <sender_id>445777</sender_id>
        <sender_name>secondOne</sender_name>
        <recipient_id>445758</recipient_id>
        <recipient_name>Jay</recipient_name>
      </conversation>
      <page>1</page>
      <next_page/>
   </messages>
</message_response>



Get Message List by Conversation ID

Resource URL : http://api.friendster.com/v1/message/:cid;

Resource Methods : GET (Retrieval of user messages by conversation id)

Resource Description : API to get the message list of a user by conversation id.

Request :

string api_key Unique API ID given to each game.
string session_key Session identifier.
numeric nonce Unique ID that avoids replay attacks.
string sig Signature of the Request.
string format (optional) XML (default), JSON.

Response :

container messages List of all private messages per conversation
container message Individual containers for messages
numeric mid Message ID
string message_body Message body
numeric message_sender_id Avatar sender id
string message_sender_name Avatar sender name
numeric message_recipient_id Avatar recipient id
string message_recipient_name Avatar recipient name

Error Conditions/Response :

Error Code Error Condition Description HTTP status code
1 Unexpected error Unexpected internal error 500
4 Wrong Method Invalid HTTP method (must be GET) 501
6 Invalid session key Invalid session key 403
8 Disabled widget App is disabled and cannot be used 403
100 Invalid input parameter Input parameters missing or invalid 4040
101 Unknown widget API Key does not exist 404
102 Session expired The current session has expired 403
103 Request replay The request was already submitted 400
104 Invalid signature Request signature is invalid 400

Example Request :

http://api.friendster.com/v1/message/120?
     api_key=2e37638f335f0545c3719d34f4d20ed0&
     session_key=M4yZuZ4LjoJQj5BJfTkw2HnGw6MG8JyM-57519&
     nonce=326233766.3425&
     sig=012345678901234567890123456789012

Example Response (XML) :

<message_response xmlns="http://api.friendster.com/v1/"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xsi:schemaLocation="http://api.friendster.com/v1/
     http://api.friendster.com/v1/friendster.xsd">
   <messages>
      <message>
        <mid>120</cid∣
        <message_body>Private message test 2</message_body>
        <message_sender_id>445758</message_sender_id>
        <message_sender_name>Jay</message_sender_name>
        <message_recipient_id>445780</message_recipient_id>
        <message_recipient_name>Marc</message_recipient_name>
      </message>
      <page>1</page>
      <next_page/>
   </messages>
</message_response>



Post a message to an avatar

Resource URL : http://api.friendster.com/v1/messages;

Resource Methods : POST (Adding Message to a conversation)

Resource Description : API to post the message of a user.

Request :

string api_key Unique API ID given to each game.
string session_key Session identifier.
numeric recipient The uid of the user to send a message to
string content The body of the message to send a message to
numeric nonce Unique ID that avoids replay attacks.
string sig Signature of the Request.
string format (optional) XML (default), JSON.

Response :

container status Status of post

Error Conditions/Response :

Error Code Error Condition Description HTTP status code
1 Unexpected error Unexpected internal error 500
4 Wrong Method Invalid HTTP method (must be GET) 501
6 Invalid session key Invalid session key 403
8 Disabled widget App is disabled and cannot be used 403
100 Invalid input parameter Input parameters missing or invalid 4040
101 Unknown widget API Key does not exist 404
102 Session expired The current session has expired 403
103 Request replay The request was already submitted 400
104 Invalid signature Request signature is invalid 400

Example Request :

http://api.friendster.com/v1/messages?
     api_key=2e37638f335f0545c3719d34f4d20ed0&
     recpient=9017&
     content=Hello+world&
     session_key=M4yZuZ4LjoJQj5BJfTkw2HnGw6MG8JyM-57519&
     nonce=326233766.3425&
     sig=012345678901234567890123456789012

Example Response (XML) :

<message_response xmlns="http://api.friendster.com/v1/"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xsi:schemaLocation="http://api.friendster.com/v1/
     http://api.friendster.com/v1/friendster.xsd">
   <status>created</status>
</message_response>



Delete a Message from a Conversation

Resource URL : http://api.friendster.com/v1/messages/destroy/:mid;

Resource Methods : POST (Deleting a Message from a conversation)

Resource Description : API to delete the message of a user.

Request :

string api_key Unique API ID given to each game.
string session_key Session identifier.
numeric nonce Unique ID that avoids replay attacks.
string sig Signature of the Request.
string format (optional) XML (default), JSON.
numeric cid Conversation ID
numeric mid Message ID
numeric uid Avatar ID

Response :

container status Status of destroy

Error Conditions/Response :

Error Code Error Condition Description HTTP status code
1 Unexpected error Unexpected internal error 500
4 Wrong Method Invalid HTTP method (must be GET) 501
6 Invalid session key Invalid session key 403
8 Disabled widget App is disabled and cannot be used 403
100 Invalid input parameter Input parameters missing or invalid 4040
101 Unknown widget API Key does not exist 404
102 Session expired The current session has expired 403
103 Request replay The request was already submitted 400
104 Invalid signature Request signature is invalid 400

Example Request :

http://api.friendster.com/v1/messages/destroy/55?
     api_key=2e37638f335f0545c3719d34f4d20ed0&
     session_key=M4yZuZ4LjoJQj5BJfTkw2HnGw6MG8JyM-57519&
     nonce=326233766.3425&
     sig=012345678901234567890123456789012

Example Response (XML) :

<message_response xmlns="http://api.friendster.com/v1/"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xsi:schemaLocation="http://api.friendster.com/v1/
     http://api.friendster.com/v1/friendster.xsd">
   <status>deleted</status>
</message_response>


Get the number of new messages

Resource URL: http://api.friendster.com/v1/newmessages

Methods: GET (query the number of new messages)

Resource Description: API to query the number of new messages for the current user since the last_update (optional parameter).

Request :

string api_key Unique API ID given to each game.
numeric nonce Unique id for every call within the same session.
numeric last_update (optional) Get only number of new messages since last_update. Will return total of all messages if not specified.
string sig Signature of the Request.
string format (optional) XML (default), JSON

Response :

integer new number of new messages
integer last_update The date in unixtime of the latest message

Error Conditions/Response:

Error Code Error Condition Description
0 Invalid signature If signature is invalid
1 Unexpected error Processing error
2 Disabled widget If API key is disabled
3 Unknown widget Unknown API key

Example Request:

http://api.friendster.com/v1/newmessages?
    api_key=2e37638f335f0545c3719d34f4d20ed0&
    nonce=326233766.3425&
    sig=012345678901234567890123456789012

Example Response (XML):

<newmessages_response xmlns="http://api.friendster.com/v1/"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xsi:schemaLocation="http://api.friendster.com/v1/ http://api.friendster.com/v1/friendster.xsd">
     <new>5</new>
     <last_update>1112241241242424</last_update>
</newmessages_response>



Post Game Score

Resource URL : http://api.friendster.com/v1/score/:avatar_id

Resource Methods : POST (Adding game score)

Resource Description : API to post the game score of an avatar. Allows games to have a private leaderboard based on game scores. Use the op parameter to specify how the scores are to be added and updated.

Request :

string api_key Unique API ID given to each game.
string session_key Session identifier.
numeric nonce Unique ID that avoids replay attacks.
string sig Signature of the Request.
numeric score Game score of the avatar
string op type of operation ( i - increment current score, d - decrement current score, r - replace score, a - append (default))
string format (optional) XML (default), JSON.

Response :

container status Status of post

Error Conditions/Response :

Error Code Error Condition Description HTTP status code
1 Unexpected error Unexpected internal error 500
4 Wrong Method Invalid HTTP method (must be GET) 501
6 Invalid session key Invalid session key 403
8 Disabled widget App is disabled and cannot be used 403
100 Invalid input parameter Input parameters missing or invalid 4040
101 Unknown widget API Key does not exist 404
102 Session expired The current session has expired 403
103 Request replay The request was already submitted 400
104 Invalid signature Request signature is invalid 400

Example Request :

http://api.friendster.com/v1/score/11111?
     api_key=2e37638f335f0545c3719d34f4d20ed0&
     session_key=M4yZuZ4LjoJQj5BJfTkw2HnGw6MG8JyM-57519&
     nonce=326233766.3425&
     sig=012345678901234567890123456789012&
     score=100

Example Response (XML) :

<game_score_response xmlns="http://api.friendster.com/v1/"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xsi:schemaLocation="http://api.friendster.com/v1/
     http://api.friendster.com/v1/friendster.xsd">
   <status>posted</status>
</game_score_response>



Get Top Score List

Resource URL : http://api.friendster.com/v1/score

Resource Methods : GET (Retrieval of top scores of the game)

Resource Description : API to get the list of top scores of the game.

Request :

string api_key Unique API ID given to each game.
string session_key Session identifier.
numeric nonce Unique ID that avoids replay attacks.
string sig Signature of the Request.
string format (optional) XML (default), JSON.
numeric limit (optional) Number of top scores to return. 10 (default).

Response :

container high_scores List of all scores
container score Individual containers for scores
numeric avatar_id Avatar ID
numeric score Score
datetime posted_at Datetime of the score was posted

Error Conditions/Response :

Error Code Error Condition Description HTTP status code
1 Unexpected error Unexpected internal error 500
4 Wrong Method Invalid HTTP method (must be GET) 501
6 Invalid session key Invalid session key 403
8 Disabled widget App is disabled and cannot be used 403
100 Invalid input parameter Input parameters missing or invalid 4040
101 Unknown widget API Key does not exist 404
102 Session expired The current session has expired 403
103 Request replay The request was already submitted 400
104 Invalid signature Request signature is invalid 400

Example Request :

http://api.friendster.com/v1/score?
     api_key=2e37638f335f0545c3719d34f4d20ed0&
     session_key=M4yZuZ4LjoJQj5BJfTkw2HnGw6MG8JyM-57519&
     nonce=326233766.3425&
     sig=012345678901234567890123456789012

Example Response (XML) :

<game_score_response xmlns="http://api.friendster.com/v1/"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xsi:schemaLocation="http://api.friendster.com/v1/
     http://api.friendster.com/v1/friendster.xsd">
   <high_scores>
      <score>
        <avatar_id>445695</avatar_id>
        <score>100</score>
        <posted_at>1325127188</posted_at>
      </score>
   </high_scores>
</game_score_response>



Post Game Event Log

Resource URL : http://api.friendster.com/v1/event/log

Resource Methods : POST (Add a game event)

Resource Description : API to post an event log entry which the user can view privately. Games can post in-game event messages here and where the user can choose to review later

Request :

string api_key Unique API ID given to each game.
string session_key Session identifier.
numeric nonce Unique ID that avoids replay attacks.
string sig Signature of the Request.
string message The event message body
string event_level The type of event possible values ('info', 'warn', 'important')
string format (optional) XML (default), JSON.

Response :

container status Status of post

Error Conditions/Response :

Error Code Error Condition Description HTTP status code
1 Unexpected error Unexpected internal error 500
4 Wrong Method Invalid HTTP method (must be GET) 501
6 Invalid session key Invalid session key 403
8 Disabled widget App is disabled and cannot be used 403
100 Invalid input parameter Input parameters missing or invalid 4040
101 Unknown widget API Key does not exist 404
102 Session expired The current session has expired 403
103 Request replay The request was already submitted 400
104 Invalid signature Request signature is invalid 400

Example Request :

http://api.friendster.com/v1/event/log?
     api_key=2e37638f335f0545c3719d34f4d20ed0&
     session_key=M4yZuZ4LjoJQj5BJfTkw2HnGw6MG8JyM-57519&
     nonce=326233766.3425&
     sig=012345678901234567890123456789012&
     score=100

Example Response (XML) :

<game_score_response xmlns="http://api.friendster.com/v1/"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xsi:schemaLocation="http://api.friendster.com/v1/
     http://api.friendster.com/v1/friendster.xsd">
   <status>posted</status>
</game_score_response>


Query available points

Resource URL :http://api.friendster.com/v1/points/:uid

Resource Method : GET (Query the users' maximum points that can be awarded for the day)

Resource Description : This API allows you to query the maximum points that can be awarded to a user for the day. It is advised to use this API first to determine eligibility before proceeding to award the user with points using the POST points API.

Request :

string api_key Unique API ID given to each game.
string session_key Session identifier.
integer uid (optional) The uid of the user to add points to. If none is specified it will add points to the current user.
numeric nonce Unique ID that avoids replay attacks.
string sig Signature of the Request.
string format (optional) XML (default), JSON.

Response :

available_points The maximum number of points that the app can award the user for the day.

Error Conditions/Response :

Error Code Error Condition Description HTTP return code
1 Unexpected error Unexpected internal error 500
4 Wrong Method Invalid HTTP method (must be POST) 501
6 Invalid Session Key Invalid session Key 403
8 Disabled widget App is disabled and cannot be used 403
100 Invalid input parameter Input parameters missing or invalid 404
101 Unknown widget API Key does not exist 404
102 Session expired The current session has expired 403
103 Request replay The request was already submitted 400
104 Invalid signature Request signature is invalid 403

Example Request :

http://api.friendster.com/v1/points?uid=1234456&points=40

Example Response (XML) :

<?xml version="1.0" encoding="UTF-8"?>
<points_response xmlns="http://api.friendster.com/v1/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://api.friendster.com/v1/ http://api.friendster.com/v1/friendster.xsd">
  <available_points>1000000</available_points>
</points_response>

Example Error Response :

<error_response xmlns="<http://api.friendster.com/v1/"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://api.friendster.com/v1/">
    <error_code>104</error_code>
    <error_msg>Invalid signature</error_msg>
</error_response>

Post points

Resource URL :http://api.friendster.com/v1/points

Resource Method : POST (Add points to a user)

Resource Description : This API adds points to a user. The user must have played your game at least once. Points allow users' to level up, get rewards and climb the guild and avatar leaderboards, use this API to give incentives to users while ingame.

Note: As a publisher of your game, your own avatar(s) is/are not eligible for points rewards. However, you will still receive popup points notifications coming from your game in order to test the 'message' parameter.

Request :

string api_key Unique API ID given to each game.
string session_key Session identifier.
integer uid (optional) The uid of the user to add points to. If none is specified it will add points to the current user.
integer points The number of points to reward to the user. There is a limit to how many points can be awarded per user per day, you may use the GET points API to determine the number of points that can be awarded to a user
string message (optional) The message the user will see when they get notified of a points reward. If none is passed the system default will be used.
numeric nonce Unique ID that avoids replay attacks.
string sig Signature of the Request.
string format (optional) XML (default), JSON.

Response :

status contains 'OK' when successful
uid returns the user id passed
points contains the points awarded

Error Conditions/Response :

Error Code Error Condition Description HTTP return code
1 Unexpected error Unexpected internal error 500
4 Wrong Method Invalid HTTP method (must be POST) 501
6 Invalid Session Key Invalid session Key 403
8 Disabled widget App is disabled and cannot be used 403
100 Invalid input parameter Input parameters missing or invalid 404
101 Unknown widget API Key does not exist 404
102 Session expired The current session has expired 403
103 Request replay The request was already submitted 400
104 Invalid signature Request signature is invalid 403

Example Request :

http://api.friendster.com/v1/points?uid=1234456&points=40

Example Response (XML) :

<points_response xmlns="http://api.friendster.com/v1/"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://api.friendster.com/v1/friendster.xsd">
    <status>OK</status>
    <uid>446259</uid>
    <points>100</points>
</points_response>

Example Error Response :

<error_response xmlns="<http://api.friendster.com/v1/"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://api.friendster.com/v1/">
    <error_code>104</error_code>
    <error_msg>Invalid signature</error_msg>
</error_response>

Destroy Current Player Session

Resource URL: https://api.friendster.com/v1/sessions/destroy

Resource Methods: POST (Destroy Session)

Resource Description: API to destroy the current session. The friendster system will issue a new session_key when the user tries to access your app/game again.

Request :

string api_key Unique API ID given to each game.
string session_key Session identifier.
string sig Signature of the Request.
string format (optional) XML (default), JSON.

Response :

string status 'success' if the operation was successful

Error Conditions/Response :

Error Code Error Condition
1 Invalid input
2 Invalid session_id
3 Unsupported version
4 Invalid field
5 Invalid format
6 Invalid sig
7 Process failed

Example Request :

 http://api.friendster.com/v1/sessions/destroy?
 api_key=2e37638f335f0545c3719d34f4d20ed0&session_key=M4yZuZ4LjoJQj5BJfT
 kw2HnGw6MG8JyM-57519&sig=fake_sig

Example Response (XML) :

<sessions_response xmlns="https://api.friendster.com/v1/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="https://api.friendster.com/v1/ https://api.friendster.com/v1/friendster.xsd">
  <status>success</status>
</wallet_response>

Example Error Response :

<error_response xmlns="<https://api.friendster.com/v1/>"
xmlns:xsi="<http://www.w3.org/2001/XMLSchema-instance>"
xsi:schemaLocation="https://api.friendster.com/v1/
https://api.friendster.com/v1/friendster.xsd">
  <error_code>300</error_code>
</error_response>

Get Guild Information

Resource URL: http://api.friendster.com/v1/guilds/<GID> or http://api.friendster.com/v1/guilds?gid=<GIDS>

Resource Methods: GET (Retrieval of guild information) : POST (Retrieval of guild information)

Resource Description: API to get information on one or more guilds. If no guild_id is specified, information about current logged in avatars' guild will be returned.

Request :

string api_key Unique API ID given to each game.
string session_key Session identifier.
string gid A comma separated list of guild ids
string cols (optional) A comma separated list of attributes that the api will return (e.g. gid,name,description,logo). All attributes are returned by default. Use this to make api responses smaller.
numeric nonce Unique ID that avoids replay attacks.
string sig Signature of the Request.
string format (optional) XML (default), JSON.

Response :

container guild Individual containers for guilds (repeatable)
numeric gid The Guild ID.
string name The guild name
string description The guilds' description
logo url The url that points to the guilds' logo'
integer creator_id The uid of this guilds' creator
string leader_id The uid of this guilds' current guild leader
integer rank The guilds' overall rank

Error Conditions/Response :

Error Code Error Condition
1 Invalid input
2 Invalid session_id
3 Unsupported version
4 Invalid field
5 Invalid format
6 Invalid sig
7 Process failed

Example Request :

http://api.friendster.com/v1/guilds/57519?
    api_key=2e37638f335f0545c3719d34f4d20ed0&
    session_key=M4yZuZ4LjoJQj5BJfTkw2HnGw6MG8JyM-57519&
    nonce=326233766.3425&
    sig=012345678901234567890123456789012
http://api.friendster.com/v1/guilds?gid=57519&
    api_key=2e37638f335f0545c3719d34f4d20ed0&
    session_key=M4yZuZ4LjoJQj5BJfTkw2HnGw6MG8JyM-57519&
    nonce=326233766.3425&
    sig=012345678901234567890123456789012

Example Response (XML) :

<?xml version="1.0" encoding="UTF-8" ?>
<guild_response xmlns="http://api.friendster.com/v1/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://api.friendster.com/v1/friendster.xsd">
    <guild>
        <gid>635423412</uid>
        <name><![CDATA[Senior]]></name>
        <description><![CDATA[Senior Guild]]></description>
        <logo>http://photos.friendster.com:81/photos/43/09/45345/1_620223562m.jpg</logo>
    </user>
</guild_response>

Example Error Response :

<error_response xmlns="<http://api.friendster.com/v1/>"
    xmlns:xsi="<http://www.w3.org/2001/XMLSchema-instance>"
xsi:schemaLocation="http://api.friendster.com/v1/
http://api.friendster.com/v1/friendster.xsd">
<error_code>7</error_code>
<error_msg>Unauthorized source IP address (ip was: 10.1.2.3)</error_msg>
</error_response>


Application Guilds

Resource URL :http://api.friendster.com/v1/application_guilds

Resource Method : GET (Get list of guilds for the game)

Resource Description : This API will give a list of guilds that play a specific game. A list of guilds (in the form of their guild IDs) will be returned. All guilds that were created, and are associated with a specific game are returned through this request.

Note: Responses will be returned for your game only.

Request :

string api_key Unique API ID given to each game.
string session_key Session identifier.
numeric nonce Unique ID that avoids replay attacks.
string sig Signature of the Request.
string format (optional) XML (default), JSON.

Response :

status contains 'OK' when successful
guilds returns the guilds that are associated with your game, the length attribute indicates the number of guilds included in the response
guild individual Guild IDs for each guild associated with your game.

Error Conditions/Response :

Error Code Error Condition Description HTTP return code
1 Unexpected error Unexpected internal error 500
4 Wrong Method Invalid HTTP method (must be GET) 501
6 Invalid Session Key Invalid session Key 403
8 Disabled widget App is disabled and cannot be used 403
100 Invalid input parameter Input parameters missing or invalid 404
101 Unknown widget API Key does not exist 404
102 Session expired The current session has expired 403
103 Request replay The request was already submitted 400
104 Invalid signature Request signature is invalid 403

Example Request :

http://api.friendster.com/v1/points?uid=1234456&points=40

Example Response (XML) :

<?xml version="1.0" encoding="UTF-8"?>
<application_guilds_response xmlns="http://api.friendster.com/v1/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://api.friendster.com/v1/ http://api.friendster.com/v1/friendster.xsd">
<app>c1793215830056bd3250e704c087e65d</app>
<guilds length="1">
<guild>26</guild>
</guilds>
</application_guilds_response>

Example Error Response :

<error_response xmlns="<http://api.friendster.com/v1/"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://api.friendster.com/v1/">
    <error_code>104</error_code>
    <error_msg>Invalid signature</error_msg>
</error_response>



Post a rich message to the current users' wall'

Resource URL:

http://api.friendster.com/v1/wall

Resource Method: POST (generate a rich wall post)

Resource Description: API to post a rich message to the users' wall. A rich message can contain images, formatted text and various interactive elements and is defined using SFML (simple friendster markup language) SFML Reference



Request:

string api_key API key
string sig Signature of the request
string session_key Session identifier
int nonce Unique ID that avoids replay attacks.
string event_icon_id (optional) An image asset to be used as the event icon. To upload assets refer to the POST asset API. If none is provided, the game wall icon will be used.
string template A valid SFML template. [SFML tags and some HTML allowed] SFML Tool
string subject Subject of the notification (max 80 characters) [HTML not allowed]
string label (optinal) Notification label (max 50 characters) [HTML not allowed]
string url_fragment url fragment that will be appended to the playground URL. For eg., if the url fragment is /notifications?sender_uid=12345, then the URL will be http://apps.friendster.com/simpleapp/notifications?sender_uid=12345&nid=<notification_id>&src=app_notifications
string (optional) format XML (default), JSON

Response :

container uids uids that were successfully notified.

Error Conditions/Response :

Error Code Error Condition Description HTTP status code
1 Unexpected error Unexpected internal error 500
4 Wrong Method Invalid HTTP method (must be POST) 501
6 Invalid session key Invalid session key 403
8 Disabled application Widget is disabled and cannot be used 403
100 Invalid input parameter Input parameters missing or invalid 400
101 Unknown application API Key does not exist 404
102 Session expired The current session has expired 403
103 Request replay The request was already submitted 400
104 Invalid signature Request signature is invalid 400

Example Request:

http://api.friendster.com/v1/wall?template=<fb:me/>&subject=wall post&label=click

Example Response (XML):

<?xml version="1.0" encoding="UTF-8"?>
<wall_response xmlns="http://api.friendster.com/v1/" xmlns:xsi="
http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://api.friendster.com/v1/ http://api.friendster.com/v1/friendster.xsd">
  <id>1845</id>
  <created_at>1342683525</created_at>
</wall_response>

Example Error Response (XML):

<?xml version="1.0" encoding="UTF-8"?>
<error_response>
  <error_code>71</error_code>
  <error_msg>Invalid Template format [["line 1 column 20: start tag [fb:me] does not match tag [a]"]]</error_msg>
</error_response>

Post Assets

Resource URL :http://api.friendster.com/v1/assets

Resource Method : POST (Upload an asset for the current publisher)

Resource Description : This API uploads an asset resource for the current publisher. This asset is accessible by any of the publishers games. Assets are used by various APIs (e.g. /v1/ wall) in order to display images and other resources.

Request :

string api_key Unique API ID given to each widget/application.
string session_key Session identifier.
string asset_serial (optional) The name to be given to the asset. If none is specified, a random name will be generated for you.
binary bin raw data of the asset. (If an image, this should contain the raw bytes of the image)
integer type Asset type (only images are supported for now). Value should be 0
numeric nonce Unique ID that avoids replay attacks.
string sig Signature of the Request.
string format (optional) XML (default), JSON.

Response :

status contains either "updated" (when shoutout is updated) or "deleted" (when shoutout is cleared)

Error Conditions/Response :

Error Code Error Condition Description HTTP return code
1 Unexpected error Unexpected internal error 500
4 Wrong Method Invalid HTTP method (must be POST) 501
6 Invalid Session Key Invalid session Key 403
8 Disabled widget App is disabled and cannot be used 403
100 Invalid input parameter Input parameters missing or invalid 404
101 Unknown widget API Key does not exist 404
102 Session expired The current session has expired 403
103 Request replay The request was already submitted 400
104 Invalid signature Request signature is invalid 403

Example Request :

http://api.friendster.com/v1/wall
::Content-Type: multipart/form-data; boundary=xxx
MIME-version: 1.0

--xxx
Content-Disposition: form-data; name="content"

Traveling to Vegas!

Example Response (XML) :

<?xml version="1.0" encoding="UTF-8"?>
<asset_response xmlns="http://api.friendster.com/v1/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://api.friendster.com/v1/ http://api.friendster.com/v1/friendster.xsd">
  <asset_serial>main_event_icon</asset_serial>
  <url>http://smackaho.st:3333/system/publisher_assets/image_assets/15/thumb_1343617066.png</url>
  <checksum>a0b413865ecacfcac327c9d7ead0aaf778f5d7ea</checksum>
</asset_response>

Example Error Response :

<error_response xmlns="<http://api.friendster.com/v1/"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://api.friendster.com/v1/">
    <error_code>104</error_code>
    <error_msg>Invalid signature</error_msg>
</error_response>

Get Random Players

Resource URL:

http://api.friendster.com/v1/players

Resource Method:

GET (obtain a random list of players who have the game currently installed)

Resource Description:

This API returns a random list of players who have the game currently installed

Request :

string api_key Unique API ID given to each widget / application.
string session_key Session identifier
int nonce Unique ID that avoids replay attacks.
string sig Request signature
string (optional) format XML (default), JSON

Response :

players A random list of user ids for users who have played this game at least once

Error Conditions/Response :

Error Code Error Condition Description HTTP status code
1 Unexpected error Unexpected internal error 500
4 Wrong Method Invalid HTTP method (must be GET) 501
6 Invalid session key Invalid session key 403
8 Disabled widget Widget is disabled and cannot be used 403
100 Invalid input parameter Input parameters missing or invalid 400
101 Unknown widget API Key does not exist 404
102 Session expired The current session has expired 403
103 Request replay The request was already submitted 400
104 Invalid signature Request signature is invalid 400

Example Request:

http://api.friendster.com/v1/application/friends

Example Response (XML):

<players_response xmlns="http://api.friendster.com/v1/"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://api.friendster.com/v1/friendster.xsd" list="true">
    <players>
      <uid>123456</uid>
      <uid>81213123</uid>
      <uid>12310993</uid>
    </players>
</players_response>

Example Error Response

<error_response xmlns="http://api.friendster.com/v1/"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://api.friendster.com/v1/">
<error_code>104</error_code>
<error_message>Invalid signature</error_message>
</error_response>

Wallet API

The wallet APIs allow developers to access the wallet in order to facilitate the purchase of virtual goods and/or services within your game. The Wallet API is available to both premium and non-premium apps, however your app must have been upgraded to premium status in order to gain access to the real wallet otherwise your app will be limited to "sandbox" mode. Developers can use sandbox mode in order to prepare their app before they request for premium status.

The Friendster payment API flow

The Friendster payment API flow is designed so that the customer’s password is not passed to the game. It allows the user to approve all transactions to his or her wallet.

A purchase is performed using the following steps:

  • App obtains a request token using the GET PAYMENT REQUEST (https:// {api_domain}/v1/wallet/payment) call. The app will need to supply all the purchase details including the amount, product name, description etc. The request token will be needed in the succeeding steps.
  • The App will be required to redirect the user to the Payments Authentication page. The URL to the payments authentication page is returned in the response of the https:// {api_domain}/v1/wallet/payment call. The behavior of the payments authentication page is described in the "PAYMENTS AUTHENTICATION PAGE" section.
  • The User must then enter his or her password in the Payments Authentication page. While the App has no control on the behavior of this page, if a return_url is provided, the user will be redirected back to the app after the user has been successfully authenticated. Additionally if your app has defined a wallet callback url in the app settings, a background call will also be initiated to notify your app of the transaction.
  • After control is returned to the App via the redirect and/or the wallet callback url, assuming the authentication process is successful the next step is for the App to issue the COMMIT PAYMENT REQUEST (https:// {api_domain}/v1/wallet/commit). At this point, the balance of the user is deducted and the App may now deliver the product purchased by the user. The transaction commit is successful if and only if there is a successful response and a transaction id is returned. For accounting purposes the App is advised to store the corresponding transaction id returned by this call. Please note that for non-sandbox mode, there will be a corresponding entry in the users’ wallet transaction history.

How the Sandbox environment works

The Wallet API provides a sandbox environment where the game developer can use a fake wallet and coins balance in order to perform integration testing. Each game has its own sandbox, which means that two different games will transact against distinct wallets. If a game developer manages two games, the game developer will have separate balances for each sandbox. Also, a distinctive chrome is displayed around your game's iframe indicating sandbox mode.

For premium apps you can access sandbox mode by clicking on the “play in sandbox” link (non-premium or normal apps will always use the sandbox wallet). A flag “sandbox=true” will be passed to your app via the iframe if the current session is using sandbox mode. The app should use this flag to prevent confusion during billing, as transactions performed against sandbox mode is not valid. Sandbox mode is only accessible by the developer and admin. The sandbox and production wallets are distinct. When a game is not played in sandbox mode, it will access the wallet the current user has created.

The sandbox wallet is automatically created upon the first use of the game in its sandbox environment. The initial balance for each new sandbox wallet is 1000000 coins.


Wallet API Reference


BALANCE INQUIRY

Resource URL: https://api.friendster.com/v1/wallet/balance

Resource Methods: GET (Wallet Balance)

Resource Description: API to query the current user's balance.

Request :

string api_key Unique API ID given to each game.
string session_key Session identifier.
numeric nonce Unique ID that avoids replay attacks.
string sig Signature of the Request.
string format (optional) XML (default), JSON.

Response :

decimal coins coins balance
string timestamp The time when the balance was queried, based on RFC 3339

Error Conditions/Response :

Error Code Error Condition
300 Wallet Does not exist 404
301 Invalid Wallet
302 Wallet Unexpected The specified user does not have a wallet yet and an attempt was made to access it
307 Access Denied - The users' wallet is either suspended or invalid. The user should be advised to seek customer support

Example Request :

 https://api.friendster.com/v1/wallet/balance?
 api_key=2e37638f335f0545c3719d34f4d20ed0&session_key=M4yZuZ4LjoJQj5BJfT
 kw2HnGw6MG8JyM-57519&nonce=326233766&sig=fake_sig

Example Response (XML) :

<wallet_response xmlns="https://api.friendster.com/v1/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="https://api.friendster.com/v1/ https://api.friendster.com/v1/friendster.xsd">
  <coins>10000</coins>
  <timestamp>1996-12-19T16:39:57-08:00</timestamp>
</wallet_response>

Example Error Response :

<error_response xmlns="<https://api.friendster.com/v1/>"
xmlns:xsi="<http://www.w3.org/2001/XMLSchema-instance>"
xsi:schemaLocation="https://api.friendster.com/v1/
https://api.friendster.com/v1/friendster.xsd">
  <error_code>300</error_code>
  <error_msg>Wallet does not exist</error_msg>
</error_response>

GET PAYMENT REQUEST

Resource URL: https://api.friendster.com/v1/wallet/payment

Resource Methods: POST (Initiate purchase of a product by getting a request token)

Resource Description:API to initiate a purchase of a virtual good or service to the currently logged in user. The API will return a request token and a redirect URL. The redirect URL is a page hosted by friendster where the user will be asked to authenticate the transaction by providing his or her password, the app will have to provide a means to redirect the user to that page (see Payments Authentication Page). The request token can be used by the app to determine if the payment authentication is successful, if so the app must then proceed to call "/v1/wallet/commit" to confirm the transaction. The request_token is valid for a maximum of 10 minutes from the time this api was called. A request_token can still be obtained even when the user has insufficient balance. In this case the wallet authentication page will present the user with the process to purchase coins if necessary.

Request :

string api_key Unique API ID given to each game.
string session_key Session identifier.
numeric nonce Unique ID that avoids replay attacks.
string name The name of the product to purchase (App defined, max 30 characters). It is advised to prefix the product name with the game name (e.g. Petstore – 200 credits) to facilitate easier reporting.
string description A description of the transaction. (max 200 characters)
numeric amt The transaction amount in Friendster coins (should be greater than 0)
string params additional params to be included in the return URL.
string image_url (optional) optional full url of product image
string display_name Optional display name of the product
string sig Signature of the Request.
string format (optional) XML (default), JSON.

Response :

string request_token A token that the game can use to monitor the status of the transaction and is used to complete the transaction using the payment commit API call.
string redirect_url The url that the user must be redirected to so that they can authenticate the transaction. This is the location of the payments authorization page.

Error Conditions/Response :

Error Code Error Condition
300 Wallet Does not exist 404
301 Invalid Wallet
302 Wallet Unexpected The specified user does not have a wallet yet and an attempt was made to access it
307 Access Denied - The users' wallet is either suspended or invalid. The user should be advised to seek customer support

Example Request :

https://api.friendster.com/v1/wallet/payment?
api_key=2e37638f335f0545c3719d34f4d20ed0&session_key=M4yZuZ4LjoJQj5BJfTkw2HnGw6
MG8JyM-57519&description=New%20Bag&amt=1000&nonce=326233766&sig=fake_sig

Example Response (XML) :

<wallet_response xmlns="https://api.friendster.com/v1/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="https://api.friendster.com/v1/ https://
api.friendster.com/v1/friendster.xsd">
<request_token>a5u3jhdidufyset-9017</request_token>
<auth_url>https://wallet.friendster.com/authenticate</redirect_url>
</wallet_response>

Example Error Response :

<error_response xmlns="https://api.friendster.com/v1/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="https://api.friendster.com/v1/
https://api.friendster.com/v1/friendster.xsd">
  <error_code>303</error_code>
  <error_msg>Insufficient Coins</error_msg>
</error_response>

COMMIT PAYMENT REQUEST

Resource URL: https://api.friendster.com/v1/wallet/commit

Resource Methods: POST (commit the transaction)

Resource Description:API to COMMIT the wallet purchase transaction initiated by Get Payment Request. The caller must pass the request_token corresponding to the transaction that it wishes to commit. The request_token must have been authenticated by the customer. If successful, the transaction id will then be returned by the service. A particular request_token can only be committed once, succeeding calls will result to an error being returned.

Request :

string api_key Unique API ID given to each game.
string session_key Session identifier.
numeric nonce Unique ID that avoids replay attacks.
string request_token The request token returned by the returnUrl or provided by the request_token purchase transaction Get Payment Request
string sig Signature of the Request.
string format (optional) XML (default), JSON.

Response :

numeric amt Amount of the transaction in Friendster coins
string transaction_id The transaction reference number
string timestamp The time when the transaction was committed, based on RFC 3339

Error Conditions/Response :

Error Code Error Condition
300 Wallet Does not exist 404
301 Invalid Wallet
302 Wallet Unexpected The specified user does not have a wallet yet and an attempt was made to access it
307 Access Denied - The users' wallet is either suspended or invalid. The user should be advised to seek customer support

Example Request :

https://api.friendster.com/v1/wallet/commit?
api_key=2e37638f335f0545c3719d34f4d20ed0&request_token=a5u3jhdidufyset-9017&
session_key=M4yZuZ4LjoJQj5BJfTkw2HnGw6MG8JyM-
57519&nonce=326233766&sig=fake_sig

Example Response (XML) :

<wallet_response xmlns="https://api.friendster.com/v1/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="https://api.friendster.com/v1/ https://
api.friendster.com/v1/friendster.xsd">
  <amt>500</amt>
  <transaction_id>0003448717ZQAVPF9DE</transaction_id>
  <timestamp>1996-12-19T16:39:57-08:00</timestamp>
</wallet_response>

Example Error Response :

<error_response xmlns="https://api.friendster.com/v1/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="https://api.friendster.com/v1/
https://api.friendster.com/v1/friendster.xsd">
  <error_code>304</error_code>
  <error_msg>Invalid Wallet token</error_msg>
</error_response>

COMMIT CONFIRM PAYMENT REQUEST

Resource URL: https://api.friendster.com/v1/wallet/commit/confirm

Resource Methods: POST (commit the transaction)

Resource Description:API to CONFIRM the wallet purchase commit transaction initiated by Commit Payment. The caller must pass the request_token corresponding to the transaction that it wishes to confirm. The request_token must have been authenticated by the customer. If successful, the transaction id will then be returned by the service.

Request :

string api_key Unique API ID given to each game.
string session_key Session identifier.
numeric nonce Unique ID that avoids replay attacks.
string request_token The request token returned by the returnUrl or provided by the request_token purchase transaction Get Payment Request
string sig Signature of the Request.
string format (optional) XML (default), JSON.

Response :

numeric amt Amount of the transaction in Friendster coins
string timestamp The time when the transaction was confirmed, based on RFC 3339

Error Conditions/Response :

Error Code Error Condition
300 Wallet Does not exist 404
301 Invalid Wallet
302 Wallet Unexpected The specified user does not have a wallet yet and an attempt was made to access it
307 Access Denied - The users' wallet is either suspended or invalid. The user should be advised to seek customer support

Example Request :

https://api.friendster.com/v1/wallet/commit/confirm?
api_key=2e37638f335f0545c3719d34f4d20ed0&request_token=a5u3jhdidufyset-9017&
session_key=M4yZuZ4LjoJQj5BJfTkw2HnGw6MG8JyM-
57519&nonce=326233766&sig=fake_sig

Example Response (XML) :

<wallet_response xmlns="https://api.friendster.com/v1/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="https://api.friendster.com/v1/ https://
api.friendster.com/v1/friendster.xsd">
  <amt>500</amt>
  <timestamp>1996-12-19T16:39:57-08:00</timestamp>
</wallet_response>

Example Error Response :

<error_response xmlns="https://api.friendster.com/v1/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="https://api.friendster.com/v1/
https://api.friendster.com/v1/friendster.xsd">
  <error_code>304</error_code>
  <error_msg>Invalid Wallet token</error_msg>
</error_response>

PAYMENTS AUTHENTICATION PAGE

A page hosted by Friendster that users can use in order to authenticate transactions coming from an app. This page makes sure that only Friendster knows about the users’ password and not the app. For reference purposes this page will be referred to as the "Payments Authentication Page". The URL of the page depends on the type of environment used by the wallet API, either if it is sandbox or normal mode. The URL to use will be returned by the GET PAYMENT request API via the “redirect_url” parameter. The page will contain the following:

  • The Name of the APP based on the api_key sent by the game.
  • The description of the transaction
  • The amount of the transaction
  • Place to enter the password

The page will show up even if the current user does not have a wallet defined. Possible behaviors are as follows:

  • If the user does not have a wallet, the authentication page will display links that would enable the user to activate his or her wallet (This will open up in another tab).
  • If the user does not have enough balance, a message will appear that he/she does not have enough balance and a link will appear telling the user to go to the topup page.

Resource URL : https://{redirect_url}

Resource Description : The Game should issue a HTTP redirect (or open it up in a new browser popup or tab) to the url returned by the GET payment request call.

Request :

string api_key The api key that identifies a game
string request_token The request token that was obtained using /v1/wallet/payment. The request token can be authenticated only once and if the user cancels the transaction you must request for a new one.
string return_url The url the page will redirect to after the user authenticates the transaction. Also known as the callback, if no URL is given the page will just close.
string sig A signature computed from the apps secret, the app should compute the sig to verify that it originated from Friendster. (refer to the API Framework docs on how this is computed)

EXAMPLE REQUEST:

Assuming the redirect url passed to you is https://api.friendster.com/wallet/authenticate you should load or issue a HTTP redirect to the following URL:

https://api.friendster.com/wallet/authenticate?api_key=669d598ee50fa90a05ddedbcbc45bd25&
return_url=http%3A%2F%2Fdevappx2.gbxsc.friendster.com%3A2375%2Fwalletui
%2Fconfirm.php&request_token=1d65ad33e9&sig=483726fdyagwyerjdufy

CALLBACK

After the user has successfully authorized the transaction, Friendster will issue a HTTP redirect back to your app passing the parameters as described below:

Assuming the return_url that you specified is http://www.mycoolgamesite.com/purchase_complete, Friendster will then issue the following HTTP redirect:

http://www.mycoolgamesite.com/purchase_complete?
api_key=2e37638f335f0545c3719d34f4d20ed0&api_domain=api.friendster.
com&sandbox=false&request_token=aye18374182adg&
params=myref&session_key=6rhe6rbh645364354d&
signed_keys=api_key,api_domain,sandbox,request_token,params,session_key,signed_keys&
status=1&sig=hsajdfiseyrqhwejr

The parameters passed is described as follows:

int amt The amount of the authenticated transaction in Friendster coins.
string api_key The api key that identifies an application
string api_domain The api endpoint the app should call
string request_token The request token that was obtained using /v1/wallet/payment. The request token can be authenticated only once and if the user cancels the transaction you must request for a new one. The app should then use this request token in the /v1/wallet/commit call to complete the transaction
string session_key The session key that the app can use for making API calls, the session key provided is in the context of the user that made the payment.
int user_id The user_id of the user
string return_url The url the page will redirect to after the user authenticates the transaction. Also known as the callback, if no URL is given the page will just close.
string sig A signature computed from the apps secret, the app should compute the sig to verify that it originated from Friendster. (refer to the API Framework docs on how this is computed)
close