Merchant (Charging to Platform) CSV Report
CSV report for merchants where the platform pays Forage fees. Includes payout transactions and summaries for easy reconciliation and settlement tracking.
This report is provided to merchants operating on a platform. The platform is responsible for Forage's fees, so the merchant report doesn't include them. This allows merchants to see only relevant transaction and payout details.
Each CSV Report contains two reports by default: Payout Transaction report and Payout report. A Transaction report is also available on request.
See below for details on each.
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
The Payout Transaction report provides an aggregated overview of payout transactions, summarizing key figures like total payout amounts, fees, and net values to offer a quick snapshot of financial performance and support high-level reconciliation.
- Purpose: A detailed breakdown of every transaction as part of the payout.
- 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 Payout 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 |
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 |
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 |
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 |
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
The Payout Report provides an aggregated overview of payout transactions, summarizing key figures like total payout amounts, fees, and net values to offer a quick snapshot of financial performance and support high-level reconciliation.
- 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 |
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 |
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 |
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_Merchant_Platform_Forage_Payout.csv - Payout Transaction Report:
YYYYMMDDHHMM_AAA_BBB_Merchant_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 Merchant (Charging to Platform) Settlement Report.
Transaction Types
Sample reports showcase examples of every transaction type. However, you might not require all transaction types in your custom reports.
Updated about 17 hours ago