Balance Report
Docs
Last updated: Oct 30th, 11:46pm
The Balance Report is used by merchants for the reconciliation of payment activities. It contains a list of all payments, disputes, and fee-incurring events. This report is available through PayPal's website and the Secure FTP Server. You can download a sample balance report here.
Using the balance report, you can:
- Reconcile payments received using PayPal with your order management system.
- Reconcile and account for all payment activities, including sales, refunds, disputes, fees, and withdrawals with the end-of-day PayPal balances.
- Understand payouts to your bank accounts.
- Reconcile all fees.
Know before you begin
- The report is only available in comma-separated values (
.csv) format. - The report uses UTF-8 (8-bit UCS/Unicode Transformation Format) character encoding.
- Amounts in this report are expressed in major units of currency. For example: dollars for USD and yen for JPY. See PayPal Supported Currencies for a list of all ISO-4217 currency codes that PayPal supports for use with payments and balances.
- Digital Currency Amounts in this report are expressed in cryptocurrency. See PayPal Supported Cryptocurrencies for a list of all cryptocurrency codes that PayPal supports.
- Money refunded from your account is shown with a minus sign. For example, -1000 USD is shown as the refunded amount.
- A single report file can contain a maximum of a million records. If the report contains more than a million records, the report is split across multiple files.
- The balance report is generated daily by 12:00 PM in the leading time zone of the reporting window. The report is available on the Secure FTP Server in the
/ppreports/outgoingdirectory. For help with SFTP reports, see Access SFTP reports.
PayPal can enhance these reports and add additional attributes to the reports in the future. Use column names when integrating with these reports, so that your integrations don't break when new columns are added to the reports.
File naming convention
The naming convention of the report filename is as follows:
${encryptedSubscriptionId}-{NodeIdentifier}-{subfamily}-{templateName}-{dateCadence}-{fileNumber}-{totalFile}-{genDateTime}.{extension}.
Example:
ABC1-6ABKUHNC34696-BRR_BALANCE_RECONCILIATION-REPORT-20220601-1-1-20220602000000.CSV
For more details about file naming convention, see the glossary.
Reconciliation
Transaction-level reconciliation
To reconcile daily changes in your PayPal account balances with your internal system of records, use the Detail Section of the Balance Report. This section provides comprehensive transaction-level data required to reconcile sales, refunds, fees, and other activities.
Reconcile net settled fees
Net-billed fees are charged at the time of the transaction and deducted upfront from the merchant's balance.
To reconcile net-billed fees, add the amounts reflected in Total Net Fees column.
Reconcile gross settled fees
Gross-billed fees are periodically billed (for example, IC++ fees) and are not deducted immediately from the transaction.
To reconcile gross-billed fees for a specific merchant account:
- Filter records by the same Merchant Account ID.
- For every record, ensure you extract the following required columns:
- Record Type
- Total Interchange Fees
- Total Scheme Fees
- Total Passthrough Fees
- Invoiced fee
- Event fees are reported only in invoicing currency.
- To fetch the total gross-settled fees, add up the amounts in the Invoiced Fee column.
- The Invoiced Fee column reflects the total amount of fees billed to you. This includes all applicable periodic charges, such as monthly scheme fees, if any, associated with your merchant account.
Notes:
- For merchants on the Gross settlement model, fees listed in transaction events will be billed in your next invoice.
- For merchants on a Net Settlement model, these fees are deducted directly from your daily processing amounts.
Report specifications
Report Header
| Position | Column name | Optional/Required | Data type | Description |
|---|---|---|---|---|
| 1 | RH | Required | Static, 2 characters | Indicates that this row of data contains report body data. |
| 2 | Report name | Required | Character varying (256) | Name of the report. The default name is BALANCE_RECONCILIATION_REPORT.If the name is customized, the report shows the custom name. |
| 3 | Report status | Required | Success / Error | Report generation status. |
| 4 | Report Start Date And Time | Required | YYYY/MM/DD HH:MM:SS offset |
The start date and time for which the data is captured in the report, where:
|
| 5 | Report End Date And Time | Required | YYYY/MM/DD HH:MM:SS offset |
The end date and time for which the data is captured in the report, where:
|
| 6 | Report Generation Date and Time | Required | YYYY/MM/DD HH:MM:SS offset |
The date and time when the report file was generated, in the following format: YYYY/MM/DD where:
|
| 7 | Hierarchy | Required | Character varying (256) | Encrypted PayPal account number for an account holding individual account in PayPal. |
| 8 | Time zone | Required | Character varying (256) | Time zone of the report. |
Report Details
| Position | Column name | Optional/Required | Data type | Description |
|---|---|---|---|---|
| 1 | RD | Required | Static, 2 characters | Descriptor advising that this section of the report contains details data. |
| 2 | Merchant account ID | Required | Character varying (256) | Encrypted account number of the merchant. |
| 3 | Record ID | Required | Character varying (256) | Unique identifier for the transaction. |
| 4 | Related record ID | Optional | Character varying (256) | Unique ID of a previous transaction referenced by this transaction. For example, refund transactions contain the ID of the original sale transaction. |
| 5 | Invoice ID | Optional | Character varying (256) | The invoice ID passed at the time of transaction. |
| 6 | Original invoice ID | Optional | Character varying (256) | The invoice ID of the original sale transaction. Used to link all transactions associated with the original invoice ID. |
| 7 | Partner identifier | Optional | Character varying (256) | Identifier for the partner/ marketplace that enabled this transaction. |
| 8 | Created at | Required | YYYY-MM-DD HH:MM:SS |
The UTC timestamp of when the record was created. |
| 9 | Record type | Required | Character varying (256) | Type of the transaction. See the glossary for more information. |
| 10 | Record subtype | Optional | Character varying (256) | Subtype of the transaction. See the glossary for more information. |
| 11 | Transaction currency | Optional | 3-character currency code Max length: 3 characters |
Currency of the transaction. See PayPal-supported currencies for possible values. |
| 12 | Gross transaction amount | Optional | Numeric (23, 2) | Total amount of the transaction before deducting fees. |
| 13 | Total Gross Fees | Optional | Numeric (23, 2) | Total sum of fees accrued to be billed in the upcoming statement. |
| 14 | Total Net Fees | Optional | Numeric (23, 2) | The fee amount for transactions where a transactional fee has been processed. |
| 15 | Partner Commission | Optional | Numeric (23, 2) | It is the commission charged by the partner or marketplace you do business with. |
| 16 | Net Transaction Amount | Optional | Numeric (23, 2) | It will be Gross Transaction amount (-) Total net fees (-) Partner Commission |
| 17 | Settlement Currency | Optional | Character (3) | The 3-letter ISO code identifies the merchant's settlement currency when the transaction amount is settled |
| 18 | Settlement Amount | Optional | Numeric (23,2) | It is the net transaction amount in settlement currency. |
| 19 | Pending Settlement Amount | Optional | Numeric (23,2) | Amount that is not settled based on settlement instructions received by PayPal |
| 20 | Exchange Rate | Optional | Numeric (23,8) | The exchange rate used to calculate the Settlement Amount or Pending Settlement Amount. |
| 21 | Reference Type | Optional | Character varying (256) | Possible values:
|
| 22 | Reference ID | Optional | Character varying (256) | Identifier or ID related to the reference type provided in the field reference type. |
| 23 | Transfer ID | Optional | Character varying (256) | The unique transfer identifier that shows on the merchant's bank statement. Used to reconcile a deposit entry against the line items. |
| 24 | Transfer Account | Optional | Character varying (256) | The last 4 digits of the account where the funds were disbursed. |
| 25 | Customer Name | Optional | Character varying (256) | Name of the customer behind the transaction. |
| 26 | Payment instrument type | Optional | Character varying (256) | The method of payment used to process the transaction. See the glossary for more information. |
| 27 | Payment instrument subtype | Optional | Character varying (256) | The specific tender used to process the transaction. See the glossary for more information. |
| 28 | Payment Network | Optional | Character varying (256) | The credit or pin-less debit network which was used |
| 29 | Payment channel | Optional | Character varying (256) | The channel for the payment transaction. Possible values:
|
| 30 | Payment Token | Optional | Character varying (256) | The vault token of this payment method. |
| 31 | Issuing Country | Optional | Character varying (256) | The country the issuer is domiciled in. |
| 32 | Issuing Bank | Optional | Character varying (256) | The name of the issuing bank. |
| 33 | BIN | Optional | Character varying (256) | The first 6 or 8 digits of a credit card identifying the issuer. |
| 34 | Acquirer Reference Number | Optional | Character varying (256) | ID assigned to the record by the acquirer. |
| 35 | Store ID | Optional | Character varying (256) | ID of the store where the transaction was initiated. |
| 36 | Reader ID | Optional | Character varying (256) | Terminal ID in the store where the transaction was initiated. |
| 37 | Reason code | Optional | Character varying (256) | The reason for declining the transaction, when available. For credit card transactions, the code is a processor decline code. For bank transactions, the code is a bank decline code. For more information, see processor decline codes. For more information on UDD Sepa declines, refer here. |
| 38 | Memo | Optional | Character varying (256) | Custom information sent by user while calling API to place transaction. |
| 39 | Custom Field | Optional | Character varying (256) | Custom information sent by user while calling API to place transaction |
| 40 | Fixed Fee | Optional | Numeric (23, 2) | Fixed fee assessed by PayPal. |
| 41 | Variable Fee Rate | Optional | Numeric (23, 2) | Variable fee assessed by PayPal. |
| 42 | Total Processing Fees | Optional | Numeric (23, 2) | The total amount of PayPal fees charged to the event. |
| 43 | FX Fixed Fee | Optional | Numeric (23, 2) | FX fixed fee assessed by PayPal. |
| 44 | FX Variable Rate | Optional | Numeric (23, 2) | FX variable fee assessed by PayPal. |
| 45 | Campaign fees | Optional | Numeric (23, 2) | Campaign fee assessed by PayPal. |
| 46 | Credit transaction fees | Optional | Numeric (23, 2) | The credit-related transaction fee amount for a merchant-selected credit offering. |
| 47 | Cross Border Fee | Optional | Numeric (23, 2) | Cross-Border fee assessed by PayPal. |
| 48 | Chargeback Protection Fee | Optional | Numeric (23, 2) | Chargeback protection fee assessed by PayPal. |
| 49 | Interchange Fixed Fee | Optional | Numeric (23, 5) | The per transaction Interchange fee applied to the event. |
| 50 | Interchange Rate | Optional | Numeric (23, 2) | The rate at which the interchange was applied to the settlement amount. |
| 51 | Total Interchange Fees | Optional | Numeric (23, 5) | The total interchange fees applied to the event. |
| 52 | Total Scheme Fees | Optional | Numeric (23, 5) | The total scheme fees applied to the event. |
| 53 | Total Passthrough Fees | Optional | Numeric (23, 5) | The sum of Total Interchange Fees and Total Scheme Fees. |
| 54 | Passthrough Fee Currency | Optional | Character (3) | Currency in which passthrough fee is charged. |
| 55 | Description | Optional | Character varying (256) | Description of:
|
| 56 | Count | Optional | Numeric (256) | The count of events in this record. This will indicate the count of transactions for which the fee is getting charged. |
| 57 | Fee Period | Optional | YYYY-MM |
The period when the transaction that incurred fees took place. |
| 58 | Invoicing Currency | Optional | Character (3) | Currency in which invoice is created. |
| 59 | Invoiced Fee | Optional | Numeric (23,5) | Total invoiced amount. |
| 60 | Digital Currency | Optional | Character (Max 5) | Currency of the transaction. See PayPal Supported Cryptocurrencies for possible values. |
| 61 | Digital Currency Gross Amount | Optional | Numeric (23, 8) | Gross transaction amount of crypto currency bought/sold/ transferred/ disputed. |
| 62 | Digital Currency Fee | Optional | Numeric (23, 8) | Fee on crypto currency bought/sold/ transferred/ disputed. |
| 63 | Digital Currency Net Amount | Optional | Numeric (23, 8) | Net transaction amount of crypto currency bought/sold/ transferred/ disputed. |