> For the complete documentation index, see [llms.txt](https://developers.bead.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.bead.xyz/split-funding/reports.md). # Split Funding Reports Reporting for partners using the Split Funding Program. These endpoints are partner-scoped only. There is no merchant or terminal scope, since the partner portion is withheld and distributed at the partner level. Use Split Funding Reports when you need to: * See the partner portion on individual payments. * Reconcile a partner distribution by merchant and MID. * See Bead's fee and partner net for a period. * Confirm enrollment and split funding versus regular payment volume for a merchant. For everything else about how the program works, the three amounts, the locked identity, the coverage check at payment creation, enrollment, and settlement behavior, see Split Funding Program. > **These reports are the only place the amounts and Bead's fee are readable after payment creation.** Nothing is echoed back on the payment creation response, the payment status endpoints, or payment tracking. ### Split funding transactions One row per split funding payment. ```http GET /partners/{partnerId}/reports/split-funding-transactions GET /partners/{partnerId}/reports/split-funding-transactions/csv ``` #### Query parameters | Parameter | Type | Description | | --------------- | ------- | ------------------------------------------------------------------ | | `From` | date | Start of the date range filter. | | `To` | date | End of the date range filter. | | `Status` | string | Filter by payment status. | | `MerchantId` | string | Filter to a single merchant. | | `Page` | integer | Page number. | | `PageSize` | integer | Results per page. | | `SortBy` | string | Field to sort by. Not every response field is accepted, see below. | | `SortDirection` | string | Sort direction: `asc` or `desc`. | **Sorting.** `SortBy` accepts a narrower set than the response field list. `splitFundingFee`, `partnerNet`, `settlementId` and `merchantId` are not sortable on this report. `amount` is accepted as an alias for `total`, and `SortBy` matching is case insensitive. #### Response fields | Field | Description | | ----------------- | --------------------------------------------------------------------------------------------------- | | `id` | Payment identifier. | | `activityDate` | Date of the payment. | | `paymentCode` | Payment reference code. | | `status` | Payment status. Includes refund status for tenders where refunds are supported. See the note below. | | `total` | What the consumer paid. | | `partnerPortion` | The amount withheld for the partner. | | `merchantPortion` | Amount settled to the merchant. | | `splitFundingFee` | Bead's per-payment fee on this payment. Nullable, see below. | | `partnerNet` | What remains of the partner portion after the fee. Nullable, see below. | | `batchId` | Batch the payment was grouped into. | | `settlementId` | Settlement the payment belongs to. | | `merchantId` | Merchant the payment belongs to. | | `merchantName` | Merchant display name. | **`status` on this report is the payment's `PaymentStatus`, not a distribution status.** The two are different objects with different value sets, and the distribution statuses described in [Distribution status values](/introduction.md#distribution-status-values) never appear in this column. Do not map one onto the other. **`splitFundingFee` and `partnerNet` are nullable, and a null is meaningful.** `splitFundingFee` is null when no rate resolves for that payment's tender, which is the same condition that defers the payment at distribution assessment. `partnerNet` is null whenever `splitFundingFee` is null, because it cannot be derived without the fee. Treat a null in either column as a missing rate to chase with your Bead contact rather than as a fault in the report. #### CSV export The CSV variant additionally accepts `IncludeHeader`, `IncludeTotals`, `Columns`, and `Separator`. `Columns` is a CSV only parameter. The JSON endpoints always return the full row and cannot be narrowed. **The CSV is not the JSON row.** It carries neither `id` nor `merchantId`, and it splits `activityDate` into separate `Date` and `Time` columns. Map the two shapes separately rather than assuming one parser covers both. Downloaded files are named `bead-report_split-funding-transactions_...`, matching the route path. **Refund handling (reserved):** no Bead tender currently supports a refund, so this does not come up in practice today. When a tender that supports refunds is added, refunded and partially refunded payments will be visible here and flagged by `status`. This report is where you will see which payments were excluded from a distribution, since that exclusion happens at the payment level, not at the settlement level. See the caution in [Residual Reporting](/settlement/residual-reporting.md). ### Split funding distribution summary Reconciliation by merchant and MID, and the authoritative view of what a partner is owed and what was paid. ```http GET /partners/{partnerId}/reports/split-funding-distribution-summary GET /partners/{partnerId}/reports/split-funding-distribution-summary/period-summary GET /partners/{partnerId}/reports/split-funding-distribution-summary/account-summary GET /partners/{partnerId}/reports/split-funding-distribution-summary/csv ``` > **This is where the deposit fee becomes visible.** Bead's per-payment fee is checked when a payment is created, but the settlement fees are charged per settlement event and cannot be evaluated per payment. They are applied at distribution assessment and appear here as `depositFee`. Reconcile against this report rather than against per-payment arithmetic. #### Base report `GET /partners/{partnerId}/reports/split-funding-distribution-summary` returns per merchant and MID totals. | Parameter | Type | Description | | --------------- | ------- | -------------------------------------------------------------- | | `From` | date | Start of the date range filter. | | `To` | date | End of the date range filter. | | `MerchantId` | string | Filter to a single merchant. | | `Page` | integer | Page number. | | `PageSize` | integer | Results per page. | | `SortBy` | string | Field to sort by. `merchantId` is not sortable on this report. | | `SortDirection` | string | Sort direction: `asc` or `desc`. | **Sorting.** `merchantId` is not accepted by `SortBy` on this report. `amount` is accepted as an alias for `total`, and `SortBy` matching is case insensitive. Selectable columns, on the base report and the CSV: `period`, `merchantId`, `merchantName`, `paymentCount`, `total`, `partnerPortion`, `merchantPortion`, `splitFundingFee`, `depositFee`, `partnerNet`. The last three columns are the whole reconciliation, so the arithmetic is worth stating plainly: ``` partnerNet = partnerPortion - splitFundingFee - depositFee ``` `splitFundingFee` is Bead's per-payment fee for the period. `depositFee` is the settlement fee recovered from the partner portion. `partnerNet` is what is paid out. **The response has two parts, and the distribution level fields are not on the rows.** Alongside the per merchant and MID rows, this report returns a separate top level `distributions[]` array. Each entry in that array carries `status` and `blockedReason` together with the period totals for the partner portion, Bead's fee and partner net. A merchant or MID row carries neither `status` nor `blockedReason`, so read them from `distributions[]`. See [Distribution status values](/introduction.md#distribution-status-values) for what `status` means, for the `blockedReason` values, and for what to do when a distribution is held. `distributions[]` is on this base report only. `status` and `blockedReason` do not appear on the period summary, do not appear on the account summary, and are not in the CSV, which writes the 10 selectable row columns only. A settlement line can show a negative value where the recovered deposit fee exceeded that line's withheld amount. This is absorbed by the distribution total rather than blocking the line. The CSV variant of this report accepts `Columns`, which the JSON endpoints do not. Downloaded files are named `bead-report_split-funding-distribution-summary_...`, matching the route path. #### Period summary `GET /partners/{partnerId}/reports/split-funding-distribution-summary/period-summary` returns partner portion amounts over time. | Parameter | Type | Description | | ---------- | ------ | -------------------------------- | | `From` | date | Start of the date range filter. | | `To` | date | End of the date range filter. | | `Interval` | string | Bucket size for the time series. | Each row carries the payment count, the partner portion, Bead's fee, and the effective ratio of partner portion to total for that period. #### Account summary `GET /partners/{partnerId}/reports/split-funding-distribution-summary/account-summary` returns enrollment and volume by merchant. | Parameter | Type | Description | | --------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `From` | date | Start of the date range filter. | | `To` | date | End of the date range filter. | | `Status` | string | Filter by payment status, not by distribution status. It selects which payments go into the rollup, before the participation figures are calculated. Accepted values: `created`, `processing`, `completed`, `underpaid`, `overpaid`, `fullyRefunded`, `partiallyRefunded`, `expired`, `invalid`, `cancelled`, `abandoned`. | Each row carries the enrolled merchant count, the split funding payment count, the regular payment count, and the split funding amount per account. The split between split funding and regular payment counts also tells you which settlements were split-funding-only and which were mixed, which determines how the deposit settlement fee was handled for that merchant. See [Settlement behavior](/introduction.md#settlement-behavior). ### What to reconcile, and when | Question | Where to look | | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | | What was withheld on a given payment | Split funding transactions | | What Bead's per-payment fee came to | The `splitFundingFee` column, on either report | | Why a distribution paid less than the sum of withheld amounts | Distribution summary, the `depositFee` column | | Why a distribution was not paid at all | Distribution summary, the `distributions[]` array: `status`, and `blockedReason` for the specific check | | Whether a merchant's day was split-funding-only or mixed | Account summary, split funding count against regular count | **Check the first month's distribution summary against your own expectations, per tender.** The creation-time coverage check protects you from a partner portion that cannot cover its own per-payment fee, but it cannot see the settlement fees. A low-volume merchant carries a larger share of those, so the first distribution is where an undersized consumer fee shows up. ### Authorization All endpoints on this page are callable with a partner API key for that partner's own `partnerId`, or for any partner beneath it in the hierarchy. ### Next steps * Split Funding Program for how the program works and how to enroll a merchant * [Settlements](/settlement/settlements.md) and [Residual Reporting](/settlement/residual-reporting.md) for settlement-level fee data, which is not the source of truth for a partner distribution * [Payment history](/reporting.md) for standard reporting --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://developers.bead.xyz/split-funding/reports.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.