티스토리 툴바

Daum
Tistory
로그인
Facebook2011/11/03 16:16

[페이스북] Facebook Credits API

원문 : http://developers.facebook.com/docs/creditsapi/
기준일 : 2011년 11월 1일

의역, 오역 많습니다. 참조만 하시기 바랍니다. 진짜 정확한 내용은 원문을 참조하세요! 
보시다가 제가 틀리게 번역한 부분은 댓글로 알려주시기 바랍니다.
 
Facebook Credits API


API 개요

페이스북 크레딧 API는 사용자가  크레딧을 사용하여 페이스북 앱 안에서 디지털, 가상 상품을 구매할 수 있게 한다.

사용자는 페이스북의 JavaScript SDK를 호출하는 버튼을 클릭하여 주문을 한다. 
페이스북에 전달되는 'order_info' 파라미터의 내용에 따라, 페이스북은 아이템에 대한 세부 정보를 얻을 수 있다.

페이스북은 사용자에게 이 세부 정보를 보여주고, 사용자의 확인을 기다린다.
만약 사용자가 충분한 크레딧을 가지고 있거나, 등록된 신용카드 또는 다른 지불에 관한 자격 증명이 있는 경우 앱에서 벗어나지 않고 
대화창에서 주문을 할 수 있다. 
사용자가 지불에 관한 자격 증명이 없는 경우, 사용자는 자격 증명을 입력할 수 있는 새로운 페이지로 이동 되거나,
지불 유형에 따라 대화창에 그대로 있게 된다.

사용자가 결제를 확인하면, 페이스북은  주문에 대한 지불을 위해 시스템에서 앱의 애플리케이션 Back end를 호출한다.
앱이 응답하면, 페이스북은 적절하게 트랜잭션을 완료하고, 사용자에게 결과를 보여준다. 
지불이 대화창에서 이루어졌다면, 사용자는 "Continue"를 클릭하여 지불창을 닫고 앱에 설정된 자바스크립트의 지시를 따르게 된다.
지불이 페이지에서 이루어졌다면 사용자는 "Continue"를 클릭하여 앱에 설정된 URL로 이동하게 된다.

크레딧 API는 "Front end credits API"와 "Back end credits API" 2가지 요소를 가지고 있다.
다음 그림은 주문 수행 절차를 간단하게 보여주고 있다.



앱 설정

앱에서 크레딧을 사용하려면, Developer사이트의 "앱"으로 가서, "Edit Settings"을 클릭한다.
그리고 왼쪽편에 있는 "Credits"를 클릭하고, 지시하는 단계를 따라가면 된다.
앱이 크레딧을 사용할 수 있다면, Githup에서 페이스북  샘플 애플리케이션을 다운로드 받아
테스트 환경을 설정할 수 있다.
링크와 페이스북 크레딧  브랜드 자산에 대한 자세한 정보는 이곳에서 찾아볼 수 있다.

새로운 JS SDK를 사용하는 경우 OAuth 2.0의 'signed_request' 파라미터를 설정해야 한다.
이것은 Developer 사이트의 "앱" 밑의 "Advanced->Migrations->OAuth 2.0 for Canvas (beta)"에서 할 수 있다.

당신을 테스트 사용자로 설정해야 하는 것을 꼭 기억해야 한다. 
테스트 사용자의 주문은 처리되지 않고, 거래에 대한 비용이 청구되지 않는다.

페이스북과 웹사이트 커넥트(Connect), 네이티브 iOS앱과 페이스북 iOS 앱에서 실행되는 모바일 웹 앱들은 페이스북 크레딧을 사용할 수 없다.


모범 사례 가이드

애플리케이션을 페이스북 크레딧과 같이 성공시키기 위해, 앱에 크리딧을 효과적으로 구현하는 과정을 도와주고, 통합 유형의 
명확한 차이를 알려주는 통합 가이드를 제공한다.


콜백 생성

크레딧이 활성화된 애플리케이션은 애플리케이션 설정에 정의되어 있는 "Callback URL"을 가지고 있다.
사용자가 앱에서 페이스북 크레딧 버튼을 클릭한 후에 페이스북은 이 페이지를 호출한다.
로직의 상당 부분은 페이스북과 앱사이의 여러 통신을 처리하는 Callback들의 코드로 이루어져 있다.

페이스북은 요청(지불요청)을 받으면, Callback URL을 호출하고 "order_info"필드에 전달되어야 할 여러 정보들과  
"payments_get_items"라는 "method"를 전달한다.
페이스북과 Callback URL사이에 전달되는 모든 정보는 JSON으로 인코딩 되어 있기 때문에 파싱하기전에 디코딩해야 한다.

Callback은 "method"라는 POST 변수를 파싱하는 조건문을 가지고 있어야 한다.
"method"가 "payments_get_items"인 경우 "order_info"라는 POST 변수를 파싱하고 페이스북에 전달했던 원래 값들을 가져온다.

상품 아이디(product_id)로 데이터베이스에서 조회하고, item_title, item_description, price, product_url, image_url과 같은 필드들에 값을 저장한다.

이것이 다시 전달되면 페이스북은 아이템 정보와 함께 "Confirm", "Cancel" 버튼을 가진 대화창을 표시한다.

구매자가 "Confirm"버튼을 클릭하면 페이스북은 같은 Callback URL을 호출하고, 아이템 정보, order_id(주문번호)와 "placed(주문)"가 설정된 
"status"와 함께 "payments_status_update"가 설정된 "method"를 반환한다.

Callback 프로그램은 다시 "method"라는 POST 변수를 파싱하고 "payments_status_update"로 설정되어 있는 곳으로 분기 시킨다.
그리고 이 "method"를 처리하는 로직에서 "status"와 "order_id"를 파싱해야 한다.

"status"가 "placed"인지 확인해야 한다. 그렇다면 "next_state"를 'settled(지불)'"라고 설정하고 페이스북에 재전송한다. 
반드시 "method" 이름(status)과 "order_id"를 전달해야 한다.

페이스북은 구매자의 크레딧  잔고를 확인하여 자금현황에 대해 파악하고, 잔고에서 당신의 계정에 적절한 크레딧을 이동시킨다.
이것이 완료되면, 페이스북은 다시 한번 "payments_status_update"값을 가진 "method"와 "settled"값을 가진 "status" 변수를 Callback URL로 보낸다.
이것으로 거래가 성공적으로 완료되었다면, 사용자에게 아이템을 주는 작업을 수행할 수 있다.

자세한 내용은 애플리케이션 Callback 섹션을 참조하세요!

또한 Github에서 크레딧 샘플 앱 callback.php를 볼 수 있다.


결제 프롬프트

"pay" 메소드를 사용하여 아이템에 대한 특정 정보를 가지고 있는 모달창을 열 수 있다.
모달창은 아이템의 이름, 설명, 크레딧의 가격, 아이템 이미지를 가지고 있다.

참고: 당신에게 의미가 있는 아이템 정보를 가지고 있는 데이터베이스 레코드를 가리키는 내부 키를 사용하여 "pay"를 호출해야 한다.

아래 코드는 모바일 웹 앱과 캔버스 아이프레임 애플리케이션에서 자바스크립트로 페이스북 크레딧 API를 어떻게 호출하는지 보여준다.

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() {
        // If using mobile, this is where you place the
        // iOS native app check for credits (see below)

        // 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',
          dev_purchase_params: {'oscif': true}
        };

        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"을 설정한다.
  •   dev_purchase_params - JSON 객체
새 페이지에 구매 창을 열고 싶다고 한다면 구매 창 문서를 참조하라.

"dev_purchase_params"의 "oscif"가 "false"로 설정되었다면, 사용자는 아래와 같은 창을 보게 될 것이다.


"dev_purchase_params"의 "oscif"가 "true"로 설정되어 있다면 좀더 효율적인 아래와 같은 창을 보게 될 것이다.


모바일 크레딧

구매창은 모바일 환경에서도 캔버스 앱과 같은 방법으로 랜더링 된다.
모바일 플랫폼에 대한 더 자세한 설명은 모바일 문서를 참조하세요!

페이스북 크레딧은 iOS 네이티브 앱을 지원하지 않는다.

당신의 앱이 네이트브 앱 안에서 동작하는지 확인하고, iOS에서 크레딧 사용을 적절하게 막으려면 아래 코드를 앱안에 넣어야 한다.

if (FB.UA.nativeApp()) {
  // add code to hide your Credits flows
}

이것은 모바일 브라우저에서 의 지불 흐름이다:



더 많은 크레딧 얻기

이 기능은 사용자가 해당 구입 항목을 구매하지 않고, 크레딧을 구입할 수 있는 API 호출이다.

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>

속성
  •   method: string - 크레딧 구매 창을 시작하는 신규 JS SDK 메소드
  •   credits_purchase - boolean

제안에 따라 크레딧 얻기

이 기능은 사용자가 광고주의 제안을 받아 크레딧을 얻을 수 있게 해준다. 
TrialAPay's "Direct Access to Offers integration guide"를 다운로드하고 살펴보시오.

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"를 참조하시오.

속성:
  •   method: string - 크레딧 구매 창을 시작하는 신규 JS SDK 메소드
  •   credits_purchase - boolean
  •   dev_purchase_params - JSON 객체

DealSport으로 크레딧 얻기

이 기능은 독점으로 매일 제공되는 제안을 받아 사용자가 크레딧을 얻을 수 있게 해준다.
자세한 내용은 TrialPay's의 "DealSpot 통합 가이드"를 다운로드 받으시오.

Front end 호출 만들기

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

파라미터:
  •   app_id: 페이스북 애플리케이션 ID 번호
  •   sid : 사용자 고유 써드-파티 아이디
참고: 
  •   DealSpot은 프로모션 상황에 따라 거래 아이콘을 자동으로 교체한다.(경우에 따라 숨기기도 함)
  •   호스트 페이지와의 통신을 위해 DealSpot SWF를 허용해야 한다.(예 trustcontent 옵션 true). 자세한 내용은 "DealSpot 통합 가이드"를          참조하시오.


잔액 가져오기

이 기능은 애플리케이션이 사용자의 잔액을 확인할 수 있는 API를 호출할 수 있다. 
이것은 게임내 통화로 크리딧을 사용하도록 지정한 개발자만이 가능하다. 이곳에서 적용 가능하다.

참고: 이 기능은 OLD REST API를 통해서만 사용할 수 있다. 또한 함수를 호출하기 전에 사용자가 허용도록 재인증 받은 후에야 사용할 수 있다.

Back end 호출 만들기

$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 ) ) 

속성:
  •   $user_id: user id - 애플리케이션이 미리 가지고 있어야 한다.
  •   $access_token: access_token - 애플리케이션에 대한  엑세스 토큰
게이머 상태

이 기능은 개발자들이 그들 게임의 경제 범위와 이해를 도와 줄 수 있는 API를 호출한다.

각 사용자들은 "gamer_status"로 태그되게 된다.
"gamer_status > 0"으로 태그되는 사용자 집합은 일반 사용자 집합보다 훨씬 높은 비율로 수익을 창출하고 있어, 
크레딧 패키이에서 20% 할인을 받을 수 있으며, 게임 경제에 영향을 줄 수 있다.
"gamer_status" 태그는 특정 사용자가 일반 사용자 집합보다 훨씬 높은 비율로 수익을 창출하는 사용자 집합에 속해 있다는 점을 빼고는,  어떠한 정보도 말해주지 않고, 확실하지는 않지만 페이스북 크레딧을 많이 할인발을 수 있는 가능성을 가지고 있다는 점만을 알려준다.

게임 운영에 관련된 관리나 내부적인 목적 이외의 다른 목적으로는 "gamer_status"를 사용할 수 없다.
예를 들어 마켓팅 목적으로 이 정보를 사용할 수 없다. 당신은 이러한 사용자들에게 특별 할인을 제공할 수 는 있지만, 가격 인상을 할 수 는 없다.

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

친구와 함께 구매

이 기능은 사용자들이 프로모션 이나 더욱 효과적인 거래를 할 수 있도록, 쉽게 친구들과 정보를 공유하게 하고, 친구들이 게임을 방문하지 않고도 
자신의 뉴스피드에서 직접 프로모션 아이템을 구매할 수 있도록 개발자에게 허용한다.
이것은 크레딧을 게임내 통화로 디자인한 개발자에게만 허용된다. 여기서 신청할 수 있다.

친구와 함께 구매를 사용하려면, 첫번째로 특정 파라미터들(duration, % discount, 등)과 거래를 만들고 그 거래에 한개 이상의 아이템을 지정해야 한다. 거래가 사용자가 사용할 수 있는지 아닌지를 결정하기 위해서는 거래 Graph API를 사용해야 한다.

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>

페이스북은 친구와 같이 구매할수 있는 구매장을 로드한다. 
페이스북은 정상적인 구매 흐름과 다른 "payments_get_itmes"콜벡 요청을 하지 않는다.
페이스북은 BWF 구매창을 구성하는 상품과 거래 개체에 대해. Graph API에서 제공된 정보를 사용한다.
당신은 여기서 게임 인센티브를 신청할 수 있다.


편의 지불(Frictionless Payments)

2011년 5월 2일 월요일에 우리는 약 1주일 동안 100 페이스북 크리딧 이하인 아이템을 위한 자동 편의 지불을 발표했다.
사용자가 아이템을 구매한 후 페이스북은 자동으로 사용자에게 성공 대화창을 보여준다.
결과적으로 아래 문서에 있는 "편의 지불 API"를 더 이상 호출하지 않아도 된다.

사용자 겸험을 유지하고, 잘 사용하기 위해 100 페이스북 크레딧 이하의 아이템에 명확한 가격 레이블이 구매 버튼 옆에 있는지를 확인해야 한다.

참고: 이미 게임 아이템에 편의 지불 API를 구현했다면, 이 아이템들은 영향 받지 않는다. 그러나 사용자들이 100% 자동 편의 지불에 대해 인식하게
되면 이 API를 지원하지 않고 기본적으로 100 크레딧 이하의 아이템은 자동 편의 지불이 표준적인 지불의 흐름이 될 것이다.

이 기능은 페이스북 크레딧 지불창을 시작하지 않고, 개발자가 플레이어의 잔액에서 인출을 가능하게 한다.
이 기능은 지불창을 대체하지는 않으며, 요청되는 금액과 같거나 큰 잔액을 가진 사용자 경우에만 동작한다.
추가로 귀하의 애플리케이션은 사용자의 크레딧 잔고를 표시해 주어야 한다.  
이것은 크레딧을 게임내 화폐로 디자인한 개발자인 경우에만 유효하다.
여기서 신청할 수 있다.

당신은 부족한 크레딧을 가지고 있는 사용자가 추가 크레딧을 구매할 수 있는 지불창을 보여주는 이벤트를 명시적으로 운영해야 한다.
이것이 처리 되면, 호출이 다시 일어난다. 

페이스북에 내부 키를 전달하면, 페이스북은 "payments_get_itmes"를 사용하여 제품 가격을 받기 위한 애플리케이션을 요청한다.
사용자로부터의 확인 요청이 없기 때문에 "payments_status_update"와 "placed"대신에 "settled"를 반환한다.

참고: 이 API 호출을 실행하기 위해, 사용자는 최근 30분안에 애플리케이션과 상호작용해야 한다.
이 기간은 아이템 구매와 사용자의 남아있는 잔고에서 인출을 강력하게 연동 시키기 위해 필요하다.

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;

파라미터:
  •   [app id] - 앱 ID
  •   access_token - 애플리케이션에 대한  엑세스 토큰
  •   from - 사용자 아이디
  •   to - 앱 ID
  •   order_details - 데이터베이스에서 상품 정보를 가리키는 내부 키

에러 코드:

Error Code Suggested Action
API_EC_INSUFFICIENT_BALANCE JS를 통한 크레딧 흐름 호출함
API_EC_PAYMENTS_UNKNOWN 사용자에게 실패 표시
API_EC_PAYMENTS_APP_INVALID 애플리케이션이 유효하지 않음.
API_EC_PAYMENTS_DATABASE 데이터베이스 에러, 재시도
API_EC_PAYMENTS_PERMISSION_DENIED JS를 통한 크레딧 흐름 호출
API_EC_PAYMENTS_APP_NO_RESPONSE 애플리케이션으로 지불 콜백 실패
API_EC_PAYMENTS_APP_ERROR_RESPONSE 애플리케이션 지불 콜백 오류 응답
API_EC_PAYMENTS_INVALID_ORDER 제공된 order-id가 올바르지 않음
API_EC_PAYMENTS_INVALID_PARAM 지불 파라미터들 중 올바르지 않은 것이 있음
API_EC_PAYMENTS_INVALID_OPERATION 잘못된 명령
API_EC_PAYMENTS_DISABLED 페이스북 크레딧을 사용할 수 없음


크레딧 Graph API

당신은 필요에 따라 주문을 확인하고 갱신할 수 있는, 페이스북 크레딧 Graph API를 사용하여 애플리케이션에서 생성된 주문들과 상호작용할 수 
있다.
"Order ID"는 Graph API내의 객체이다.

주의: Graph API를 호출할때는 실제 주문들을 사용해야 한다. 테스트 사용자의 주문은 처리되지 않는다.


주문 가져오기

지정된 order_id에 대한 세부 정보를 가져온다.

API

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

파라미터:
  •   [order id] - 주문에 대한 64비트 ID
  •   access_token - 애플리케이션에 대한  엑세스 토큰

반환:
  •   JSON 객체:

            {
               "id": "",
               "from": {
                  "name": "",
                  "id": ""
               },
               "to": {
                  "name": "",
                  "id": ""
               },
               "amount": ,
               "status": "",
               "application": {
                  "name": "",
                  "id": ""
               },
               "country": "",
               "created_time": "",
               "updated_time": ""
            }

  •   refund_code: 페이스북에 의해 환불이 일어난 주문에 대해서만 반환된다. 아래의 환불 코드를 보시오

주문 갱신하기

이미 있는 주문의 상태를 갱신할 수 있다.
이 API는 1분당 100번 정도 호출할 수 있다.

API

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

파라미터:
  •   [order id] - 주문에 대한 64비트 ID
  •   access_token - 애플리케이션에 대한  엑세스 토큰
  •   status - 원하는 주문단계를 나타내는 문자열. "settled(지불)", "refunded(환불)", "canceled(취소)"중 하나이어야 한다.
  •   message - 주문 갱신에 대한 메시지
  •   refund_reason - 환불 이유
  •   params - (선택) JSON 인코드된 사전객체 {'connent'=>}

반환:
  •   성공 또는 실패 boolean

여러 주문 가져오기

지정한 애플리케이션이나 사용자의 모든 주문을 가져온다.
참고: 현재 동일 날짜/시간 범위내에서 100,000개의 주문을 반환한다.
만일 동일 24시간 내에 100,000개 이상의 주문을 가져와야 된다면, 다른 시간대에서 다중 질의를 할 수 있도록
하루를 분리하면 된다.

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

파라미터:
  •   [app id] - 애플리케이션 아이디
  •   [user id] - 애플리케이션에 추가된 사용자
  •   status - 지정된 상태의 주문을 반환한다. "reserved(예약)", "settled(지불)", "refund(환불)"중 하나이다.
  •   since - UNIX 시간
  •   until - UNIX 시간. 시작과 끝 시간 사이가 24시간을 초과할 수 없다. 만약 전체 주에 대하여 필요하다면 24시간마다 간단하게 7번 getOrders를 호출하면 된다.
  •   access_token - 애플리케이션에 대한  엑세스 토큰
반환:
  •   JSON 객체
            {
               "data": [
                  {
                     "id": "",
                     "from": {
                        "name": "",
                        "id": ""
                     },
                     "to": {
                        "name": "",
                        "id": ""
                     },
                     "amount": ,
                     "status": "",
                     "application": {
                        "name": "",
                        "id": ""
                     },
                     "created_time": "",
                     "updated_time": ""
                  },
               ...
               ],
               "paging": {
                  "previous": "",
                  "next": ""
               }
            }


애플리케이션 Callback
  
페이스북이 애플리케이션 Back end에서 만드는 2개의 Callback이 있다.
애플리케이션은  페이스북으로부터의 요청인지 알기 위해 "signed_request" 파리미터를 확인할 필요가 있다.

payments_get_items: 요청과 함께 페이스북은 "order_id"와 "order_info"를 제공하고, 주문과 관련된 아이템에 대한 JSON 인코딩된 배열을 얻어간다.
파라미터:
  1.   order_id - 주문에 대한 64비트 ID
  2.   order_info - Front end에서 애플리케이션에 의해 페이스북에 제공된 "order_info" 이다.

반환 값: {itmes}에 대한 JSON 인코딩 배열. 참고: 현재 단 하나의 아이템만 허용되지만, 배열로 반환받는다. 아이템은 다음과 같은 필드를 가지고 있다.
  1.   item_id - 페이스북이 사용하지 않는 사용자 식별자
  2.   title - 상품 이름 <= 50자.
  3.   description - 상품 설명 <= 175자
  4.   image_url - 사용자에게 보여지는 상품 이미지 URL
  5.   product_url - 사용자에게 상품을 표시하는 퍼머링크(불편의 절대 URL) URL
  6.   price - 가격은 0 크레딧 보다는 커야 한다.
  7.   data - (선택) 페이스북에서는 사용되지 않지만, 저장되고 "order_details"와 함께 애플리케이션에 전달되어야 하는 데이터

개발자의 Callback 응답 샘플

{"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: 페이스북은 주문 상태와 "order_details"와 함께 애플리케이션을 호출한다. 애플리케이션은 주문을 진행하려면 다음 상태를 응답해야 한다.

파라미터:
  1.   order_id - 주문에 대한 64비트 ID
  2.   status - "placed(주문)", "reserved(예약)", "settled(지불)", "canceled(취소)"중 하나여야 한다.
  3.   order_details - "payments_get_items"에서 전달된 정보

반환 값:
  1.   status - 갱신하기 전에 주문 상태에 따른 상태 값.

응답 방식: 상태가 "placed"라면 애플리케이션은 "canceled"나 "settled"를 반환한다. (애플리케이션은  페이스북으로부터의 요청인지 알기 위해 "signed_request" 파리미터를 확인할 필요가 있다.)

주문 상태: 3가지 상태중 하나로 응답한다: settled, canceled, refunded

Status Notes
settled 이 상태는 거래가 "captured(포착)"되었을 경우 발생한다. - "authorized"로 부터 이동된다. 이때 구매자의 계좌에서 크레딧이 이동한다.
canceled 이 상태는 "placed"상태에서만 발생한다. 이 상태가 되면, 사용자는 구매를 완료하는 데 필요한 충분한 크레딧을 보유하지 않은 상태기 때문에, 사용자의 잔고는 사용자가 선택한 결제 방식으로 크레딧 구매를한  아이템 가격만큼 증가하게 된다.. 
refunded 이 상태는 개발자나 페이스북에 의해 시작 된다. 전체 금액이 구매자에게 환불 되고 개발자는 절대 요금이나 수수료를 부과할 수 없다.


보고

일일 요약 및 상세 보고서뿐만 아니라 격월 지불 보고서가 <noreplay@fb.com>이라는 페이스북 크레딧 주소에서 가입할때 입력한 이메일로 발송 될 것이다.
이메일로 보고서를 받지 못하는 것을 피하기 위해 모든 스팸 필터에서 이메일이 허용되어 있는지 확인해야 한다.
각 파일은 100,000라인 이하로 구성되어 있다. 100,000라인 이상의 거래가 일어날 경우에는 여러 파일로 제공된다.

요약 보고서

요약 보고서는 회사와 관련되어 서비스 되고 있는 애플리케이션들에서 발생하는 모든 타입의 요약정보가 포함된다.

이메일의 제목은 아래와 같이 고유한 대문자 형식이다.

COMPANY_NAME: Facebook Credits Daily Digest Report for DATE

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

이 보고서는 "tab separated values text file (.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

상세 보고서

상세 보고서는 모회사와 관련되어 서비스 되고 있는 애플리케이션들이 발생하는 모든 거래정보가 포함된다.
이메일의 제목은 아래와 같이 고유한 대문자 형식이다.

COMPANY_NAME: Facebook Credits Daily Detail Report for DATE

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

이 보고서는 .zip으로 압축된 "tab separated values text file (.tsv)" 첨부파일이다.
첨부파일의 이름은 아래와 같이 고유한 대문자 형식이다.

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

참고: 이 보고서는 주문에 대한 동일한 거래 ID와 주문 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

다른 가능한 설명은 주문이 환불되었을 경우 주문에 대한 여러 라인을 가질 수 있다.
아래 예는 초기 거래 후 1분 후에 환불된 주문의 예를 보여준다.

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

지불 요약

지불 요약은 매월 5일, 20일에 발송된다. 
일간 보고와 같은 형식으로 지불 기간동안 주문 상세정보를 가지고 있는 압축된 첨부파일을 가지고 있다.
상세 보고서뿐만 아니라 지불기간동안 각 앱의 거래 요약정보를 받게 된다.

지불기간내에 보내지는 요약 이메일은 아래와 같은 형식이다.

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

가능 거래 유형:

txn_type Type of Transaction
S(Spend) 애플리케이션에 크레딧이 사용되는 경우
R(Refund) 페이스북이나 개발자에 의해 사용자에게 크레딧이 환불되는 경우, 개발자 지불은 제외
C(Chargeback) 페이스북이나 개발자에 의해 사용자에게 환불되는 경우, 개발자 지불은 제외
D(Chargeback) 90일후 지불 취소되는 경우,  최종 지불에는 계산되지 않는다.
L(Deferred payment initiated) 아이템 구매시 사용자가 지불을 이후로 연기한 경우
P(Deferred payment repayment) 연기된 지불이 상환된 경우, 페이스북은 개발자에게 크레딧을 이전한다.
F(Deferred payment refund) 연기된 지불에 대해 환불할 경우, 사용자는 크레딧을 받지 않는다.
Q(Repayment refund) 페이스북이나 개발자에 의해 환불 상환이 완료된 경우, 개발자 지불은 제외


분쟁 해결

분쟁 해결 시스템은 사용자와 개발자에게 페이스북 크레딧을 사용한 지불에 대해 상호 작용할 수 있고 서로의 분쟁을 해결하기 위한 쉬운 방법을 
제공한다. 페이스북은 사용자의 지불 금액을 환불하거나, 사용자가 만족할 수 있도록 적절한 설명과 함께 분쟁을 해결할 수 있도록 애플리케이션을 신뢰한다.

사용자 상호작용

지불을 사용하는 앱의 캔버스 페이지 애플리케이션 하단에 링크가 있다: "Report". 사용자가 링크를 클릭하면, 아래와 같은  "Dispute..."중 하나를 선택하라는 메시지가 표시된다.

  1.   사용자가 분쟁을 원하는 주문을 선택할 수 있는 주문 선택 창이 표시된다. (지난 30일 동안 앱에서 구매한 것들이 보여진다.)
  2.   완료되면, 개발자와 페이스북에 메일이 전달되고, 사용자와 애플리케이션이 서로 분쟁중이라는 정보가 설정된다.

주문에 대해 사용자가 분쟁을 걸 때 status는 "disputed"를 가지는 'payments_status_update' 통보가 애플리케이션의 payments_callback_url로 전달된다.
이것은 'order_state' 거래와 같이 애플리케이션에 보내지는 'status-update' 통보와 같은 구성으로 이루어져 있다.
애플리케이션은 또한 /payment API를 사용하여 그 분쟁 주문들을 질의할 수 있다.

참고: 사용자들의 분쟁을 해결하는 동안 개발자에게 이메일이 보내지고, 사용자는 이메일에 참조된다. 개발자는 사용자들이 만족했는지 이러한 채널을 통해 상호 작용할 수 있다.

분쟁 해결하기

개발자는 분쟁을 해결하기 위해 2가지 방법으로 사용자와 상호작용할 수 있다.
  1.    /[order id] API를 호출하여 주문을 환불 하기 위해서는 적합한 order_id, status=refunded를 제공하고, 추가로 'comment' 파라미터에 환불에 대한 이유를 적어야 한다.
  2.   개발자는 사용자와의 상호작용을 통해 요금에 대한 사용자의 이해를 돕고 만족 시켰다면, order-id, ststus=settled, 'comment'파라미터에 이유를 적어, /[order_id] API를 호출하여 분쟁을 해결한다.
참고: 환불없는 분쟁이 어떻게 해결되었는지 기록해야 하고, 확인해야 하기 때문에 이 사례에서는 이유를 반드시 지정해야 한다.


지불취소

애플리케이션은 크레딧 사용후 90일 이내에 발생하는 지불 취소에 대해서는 법적 책임이 있다. 지불 취소의 경우 수수료를 포함한 모든 금액이 환불되어야 한다.


환불 응답 코드(GET to /[order id] API)

당신이 /[order id] API로 GET 요청 하고, 주문이 페이스북에 의해 환불된거라면 아래 값들 중 하나를 가지는  "refund_reason_code"라는 추가 필드가 반환된다:

Compromised Account (계정 도용)
Stolen Financial Instrument (도난 금융 수단)
Not Fraud (사기는 아님)
User Confusion (사용자 착각)
Dev System Issue (개발 시스템 문제)
FB System Issue (페이스북 시스템 문제)

graph API를 통해 getOrder 호출:

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

출력 예:

{
   "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"
}


에러 코드

아래 섹션에서는 Frontend API와 Backend API에서 발생할 수 있는 각각의 에러들을 다룬다.

Front End 에러 코드

Error_code Error_message Note
1383001 Unknown 페이스북 시스템 문제
1383002 InvalidParameters 개발자가 잘못된 파라미터로 호출함
1383003 PaymentFailure 프로세서가 거부함
1383004 InvalidOperation 개발자가 페이스북이 허용하지 않은 명령을 시도함
1383005 PermissionDenied 페이스북 시스템 문제
1383006 DatabaseError 페이스북 시스템 문제
1383007 InvalidApp 앱이 허용되지 않았거나 테스트 모드, 개발자가 허용하지 않은 사용자가 결제하도록 시도하고 있음
1383008 AppNoResponse 앱이 응답하지 않음, 대부분 서버 타임아웃 문제
1383009 AppErrorResponse 앱이 에러 코드를 페이스북에 응답함
1383010 UserCanceled 사용자가 결제중 명시적으로 취소함
1383011 Disabled 페이스북 시스템 문제
1383013 OrderFailureAfterPurchaseCredit 페이스북 시스템 문제
1383014 DisputeFlow 페이스북 시스템 문제
1383015 AccountNotCharged 애플리케이션이 주문을 취소함
1383017 ExceedCreditBalanceLimit 당신의 잔액이 크레딧 최대 갯수에 도달함
1383018 ExceedCreditDailyPurchaseLimit 사용자가 미리 정의된 일일 최대 수치에 도달했을 때 발생함
1383019 ExceedCreditDailySpendLimit 신용 금액 사용자가 미리 정의한 일일 임계점을 초과하여 사용할 경우 발생함
1383040 UserThrottled 애플리케이션을 일시적으로 사용할 수 없음
1383041 BuyerPaymentFailure 사용자의 금융 수단으로 과금이 되지 않음
1383042 LoggedOutUser 로그인이 필요함
1383043 AppInfoFetchFailure 페이스북 시스템 문제
1383044 InvalidAppInfo 애플리케이션은 올바른 콜백 URL이 필요함
1383045 AppInvalidEncodedResponse 애플리케이션이 올바른 json 인코딩된 응답을 반환하지 못함
1383046 AppInvalidDecodedResponse 애플리케이션 반환값이 json 디코딩 후 잘못됨
1383047 AppInvalidMethodResponse 애플리케이션의 응답이 요청과 맞지 않는 'method'파라미터를 포함하고 있음
1383048 AppMissingContentResponse 애플리케이션 응답이 'content'필드를 포함하고 있지 않음
1383049 AppUnknownResponseError 애플리케이션 알수 없는 응답을 반환함
1383050 AppUserValidationFailedResponse 애플리케이션 콜백을 보낼때, 사용자 확인을 실패함
1383051 AppInvalidItemParam 애플리케이션이 잘못된 아이템 파라미터들을 보냄 (예를 들면, 아이템의 가격이나, 수량은 잘못된 파라미터이다.)
1383052 EmptyAppId 빈 앱 ID

Back End 에러 코드

아래 에러들은 정규 API 예외에 추가되어 반환된다:

Error Code Error Name Note
1150 API_EC_PAYMENTS_UNKNOWN 알수 없는 에러
1151 API_EC_PAYMENTS_APP_INVALID 애플리케이션은 페이스북 크레딧을 사용할 수 없음
1152 API_EC_PAYMENTS_DATABASE 데이터베이스 에러가 발생함
1153 API_EC_PAYMENTS_PERMISSION_DENIED 주문 내용 확인 권한이 거부됨
1154 API_EC_PAYMENTS_APP_NO_RESPONSE 애플리케이션의 지불 콜백이 실패함
1155 API_EC_PAYMENTS_APP_ERROR_RESPONSE 애플리케이션의 지불 콜백이 에러 응답을 받음
1156 API_EC_PAYMENTS_INVALID_ORDER 제공된 주문 ID가 잘못됨
1157 API_EC_PAYMENTS_INVALID_PARAM 지불 파라미터중 하나가 잘못됨
1158 API_EC_PAYMENTS_INVALID_OPERATION 명령이 잘못됨
1159 API_EC_PAYMENTS_PAYMENT_FAILED 지불 프로세싱이 실패함
1160 API_EC_PAYMENTS_DISABLED 페이스북 크레딧 시스템이 동작하지 않음
1161 API_EC_PAYMENTS_INSUFFICIENT_BALANCE 잔고 부족
1162 API_EC_PAYMENTS_EXCEED_CREDIT_BALANCE_LIMIT 크레딧 잔고가 제한을 초과함
1163 API_EC_PAYMENTS_EXCEED_CREDIT_DAILY_PURCHASE_LIMIT 일일 크레딧 구매 제한을 초과함
1164 API_EC_PAYMENTS_EXCEED_CREDIT_DAILY_SPEND_LIMIT 일일 크레딧 사용 제한을 초과함
1166 API_EC_PAYMENTS_INVALID_FUNDING_AMOUNT 주문 금액과 자금 출처에서 구매된 크레딧이 일치하지 않음
1167 API_EC_PAYMENTS_NON_REFUNDABLE_PAYMENT_METHOD 자금 출처가 환불할수 없는 지불 방법임
1168 API_EC_PAYMENTS_USER_THROTTLED 애플리케이션이 일부 사용자들에 대해 조절하도록 설정되어 있음
1169 API_EC_PAYMENTS_LOGIN_REQUIRED 사용자가 로그인 되어 있지 않음
1170 API_EC_APP_INFO_FETCH_FAILURE 애플리케이션 정보를 가져올때 오류가 발생함
1171 API_EC_INVALID_APP_INFO 잘못된 애플리케이션 정보가 반환됨
1172 API_EC_PAYMENTS_APP_INSUFFICIENT_BALANCE 애플리케이션이 잔고가 충분하지 않음 (app2user)
 
저작자 표시
크리에이티브 커먼즈 라이선스
Creative Commons License
Posted by 우끼리
TAG , , , ,

Trackback 0 Comment 0

TRACKBACK http://moogi.tistory.com/trackback/78 관련글 쓰기

댓글을 달아 주세요