支付报告

概览

本文档将详细说明这些报告的内容，介绍请求获取这些报告的 API 以及报告的格式。

• 下载每日报告
• 报告内容
• 何时请求获取报告
• 通过 API 下载每日报告
• 每日报告的格式
• 报告标头
• 版块标头
• 栏标头
• 版块数据
• 版块页脚
• 报告页脚
• 报告示例

下载每日报告

如要下载应用的每日报告，公司管理员可前往公司设置页面，选择想要获取报告的公司，然后前往“报告”选项卡。在此页面上，公司管理员可以通过日历工具选择报告日期，并在下拉菜单中选择要下载报告的报告类型。

或者，管理员也可以通过前往以下设置转到公司设置页面：

• 对于 Canvas 游戏：网络支付 > 网络支付 > 公司 > 查看/编辑
• 对于小游戏：应用内购买 > 帐户 > 前往公司设置

选择这些选项后，点击下载，即可开始下载您公司的每日报告。

报告内容

每份报告涵盖单日（从美国太平洋时间 [UTC -8/-7] 凌晨 00:00 到晚上 11:59:59）的数据，包含当日所有应用中向同一公司付费的所有交易。

对于任意日期，您都可以请求获取以下 2 种单独的报告。

• detail 报告：在此报告中，每一笔交易（即每一笔销售、每一笔退款等）都有一条相关记录。从 Facebook 角度而言，detail 报告是缴费报告。
• digest 报告：此报告会汇总特定应用中特定类型的所有交易。

小游戏报告与此类似，但是名称不同：

• ig_detail 报告：在此报告中，每一笔交易（即每一笔销售、每一笔退款等）都有一条相关记录。
• ig_digest 报告：此报告会汇总特定小游戏中特定类型的所有交易。

目前，支付报告有 2 个部分，但是您编写解析程序时不应受限于此，因为报告格式经过专门设计，能够轻松扩展。

• 一个部分是 credits_digest 或 credits_detail（取决于您要读取的报告）：此部分涵盖使用 Facebook 币功能进行的所有交易，其中包括通过支付对话框的 buy_item 操作完成的所有游戏内购买。此版块已被停用，因为开发者不能再接收 Facebook 币付款。

• 另一个版块是 payment_digest 或 payment_detail：此版块涵盖使用 Facebook 支付功能（即订阅和支付功能）完成的交易。

何时请求获取报告

我们每天生成一次新报告，并在美国太平洋时间 (UTC -8/-7) 正午时分提供报告，因此最近一次生成报告的日期通常为请求前一天。对于小游戏而言，则会延迟 2 天。

通过 API 下载每日报告

您可以通过基于网页的 API 获取支付报告，该 API 支持您请求获取特定日期交易的摘要报告或详尽报告。

您可以通过以下 3 个步骤获取报告：

1. 获取公司编号和密钥
2. 获取 Company access_token
3. 下载报告文件

获取公司编号和密钥

在开始之前，您需要确保已启用应用的支付功能，包括设置收取付款的公司。

完成此操作后，您可以在公司设置页面的凭证选项卡上找到公司编号和密钥。

一个公司只需要一个编号/密钥对；此编号/密钥对可用于该公司的所有应用。您必须有这些凭证才能获取 access_token，而这是下载您应用的每日交易报告的必要项。

获取 Company Access Token

通过 Company Access Token，您可以访问与口令授予方所代表公司关联的所有应用的报告。如要获取该口令，请向以下网址发送 GET 请求

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

请使用以下查询参数：

除非您重置公司密钥，否则此口令不会过期，所以您必须存储并重复使用此口令，而不是在每次请求获取报告时重新生成此口令。

公司 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 后，您可以使用此口令请求下载包含公司所有应用数据的每日报告文件。如上文所述，我们可生成以下 2 种报告：

• digest 报告：在此报告中，每个应用-交易类型对为一个数据行，其中汇总了每个应用的销售、退款和其他交易事件
• detail 报告：顾名思义，在此报告中，每笔交易为一个数据行

如要下载任意一天的报告文件，请向以下网址发送 GET 请求

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

请使用以下查询参数：

同样如上文所述，date 不能是当天的日期。特定日期的报告是在该日期后一天的美国太平洋时间 (UTC -8/-7) 上午 8:00 过后提供。

每日报告请求示例

每日 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 的文件。

报告格式

所有报告均使用相同的整体结构：

• 报告是采用逗号分隔值 (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 行包含下列字段：

报告标头示例

以下为报告标头行示例：

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

以下为该行示例的解读方法：

版块标头 (SH)

报告标头和报告页脚之间的每一行都属于版块内容。报告的每个版块都由版块标头引入；相应的版块始于其标头，止于下一个版块页脚。SH 行包含下列字段：

版块标头示例

以下为版块标头行示例：

SH,213030545409781,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 版块，每一行代表特定应用中特定类型的所有交易的汇总（例如：“应用编号 276999562313463 中的所有销售”、“应用编号 276899562313544 中所有的日元订阅退款”）。目前有 4 种类型的版块，具体介绍如下。

版块数据示例

payment_detailSD 行

字段：

以下为订阅行示例：

SD,266989143414,S,S,267668373345994,2012-07-22 00:07:23 PDT,USD,19.99,123456789ABCDEF00123456789ABCDEF,1.0000000000,USD,20000000007,US,0.99

以下为该订阅行示例的解读方法：

以下为支付行示例：

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

以下为该支付行示例的解读方法：

payment_digestSD 行

字段：

以下为订阅行示例：

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

以下为该订阅行示例的解读方法：

以下为支付行示例：

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

以下为该支付行示例的解读方法：

版块页脚 (SF)

每个版块以版块页脚行结束，版块页脚行本身可以后接新的版块，以新的 SH 行开始；也可以后接报告页脚行，表示报告结束。类型字段后面的一个数据栏包含：

版块页脚示例

以下为版块页脚行示例：

SF,7

以下为该行示例的解读方法：

报告页脚 (RF)

报告以报告页脚行结束，该行应该是文件的最后一行。在行类型栏之后，有 2 项汇总数据：

报告页脚示例

以下为报告页脚行示例：

RF,2,7

以下为该行示例的解读方法：

报告示例

请根据上述说明阅读这些报告示例。此外，请注意以下事项：

• 每个报告示例顶部的代码行是通用的报告标头。
• 下一块文本包含 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 为“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)

Google Play 购物

这些购物由 ig_detail 报告内 platform 为“G”的交易表示。

计算时采用以下公式：
net_developer_revenue = recv_amount * fx_rate

注意：这只是基于付费数据的估计值；进账前可能会产生其他费用。以后更新报告后，此计算将更准确、更简单。