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.

{
  "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)

{
  "merchantId": "merchant_abc123",
  "amount": 100.00,
  "currency": "USDC",
  "consumerFeeAmount": 3.00,
  "splitConfiguration": {
    "destinationAccountId": "acct_partner_xyz"
  }
}

Response

{
  "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.