Game Payments

Payments Reports

Updated: Jun 30, 2026
Copy for LLM
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.
Payment Reports show in-app purchases only, not Facebook Audience Network revenue. To generate payments reports for Audience Network apps, please refer to the Audience Network Reporting API reference document.

Downloading reports via UI

A financial entity admin can get to the company settings by going to:
  • Business Manager > https://www.business.facebook.com > Settings > Billing and payments
  • Payout Hub > https://www.facebook.com/payout/setting/[financial_entity_id]/ > Go to Business Suite
  • For Canvas Games: Web Payments > Payout > Company > View/Edit
  • For Instant Games: Use cases > In app purchase > Account > Go to Company Settings
There are multiple types of reports to download for your apps.

Invoice Report

A business’ admin can go to their company settings page on Business Manager, select the company they want to get the reports for and go to the Billing and payments hub. Then they can navigate to the Invoices tab. On this page, they can select the Create report button for the report that you want to download.
After you’ve selected these options, click Create to start downloading the Invoice report for your company.
Create report dialog for an Invoice and Campaign report, with Invoice and Campaign breakdown field checkboxes

Transaction Report

A business’ admin can go to Payout Hub > Transactions and click Download. These reports are granular to a monthly scale.
Payout Hub Transactions panel with All, Earnings, and Payouts tabs and a Download button for exporting transaction reports

Ads Report

A business’ admin can go to Business Manager > Ads reporting
Ads reporting Reports view with a Create report button and a list of saved reports to download

Daily Reports

Daily reports are currently only available to be downloaded through API.

What’s in the reports

Invoice Reports

Detailed Invoice and Campaign reports or Statement of Accounts reports for all payment activity.

Transaction Reports

Monthly summary of your payout history.

Ads Reports

Report of metrics and breakdowns surrounding Ads and Ads campaigns.

Daily 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.
Payment reports will be available to download for up to 45 days.

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 https://developers.facebook.com/settings/company/[financial_entity_id].
Company Settings page showing the Company Credentials section with Company ID and Company Secret fields
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:
Name Type Value
client_id
Integer
Your company ID
client_secret
String
Your company secret
grant_type
String
client_credentials
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:
Name Type Value
date
String
Day for which to download report, in YYYY-MM-DD format
type
String
One of detail, digest (web games) or ig_detail, ig_digest (Instant Games)
access_token
String
Your company access token
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:
Name Description
company_id
Developer’s company ID
report_type
The report type, currently either daily_detail or daily_digest
start_time
Report period start time formatted as YYYY-MM-DD 00:00:00 TIMEZONE
end_time
Report period end time formatted as YYYY-MM-DD 23:59:59 TIMEZONE
format_version
1

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:
Column Value Description
1
RH
row type: report header
2
213030545409781
company ID
3
daily_detail
indicates that this is a detail report
4
2011-11-21 00:00:00 PST
the start time for this report
5
2011-11-21 23:59:59 PST
the end time
6
1
the version of the report schema

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:
Name Value
company_id
Developer’s company ID
section_type
Currently, one of credits_detail, credits_digest, payment_detail, or payment_digest

Section header example

Sample row:
SH,213030545409781,payment_detail
How to read the sample row:
Column Value Description
1
SH
row type: section header
2
213030545409781
company ID
3
payment_detail
this is a header for a payment_detail section

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

The credits_detail and credits_digest sections are now deprecated as apps are no longer able to create payments with Facebook Credits.

payment_detail SD row

Fields:
Name Description
app_id
the ID of the app in which the transaction was made.
payment_type
one of the below code:
  • S: Sale
  • R: Refund
  • C: Chargeback
  • D: Out of window chargeback
  • K: Chargeback reversal
  • J: Out of window chargeback reversal
  • N: Decline
When calculating revenue, this corresponds with the following coefficients:
S => 1, R => -1, C => -1, D => 0, K => 1, J => 0, N => -1
product_type
‘S’ to indicate a subscription and ‘P’ for Payments.
payment_id
the unique ID of the payment, analogous to the txn_id in the credits_detail case.
time_completed
timestamp at which the transaction completed, formatted as YYYY-MM-DD HH:MM:SS timezone.
recv_currency
the currency in which the costumer paid, expressed as a 3-letter ISO 4217 code.
recv_amount
The net amount, in units of that currency, including the tax amount. This may not be the amount the developer receives, since Facebook’s revenue share still needs to be removed.
For the final payout amount, check your payout reports.
fx_batch_id
the unique ID of the exchange-rate batch in which this transaction was processed.
fx_rate
the exchange rate at which one unit of the recv_currency buys settle_currency under that fx_batch_id.
settle_currency
the currency in which the developer is paid, expressed as a 3-letter ISO 4217 code. Currently, this field is always USD.
reference_id
The billing agreement ID for the subscription and request_id for payments.
tax_country
the country where the customer made the purchase, given as an ISO 3166-1 alpha-2 country code.
tax_amount
the actual VAT or Sales Tax amount remitted by Facebook on your behalf in the currency used in the transaction.
platform
Only available for ig_detail reports.
'F' corresponds to a Facebook Pay purchase, and 'G' corresponds to a Google Play purchase.
platform_fee
Only available for ig_detail reports.
This is platform fee charged by non-Facebook platforms. For Facebook, the rev-share agreement still applies and would not be included here.
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:
Column Value Description
1
SD
row type: section data
2
266989143414
the app_id in which the payment took place
3
S
the transaction was a sale
4
S
the product sold was a subscription
5
267668373345994
the ID of the sale
6
2012-07-22 00:07:23 PDT
time the payment processing completed
7
USD
the purchasing costumer paid in US dollars
8
19.99
the costumer paid US$19.99
9
123456789ABCDEF00123456789ABCDEF
the exchange rate batch ID
10
1.0000000000
the exchange rate from USD to USD
11
USD
the developer is paid in US dollars
12
20000000007
this payment is part of subscription billing agreement 20000000007’s history
13
US
the purchasing costumer is in the United States of America
14
0.99
the actual VAT amount remitted on your behalf
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:
Column Value Description
1
SD
row type: section data
2
480369938658210
the app_id in which the payment took place
3
S
the transaction was a sale
4
P
the transaction was from a payment
5
362736900505327
the payment ID of the sale
6
2013-06-12 16:33:52 PDT
time the payment processing completed
7
USD
the purchasing costumer paid in US dollars
8
1
the costumer paid US$1.00
9
6E5D989082A04A68AA801DB17A30721A
the exchange rate batch ID
10
1.0000000000
the exchange rate from USD to USD
11
USD
the developer is paid in US dollars
12
QQ6C7XaxeMyCW4RdZXFGwKTQM1IkMBIO-peWtFFJelHUdSC9NaeYlBXEMJd3LO17k
the app’s request_id for this payment
13
US
the purchasing costumer is in the United States of America
14
0.09
the actual VAT amount remitted on your behalf

payment_digest SD row

Fields:
Name Description
app_id
the app_id whose payments are being summarized
app_name
the name of that app
payment_type
one of the below code:
  • S: Sale
  • R: Refund
  • C: Chargeback
  • D: out of window chargeback
  • K: chargeback reversal
  • J: out of window chargeback reversal
  • N: Decline
product_type
‘S’ to indicate a subscription and ‘P’ for Payments
recv_currency
the payer currency being summarized, expressed as a 3-letter ISO 4217 code
recv_amount
the total amount of that currency involved in payments of the current type during a given forex batch
fx_batch_id
the ID of that batch
fx_rate
the exchange rate at which one recv_currency buys settle_currency under that fx_batch_id
settle_currency
the currency in which the developer is paid, expressed as a 3-letter ISO 4217 code
settle_amount
the total amount of that currency matching the app, payment type, product type, currency, and forex batch during the report period
tax_amount
the actual VAT or Sales Tax amount remitted by Facebook on your behalf
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:
Column Value Description
1
SD
row type: section data
2
200000000000002
considering the app with ID 200000000000002
3
Game2
...which is called “Game2”
4
S
...looking at all sales
5
S
...of subscriptions
6
CNY
...paid in Chinese Yuan (renminbi)
7
5000.0
...and totaling 5000 CNY
8
FXBATCHID1
...which were converted under FXBATCHID1
9
0.2
...at a rate of 1 CNY = 0.2 USD
10
USD
the developer is paid in USD
11
1000.0
total: “Game2 had US$1000 in sales during the report period, summing across people who bought subscriptions using Chinese Yuan(renminbi) during FXBATCHID1”
12
9.99
the VAT amount remitted on your behalf is 9.99
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:
Column Value Description
1
SD
row type: section data
2
200000000000002
considering the app with ID 900000000000009
3
Game9
...which is called “Game9”
4
S
...looking at all sales
5
P
...of payments
6
CNY
...requested in Chinese Yuan (renminbi)
7
5000.0
...and totaling 5000 CNY
8
FXBATCHID1
...which were converted under FXBATCHID1
9
0.2
...at a rate of 1 CNY = 0.2 USD
10
USD
the developer is paid in USD
11
1000.0
total: “Game2 had US$1000 in sales during the report period, summing across people who bought in-app goods with payments using Chinese Yuan(renminbi) during FXBATCHID1”
12
9.99
the VAT amount remitted on your behalf is 9.99
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:
Name Description
number_of_total_data_rows
The total number of section data rows contained in this section of this report
Sample row:
SF,7
How to read the sample row:
Column Value Description
1
SF
row type: section footer
2
7
this section contained 7 SD rows
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:
Name Description
number_of_sections
the total number of section header rows in this report
number_of_total_data_rows
The total number of section data rows contained in all sections in this report
Sample row:
RF,2,7
How to read the sample row:
Column Value Description
1
RF
row type: report footer
2
2
this report contained 2 SH rows
3
7
this report contained 7 SD rows, summing across all sections

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.