Payments Reports

Overview

This document details the contents of the reports, describes the API for requesting them, and lays out the format in which they're delivered.

• Downloading the daily reports
• What's in the reports
• When to request reports
• Downloading daily reports via API
• The format of the daily reports
• Report header
• Section header
• Column header
• Section data
• Section footer
• Report footer
• Sample reports

Downloading the daily reports

To download a daily report for your apps, a business’ admin can go to their company settings page, select the company they want to get the reports for and go to the Reports tab. On this page, they can select the Report Date with the calendar tool and Report Type from the drop down menu for the report that you want to download.

As an alternative, the admin also can get to the company settings by going to:

• For Canvas Games: Web Payments > Web Payments > Company > View/Edit
• For Instant Games: In app purchase > Account > Go to Company Settings

After you've selected these options, click Download to start downloading the daily report for your company.

What's in the reports

Each report covers one day, from 12AM-11:59:59PM US Pacific Time (UTC -8/-7), and includes all the transactions across all the apps that paid out to the same company on that day.

For any given day, there are 2 separate reports you can request.

• The detail report has one record for each individual transaction - that is, for each sale, each refund, and so on. The details report are pay-in from the perspective of Facebook.
• The digest report summarizes all transactions of a given type for a given app.

The Instant Games reports are similar but named differently:

• The ig_detail report has one record for each individual transaction - that is, for each sale, each refund, and so on.
• The ig_digest report summarizes all transactions of a given type for a given Instant Game.

Currently, payment reports have 2 sections, although you shouldn't depend on this when writing your parser, as the reports format is designed to be readily extended.

• One section, credits_digest or credits_detail depending on which report you're reading, covers all transactions using the Facebook Credits feature, and includes all in-game purchases done through the Pay dialog's buy_item action. This section has been deprecated as developers can no longer receive payments in Facebook Credits.

• The other, payment_digest or payment_detail, covers transactions using the Facebook payments feature, namely Subscriptions and Payments.

When to request reports

We build new reports once per day and make them available by noon US Pacific Time (UTC -8/-7), so the most recent date for which reports are available is typically the day before the request. For Instant Games, there is a two day delay.

Downloading daily reports via API

Payments reports are available via a web-based API, which allows you to request either a summary or a highly detailed report of transactions during a selected day.

There are 3 steps to getting your reports:

1. Get your Company ID and secret
2. Get a Company access_token
3. Download report files

Get your company ID and secret

Before you can proceed, you'll need to make sure that you've enabled an app for payments, including setting up a company to receive payments.

Once you've done that, you'll find your company ID and secret on your Company Settings page, on the Credentials tab.

Only one id/secret pair is required for a given company; the same ones are used across all of that company's apps. You'll need these credentials to be able to get the access_token required to download daily transaction reports for your apps.

Get a Company Access Token

A Company Access Token allows you to access reports for all apps associated with the company on whose behalf the token was issued. To get one, issue a GET request to

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

with the following query parameters:

This token won't expire unless you reset your company secret, so you must store and reuse it, rather than generating it anew each time you request reports.

Example company access_token request

Sample request:

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

Sample response from Facebook:

access_token=230001349987723|aBc_dEFaEUZberrtkrp8pbtwXyZ

Download daily files

Once you have your company access_token, you can use it to request daily report files which cover all your company's apps. As mentioned above, we generate 2 kinds of reports:

• The digest report contains a data row for each app-transaction type pair, summarizing the sales, refunds and other transaction events for each app
• The detail report, as its name suggests, has a row for each individual transaction

To download the report files for any day, issue a GET request to

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

With the following query parameters:

Also as mentioned above, date can't be today's date. A given day's reports are available after 8AM US Pacific Time (UTC -8/-7) on the day that follows.

Example daily report requests

Sample developer request for a daily detail report:

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

The request above would return a file named 23459934998762_detail_2012-05-15.csv.zip.

Sample developer request for a digest report:

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

The request above would give you a file named 23459934998762_digest_2012-05-15.csv.zip.

Report format

All reports share a common overall structure:

• Reports are comma-separated-value (CSV) text files.
• Line separators are Unix-style "\n" (new line).
• Fields that contain commas will be wrapped in double-quotes for easy Excel importing.
• Each row's first column is a row type code, which determines how the remaining columns are interpreted.
• Reports use 6 row types, structured as follows:
• One report header (type code RH)
• One or more sections, each consisting of
• One section header (SH)
• One column header (CH)
• Zero or more section data (SD) rows
• One section footer (SF)
• One report footer (RF)

Their structure can be visualized like this:

RH,     ...

  SH,   ...
    CH, ...
    SD, ...
    [More section data rows]
  SF,   ...

  SH,   ...
    CH, ...
    SD, ...
    [More section data rows]
  SF,   ...

  [Possibly more sections]

RF,     ...

Note that the indentation and spacing above are aids to reading; the actual reports are unindented, and have spaces only where the data in the fields has spaces.

Examples which include fully populated fields can be found in the sample files section at the end of this document.

Report header (RH)

The first row is the report header, which contains data which applies to all rows below it, down to the next report footer, which marks the end of the report. RH rows contain these fields:

Report header example

Sample row:

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

How to read the sample row:

Section header (SH)

Every row between the report header and footer is part of a section. Each section of the report is introduced by a section header; the section runs from its header to the next section footer. SH rows contain the following fields:

Section header example

Sample row:

SH,213030545409781,payment_detail

How to read the sample row:

Column header (CH)

Each section header is followed by a column header, which gives the field names for that section's section data rows. Each section type has different fields. It's important that you read the CH rows to obtain the names of the fields in each section. The report format is easy to extend by updating its self-description, so column orders or section specifications may change in ways that will invalidate any hard-coded parsing solution.

Column header examples

An example of a CH row from a payment_detail section:

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

An example of a CH row from a payment_digest section:

CH,app_id,app_name,payment_type,product_type,recv_currency,
,fx_batch_id,fx_rate,settle_currency,settle_amount

Section data (SD)

Following a section's column header, there are zero or more section data rows which take their field names from the CH row. The meaning of the rows depend on the section type: in detail sections, each row is a single transaction and in digest sections, each row is the sum of all transactions of a given type within a given app (e.g. "all the sales in app ID 276999562313463", "all the Japanese yen denominated subscription refunds in app ID 276899562313544"). Currently, there are 4 types of sections, explained below.

Section data examples

payment_detail SD row

Fields:

Subscription sample row:

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

How to read the subscription sample row:

Payments sample row:

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

How to read the payments sample row:

payment_digest SD row

Fields:

Subscription sample row:

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

How to read the subscription sample row:

Payments sample row:

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

How to read the payment sample row:

Section Footer (SF)

Each section ends with a Section Footer row, which itself can be followed by either a new section, beginning with an SH row, or by the Report Footer row, indicating the end of the report. The single column of data following the type field contains:

Section Footer example

Sample row:

SF,7

How to read the sample row:

Report footer (RF)

The report ends with a Report Footer row, which should be the last row in the file. It has 2 pieces of summary data following its type column:

Report footer example

Sample row:

RF,2,7

How to read the sample row:

Sample reports

Read these samples according to the instructions above. Also, please note the following:

• The lines at the top of each sample report are the common report headers.
• The next block of text contains the credits_detail or _digest sections.
• The block of text after that (just above footer) contains the payment_detail or payment_digest sections.
• The lines at the top bottom of sample are the common report footers.

Sample detail report

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

Sample digest report

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

Calculations

To help calculate developer net revenue, please use the following information.

Facebook Pay purchases

These are denoted by transactions with platform equal to "F" in a ig_detail report or all transactions in a detail report.

Assume that a tax_country of "US" means that the purchase is tax exclusive and that the calculation follows this formula:
net_developer_revenue = (recv_amount - tax_amount) * fx_rate * rev_share

Otherwise, assume the purchase is tax inclusive and that the calculation follows this formula:
net_developer_revenue = (recv_amount * fx_rate) * rev_share - (tax_amount * fx_rate)

Google Play purchases

These are denoted by transactions with platform equal to "G" in a ig_detail report.

The calculation follows this formula:
net_developer_revenue = recv_amount * fx_rate

Note: this is just an estimate based on pay-in data; additional fees may apply before payout. A future update to the reports will make this calculation both more exact and easier.