Payments Reports

If you've developed apps that use Facebook payments and subscription features, you can get a report from us, breaking down payment activity in your apps on a given day, by using the reports feature of Facebook payments.

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 aren't available for apps that use the Facebook Audience Network. To generate payments reports for Audience Network apps, please refer to the Audience Network Reporting API reference document.

Downloading the daily reports

To download a daily report for your apps, go to your company settings page, select the company you want to get the reports for and go the Reports tab.

On this page, you'll be able to select the Report Date with the calendar tool and Report Type from the drop down menu for the report that you want to download.

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 digest report summarizes all transactions of a given type for a given app.

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 including 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 at 8AM US Pacific Time (UTC -8/-7), so the most recent date for which reports are available is typically the day before the request.

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, 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:

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

Either detail or digest

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,recv_amount,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

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 number of units of that currency that the app requested

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 costumer made the purchase, given as an ISO 3166-1 alpha-2 country cod

tax_amount

The actual VAT amount remitted by Facebook on your behalf.

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 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

Section Footer example

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

Report footer example

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