付款報告

如果您開發的應用程式使用 Facebook 的付款和訂閱功能，則您可以使用 Facebook 付款的報告功能，獲取報告以查閱您的應用程式在指定日子的付款活動資料細節。

概覽

本文件會詳述報告內容、說明用於索取報告的 API，並列出報告傳送格式。

下載每日報告
報告內容
索取報告的時間
透過 API 下載每日報告
每日報告的格式
報告標題
區塊標題
直欄標題
區塊資料
區塊頁尾
報告頁尾
報告範例

付款報告只會顯示應用程式內購物交易的明細，不會顯示 Facebook Audience Network 收益。若要產生 Audience Network 應用程式的付款報告，請參閱 Audience Network 分析報告 API 參考文件。

下載每日報告

若要下載應用程式的每日報告，企業管理員可以前往公司設定頁面，選擇想取得哪間公司的報告，然後前往「報告」分頁。在此頁面上，管理員可以透過日曆工具選擇報告日期，以及在下拉式選單選擇報告類型，以選取想下載的報告。

除此之外，管理員也可以前往以下位置選擇公司設定：

Canvas（畫布）遊戲：網絡付款 > 網絡付款 > 公司 >查看／編輯
即時遊戲：應用程式內購物 > 帳戶 > 前往「公司設定」

選擇這些選項後，點擊下載即可開始下載自家公司的每日報告。

即時遊戲的報告會分別顯示為即時遊戲摘要和即時遊戲詳情。

即時遊戲報告亦適用於雲端遊戲。

報告內容

每份報告的時間範圍都是從美國太平洋時間午夜 12 時到晚上 11:59:59（UTC -8／-7）的一整天，內容包含所有應用程式當天為同一間公司帶來收益的所有交易。

您可以就任何指定日子索取兩種不同的報告。

detail 報告會為銷售和退款等每項交易都設一筆記錄。對於 Facebook 而言，詳情報告屬於付款報告。
digest 報告會總結指定應用程式的所有指定類型交易。

即時遊戲報告內容相同，但命名方式不同：

ig_detail 報告會為銷售和退款等每項交易都設一筆記錄。
ig_digest 報告會總結指定應用程式的所有指定類型交易。

付款報告目前有兩個區塊，但您在編寫剖析工具時不應以此為據，因為報告格式採用的是能立即延伸的設計。

視乎您在閱讀哪種報告，credits_digest 或 credits_detail 區塊會列出所有使用 Facebook credit 功能的交易，並且涵蓋所有透過付款對話框的 buy_item 動作完成的遊戲內購買交易。此區塊已經停用，因為開發人員無法再透過 Facebook credit 收款。
另一個區塊 payment_digest 或 payment_detail 會列出使用訂閱和付款這些 Facebook 付款功能的交易。

索取報告的時間

我們每天都會製作一次新報告，並於美國太平洋時間中午時分（UTC -8／-7）發佈報告，因此一般您能索取最近的報告會是有關要求之前一天的報告。即時遊戲的報告會延遲兩天提供。

付款報告最長可供下載 45 天。

透過 API 下載每日報告

付款報告可透過網頁式 API 取得，您可索取指定日期的摘要或超詳細交易報告。

如需取得報告，需完成 3 個步驟：

備妥公司的編號和密碼
備妥 Company access_token
下載報告檔案

備妥公司的編號和密碼

在繼續之前，您需要確保已啟用應用程式付款功能，包括設定收款公司。

完成後，請前往「公司設定」頁面的憑證分頁，查看公司編號和密碼。

每間公司只需一組編號和密碼；這組編號和密碼適用於該公司所有的應用程式。您需要使用有關憑證，才能取得下載應用程式每日交易報告所需的 access_token。

備妥 `Company Access Token`

透過 Company Access Token，您可以因應獲代為發出憑證的公司，就與之相關的所有應用程式存取報告。若要取得憑證，請向以下網址發出 GET 要求

https://graph.facebook.com/oauth/access_token?

並加入下列查詢參數：

名稱	類型	值
`client_id`	整數	您的公司編號
`client_secret`	字串	您的公司密碼
`grant_type`	字串	`client_credentials

除非您重設公司密碼，否則這個憑證不會過期，因此務必儲存並重複使用此憑證，而不是在每次索取報告時都重新產生憑證。

公司 `access_token` 要求範例

要求範例：

https://graph.facebook.com/oauth/access_token?
                                 client_id=COMPANY_ID&amp;
                                 client_secret=COMPANY_SECRET&amp;
                                 grant_type=client_credentials

Facebook 回應範例：

access_token=230001349987723|aBc_dEFaEUZberrtkrp8pbtwXyZ

下載每日檔案

備妥公司 access_token 後，您便可將其用於索取每日報告檔案，當中涵蓋您公司所有的應用程式。如上所述，我們會產生兩種報告：

digest 報告就每個應用程式與交易類型組合分別設立資料列，總結每個應用程式的銷售、退款和其他交易事件
顧名思義，detail 報告就每項交易各設資料列

若要下載任何一天的報告檔案，請向以下網址發出 GET 要求

https://paymentreports.facebook.com/COMPANY_ID/report?

並加入下列查詢參數：

名稱	類型	值
`date`	字串	要下載的報告所屬的日期，此參數以 YYYY-MM-DD 格式顯示
`type`	字串	`detail`、`digest`（網頁遊戲）或 `ig_detail`、`ig_digest`（即時遊戲）之一
`access_token`	字串	您的公司存取憑證

同樣如上所述，date 不能是今天的日期。當天的報告會在美國太平洋時間的隔天早上 8 時（UTC -8／-7）提供。

每日報告要求範例

每日 detail 報告的開發人員要求範例：

wget "https://paymentreports.facebook.com/23459934998762/report?
                                          date=2012-05-15&amp;
                                          type=detail&amp;                                     access_token=234599349987627|aBc_dEFaEUZbqpatkrp8pbtwXyZ"

上述要求會傳回名為 23459934998762_detail_2012-05-15.csv.zip 的檔案。

digest 報告的開發人員要求範例：

wget "https://paymentreports.facebook.com/23459934998762/report?
                                          date=2012-05-15&amp;
                                          type=digest&amp;
                                          access_token=23459934998762|aBc_dEFaEUZbqpatkrp8pbtwXyZ"

上述要求會提供名為 23459934998762_digest_2012-05-15.csv.zip 的檔案。

報告格式

所有報告的整體結構都相同：

報告是逗號分隔值（CSV）文字檔案。
分行符號為 Unix 格式的「\n」（新行）。
內含逗號的欄位都會以雙引號包住，以便輕鬆匯入 Excel。
每列的第一欄都是資料列類型代碼，這決定了其他直欄的解讀方式。
報告會使用 6 種資料列，結構如下：
一個報告標題（類型代碼 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	開發人員的公司編號
report_type	報告類型，目前為 `daily_detail` 或 `daily_digest` 其中之一
start_time	報告時段開始時間，格式為 YYYY-MM-DD `00:00:00` 時區
end_time	報告時段結束時間，格式為 YYYY-MM-DD `23:59:59` 時區
format_version	`1`

報告標題範例

資料列範例：

RH,213030545409781,daily_detail,2011-11-21 00:00:00 PST,2011-11-21 23:59:59 PST,1

資料列範例的解讀指引：

直欄	值	說明
1	`RH`	資料列類型：報告標題
2	`213030545409781`	公司編號
3	`daily_detail`	表示此為 `detail` 報告
4	`2011-11-21 00:00:00 PST`	此報告的開始時間
5	`2011-11-21 23:59:59 PST`	結束時間
6	`1`	報告架構版本

區塊標題（`SH`）

報告標題和頁尾之間的每一列都屬於區塊。報告的每個區塊都是由區塊標題帶出；區塊範圍從標題開始，到下一個區塊頁尾結束。SH 資料列包含下列欄位：

名稱	值
company_id	開發人員的公司編號
section_type	目前為 `credits_detail`、`credits_digest`、`payment_detail` 或 `payment_digest` 之一

區塊標題範例

資料列範例：

SH,213030545409781,payment_detail

資料列範例的解讀指引：

直欄	值	說明
1	`SH`	資料列類型：區塊標題
2	`213030545409781`	公司編號
3	`payment_detail`	`payment_detail` 區塊的標題

直欄標題（`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`）

在區塊的直欄標題之後會有零個或多個 section data 資料列，其欄位名稱則取自 CH 資料列。這些資料列的意義取決於區塊類型：detail 區塊中的每列都代表一筆交易，而 digest 區塊的每列都是指定應用程式內所有指定交易類別的總和，例如「應用程式 ID 276999562313463 中的所有銷售」、「應用程式 ID 276899562313544 中所有以日圓表示的訂閱退款」。目前有 4 種區塊，說明如下。

區塊資料範例

credits_detail 和 credits_digest 區塊現已停用，因為應用程式無法再透過 Facebook credit 建立付款。

`payment_detailSD` 資料列

欄位：

名稱	說明
`app_id`	發生交易的應用程式之編號。
`payment_type`	以下代碼之一： S：銷售 R：退款 C：付款服務供應商退款 D：期限外付款服務供應商退款 K：撤銷付款服務供應商退款 J：撤銷期限外的付款服務供應商退款 N：拒絕在計算收益時，上述代碼分別與下列係數對應： S => 1、R => -1、C => -1、D => 0、K => 1、J => 0、N => -1
`product_type`	「S」代表訂閱，「P」代表付款。
`payment_id`	付款的不重複編號，可類比為 `credits_detail` 情況下的 `txn_id`。
`time_completed`	交易完成時間的時戳，以 YYYY-MM-DD HH:MM:SS 時區格式顯示。
`recv_currency`	顧客的付款貨幣，以 3 個字母組成的 ISO 4217 代碼表示。
`recv_amount`	以該貨幣為單位的淨金額，包含稅項金額。這可能並非開發人員收到的金額，因為還需要減去 Facebook 的收益分潤。如需了解最終支付款項，請查閱您的支付款項報告。
`fx_batch_id`	處理此交易時所屬的匯率批次之不重複編號。
`fx_rate`	`fx_batch_id` 之下一單位 `recv_currency` 換一單位 `settle_currency` 的匯率。
`settle_currency`	開發人員的收款貨幣，以 3 個字母組成的 ISO 4217 代碼表示。目前此欄位一律為 USD。
`reference_id`	訂閱的帳單協議編號和付款的 request_id。
`tax_country`	顧客購物時所在的國家／地區，以 ISO 3166-1 二位字母國碼／區碼顯示。
`tax_amount`	Facebook 代您繳納的實際增值稅或銷售稅金額，以在交易中使用的貨幣計算。
`platform`	僅適用於 `ig_detail` 報告。 `'F'` 表示 Facebook Pay 購物交易，`'G'` 表示 Google Play 購物交易。
`platform_fee`	僅適用於 `ig_detail` 報告。這是非 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	`SD`	列類型：區塊資料
2	`266989143414`	付款交易在哪個 `app_id` 發生
3	`S`	該交易為銷售
4	`S`	所售產品為訂閱服務
5	`267668373345994`	銷售編號
6	`2012-07-22 00:07:23 PDT`	完成付款處理的時間
7	`USD`	消費者以美金付款
8	`19.99`	顧客支付 $19.99 美金
9	`123456789ABCDEF00123456789ABCDEF`	匯率批次編號
10	`1.0000000000`	美金對美金的匯率
11	`USD`	以美金向開發人員付費
12	`20000000007`	此付款包含在訂閱帳單協議 20000000007 的 `history` 中
13	`US`	消費者位於美國
14	`0.99`	代您繳納的實際增值稅金額

付款資料列範例：

SD,480369938658210,S,P,362736900505327,2013-06-12 16:33:52 PDT,USD,1,6E5D989082A04A68AA801DB17A30721A,1,USD,QQ6C7XaxeMyCW4RdZXFGwKTQM1IkMBIOpeWtFFJelHUdSC9NaeYlBXEMJd3LO17k,US,0.09

付款資料列範例的解讀指引：

直欄	值	說明
1	`SD`	列類型：區塊資料
2	`480369938658210`	付款交易在哪個 `app_id` 發生
3	`S`	該交易為銷售
4	`P`	該交易來自一筆付款
5	`362736900505327`	銷售交易的付款編號
6	`2013-06-12 16:33:52 PDT`	完成付款處理的時間
7	`USD`	消費者以美金付款
8	`1`	顧客支付 $1.00 美金
9	`6E5D989082A04A68AA801DB17A30721A`	匯率批次編號
10	`1.0000000000`	美金對美金的匯率
11	`USD`	以美金向開發人員付費
12	`QQ6C7XaxeMyCW4RdZXFGwKTQM1IkMBIO-peWtFFJelHUdSC9NaeYlBXEMJd3LO17k`	應用程式針對此筆款項的 `request_id`
13	`US`	消費者位於美國
14	`0.09`	代您繳納的實際增值稅金額

`payment_digestSD` 資料列

欄位：

名稱	說明
`app_id`	所總結的付款所屬的 `app_id`
`app_name`	應用程式名稱
`payment_type`	以下代碼之一： S：銷售 R：退款 C：付款服務供應商退款 D：期限外付款服務供應商退款 K：撤銷付款服務供應商退款 J：撤銷期限外的付款服務供應商退款 N：拒絕
`product_type`	「S」代表訂閱，「P」代表付款
`recv_currency`	所總結的付款者貨幣，以 3 個字母的 ISO 4217 代碼表示
`recv_amount`	指定外匯批次期間目前類型所用的付款貨幣總金額
`fx_batch_id`	批次編號
`fx_rate`	`fx_batch_id` 之下一 `recv_currency` 換一 `settle_currency` 的匯率
`settle_currency`	開發人員的收款貨幣，以 3 個字母組成的 ISO 4217 代碼表示
`settle_amount`	報告期限內，與應用程式、付款類型、產品類型、貨幣和外匯批次相符的貨幣總金額
`tax_amount`	Facebook 代您繳納的實際增值稅或銷售稅金額

訂閱資料列範例：

SD,200000000000002,Game2,S,S,CNY,5000.0,FXBATCHID1,0.2,USD,1000.0,9.99

訂閱資料列範例的解讀指引：

直欄	值	說明
1	`SD`	列類型：區塊資料
2	`200000000000002`	涉及編號為 200000000000002 的應用程式
3	`Game2`	應用程式名稱為「Game2」
4	`S`	檢視所有銷售業績
5	`S`	交易來自訂閱
6	`CNY`	以人民幣支付
7	`5000.0`	總計為 5000 人民幣
8	`FXBATCHID1`	屬於 FXBATCHID1 匯率批次
9	`0.2`	採用 1 人民幣 = 0.2 美金的匯率
10	`USD`	以美金向開發人員付費
11	`1000.0`	總計：「Game2 在報告期間的銷售額達到 $1000 美金，此總和數據來自 FXBATCHID1 匯率批次期間以人民幣購買訂閱的所有顧客」
12	`9.99`	代您繳納的增值稅金額為 9.99 美金

付款資料列範例：

SD,900000000000009,Game9,S,P,CNY,5000.0,FXBATCHID1,0.2,USD,1000.0,9.99

付款資料列範例的解讀指引：

直欄	值	說明
1	`SD`	列類型：區塊資料
2	`200000000000002`	涉及編號為 900000000000009 的應用程式
3	`Game9`	應用程式名稱為「Game9」
4	`S`	檢視所有銷售業績
5	`P`	交易來自付款
6	`CNY`	以人民幣收付
7	`5000.0`	總計為 5000 人民幣
8	`FXBATCHID1`	屬於 FXBATCHID1 匯率批次
9	`0.2`	採用 1 人民幣 = 0.2 美金的匯率
10	`USD`	以美金向開發人員付費
11	`1000.0`	總計：「Game2 在報告期間的銷售額達到 $1000 美金，此總和數據來自 FXBATCHID1 匯率批次期間以人民幣購買應用程式內商品的所有顧客」
12	`9.99`	代您繳納的增值稅金額為 9.99 美金

區塊頁尾（`SF`）

每個區塊都是以「區塊頁尾」資料列作結，後面可接以 SH 資料列開首的新區塊，或接「報告頁尾」資料列以示報告完結。緊接類型欄位的單一資料欄包含以下內容：

名稱	說明
`number_of_total_data_rows`	此報告這一區塊中所含的區塊資料列總數

區塊頁尾範例

資料列範例：

SF,7

資料列範例的解讀指引：

直欄	值	說明
1	`SF`	資料列類型：區塊頁尾
2	`7`	此區塊包含 7 個 `SD` 資料列

報告頁尾（`RF`）

報告以「報告頁尾」資料列作結，該資料列應為檔案中的最後一列。類型直欄後緊接兩筆摘要資料：

名稱	說明
`number_of_sections`	此報告的區塊標題資料列總數
`number_of_total_data_rows`	此報告所有區塊中所含的區塊資料列總數

報告頁尾範例

資料列範例：

RF,2,7

資料列範例的解讀指引：

直欄	值	說明
1	`RF`	資料列類型：報告頁尾
2	`2`	此報告包含兩個 `SH` 資料列
3	`7`	此報告包含 7 個 `SD` 資料列，是所有區塊有關資料列的數量總和

報告範例

請根據上述指示解讀這些範例。此外，請注意下列事項：

每個報告範例的頂端幾行是常見報告標題。
接下來的一段文字包含 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

計算

請使用以下資訊以助計算開發人員的淨收益。

Facebook Pay 購物交易

在 ig_detail 報告中，這類購物交易的 platform 以「F」表示；在 detail 報告中，這類交易屬於「所有」交易。

假設 tax_country「美國」代表該筆購物交易不含稅項，則計算公式如下：
net_developer_revenue = (recv_amount - tax_amount) * fx_rate * rev_share

否則，假設該筆購物交易包含稅項，則計算公式如下：
net_developer_revenue = (recv_amount * fx_rate) * rev_share - (tax_amount * fx_rate)

Google Play 購物交易

在 ig_detail 報告中，這類購物交易的 platform 以「G」表示。

計算公式如下：
net_developer_revenue = recv_amount * fx_rate

備註：這只是基於付款資料得出的估計值；支付款項前，可能仍需支付其他費用。我們未來會更新報告，務求令此計算方式更精確並簡單。

付款報告

概覽

下載每日報告

報告內容

索取報告的時間

透過 API 下載每日報告

備妥公司的編號和密碼

備妥 Company Access Token

公司 access_token 要求範例

下載每日檔案

每日報告要求範例

報告格式

報告標題（RH）

報告標題範例

區塊標題（SH）

區塊標題範例

直欄標題（CH）

直欄標題範例

區塊資料（SD）

區塊資料範例

payment_detailSD 資料列

payment_digestSD 資料列

區塊頁尾（SF）

區塊頁尾範例

報告頁尾（RF）

報告頁尾範例

報告範例

detail 報告範例

digest 報告範例

計算

Facebook Pay 購物交易

Google Play 購物交易

備妥 `Company Access Token`

公司 `access_token` 要求範例

報告標題（`RH`）

區塊標題（`SH`）

直欄標題（`CH`）

區塊資料（`SD`）

`payment_detailSD` 資料列

`payment_digestSD` 資料列

區塊頁尾（`SF`）

報告頁尾（`RF`）

`detail` 報告範例

`digest` 報告範例