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.
GET /partners/{partnerId}/reports/split-funding-transactions
GET /partners/{partnerId}/reports/split-funding-transactions/csvQuery parameters
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
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 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.
Split funding distribution summary
Reconciliation by merchant and MID, and the authoritative view of what a partner is owed and what was paid.
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.
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:
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 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.
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.
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.
What to reconcile, and when
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 and Residual Reporting for settlement-level fee data, which is not the source of truth for a partner distribution
Payment history for standard reporting
Last updated