http://developers.facebook.com/docs/creditsapi/


API Overview

Facebook Dredits APIを使うと、ユーザはキャンバスアプリケーション上で、クレジットを用いてデジタル／バーチャルなグッズを購入することができます。このAPIはまだキャンバスアプリケーション専用で、外部のウェブサイトでは利用できないことに注意してください。

ユーザは"Pay with Facebook"をクリックすることによって発注します。注文はJavaScriptを用いてFacebookへ送られます。'order_info'パラメータの中身（以下をご覧ください）によってFacebookはアイテムの詳細を得ます。

詳細を送られるとFacebookはその情報をユーザに表示し、ユーザが確認するのを待ちます。ユーザが十分なクレジットを持っているか、クレジットカード情報を預けている、もしくは他の支払い方法を用いている場合、アプリケーション画面から遷移すること無しに確認ダイアログが表示されます。ユーザのクレジットが支払い方法を持たない場合は、支払い方法によってはクレジット情報の入力用ページへリダイレクトされたり、そのままダイアログに留まったりします。

ユーザ自身が支払いの意思を確認すると、Facebookはアプリケーションバックエンドを呼び、アプリケーションのシステムに注文を確定させます。アプリケーションがレスポンスを返すと、Facebookは適切に取引を完了させ、ユーザに結果を表示します。ダイアログ中で支払いが完了した場合、ユーザはcontinueをクリックしてダイアログを閉じ、アプリケーション側のjavascriptの動作に従います。千位後のページで支払いが行われた場合、ユーザはcontinueをクリックしてアプリケーションが指定したURLへ移ります。

Credits APIは２つのコンポーネントから成り立ちます。フロントエンドとバックエンドです。以下の図がシンプルな注文プロセスを解説しています。



23ml8o1

Setting Up Your Application

Creditsを利用できるようにするには、Developer Appページへ行って該当アプリケーションの"Edit Settings"をクリックしてください。それから左側メニューの"Credits"を選択し、表示されるステップに従います。

利用可能状態になると、Githubからサンプルをダウンロードしてテスト環境をセットアップできるようになります。詳細情報へのリンクなどはこちらをご覧ください。

新しいJS SDKを利用する場合には、OAuth2.0のsigned_requestを扱える状態になっていることを確認します。developerアプリケーションのAdvanced > Migrations > OAuth 2.0 for Canvas(beta) メニューで確認できます。自分自身をテストユーザに加えることも忘れないでください。テストユーザからの注文は実行されず、支払いを請求されることはありません。
いま現在、Facebook上のIFrameアプリケーションのみが以下のCredits APIメソッドを利用できます。Facebook Connectを用いた外部サイトでは利用できません。 

Best Practices Guide

あなたのアプリケーションがFacebook Creditsを正しく動作させられることを確認するために実装ガイドが提供されています。このガイドは効率よくクレジット機能を実装することを助け、実装方法の違いを明確にしてくれます。

Creating your Callback

クレジット機能を実装したアプリケーションには、アプリケーション設定でコールバックURLが指定されています。ユーザがアプリケーション内部のFacebook Creditsボタンをクリックすると、FacebookがそのURLを呼びます。Facebookとアプリケーションの複数タイプの対話を可能にするため、相当量のコーディングが必要となります。 

Facebookoがリクエスト（payリクエストなど）を受けると、FacebookはコールバックURLを呼び、"payments_get_items" というメソッド名とorder_infoフィールド値が返されます。FacebookとコールバックURLとの間で送られる全情報はJSONエンコードされているので、自分でデコードする必要があります。

コールバックは、methodという名前のPOST値によって処理を分けるような条件分岐を持たなくてはなりません。payments_get_itemsが渡ってきた場合、order_infoというPOST値を見て、あなたがFacebookに対して渡した値を得ます。

自身のデータベースをでproduct_id を参照して、item_title, item_description, price, product_url, image_urlを引き出し、それぞれ該当するフィールドを補完します。

それらの値が渡されると、アイテム情報と"Confirm/Cancel"ボタンが入ったポップアップダイアログが表示されます。

購入者が"Confirm"をクリックするとFacebookは先ほどと同じコールバックを呼び、"payments_status_update"、placedという値が指定された"status"、注文番号、アイテム情報を渡します。あなたのプログラムは再度、methodという名前のポスト値をパースし、 "payments_status_update"メソッドを元にロジックを切り分けます。これらのメソッド呼び出しのロジック中で、statusとorder_idもパースするべきです。

statusパラメータの値にplacedが指定されていることを確認してください。指定されていたら、next_stat="settled"を指定してFacebookへ返します。メソッド名と注文IDも一緒に返さなくてはなりません。するとFacebookはトランザクションを開始し、購入者の残クレジットを確認してあなたのアカウントに移します。これが完了すると、もういちどコールバックURLが呼ばれ、"payments_status_update"メソッドとsettledが指定されたstatusパラメータが渡されます。この段階になって初めてトランザクションは完了し、ユーザに対してアイテムを与える動作に移ることができます。

Application Callback の項目で詳細を確認してください。

Githubのcallback.phpサンプルを参考にすることもできます。


Payment Prompt

payメソッドを使うと、アイテム情報が含まれるモーダルダイアログを表示することができます。ダイアログには、アイテムのタイトル、説明文、値段、アイテム画像が含まれます。

注意：payメソッドを使う際には、あなたにとってのみ意味を成す内部的なキーを使い、それを基にデータベースからアイテム情報のレコードを取得すべきです。

以下は、JavaScriptでFacebook Credits APIを利用するサンプルコードです。これを手軽にテストするには、GithubのCredits Sample App を使います。


Making call using the JS SDK:

     // This example requires callback.php to be enabled and coded.

 <html>
    <head>
      <title>My Facebook Credits Page</title>
    </head>
    <body>
      <div id="fb-root"></div>
      <script src="http://connect.facebook.net/en_US/all.js"></script>
<p> <a onclick="placeOrder(); return false;">Buy Stuff</a></p>

<script> 
    FB.init({appId: <your_app_id>, status: true, cookie: true});

    function placeOrder() {

      // Assign an internal ID that points to a database record
      var order_info = 'abc123';

      // calling the API ...
      var obj = {
        method: 'pay',
        order_info: order_info,
        purchase_type: 'item'
      };

      FB.ui(obj, callback);
    }
    
    var callback = function(data) {
      if (data['order_id']) {
        return true;
      } else {
        //handle errors here
        return false;
      }
    };

    function writeback(str) {
      document.getElementById('output').innerHTML=str;
    }
</script>
</body>
 </html>

アトリビュート：

  • method - pay指定
  • order_info - 製品情報を得るのに使う内部キー
  • purchase_type - item指定

新規ページでダイアログを開くにはpay dialog documentationを参照してください。

Get More Credits

このAPIを用いると、ユーザはアイテムを購入する事なしに追加のクレジットを購入できます。


Making call using the JS SDK:

 <html>
    <head>
      <title>My Facebook Credits Page</title>
    </head>
    <body>
      <div id="fb-root"></div>
      <script src="http://connect.facebook.net/en_US/all.js"></script>
<p> <a onclick="getMore(); return false;">Get More</a></p>

<script>
 function getMore(){
    // Initialization
    FB.init({appId: <your_app_id>, status: true, cookie: true});

    // calling the API ...
    var obj = {
         method: 'pay',
         credits_purchase: true,
    };

    FB.ui(obj, callback);
 }
</script>
</body>
 </html>

Attributes:

  • method: string - 新しいJS SDKのメソッドで、クレジット購入ダイアログを初期化します。
  • credits_purchase - boolean

Earning Credits Using Offers

この機能を使うと、ユーザは広告主の提示を受け入れる事によってクレジットを得る事ができます。Direct Access to Offers integration guideをダウンロードして習得してください。


Making call using the JS SDK:

 <html>
    <head>
      <title>My Facebook Credits Page</title>
    </head>
    <body>
      <div id="fb-root"></div>
      <script src="http://connect.facebook.net/en_US/all.js"></script>
<p> <a onclick="earnCredits(); return false;">Earn Credits</a></p>

<script>
 function earnCredits(){
    // Initialization
    FB.init({appId: <your_app_id>, status: true, cookie: true});

    // calling the API ...
    var obj = {
         method: 'pay',
         credits_purchase: true,
         dev_purchase_params: {"shortcut":"offer"}
    };

    FB.ui(obj, callback);
 }
</script>
</body>
 </html>
注意：新しいJS SDKに切り替えていない場合、Direct Access to Offers guideを参照すると代替方法がわかります。


Attributes:

  • method: string - 新しいJS SDKのメソッドで、クレジット購入ダイアログを初期化します。
  • credits_purchase - boolean
  • dev_purchase_params - JSON object

Earning Credits Using DealSpot

この機能を使うと、ユーザは日々の提示を達成することによってクレジットを得ることができます。DealSpot integration guideをダウンロードして習得してください。


Making front end call:

http://assets.tp-cdn.com/static3/swf/dealspot.swf?app_id=&mode=fbpayments&sid=

パラメータ：

  • app_id: アプリケーションID
  • sid: ユーザのサードパーティID

注意：

  • DealSpotは、プロモーションの可否に応じて自動的にディールアイコンを切り替え（必要に応じて隠し）ます。
  • DealSpotのSWFを許可して、ホストとなるページと対話できるようにしてください。DealSpot integration guideで習得できます。

Get Balance

このAPIを用いると、ユーザの残高を決定することができます。ゲーム中での通貨としてクレジットを利用するアプリのみ使うことができます。こちらから申請できます。

注意：今現在、旧PHP SDKからのみ利用可能です。また、実際に関数を呼ぶ前に、ユーザを再認証する必要があります。


Making backend call:

$obj = json_decode( 
         file_get_contents('https://api.facebook.com/method/users.getStandardinfo'.
                           '?uids=<UID>&fields=credit_balance&access_token='.
                           '<ACCESS_TOKEN>&format=json'));

returns Array ( [0] => stdClass Object ( [uid] =>  [credit_balance] => 48 ) )

Attributes:

  • $user_id: user id - アプリケーションを追加済みのユーザでなくては成りません。
  • $access_token: access_token - アプリケーションのアクセストークン

Gamer Status

全ユーザはgamer_statusでタグ付けされています。gamer_status > 0 の状態にタグ付けされたユーザ群は通常よりも高いマネタイズ効果を持っていて、クレジットの20%割引対象となりますので、あなたのゲーム経済に影響を与え得ます。gamer_statusタグはユーザに関して特定の情報を与えるものではありませんが、他の一般ユーザよりも高いマネタイズ性を持っていることを示しますから、Facebook Creditの割引になる可能性があるのです。

gamer_statusを内部機能やゲーム管理用の機能以外の目的、例えばマーケティング目的に用いることはできません。あなたはこれらのユーザに対して特別割引を行うことができますが、値上げすることはできません。

$ret = $facebook->api_client->users_getStandardInfo($user_id, array('gamer_status'));

Buy with Friends

これは開発者がプロモーションや取引をより効率的に行うための機能で、ユーザがプロモーション／取引を友達同士で共有することを簡単にし、共有対象となった友達はnews feedから直接購入することができます。Creditをゲーム中の貨幣として指定している開発者のみが対象です。こちらで申請してください。

Buy With Friendsを使うには、ある特定のパラメータ（期間、割引率、その他）を指定してdealを作成する必要があります。そして、一つもしくは複数のアイテムをdealに足します。必ずDeal Graph APIを用いて、対象ユーザが取引可能な相手であるか確かめてください。


Making call using the JS SDK:

<script>
 …
 // Initiate JS FB object
 FB.init({appId: [app id], status: true, cookie: true});

 var order_info = [order information];

 // Purchase parameters
 // Assumes you’ve already created a deal
 var dev_purchase_params = {
   deal_id: [deal id]
 };

 // Populate request object
 var obj = {
   method: "pay",
   order_info: order_info,
   // A purchase for credits so set to true
   credits_purchase: true,
   dev_purchase_params: dev_purchase_params
 };

 // Submit order to Facebook
 FB.ui(obj, callback);
 …
</script>

まずFacebookが Buy with Friendsダイアログを開きます。payments_get_itemsコールバックへリクエストが行かないことに気をつけてください。Facebookは、dealオブジェクトやGraph API上の製品から提供された情報を用いてBuy With Friendsダイアログを生成します。

ゲーム中でのインセンティブはこちらから申請できます。


Frictionless Payments

2011年5月2日から、100Facebook Credits以下のアイテムを対象に、自動化されたFrictionless Paymentsを提供する予定です。ユーザがアイテムを購入するとFacebookは自動でダイアログを表示します。結果、以下に説明されているFrictionless Payments APIを利用する必要が無くなります。ベストプラクティスとしては、まず100 Facebook Creditsより安いアイテムには値段が明記され、「購入する」ボタンが近くにあるようにしてください。

注意：すでにゲームアイテムにFrictionless Payments APIを用いている場合、それらのアイテムは影響を受けるべきではありません。しかしながら、自動化されたFrictionless Paymentsが全ユーザに対して利用可能となったら、通常のFrictionless Payments APIから切り替えるようお勧めします。そして、通常の支払いフローを使うようにすると、100クレジット未満の支払いに対してはデフォルトでFrictionless Paymentsが使われるようになります。

この機能があると、開発者はFacebook Credits Payment Dialogを表示すること無しにユーザからの引き落としが可能となります。pay dialogの代替手段ではありません。必要とされる金額と同等、もしくはそれ以上の残高を持っているユーザのみが利用可能です。この機能の利用対象となるのは、ゲーム中での貨幣をCreditsに指定した開発者のみです。こちらで申請してください。

ユーザが十分な残高を持っていない場合のイベントは、pay dialogを表示して追加クレジットを購入させるなど、明示的に行ってください。この追加購入プロセスが完了すると、再度実行されます。

あなたは内部キーをFacebookに渡しているので、Facebookはpayments_get_itemsを用いて、製品の値段を返すよう要求します。途中に確認ステップは無いので、Facebookは自動的に"payments_status_update"に"settiled"を指定します。

注意：このAPIを利用するには、直近30分以内にユーザがアプリケーションを利用している必要があります。この時間の制限は、アイテム購入とユーザ残高からの引き落としを結びつける為に必要です。


Calling frictionless using the Graph API

$app_id = APPLICATION_ID;
$app_secret = APPLICATION_SECRET;
$to_id = USER_ID_TRANSFERRING_FUNDS;

$app_token_url = "https://graph.facebook.com/oauth/access_token?client_id=".
    $app_id."&client_secret=".$app_secret."&grant_type=client_credentials";

$app_access_token = file_get_contents($app_token_url);

$url = "https://graph.facebook.com/".$app_id."/payments?to=".$app_id."&from=".
$to_id."&"."order_details=abc123&method=post&".$app_access_token;

$ret = file_get_contents($url);

echo "Order ID: ".$ret;


Parameters:

  • [app id] - アプリケーションID
  • access_token - application access token.
  • from - ユーザID
  • to - アプリケーションID
  • order_details - あなたのデータベース中の製品レコードを示す内部キー

Error Codes:

Error CodeSuggested Action
API_EC_INSUFFICIENT_BALANCEJSでCreditsフローを開始
API_EC_PAYMENTS_UNKNOWNユーザにエラーを通知
API_EC_PAYMENTS_APP_INVALIDアプリケーションの不備
API_EC_PAYMENTS_DATABASEデータベースエラー。再度試してください。
API_EC_PAYMENTS_PERMISSION_DENIEDJSでCreditsフローを開始
API_EC_PAYMENTS_APP_NO_RESPONSE失敗したアプリケーションのコールバック
API_EC_PAYMENTS_APP_ERROR_RESPONSEエラーレスポンスを受け取ったアプリケーションのコールバック
API_EC_PAYMENTS_INVALID_ORDER提供された注文IDが正しくありません。
API_EC_PAYMENTS_INVALID_PARAMPaymentsパラメータの一つが正しくありません
API_EC_PAYMENTS_INVALID_OPERATIONオペレーションが正しくありません。
API_EC_PAYMENTS_DISABLED Facebook Creditsが利用できません

Credits Graph API

Facebook Credits APIを用いてアプリケーションが作成した注文情報を得ることができ、必要に応じて更新することが可能です。Order IDはGraph API上のオブジェクトです。

注意：Graph APIを用いる時には、実在する注文を使ってください。テストユーザからの注文は実行されません。

Get Order

任意のorder_idについて詳細な注文情報を返します。


API

GET https://graph.facebook.com/[order id]?access_token=ACCESS_TOKEN


Parameters:

  • [order id] - 注文の64ビットのID
  • access_token - アプリケーションのアクセストークン

Returns:

  • a JSON object: 
                {
               "id": "",
               "from": {
                  "name": "",
                  "id": ""
               },
               "to": {
                  "name": "",
                  "id": ""
               },
               "amount": ,
               "status": "",
               "application": {
                  "name": "",
                  "id": ""
               },
               "country": "",
               "created_time": "
  • refund_code: Facebookによって払い戻しが行われた場合にのみ返されます。詳細については下記のRefund Reason Codesをご覧ください。

Update Order

既存の注文情報を更新します。


API

POST https://graph.facebook.com/[order id]?access_token=ACCESS_TOKEN&status=STATUS&message=MESSAGE&refund_funding_source=SOURCE


Parameters:

  • [order id] - 注文の64ビットID
  • access_token - アプリケーションのアクセストークン
  • status - 変更後のステータス指定。settled/refunded/canceledのいずれかです。
  • message - 更新に付随するメッセージ。
  • refund_funding_source - 真偽値。支払い（クレジットカード、ペイパル、その他）の払い戻しをするなら真。それ以外なら偽。
  • refund_reason - 払い戻しの理由
  • params - 付随情報のオプション。{'comment' => }

Returns:

  • 成功／失敗の真偽値

Get Orders

任意のアプリケーションへの全注文を返します。

注意：date/time範囲指定の一度のリクエストで返すのは、今のところ100,000レコードが上限です。24時間の範囲内でそれ以上の注文情報が必要な場合は、範囲を小分けして複数回のクエリを発行してください。


API

GET https://graph.facebook.com/[app id]/payments?status=STATUS&since=SINCE&until=UNTIL&access_token=ACCESS_TOKEN
GET https://graph.facebook.com/[user id]/payments?status=STATUS&since=SINCE&until=UNTIL&access_token=ACCESS_TOKEN


Parameters

  • [app id] - アプリケーションID
  • [user id] - ユーザID。対象ユーザはアプリケーション利用者でなくてはなりません。
  • status - 指定したステータスの注文のみ返します。reserved/settled/refundedのいずれかです。
  • since - Unix time
  • until - Unix time. startとendの範囲は24時間を超えることができません。１週間分の情報が欲しいときは、getOrdersを7回実行してください。
  • access_token - アプリケーションのアクセストークン。

Returns:

  • A JSON object: 
                {
               "data": [
                  {
                     "id": "",
                     "from": {
                        "name": "",
                        "id": ""
                     },
                     "to": {
                        "name": "",
                        "id": ""
                     },
                     "amount": ,
                     "status": "",
                     "application": {
                        "name": "",
                        "id": ""
                     },
                     "created_time": "

Application Callbacks

アプリケーションのバックエンドに対してFacebookから呼ぶコールバックは2つあります。アプリケーション側はfb_sigパラメータを見てリクエストがFacebookから来ていることを確認してください。


payments_get_items: コールバック実行時に、Facebookからorder_id、order_info、対象アイテムのJSONエンコードされた配列が渡されます。
Parameters:

  1. order_id - 注文の64ビットID
  2. order_info - フロントエンド側でアプリケーションからFaecbookへ渡されたorder_info

Return value: {items}のJSONエンコードされた配列。

注意：今のところ、一つのアイテムのみが対象となりますが、配列で返されます。


An item has the following fields:

  1. item_id - アプリケーション側で用いる固有ID。Facebook側で利用されることはありません。
  2. title - 50文字以下の製品名
  3. description - 175文字以下の製品の説明
  4. image_url - ユーザに表示する画像のURL
  5. product_url - ユーザに製品を表示するページのURL
  6. price - 0クレジット以上の値を持つ値段
  7. data - Facebook側では利用されないオプション値。ただし、Facebookに保持され、order_detailsと共にアプリケーションへ渡されます。

Example callback response from developer:

{"content":[{"title":"[Test Mode] Unicorn","description":"[Test Mode] Own your own mythical beast!","price":2,"image_url":"http:\/\/www.facebook.com\/images\/gifts\/21.png","product_url":"http:\/\/www.facebook.com\/images\/gifts\/21.png"}],"method":"payments_get_items"}

payments_status_update: Facebookはorder_detailsと注文のstatus情報とともにアプリケーションを呼び出します。アプリケーション側は、注文の更新後のstatus値を返します。


Parameters:

  1. order_id - 注文の64ビットID
  2. status - placed, reserved, settled, canceledのいずれか
  3. order_details - payments_get_itemsで渡された情報全て

Returns:

  1. status - 更新前のステータスに従って変わるステータス (下記参照)

How to Respond: statusがplacedである場合、アプリケーションはcanceledもしくはsettledを返すことができます。

注意：fb_sigパラメータを確認してFacebookからの呼び出しであることを確認する必要があります。


Order Statuses settled, canceled, refundedの3つのうちの一つのステータスを返すことができます。

StatusNotes
settledトランザクションが"キャプチャされた"ときに発生しますので、"authorized"からの遷移です。この時点で、購入者のアカウントから引き落とされます。
canceledplaced以外のステータスからcanceldになることはありません。このステータスが指定される場合というのは、ユーザが十分な残高を持っていなかった場合です。クレジットがゲーム中で使われることは無く、ユーザのアカウントに残ります。
refundedこのステータスは開発者本人もしくはFacebookによって指定されます。対価は購入者に戻され、認証に関して開発者に手数料が請求されることはありません。

Reporting

月二回のレポートと同様、日々のレポートはサインアップ時に指定されたメールアドレスに対してFacebook Credits<noreply@fb.com>アカウントから送信されます。受け取れないという事がないよう、スパムフィルタの設定を確認してください。それぞれのファイルは100,000行を越える事はありませんが、もし100,000で足りないだけのトランザクションがあった場合は、複数ファイルに分けて送信されます。


Digest Report

digestレポートには企業が所有するアプリケーション内で起きた各トランザクションタイプの要約が含まれています。

メールのタイトルは下記のようなフォーマットで一意なものになっています。

COMPANY_NAME: Facebook Credits Daily Digest Report for DATE

Example:
My Sweet Company: Facebook Credits Daily Digest Report for 2011-03-02

レポート内容は各値がタブ区切りになった添付ファイル（.tsv）に収まっています。添付ファイルの名前は以下のようなフォーマットで一意なものです。

Digest_FBFINANCIALID_DATEOFREPORT.tsv

Example:
Digest_12345678910_2011-03-02.tsv

.tsvファイルは'\t'で区切られていて、改行は'\n'です。最初の行はフィールド名です。タイトルの行とサンプル値は下記をご覧下さい。

app_id  app_name    txn_type    txn_date    settle_date value   credits
12345678    CreditsApp  S   2011-03-02  2011-03-02  0.0 20.0
12345678    CreditsApp  S   2011-03-02  2011-03-02  0.1 139.0
12345678    CreditsApp  R   2011-03-02  2011-03-02  0.1 10.0
12345678    CreditsApp  D   2011-03-02  2011-03-02  0.1 5.0
123456789   CreditsAppTwo   S   2011-03-02  2011-03-02  0.0 10.0
123456789   CreditsAppTwo   S   2011-03-02  2011-03-02  0.1 269.0
123456789   CreditsAppTwo   R   2011-03-02  2011-03-02  0.1 4.0

Detail Report

detailレポートは企業が所有するアプリケーション内で起こった全トランザクションが含まれています。

メールのタイトルは下記のようなフォーマットで一意になっています。

COMPANY_NAME: Facebook Credits Daily Detail Report for DATE

Example:
My Sweet Company: Facebook Credits Daily Detail Report for 2011-03-02

レポート内容は各値がタブ区切りになった添付ファイル（.tsv）がzip形式で圧縮されたものです。添付ファイルのタイトルは下記のようなフォーマットで一意になっています。

Detail_FBFINANCIALID_DATEOFREPORT_CURRENTNUMEMAILOFTOTAL_TOTALNUMEMAILS.tsv.zip

Example:
Detail_12345678910_2011-03-02_001_001.tsv.zip

添付ファイルを解凍した中身の.tsvファイルは'\t'で区切られていて、改行は'\n'です。最初の行はフィールド名です。タイトルの行とサンプル値は下記をご覧下さい。

app_id  txn_type    txn_id  order_id    txn_time    settle_date value   credits
123456789   S   517433941473201975  9307560877689   2011-03-02 12:06:07 PST 2011-03-02  0.1 1.0

注意：一つの注文に対して同じtransaction ID/order IDで複数行のレコードが含まれる事があります。以下のような理由が考えられます。

app_id  txn_type    txn_id  order_id    txn_time    settle_date value   credits
123456789   S   517433941473201975  9307560877689   2011-03-02 12:06:07 PST 2011-03-02  0.1 1.0
123456789   S   517433941473201975  9307560877689   2011-03-02 12:06:07 PST 2011-03-02  0.0 9.0

もう一つの可能性としては、注文がrefundになった場合です。以下の例はトランザクション成功の１分後にrefundになった状態を示しています。

app_id  txn_type    txn_id  order_id    txn_time    settle_date value   credits
123456789   S   517433941473201975  9307560877689   2011-03-02 12:06:07 PST 2011-03-02  0.1 1.0
123456789   R   517433941473201988  9307560877689   2011-03-02 12:07:07 PST 2011-03-02  0.1 1.0

Payout Summary

payout summaryは毎月の5日と20日に送られます。これにはzip圧縮された添付ファイルが添付され、日々のレポートと同じ形式で、全注文の詳細が含まれています。detailed report意外にも、それぞれのアプリケーションのサマリーが含まれます。

任意の支払い期間中のsummaryメールのフォーマットは以下の通りです。

app_id  app_name    txn_type    value   credits
13020537    MyTestApp   S   0.0 156.0
13020537    MyTestApp   S   0.1 729.0

Possible transaction types:

txn_typeType of Transaction
S (Spend)アプリケーション中でクレジットが消費された
R (Refund)クレジットがユーザもしくは開発者に対して払い戻しされた
C (Chargeback)Facebookか開発者によってユーザに対して払い戻しされた
D (Chargeback)90日以降のChargeback。
L (Deferred payment initiated)アイテム購入の支払いを、ユーザが引き延ばした
P (Deferred payment repayment)引き延ばした購入分の支払い完了。Facebookがクレジットを開発者へと移します。
F (Deferred payment refund)引き延ばした分の支払いが払い戻しされ、ユーザはクレジットを受け取らない
Q (Repayment refund)引き延ばした分の支払いがFacebookもしくは開発者によって払い戻された

Dispute Resolution

論争（dispute）解決システムはユーザと開発者に対して、Facebook Creditsを利用した過去の支払いについて話し合い、解決する方法を提供します。ユーザに対して払い戻しをする、もしくはユーザが満足していると明確にすることによって論争を解決することを信用していますし、適切な説明をするものと信用しています。


User Interaction

Facebookの決済システムを利用しているアプリケーションのキャンバスページ最下部には"Report"というリンクが置かれています。ユーザがここをクリックすると選択肢が現れますが、そのうちの一つが"Dispute..."で、以下の動作をします。

  1. 注文選択ダイアログが開かれ、直近30日以内の購入履歴が現れます。その一覧からユーザは不満を持った注文を選択し、その理由をフォームに入力します。
  2. 完了すると、ユーザの期待する内容が開発者／Facebook／ユーザに対してメールで送られます。

ユーザが苦情の申し立てをすると、statusにdisputedが指定された状態のpayments_status_updateがアプリケーションのapyments_callback_urlへ送られます。これはトランザクション中にアプリケーションへ送られる他のstatus-update通知と一貫性があります。アプリケーション側からも、/payments APIを使ってdisputedステータスの注文情報を得ることができます。


注意：ユーザとの論争を解決する間、開発者に対してメールが送信され、そのメールはユーザに対してもCCで送られます。開発者はこの対話チャンネルによって、ユーザが満足していることを確認できます。


Resolve a Dispute
開発者は２つの方法で論争を解決できます。

  1. /[order id] APIを用いて注文の払い戻しを行う。その際、適切なorder_idとstatus=refunded、それから理由を明記したcommentパラメータを送ってください。
  2. ユーザとのやり取りの後、課金に関してユーザの理解を得られたと確証があったら、/[order id] APIに対してorder_idとstatus=settled、それから理由を明記したcommentパラメータを送ってください。
注意：払い戻し以外の方法で解決したのが適切だったか理由を特定するため、理由を明記するのは必須となっています。

Chargebacks

アプリケーションは直近90日以内の支払い拒否に関して責任を負わなくてはなりません。支払い拒否が起きた場合、手数料を含む全額は払い戻されます。

Refund Reason Codes (GET to /[order id] API)

/[order_id] APIに対してGETリクエストを送った対象レコードがFacebookによって払い戻しされている場合、refund_reason_codeという追加フィールドが返されます。値は下記のうちの一つです。

Compromised Account
Stolen Financial Instrument
Not Fraud
User Confusion
Dev System Issue
FB System Issue


Call getOrder via graph API:

https://graph.facebook.com/ORDER_ID?access_token=ACCESS_TOKEN

Example Output:

{
   "id": "9003976483685",
   "from": {
      "name": "Daniel Schultz",
      "id": "221159"
   },
   "to": {
      "name": "Daniel Schultz",
      "id": "221159"
   },
   "amount": 1,
   "status": "refunded",
   "refund_reason_code": "FB System Issue",
   "application": {
      "name": "credits_new_reg",
      "id": "128163550571392"
   },
   "country": "US",
   "created_time": "2011-02-04T20:23:17+0000",
   "updated_time": "2011-02-08T19:12:03+0000"
}

Error Codes

フロントエンドとバックエンドAPI両方のエラーコードは下記の通りです。

Front End Error Codes

Error_codeError_messageNote
1383001UnknownFacebookのシステム不具合
1383002InvalidParameters開発者の指定したパラメータが不正
1383003PaymentFailureプロセスの失敗
1383004InvalidOperationFacebookが許可していない動作を開発者が指定した
1383005PermissionDeniedFacebookのシステム不具合
1383006DatabaseErrorFacebookのシステム不具合
1383007InvalidAppアプリケーションがホワイトリストに追加されていない。もしくはテスト中のアプリケーションで、ホワイトリストに足されていないユーザの支払い処理をしようとした。
1383008AppNoResponseアプリケーションが応答していない。サーバのタイムアウトの可能性
1383009AppErrorResponseアプリケーションがエラーコードをFacebookへ返した
1383010UserCanceled明らかにユーザが支払いフローをキャンセルした
1383011DisabledFacebookのシステム不具合
1383013OrderFailureAfterPurchaseCreditFacebookのシステム不具合
1383014DisputeFlowFacebookのシステム不具合
1383015AccountNotChargedアプリケーションが注文をキャンセルした
1383017ExceedCreditBalanceLimit残高に対するクレジット上限値に達した
1383018ExceedCreditDailyPurchaseLimitユーザが前もって決められた上限値に到達した
1383019ExceedCreditDailySpendLimitユーザが支払ったクレジットが、前もって決められた上限値に到達した
1383040UserThrottledアプリケーションが一時的に利用不可
1383041BuyerPaymentFailureユーザの支払い手段に対して課金できなかった
1383042LoggedOutUserログイン必須
1383043AppInfoFetchFailureFacebookのシステム不具合
1383044InvalidAppInfoアプリケーションのcallback URLが不正
1383045AppInvalidEncodedResponseアプリケーションがJSONエンコードされた正しいレスポンスを返さなかった
1383046AppInvalidDecodedResponseアプリケーションのレスポンスをJSONデコードしたが不正だった
1383047AppInvalidMethodResponseリクエストに合わないmethodパラメータをアプリケーションが返した
1383048AppMissingContentResponse contentフィールドが返り値に含まれなかった
1383049AppUnknownResponseError不明なレスポンスをアプリケーションが返した
1383050AppUserValidationFailedResponseアプリケーションのコールバック呼び出し時、ユーザのチェックに失敗
1383051AppInvalidItemParamアプリケーションの送るitemパラメータが不正（値段や数量が不正であるなど）
1383052EmptyAppIdアプリケーションIDが空

Back End Error Codes

The following errors can be returned in addition to the regular API exceptions:

Error CodeError NameNote
1150API_EC_PAYMENTS_UNKNOWN不明なエラー
1151API_EC_PAYMENTS_APP_INVALIDアプリケーションがFacebook Creditsを使える状態になっていない
1152API_EC_PAYMENTS_DATABASEデータベースエラー
1153API_EC_PAYMENTS_PERMISSION_DENIED注文情報をチェックするパーミッションがない
1154API_EC_PAYMENTS_APP_NO_RESPONSEアプリケーションのコールバック呼び出しに失敗
1155API_EC_PAYMENTS_APP_ERROR_RESPONSEアプリケーションのコールバックがエラーを返した
1156API_EC_PAYMENTS_INVALID_ORDER注文IDが不正
1157API_EC_PAYMENTS_INVALID_PARAM支払いパラメータの一つが不正
1158API_EC_PAYMENTS_INVALID_OPERATIONオペレーションが不正
1159API_EC_PAYMENTS_PAYMENT_FAILED支払いプロセスに失敗
1160API_EC_PAYMENTS_DISABLEDFacebook Creditsシステムが利用できない状態
1161API_EC_PAYMENTS_INSUFFICIENT_BALANCE残高が不十分
1162API_EC_PAYMENTS_EXCEED_CREDIT_BALANCE_LIMITクレジットの上限を越えた
1163API_EC_PAYMENTS_EXCEED_CREDIT_DAILY_PURCHASE_LIMIT一日あたりの購入上限を越えた
1164API_EC_PAYMENTS_EXCEED_CREDIT_DAILY_SPEND_LIMIT一日あたりのクレジット支払い上限を越えた
1166API_EC_PAYMENTS_INVALID_FUNDING_AMOUNT引き落とし額が注文時の支払額と合わない
1167API_EC_PAYMENTS_NON_REFUNDABLE_PAYMENT_METHOD支払い方法が払い戻し不可
1168API_EC_PAYMENTS_USER_THROTTLEDアプリケーションが、一部のユーザをthrottleする設定になっている。
1169API_EC_PAYMENTS_LOGIN_REQUIREDユーザが未ログイン
1170API_EC_APP_INFO_FETCH_FAILUREアプリケーション情報の取得時にエラー
1171API_EC_INVALID_APP_INFO不正なアプリケーション情報が返された
1172API_EC_PAYMENTS_APP_INSUFFICIENT_BALANCEアプリケーションが十分な残高を持っていない(app2user)
タグ ：
#Credit