Platform CSV Report
CSV report for platforms managing multiple merchants. Provides aggregated payout and transaction data to streamline platform-level reconciliation.
This report is designed exclusively for platforms, not individual merchants.
It provides an overview of all payouts made to merchants on the platform. Additionally, if the platform takes a share of the revenue, this report includes the platform_payout_amount field, which indicates the platform’s earnings portion.
Unlike the merchant reports, which center on individual merchant transactions, the platform report consolidates payout details for all merchants under the platform’s management.
Each CSV Report contains two reports by default: Payout Transaction report and Payout report. A Transaction report is also available on request.
Settlement Delays
Settlement delays vary by merchant (e.g., T+3 means a Monday transaction is settled on Thursday).
10-Character Unique IDs
All 10-character IDs provided by Forage are guaranteed to be unique within their respective fields.
This means that, for example, every
order_idwill be unique within the list of order IDs. However, these IDs are not globally unique across different fields; the same 10-character sequence might also be used as amerchant_id,payment_id, or in another field.
Payout Transaction report
- Purpose: A detailed breakdown of every individual payout transaction.
- Content: Includes granular details such as unique transaction IDs, amounts, fees, timestamps, and other relevant data points, allowing a complete audit trail.
- Use Cases: Designed for merchants who need to reconcile individual transactions and verify the accuracy of each payout.
Payout Transaction Report fields
Here are the fields used in the PayoutTransaction report:
| Field | Description | Sample |
|---|---|---|
merchant_id | A 10-character unique hash identifying the merchant associated with this transaction. | gxe37pc24y |
fns_id | The FNS number of the merchant that received the payout including this transaction. | 9900099 |
recorded_date | The date and time of the transaction, formatted as an ISO 8601 string in the UTC timezone. | 2023-12-28T00:08:38.890Z |
payout_issued_date | The timestamp of when the payout was created. (Value only populated for Payout Transaction Reports) | 1/3/2024 |
expected_deposit_date | A timestamp of when Forage expects the payout to be deposited. This is typically the payout_issued_date plus one business day, if the ACH method is next-day. | 1/4/2024 |
payment_method | The unique reference hash for the existing Forage PaymentMethod that is to be charged in this transaction. | SNAP |
transaction_type | The type of the transaction. Must be one of the following: - Purchase- Purchase_With_Cash_Back- Refund- Withdrawal- Chargeback- Void_Purchase- Void_Refund- Negative_adjustment- Positive_adjustment- Balance_Inquiry_Fee- Refund_Processing_Fee | Purchase |
transaction_amount | The total amount in USD charged, voided, or refunded to the customer. | 126.05 |
forage_fee | The amount of Forage fees applied to the transaction. | 3.96 |
merchant_net_settlement | The net amount sent to the merchant, equal to the sum of purchases minus refunds, chargebacks, fees, and any other deductions. This value is blank if the settlement reflects a platform instead of a merchant payout. | 122.09 |
platform_net_settlement | The net amount sent to the platform, if applicable, equal to the sum of purchases minus refunds, chargebacks, fees, and any other deductions. This value is blank if the settlement reflects a merchant payout and no platform was involved. | 0.00 |
order_id | A 10-character unique hash identifying the order for Fully Hosted and Custom integrations. Blank for SDK integrations. | a9a7226jm8 |
external_order_id | A unique, merchant or platform-provided identifier for the order that corresponds to their own database, as provided in the original request to create the Payment. Only one external_order_id can be passed as a query param at a time.You must build with Forage Version 2023-05-15 or later to use external_order_id. Either pass 2023-05-15 as the API-Version header on a per request basis, or set the version for all requests in the Forage dashboard. | (Platform-defined ID) |
payment_id | A 10-character unique hash identifying the related Payment or OrderPayment. | mn0yo1orjw |
refund_id | A 10-character unique hash identifying the related Refund or OrderRefund. | 56us47lbpo |
chargeback_id | A 10-character unique hash identifying the chargeback transaction. Present only when transaction_type is Chargeback. | luw8sozitr |
merchant_payout_id | A 10-character unique hash identifying the merchant payout. Present only in Payout Transaction Reports. | jakqbi64tv |
platform_payout_id | A 10-character unique hash identifying the platform payout. Present only if the transaction is part of a platform payout, and only in Payout Transaction Reports. | atn1ulwziv |
merchant_destination_account_ref | A 10-character unique hash for the merchant's destination bank account. Blank if settled to a platform account. | c45b20e98a |
external_location_id | A unique identifier, provided by the merchant or platform (not Forage), that indicates the physical fulfillment location for the order. For example, this field could specify which location of a grocery store chain fulfilled an order. | (Platform-defined description) |
description | A text field supplied by the merchant or platform (not Forage) that can be used for descriptive purposes. | (User-defined description) |
corporation_ref | A 10-character unique hash referencing the corporation linked to the onboarding merchant. A corporation is the umbrella legal entity that the merchant is nested under. If no corporation is provided in the request, Forage creates one and returns the reference. | tp43855aag |
merchant_group_ref | A 10-character unique hash referencing the merchant group associated with the merchant. A merchant group is a collection of merchant IDs. If no merchant_group is provided in the request, Forage creates one and returns the reference. | o73bnhm6pn |
Payout Report
- Purpose: To provide an aggregated view of all payout transactions over a specified period. This should match the settlement amount for the reported day.
- Content: Summarizes key figures, including total payout amounts, overall fees, and net values, making it easier to understand the financial performance quickly.
- Use Cases: Ideal for getting a bird’s-eye view of payout trends, aiding in high-level reconciliation, and financial reporting.
Payout Report fields
Here are the fields used in the Payout Report:
| Field | Description | Sample |
|---|---|---|
merchant_payout_id | A 10-character unique hash identifying the merchant payout. Present only in Payout Transaction Reports. | jakqbi64tv |
platform_payout_id | A 10-character unique hash identifying the platform payout. Present only if the transaction is part of a platform payout, and only in Payout Transaction Reports. | atn1ulwziv |
merchant_id | A 10-character unique hash identifying the merchant associated with this transaction. | gxe37pc24y |
fns_id | The FNS number of the merchant that received the payout including this transaction. | 9900099 |
payout_issued_date | The timestamp of when the payout was created. (Value only populated for Payout Transaction Reports) | 1/3/2024 |
expected_deposit_date | A timestamp of when Forage expects the payout to be deposited. This is typically the payout_issued_date plus one business day, if the ACH method is next-day. | 1/4/2024 |
total_purchases | The total amount in USD of all of the purchases included in this payout. | 180.98 |
total_refunds | The total amount in USD of all of the refunds included in this payout. | 0.00 |
total_void_purchases | The total amount in USD refunded to customers due to a voided purchase initiated by Forage or the server. | 1.12 |
total_void_refunds | The total amount in USD debited from customers due to a voided refund initiated by Forage or the server. | 0.22 |
total_chargebacks | The total amount in USD of refunds paid to customers as the result of dispute resolutions during this payout period. The total_chargebacks value is distinct and not included in the total_refunds value. | 0.00 |
total_positive_adjustment | If any, the total arbitrary amount in USD that has been added to the settlement. For example, this could happen in the rare case that Forage corrects a previous settlement. | 0.00 |
total_negative_adjustments | If any, the total arbitrary amount in USD that has been deducted from the settlement. For example, this could happen in the rare case that Forage corrects a previous settlement. | 0.00 |
forage_fee | The amount of Forage fees applied to the transaction. | 3.96 |
merchant_net_settlement | The net amount sent to the merchant, equal to the sum of purchases minus refunds, chargebacks, fees, and any other deductions. This value is blank if the settlement reflects a platform instead of a merchant payout. | 122.09 |
platform_net_settlement | The net amount sent to the platform, if applicable, equal to the sum of purchases minus refunds, chargebacks, fees, and any other deductions. This value is blank if the settlement reflects a merchant payout and no platform was involved. | 0.00 |
merchant_destination_account_ref | A 10-character unique hash for the merchant's destination bank account. Blank if settled to a platform account. | c45b20e98a |
Transaction Report (on request)
A Transaction Report provides a comprehensive record of all financial operations from the previous day that involved a flow of funds—even those not included in a payout. This report delivers granular data across multiple transaction types, serving as a robust audit trail.
Enabling Transaction Reports
Please reach out to your Forage contact if you'd like to include a Transaction Report in your SFTP report.
- Purpose: To present a complete snapshot of all fund movements from the previous day, regardless of their inclusion in a payout.
- Content: Includes detailed fields such as merchant and FNS IDs, recorded dates, payment methods, transaction amounts, unique identifiers (for orders, payments, refunds, and chargebacks), and additional metadata.
- Use Cases: Ideal for reconciling your accounting records with the Forage ledger, ensuring accuracy in financial tracking, and verifying that every transaction is properly accounted for.
Transaction Report fields
Here are the fields used in the Transaction Report:
| Field | Description | Sample |
|---|---|---|
merchant_id | A 10-character unique hash identifying the merchant associated with this transaction. | gxe37pc24y |
fns_id | The FNS number of the merchant that received the payout including this transaction. | 9900099 |
recorded_date | The date and time of the transaction, formatted as an ISO 8601 string in the UTC timezone. | 2023-12-28T00:08:38.890Z |
payment_method | The unique reference hash for the existing Forage PaymentMethod that is to be charged in this transaction. | SNAP |
transaction_type | The type of the transaction. Must be one of the following: - Purchase- Purchase_With_Cash_Back- Refund- Withdrawal- Chargeback- Void_Purchase- Void_Refund- Negative_adjustment- Positive_adjustment- Balance_Inquiry_Fee- Refund_Processing_Fee | Purchase |
transaction_amount | The total amount in USD charged, voided, or refunded to the customer. | 126.05 |
merchant_net_settlement | The net amount sent to the merchant, equal to the sum of purchases minus refunds, chargebacks, fees, and any other deductions. This value is blank if the settlement reflects a platform instead of a merchant payout. | 122.09 |
platform_net_settlement | The net amount sent to the platform, if applicable, equal to the sum of purchases minus refunds, chargebacks, fees, and any other deductions. This value is blank if the settlement reflects a merchant payout and no platform was involved. | 0.00 |
order_id | A 10-character unique hash identifying the order for Fully Hosted and Custom integrations. Blank for SDK integrations. | a9a7226jm8 |
external_order_id | A unique, merchant or platform-provided identifier for the order that corresponds to their own database, as provided in the original request to create the Payment.Only one external_order_id can be passed as a query param at a time.You must build with Forage Version 2023-05-15 or later to use external_order_id. Either pass 2023-05-15 as the API-Version header on a per request basis, or set the version for all requests in the Forage dashboard. | (Platform-defined external order ID) |
payment_id | A 10-character unique hash identifying the related Payment or OrderPayment. | mn0yo1orjw |
refund_id | A 10-character unique hash identifying the related Refund or OrderRefund. | 56us47lbpo |
chargeback_id | A 10-character unique hash identifying the chargeback transaction. Present only when transaction_type is Chargeback. | luw8sozitr |
merchant_destination_account_ref | A 10-character unique hash for the merchant's destination bank account. Blank if settled to a platform account. | c45b20e98a |
external_location_id | A unique identifier, provided by the merchant or platform (not Forage), that indicates the physical fulfillment location for the order. For example, this field could specify which location of a grocery store chain fulfilled an order. | (Platform-defined external location id) |
description | (Platform-defined description) | (User-defined description) |
corporation_ref | A 10-character unique hash referencing the corporation linked to the onboarding merchant. A corporation is the umbrella legal entity that the merchant is nested under. If no corporation is provided in the request, Forage creates one and returns the reference. | tp43855aag |
merchant_group_ref | A 10-character unique hash referencing the merchant group associated with the merchant. A merchant group is a collection of merchant IDs. If no merchant_group is provided in the request, Forage creates one and returns the reference. | o73bnhm6pn |
forage_fee | The amount of Forage fees applied to the transaction. | 3.96 |
File Naming Conventions
Each report follows a structured filename format, with specific elements indicating the type, timing, and versioning details.
- Payout Report:
YYYYMMDDHHMM_AAA_BBB_Platform_Forage_Payout.csv - Payout Transaction Report:
YYYYMMDDHHMM_AAA_BBB_Platform_Forage_PayoutTransaction.csv
Understanding the Filename Components
Here's how report filenames are structured for CSV reports on the SFTP server.
| Component | Description |
|---|---|
| YYYYMMDDHHMM | The UTC timestamp when the report was generated. In case of a revision, the original timestamp is retained. HHMM can be 0000 or randomized. |
| AAA | The attempt number for file generation starts at 001 and is incremented for each correction. |
| BBB | The file format's version number starts at 01 and increments for each new specification. |
| Merchant | Represents the recipient type (merchant, merchant group, or corporation). The merchant name is sanitized (special characters removed, camel-cased). |
| Platform | The name of the e-commerce platform the merchant operates on. If a merchant sells through a third-party platform, the name of that platform appears here. If the merchant uses its own system, the platform is the same as the merchant's name. |
Sample CSV Report
Here's a sample CSV file for a Generic Platform CSV Report.
Transaction Types
Sample reports showcase examples of every transaction type. However, you might not require all transaction types in your custom reports.
- Sample: Platform-Report-Sample.zip
Updated about 17 hours ago