Facebook 결제와 구독 기능을 사용하는 앱을 개발했다면 Facebook 결제의 보고서 기능을 사용하여 특정 날짜에 앱에서 발생한 결제 활동의 분석 정보가 나와 있는 보고서를 받게 됩니다. |
이 문서에서는 보고서의 내용, 보고서를 요청하기 위한 API, 보고서를 제공하는 형식을 설명합니다.
결제 보고서는 Facebook Audience Network 수익이 아니라 앱 내 구매를 표시합니다. Audience Network 앱의 결제 보고서를 생성하려면 Audience Network 보고서 API 참고 문서를 참조하세요.
앱의 일일 보고서를 다운로드하려면 회사 설정 페이지로 이동하여 보고서를 받아볼 회사를 선택하고 보고서 탭으로 이동합니다. 이 페이지에서 달력 도구로 보고서 날짜를 선택하고 드롭다운 메뉴에서 다운로드할 보고서 유형을 선택할 수 있습니다.
또는 관리자가 다음의 경로로 회사 설정으로 이동할 수 있습니다.
이 옵션을 선택한 후 다운로드를 클릭하여 회사의 일일 보고서를 다운로드하기 시작합니다.
인스턴트 게임의 보고서는 인스턴트 게임 요약과 인스턴트 게임 상세 정보로 별도 표시됩니다.
인스턴트 게임에 대한 보고서는 클라우드 게임에도 사용됩니다.
각 보고서는 미국 태평양 표준시 12AM~11:59:59PM(UTC -8/-7)까지 하루 단위로 제공되고 그날에 해당 회사에 지불된 모든 앱에 대한 모든 거래가 포함됩니다.
특정 날짜에 대해 두 가지 보고서를 요청할 수 있습니다.
detail
보고서에는 판매, 환불 등 거래마다 하나의 기록이 표시됩니다. 상세 정보 보고서는 Facebook의 관점에서 불입입니다.digest
보고서에는 특정 앱에 대해 특정 유형의 모든 거래가 요약됩니다.인스턴트 게임 보고서는 유사하지만 이름이 다릅니다.
ig_detail
보고서에는 판매, 환불 등 거래마다 하나의 기록이 표시됩니다. ig_digest
보고서에는 특정 인스턴트 게임에 대해 특정 유형의 모든 거래가 요약됩니다.현재 결제 보고서에는 두 개의 섹션이 있습니다. 그러나 보고서 형식이 확장 가능하도록 설계되었기 때문에 파서를 작성할 때는 여기에 의존해서는 안 됩니다.
한 섹션(보고서에 따라 credits_digest
또는 credits_detail
)에서는 Facebook 크레딧 기능을 사용한 모든 거래를 다루며 결제 대화 상자의 buy_item
작업을 통해 발생한 모든 게임 내 구매를 포함합니다. 이 섹션은 개발자가 더 이상 Facebook 크레딧에서 지불을 받을 수 없기 때문에 사용이 중단되었습니다.
Facebook은 하루에 한 번 새로운 보고서를 작성하고 미국 태평양(UTC -8/-7) 기준으로 정오에 공개하므로 보고서를 확인할 수 있는 가장 최근 날짜는 일반적으로 요청일 전날입니다. 인스턴트 게임의 경우 2일이 지연됩니다.
결제 보고서는 최대 45일 동안 다운로드할 수 있습니다.
결제 보고서는 웹 기반 API를 통해 제공되므로 선택된 날짜에 발생한 거래의 요약이나 매우 상세한 보고서를 요청할 수 있습니다.
보고서를 받는 과정은 3단계로 구성됩니다.
계속 진행하기 전에 회사가 결제를 받도록 설정하는 것을 포함하여 앱에서 결제를 받도록 활성화했는지 확인해야 합니다.
이 단계를 완료했다면 자격 증명 탭의 회사 설정 페이지에서 회사 ID와 시크릿 코드를 확인할 수 있습니다.
한 회사에는 ID/시크릿 코드 한 쌍만 필요합니다. 회사의 모든 앱에서 동일한 쌍을 사용합니다. 앱의 일일 거래 보고서를 다운로드할 때 필요한 access_token
을 받으려면 이러한 로그인 정보가 필요합니다.
Company Access Token
받기Company Access Token
은 토큰이 발급된 사람을 대신하여 회사와 관련된 모든 앱의 보고서에 액세스할 수 있게 합니다. 토큰을 받으려면
https://graph.facebook.com/oauth/access_token?
다음 쿼리 매개변수를 포함하여 GET 요청을 보냅니다.
이름 | 유형 | 값 |
---|---|---|
| 정수 | 회사 ID |
| 문자열 | 회사 시크릿 코드 |
| 문자열 | `client_credentials |
이 토큰은 회사 시크릿 코드를 재설정하기 전까지 만료되지 않으므로 보고서를 요청할 때마다 새로 생성하는 대신 저장해두고 다시 사용해야 합니다.
access_token
요청 예시요청 샘플:
https://graph.facebook.com/oauth/access_token? client_id=COMPANY_ID& client_secret=COMPANY_SECRET& grant_type=client_credentials
Facebook의 샘플 응답:
access_token=230001349987723|aBc_dEFaEUZberrtkrp8pbtwXyZ
회사 access_token
을 받았으면 회사의 모든 앱에 대한 일일 보고서 파일을 요청하는 데 사용할 수 있습니다. 앞서 언급한 대로 두 종류의 보고서를 생성합니다.
digest
보고서에는 앱-거래 유형별로 데이터 행을 포함하며, 각 앱의 판매, 환불, 다른 거래 이벤트가 요약되어 있습니다.detail
보고서는 이름에서 알 수 있듯 거래마다 행이 표시됩니다.언제든 보고서 파일을 다운로드하려면
https://paymentreports.facebook.com/COMPANY_ID/report?
다음 쿼리 매개변수를 포함하여 GET 요청을 보냅니다.
이름 | 유형 | 값 |
---|---|---|
| 문자열 | 보고서를 다운로드할 날짜(YYYY-MM-DD 형식) |
| 문자열 |
|
| 문자열 |
또한 위에 언급한 바와 같이 date
는 오늘 날짜가 될 수 없습니다. 특정 날짜의 보고서는 그다음 날 미국 태평양(UTC -8/-7) 오전 8시 이후에 확인할 수 있습니다.
일일 detail
보고서에 대한 개발자 요청 샘플:
wget "https://paymentreports.facebook.com/23459934998762/report? date=2012-05-15& type=detail& access_token=234599349987627|aBc_dEFaEUZbqpatkrp8pbtwXyZ"
위와 같이 요청하면 23459934998762_detail_2012-05-15.csv.zip
라는 파일이 생성됩니다.
digest
보고서에 대한 개발자 요청 샘플:
wget "https://paymentreports.facebook.com/23459934998762/report? date=2012-05-15& type=digest& access_token=23459934998762|aBc_dEFaEUZbqpatkrp8pbtwXyZ"
위와 같이 요청하면 23459934998762_digest_2012-05-15.csv.zip
라는 파일이 생성됩니다.
모든 보고서는 공통의 전체 구조를 공유합니다.
\n
'(새로운 행)입니다.RH
)SH
)CH
)SD
)SF
)RF
)보고서 구조는 다음과 같이 시각화됩니다.
RH, ... SH, ... CH, ... SD, ... [More section data rows] SF, ... SH, ... CH, ... SD, ... [More section data rows] SF, ... [Possibly more sections] RF, ...
위의 들여쓰기와 공백은 가독성을 위한 것입니다. 실제 보고서는 들여쓰기를 하지 않고 필드 데이터에 공백이 있는 경우에만 공백이 표시됩니다.
필드가 모두 입력된 예시는 이 문서 끝의 샘플 파일 섹션에서 확인할 수 있습니다.
RH
)첫 번째 행은 보고서 헤더로, 다음에 나오는 보고서 푸터까지 아래에 있는 모든 행에 적용되는 데이터를 포함합니다. 보고서 푸터는 보고서의 끝을 표시합니다. RH
행에 포함되는 필드는 다음과 같습니다.
이름 | 설명 |
---|---|
company_id | 개발자의 회사 ID |
report_type | 보고서 유형. 현재는 |
start_time | 보고 기간의 시작 시각. YYYY-MM-DD |
end_time | 보고 기간의 종료 시각. YYYY-MM-DD |
format_version |
|
샘플 행:
RH,213030545409781,daily_detail,2011-11-21 00:00:00 PST,2011-11-21 23:59:59 PST,1
샘플 행을 읽는 방법:
열 | 값 | 설명 |
---|---|---|
1 |
| 행 유형: 보고서 헤더 |
2 |
| 회사 ID |
3 |
|
|
4 |
| 이 보고서의 시작 시각 |
5 |
| 종료 시각 |
6 |
| 보고서 스키마의 버전 |
SH
)보고서 헤더와 푸터 사이의 모든 행은 섹션에 포함됩니다. 보고서의 각 섹션은 섹션 헤더로 시작되며, 섹션은 헤더에서 시작하여 다음에 나오는 섹션 푸터까지 계속됩니다. SH
행에 포함되는 필드는 다음과 같습니다.
이름 | 값 |
---|---|
company_id | 개발자의 회사 ID |
section_type | 현재는 |
샘플 행:
SH,213030545409781,payment_detail
샘플 행을 읽는 방법:
열 | 값 | 설명 |
---|---|---|
1 |
| 행 유형: 섹션 헤더 |
2 |
| 회사 ID |
3 |
|
|
CH
)각 섹션 헤더 다음에는 열 헤더가 나옵니다. 열 헤더는 해당 섹션의 섹션 데이터 행의 필드 이름을 지정합니다. 섹션 유형마다 필드가 다릅니다. CH 행을 읽고 각 섹션의 필드 이름을 아는 것이 중요합니다. 보고서 형식은 자체 설명을 업데이트하여 쉽게 확장할 수 있으므로 열 순서나 섹션 설명이 하드 코딩된 파싱 솔루션이 무효화되는 방식으로 변경될 수 있습니다.
payment_detail
섹션의 CH
행 예시:
CH,app_id,payment_type,product_type,payment_id,time_completed,recv_currency,recv_amount,fx_batch_id,fx_rate,settle_currency,reference_id,tax_country
payment_digest
섹션의 CH
행 예시:
CH,app_id,app_name,payment_type,product_type,recv_currency, ,fx_batch_id,fx_rate,settle_currency,settle_amount
SD
)섹션의 열 헤더 다음에는 0개 이상의 section data
행이 나오며, 이 행의 필드 이름은 CH
행을 따릅니다. 행의 의미는 섹션 유형에 따라 다릅니다. detail
섹션에서 각 행은 하나의 거래를 나타내며 digest
섹션에서 각 행은 특정 앱에서 특정 유형의 모든 거래의 합계를 나타냅니다(예: '앱 내 모든 판매 ID 276999562313463', '앱에서 일본 엔으로 표시된 모든 구독 환불 ID 276899562313544'). 현재 4가지 유형의 섹션이 있으며 아래에 설명이 나와 있습니다.
credits_detail
및 credits_digest
섹션은 앱이 Facebook 크레딧으로 더 이상 결제를 만들 수 없으므로 이제 지원이 중단됩니다.
payment_detail
SD
행필드:
이름 | 설명 |
---|---|
| 거래가 발생한 앱의 ID. |
| 다음의 코드 중 하나입니다.
수익을 계산할 때 이는 다음의 계수에 해당합니다. S => 1, R => -1, C => -1, D => 0, K => 1, J => 0, N => -1 |
| |
| 결제의 고유 ID. |
| 거래가 완료된 시점의 타임스탬프(YYYY-MM-DD HH:MM:SS 시간대 형식). |
| 소비자가 지불한 통화(3자 ISO 4217 코드로 표시). |
| 화폐 단위로 표시된 순 금액(세금 포함). 여전히 Facebook 수익 공유를 제거해야 할 필요가 있기 때문에 이는 개발자가 받는 금액이 아닐 수 있습니다. 최초 결제 금액의 경우 결제 보고서를 확인하세요. |
| 이 거래가 처리된 환율 배치의 고유 ID. |
|
|
| 개발자가 받은 통화(3자 ISO 4217 코드로 표시). 현재 이 필드는 언제나 USD입니다. |
| 구독에 대한 청구 계약 ID와 결제에 대한 request_id입니다. |
| 고객이 구매한 국가(ISO 3166-1 alpha-2 국가 코드로 표시). |
| Facebook이 개발자를 대신하여 거래에 사용된 통화로 납부한 실제 VAT 또는 판매세 금액. |
|
|
|
Facebook 외의 플랫폼에서 청구하는 플랫폼 수수료. Facebook의 경우, 수익 공유 계약이 여전히 적용되고 여기에 포함되지 않습니다. |
구독 샘플 행:
SD,266989143414,S,S,267668373345994,2012-07-22 00:07:23 PDT,USD,19.99,123456789ABCDEF00123456789ABCDEF,1.0000000000,USD,20000000007,US,0.99
구독 샘플 행을 읽는 방법은 다음과 같습니다.
열 | 값 | 설명 |
---|---|---|
1 |
| 행 유형: 섹션 데이터 |
2 |
| 결제가 이루어진 |
3 |
| 거래가 판매인 경우 |
4 |
| 판매된 제품이 구독인 경우 |
5 |
| 판매의 ID |
6 |
| 결제 처리가 완료된 시각 |
7 |
| 소비자가 미국 달러로 지불한 구매 금액 |
8 |
| 소비자가 US$19.99 지불 |
9 |
| 환율 배치 ID |
10 |
| USD에서 USD로 환전 시 환율 |
11 |
| 개발자가 미국 달러로 지불 |
12 |
| 이 결제는 청구 계약 20000000007의 |
13 |
| 구매하는 소비자가 미국에 거주 |
14 |
| 개발자를 대신해 납부한 실제 VAT 금액 |
결제 샘플 행:
SD,480369938658210,S,P,362736900505327,2013-06-12 16:33:52 PDT,USD,1,6E5D989082A04A68AA801DB17A30721A,1,USD,QQ6C7XaxeMyCW4RdZXFGwKTQM1IkMBIOpeWtFFJelHUdSC9NaeYlBXEMJd3LO17k,US,0.09
결제 샘플 행을 읽는 방법은 다음과 같습니다.
열 | 값 | 설명 |
---|---|---|
1 |
| 행 유형: 섹션 데이터 |
2 |
| 결제가 이루어진 |
3 |
| 거래가 판매인 경우 |
4 |
| 결제에서 발생한 거래 |
5 |
| 판매의 결제 ID |
6 |
| 결제 처리가 완료된 시각 |
7 |
| 소비자가 미국 달러로 지불한 구매 금액 |
8 |
| 소비자가 US$1.00 지불 |
9 |
| 환율 배치 ID |
10 |
| USD에서 USD로 환전 시 환율 |
11 |
| 개발자가 미국 달러로 지불 |
12 |
| 이 결제에 대한 앱의 |
13 |
| 구매하는 소비자가 미국에 거주 |
14 |
| 개발자를 대신해 납부한 실제 VAT 금액 |
payment_digest
SD
행필드:
이름 | 설명 |
---|---|
| 결제가 요약되는 |
| 앱의 이름 |
| 다음의 코드 중 하나입니다.
|
| 'S'는 구독을 나타내고 'P'는 결제를 나타냄 |
| 요약 대상인 결제자의 통화(3자 ISO 4217 코드로 표시) |
| 특정 환율 배치에서 현재 유형의 결제와 관련된 해당 통화의 총 금액 |
| 해당 배치의 ID |
|
|
| 개발자가 받는 통화(3자 ISO 4217 코드로 표시) |
| 보고 기간의 앱, 결제 유형, 제품 유형, 통화, 외환 배치와 일치하는 총 금액 |
| Facebook이 개발자를 대신하여 납부한 실제 VAT 또는 판매세 금액 |
구독 샘플 행:
SD,200000000000002,Game2,S,S,CNY,5000.0,FXBATCHID1,0.2,USD,1000.0,9.99
구독 샘플 행을 읽는 방법은 다음과 같습니다.
열 | 값 | 설명 |
---|---|---|
1 |
| 행 유형: 섹션 데이터 |
2 |
| ID 200000000000002인 앱 관련 |
3 |
| ...이름은 'Game2' |
4 |
| ...모든 판매 |
5 |
| ...구독 |
6 |
| ...중국 위안(인민폐)으로 결제 |
7 |
| ...총 5000 CNY |
8 |
| ...FXBATCHID1에서 변환됨 |
9 |
| ...환율 1 CNY = 0.2 USD |
10 |
| 개발자에게 USD로 지급 |
11 |
| 합계: 'Game2는 보고 기간 동안 FXBATCHID1 동안 중국 위안(인민폐)을 사용하여 구독을 구매한 사용자를 합쳐서 US$1,000의 매출이 발생했습니다' |
12 |
| 개발자를 대신해 납부한 VAT 금액: 9.99 |
결제 샘플 행:
SD,900000000000009,Game9,S,P,CNY,5000.0,FXBATCHID1,0.2,USD,1000.0,9.99
결제 샘플 행을 읽는 방법은 다음과 같습니다.
열 | 값 | 설명 |
---|---|---|
1 |
| 행 유형: 섹션 데이터 |
2 |
| ID 900000000000009인 앱 관련 |
3 |
| ...앱 이름은 'Game9' |
4 |
| ...모든 판매 |
5 |
| ...결제 |
6 |
| ...중국 위안(인민폐)으로 요청 |
7 |
| ...총 5000 CNY |
8 |
| ...FXBATCHID1에서 변환됨 |
9 |
| ...환율 1 CNY = 0.2 USD |
10 |
| 개발자에게 USD로 지급 |
11 |
| 합계: 'Game2는 보고 기간에 FXBATCHID1 중 중국 위안(인민폐)을 사용하여 앱 내 상품을 결제한 사용자를 모두 합쳐 US$1,000의 매출이 발생했습니다' |
12 |
| 개발자를 대신해 납부한 VAT 금액: 9.99 |
SF
)각 섹션은 섹션 푸터 행으로 끝나며, 섹션 푸터 행 다음에는 SH
행으로 시작하는 새로운 섹션이 나오거나 보고서의 끝을 나타내는 보고서 푸터 행이 나올 수 있습니다. 유형 필드 다음에 나오는 데이터의 단일 열은 다음과 같습니다.
이름 | 설명 |
---|---|
| 섹션 데이터 해의 총 합계는 이 보고서의 이 섹션에 포함되어 있습니다. |
샘플 행:
SF,7
샘플 행을 읽는 방법:
열 | 값 | 설명 |
---|---|---|
1 |
| 행 유형: 섹션 푸터 |
2 |
| 이 섹션에 |
RF
)보고서는 보고서 푸터 행으로 끝나가 이는 파일의 마지막 행이 되어야 합니다. 유형 열 뒤에 요약 데이터 2개가 나옵니다.
이름 | 설명 |
---|---|
| 이 보고서에서 섹션 헤더 행의 총 개수 |
| 이 보고서에서 모든 섹션에 포함된 섹션 데이터 행의 총 개수 |
샘플 행:
RF,2,7
샘플 행을 읽는 방법:
열 | 값 | 설명 |
---|---|---|
1 |
| 행 유형: 보고서 푸터 |
2 |
| 이 보고세어 |
3 |
| 이 보고서에 모든 섹션을 망라하여 |
위의 지침에 따라 이 샘플을 읽어 보세요. 또한 다음을 참조하세요.
credits_detail
또는 _digest
섹션이 포함되어 있습니다.payment_detail
또는 payment_digest
섹션이 포함되어 있습니다.detail
보고서RH,10808080808080808,daily_detail,2012-04-24 00:00:00 PDT,2012-04-24 23:59:59 PDT,1 SH,10808080808080808,credits_detail CH,app_id,txn_type,txn_id,order_id,txn_time,value,credits SH,10808080808080808,payment_detail CH,app_id,payment_type,product_type,payment_id,time_completed,recv_currency,recv_amount,fx_batch_id,fx_rate,settle_currency,reference_id,tax_country SD,266989143414,S,S,267668373345994,2012-07-22 00:07:23 PDT,USD,19.99,123456789ABCDEF00123456789ABCDEF,1.0000000000,USD,20000000007,US SD,266989143414,S,S,272014936246430,2012-07-22 00:08:18 PDT,USD,21.09,123456789ABCDEF00123456789ABCDEF,1.0000000000,USD,20000000008,US SD,266989143414,S,S,272990136150221,2012-07-22 00:09:18 PDT,USD,22.99,123456789ABCDEF00123456789ABCDEF,1.0000000000,USD,20000000009,CY SD,266989143414,S,S,278092248972451,2012-07-22 00:08:34 PDT,USD,19.99,123456789ABCDEF00123456789ABCDEF,1.0000000000,USD,20000000010,US SD,266989143414,S,P,376727629107629,2012-07-22 00:08:34 PDT,USD,19.99,123456789ABCDEF00123456789ABCDEF,1.0000000000,USD,20000000010,US SF,4 RF,2,13
digest
보고서RH,108080808080808,daily_digest,2012-04-25 00:00:00 PDT,2012-04-25 23:59:59 PDT,1 SH,108080808080808,credits_digest CH,app_id,app_name,txn_type,value,credits SH,108080808080808,payment_digest CH,app_id,app_name,payment_type,product_type,recv_currency,recv_amount,fx_batch_id,fx_rate,settle_currency,settle_amount SD,200000000000002,Game2,S,S,CNY,5000.0,FXBATCHID1,0.2,USD,1000.0 SD,200000000000002,Game2,R,S,CNY,2000.0,FXBATCHID1,0.2,USD,400.0 SD,200000000000002,Game2,S,P,CNY,1000.0,FXBATCHID1,0.2,USD,200.0 SF,2 RF,2,5
개발자의 순수익을 계산하는 데 도움을 받으려면 다음의 정보를 참조하세요.
ig_detail
보고서에서 'F'에 해당하거나 detail
보고서의 모든 거래에 해당하는 platform
과의 거래를 의미합니다.
tax_country에서 'US'는 구매 금액에서 세금이 제외되고 계산이 다음의 공식을 따르는 것으로 가정합니다.net_developer_revenue = (recv_amount - tax_amount) * fx_rate * rev_share
그 외에는 구매 금액에 세금이 포함되고 계산이 다음의 공식을 따르는 것으로 가정합니다.net_developer_revenue = (recv_amount * fx_rate) * rev_share - (tax_amount * fx_rate)
ig_detail
보고서에서 'G'에 해당하는 platform
과의 거래를 의미합니다.
계산은 다음의 공식을 따릅니다. net_developer_revenue = recv_amount * fx_rate
참고: 불입 데이터를 기준으로 한 추정치에 불과합니다. 지급 전에 추가적 수수료가 적용될 수 있습니다. 향후 보고서 업데이트에서는 이 계산을 더욱 정확하고 쉬워질 것입니다.