DocsToolsSupportNewsApps

Payments Reports

We are transitioning all canvas game developers away from Facebook Credits to local currency payments by September 12, 2013, 90 days after breaking change announcement. The new payments system simplifies the purchase experience for users, improves the performance of the payment flow, and makes it easier for developers to price virtual goods for a global audience. For more information, please see our local currency payments overview.

However, the Payments Reports support Credits, Subsciptions and Local Currency Payments.

If you have developed apps that use Facebook's 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. This document details the contents of the reports, describes the API for requesting them, and lays out the format in which they're delivered.

Contents

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 two 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 two sections, although you should not 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

  • The other, payment_digest or payment_detail, covers transactions using the Facebook Payments feature, namely Subscriptions and Local Currency 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.

Note: 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 three 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.

Only one id/secret pair is required for a given company; the same ones are used across all of that company's apps. You will 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 will not expire unless you reset your company secret, so you should store and reuse it, rather then 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, Facebook generates two 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/234599349987627/report?
                                          date=2012-05-15&
                                          type=detail&
                                          access_token=234599349987627|aBc_dEFaEUZbqpatkrp8pbtwXyZ"

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

Sample developer request for a digest report:

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

The request above would give you a file named 234599349987627_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".
  • 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 to be interpreted.
  • Reports use six row types, structured as follows:

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

How to read the sample row:

Column Value Description
1 SH row type: section header
2 213030545409781 company ID
3 credits_detail this is a header for a credits_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 is important that you read the CH rows to obtain the names of the fields in each section. The report format is designed to be 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 credits_detail section:

CH,app_id,txn_type,txn_id,order_id,txn_time,value,credits

An example of a CH row from a credits_digest section:

CH,app_id,app_name,txn_type,value,credits

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 meanings 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 four types of sections, explained below.

Section Data examples
credits_detail SD row

Fields:

Name Value
app_id the app_id in which the transaction took place
txn_type one of S: Sale, R: Refund, C: Chargeback, D:out of window chargeback, K: chargeback reversal, J out of window chargeback reversal
txn_id the Facebook transaction ID, which is not guaranteed to be unique
order_id the Facebook ID of the order object which this transaction belongs to; note that any order might have several associated transactions
txn_time transaction completion time, formatted as YYYY-MM-DD HH:MM:SS TIMEZONE
value USD per credit
credits number of credits

Sample row:

SD,276999562313463,S,3503800510095823949,9006239549976,2011-11-21 20:46:53 PST,0.1,10.0

How to read the sample row:

Column Value Description
1 SD row type: section data
2 276999562313463 the app_id in which the transaction took place
3 S this transaction's type, a Sale
4 3503800510095823949 the txn_id for this transaction
5 9006239549976 the order_id which this transaction applies to (a given order may have many transactions, for instance a sale, followed by a refund)
6 2011-11-21 20:46:53 PST the time at which the transaction was processed
7 0.1 the price of a credit in the payout currency (US dollars)
8 10.0 the number of credits involved: "Transaction 3503800510095823949 was a Sale for 30 credits that happened under order ID 9006239549976, in app 276999562313463"
credits_digest SD row

Fields:

Name Description
app_id the ID of the app whose transactions are being summarized
app_name the app's name
txn_type one of S: Sale, R: Refund, C: Chargeback, D:out of window chargeback, K: chargeback reversal, J out of window chargeback reversal
value the price of a credit in the payout currency (US dollars)
credits number of credits

Sample row:

SD,276999562313463,"Test app with, like, commas in the name",S,0.1,30.0

How to read the sample row:

Column Value Description
1 SD row type: section data
2 276999562313463 the app_id whose transactions are being summarized
3 "Test app with, like, commas in the name" the name of the app with app_id 276999562313463, illustrating the double-quoting of values containing commas
4 S the type of transaction being summarized, Sales
5 0.1 the price of a credit in the payout currency (US dollars)
6 30.0 total: "During the report period, the total value of Sale transactions for app 276999562313463 was 30 credits"
payments_detail SD row

Fields:

Name Description
app_id the ID of the app in which the transaction was made
payment_type one of S: Sale, R: Refund, C: Chargeback, D:out of window chargeback, K: chargeback reversal, J out of window chargeback reversal
product_type 'S' to indicate a subscription and 'P' for Local Currency 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 user 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 local currency payments
tax_country the country where the user made the purchase, given as an ISO 3166-1 alpha-2 country code

Subscription sample row:

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

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 user paid in US dollars
8 19.99 the user 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 user is in the United States of America

Local currency payments sample row:

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

How to read the local currency 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 local currency 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 user paid in US dollars
8 1 the user 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 QQ6C7XaxeMyCW4RdZXFGwKTQM1IkMBIOpeWtFFJelHUdSC9NaeYlBXEMJd3LO17k the app's request_id for this payment
13 US the purchasing user is in the United States of America
payments_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 S: Sale, R: Refund, C: Chargeback, D:out of window chargeback, K: chargeback reversal, J out of window chargeback reversal
product_type 'S' to indicate a subscription and 'P' for Local Currency 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

Subscription sample row:

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

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 renminbi
7 5000.0 ...and totalling 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 users who bought subscriptions using renminbi during FXBATCHID1"

Local currency payments sample row:

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

How to read the local currency payments 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 renminbi
7 5000.0 ...and totalling 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 users who bought in-app goods with local currency payments using renminbi during FXBATCHID1"

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 the file. It has two 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 according to the instructions above. For visual clarity, they've been color-coded: the red text is the common report header and footer, the green text is the credits_detail or _digest section, and the blue text is the payments_detail or _digest section.

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 SD,2000000001,S,364791569818956,9007847835,2012-04-24 00:05:42 PDT,0.1,10.0
SD,2000000001,S,364791569818969,9007845424,2012-04-24 00:29:14 PDT,0.1,1.0
SD,2000000001,S,364791569818969,9007845424,2012-04-24 00:29:14 PDT,0.1,5.0
SD,2000000001,S,364791569818991,9007848970,2012-04-24 00:49:43 PDT,0.1,8.0
SD,2000000001,S,4503599660878,9007846290,2012-04-24 01:15:24 PDT,0.1,233.0
SD,2000000001,S,364791569855336,9007850143,2012-04-24 01:27:13 PDT,0.1,2.0
SD,2000000001,S,4503599660917,9007840723,2012-04-24 01:48:11 PDT,0.1,18.0
SD,200000000000002,C,774619135909348,9679000097,2012-04-24 22:09:21 PDT,0.1,47.0
SD,200000000000002,C,774619135909349,9007345108,2012-04-24 22:09:21 PDT,0.1,47.0
SF,9

SH,2000000000002,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
SD,200000000000001,Game1,C,0.1,141343.0
SD,200000000000002,Game2,C,0.1,2036.0
SD,200000000000002,Game2,S,0.1,3640.0
SF,3

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

Updated last Thursday
Facebook © 2013 · English (US)
AboutAdvertisingCareersPlatform PoliciesPrivacy Policy