> 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/upcoming-changes/consumer-fee-control-and-exact-net-settlement.md). # Consumer Fee Control and Exact Net Settlement > **Upcoming — Not Yet Available** The fields and behaviors described on this page do not exist in the API yet. Do not attempt to use them in production or sandbox environments. **Target:** Q3 2026. Development begins end of July 2026 with an estimated 4 to 6 week build cycle. ### What This Feature Does Partners will be able to pass a consumer fee amount directly with each payment request. Merchants can be configured to receive exactly the amount they invoiced and their settlement will not be reduced by processing costs. The consumer fee is collected from the consumer at checkout and routed to a separate destination account specified by the partner. This gives partners precise control over how fees are presented to consumers and how settlement flows to merchants. ### When to Use This Feature **Exact merchant settlement** The merchant receives precisely the amount they invoiced. Processing costs are covered by the consumer fee rather than deducted from the merchant payout. **Consumer fee routing** The consumer fee amount, after processing costs, is routed to a separate partner controlled destination account rather than netting out against merchant settlement. **Dynamic fee amounts** The fee amount varies per transaction (for example, based on cart total, merchant tier, or product type). Rather than a fixed platform fee, the partner calculates and passes the exact fee at payment time. **Transparent consumer facing pricing** The consumer sees a clear line item fee at checkout. The fee is passed through exactly as shown with no rounding and no blending with the base amount. ### New Fields on POST /Payments/crypto Three new optional fields will be added to the payment request body. All existing fields remain unchanged. | Field | Type | Required | Description | | ----------------------- | ------- | -------- | --------------------------------------------------------------------------------------------------------------------------------- | | `consumerFeeAmount` | decimal | No | The fee amount collected from the consumer, expressed in the payment currency. Use when specifying an exact fee value. | | `consumerFeePercentage` | decimal | No | The fee expressed as a percentage of the payment total. Use when the fee should be calculated as a proportion of the base amount. | | `splitConfiguration` | object | No | Defines how the consumer fee is split and routed after processing costs. See Split Configuration below. | > `consumerFeeAmount` and `consumerFeePercentage` are mutually exclusive. Only one should be provided per request. Full validation rules will be published when the feature reaches test availability. #### Split Configuration The `splitConfiguration` object controls where the consumer fee is routed after processing costs are deducted. | Field | Type | Description | | ---------------------- | ------ | ------------------------------------------------------------------------- | | `destinationAccountId` | string | The account ID that receives the net consumer fee after processing costs. | > Full `splitConfiguration` schema will be finalized and documented prior to test availability. ### Settlement Models Three settlement models will be supported. The model is configured at the partner or merchant level, not per transaction. | Model | Description | | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `StandardProcessing` | Default. Processing fees are deducted from merchant settlement. No change from current behavior. | | `ExactNetSettlement` | Merchant receives exactly the invoiced amount. The consumer fee passed in the request covers processing costs. Requires `consumerFeeAmount` or `consumerFeePercentage` to be provided. | | `ConsumerFee` | Partner specifies the consumer fee amount at payment time. After processing costs are deducted, the net fee amount is routed to the destination account specified in `splitConfiguration`. | > On model naming: The API model identifier may differ from the display name used in documentation. Where a mismatch exists, this page will note both values and describe the behavior using the plain English name. ### Example Flow The following illustrates how a $100 payment with a $3 consumer fee is handled under the `ExactNetSettlement` model. | Party | Amount | Notes | | --------------------------- | ------- | ------------------------------ | | Consumer pays | $103.00 | Base amount plus consumer fee | | Merchant receives | $100.00 | Exact invoiced amount | | Processing costs | \~$2.50 | Deducted from the consumer fee | | Net consumer fee to partner | \~$0.50 | Routes to destination account | The merchant always receives $100.00 regardless of processing cost fluctuations. ### Updated Payment Response: feeBreakdown A new `feeBreakdown` field will be added to the payment response to provide a clear breakdown of how the consumer fee was applied. ```json { "paymentId": "...", "status": "Completed", "amount": 100.00, "feeBreakdown": { "consumerFeeAmount": 3.00, "processingCost": 2.50, "netFeeRouted": 0.50, "destinationAccountId": "acct_..." } } ``` > Exact field names and structure are subject to change before release. ### API Reference Preview #### Request (POST /Payments/crypto) ```json { "merchantId": "merchant_abc123", "amount": 100.00, "currency": "USDC", "consumerFeeAmount": 3.00, "splitConfiguration": { "destinationAccountId": "acct_partner_xyz" } } ``` #### Response ```json { "paymentId": "pay_9876xyz", "status": "Pending", "amount": 100.00, "consumerFeeAmount": 3.00, "feeBreakdown": { "consumerFeeAmount": 3.00, "processingCost": 2.50, "netFeeRouted": 0.50, "destinationAccountId": "acct_partner_xyz" }, "createdAt": "2026-09-01T14:22:00Z" } ``` ### Backward Compatibility This feature is fully backward compatible. * All new fields are optional * Existing integrations require no changes * Default settlement behavior (StandardProcessing) is unchanged * No new required fields on any existing endpoints * No changes to authentication, webhooks, or error response formats Partners not using `consumerFeeAmount`, `consumerFeePercentage`, or `splitConfiguration` will see no difference in behavior. ### Questions and Early Access Reach out to your Bead integration contact if you have questions about this feature or want to request early access to the test environment. --- # 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 dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://developers.bead.xyz/upcoming-changes/consumer-fee-control-and-exact-net-settlement.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.