Create a fee rule

Create a platform fee rule for a specific transaction type. The rule defines the markup your platform charges customers on top of Lightspark and counterparty fees. Only one rule per transaction type is allowed.

Fee rules are evaluated at quote creation time. The resulting platform fee is included in the quote’s rateDetails and collected in real time during settlement — no manual reconciliation is needed.

Fee types:

• FIXED — a flat amount per transaction (requires fixedFee)
• PERCENTAGE — a rate of the transaction amount (requires variableFeeRate)
• HYBRID — both a fixed amount and a percentage rate (requires both)

POST /fee-rules

cURL

fixedFee

curl --request POST \
  --url https://api.lightspark.com/grid/2025-10-13/fee-rules \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "transactionType": "TRANSFER_OUT",
  "feeType": "FIXED",
  "fixedFee": 150
}
'

201

{
  "id": "FeeRule:019c6a2b-4f8e-7d01-0000-000000000001",
  "transactionType": "CROSS_BORDER_PAYOUT",
  "feeType": "HYBRID",
  "enabled": true,
  "createdAt": "2026-01-15T00:00:00Z",
  "updatedAt": "2026-02-01T12:30:00Z",
  "fixedFee": 150,
  "variableFeeRate": 0.005
}

Authorizations

Authorization · string · header · required

API token authentication using format <api token id>:<api client secret>

Body

application/json

Request body for creating a new platform fee rule.

transactionType · enum<string> · required

The type of transaction the fee rule applies to. Platform fee rules are scoped to a single transaction type — only one rule per type is allowed.

Available options: TRANSFER_IN, TRANSFER_OUT, RAMP_ON, RAMP_OFF, CROSS_BORDER_PAYOUT

Example:

"CROSS_BORDER_PAYOUT"

feeType · enum<string> · required

Determines which fee components apply. FIXED charges a flat amount per transaction. PERCENTAGE charges a rate of the transaction amount. HYBRID applies both a fixed amount and a percentage rate.

Available options: FIXED, PERCENTAGE, HYBRID

Example:

"HYBRID"

fixedFee · integer<int64>

Fixed fee in the smallest unit of USD (cents). Required when feeType is FIXED or HYBRID. Must be between 0 and 10000 ($100.00).

Required range: 0 <= x <= 10000

Example:

150

variableFeeRate · number<double>

Variable fee as a decimal rate (e.g., 0.005 = 0.5%). Required when feeType is PERCENTAGE or HYBRID. Must be between 0 and 0.20 (20%).

Required range: 0 <= x <= 0.2

Example:

0.005

enabled · boolean · default: true

Whether the rule should be active immediately. Defaults to true.

Example:

true

Response

201

application/json

Fee rule created successfully

A platform fee rule defines the markup a platform charges its customers on a specific transaction type, on top of Lightspark and counterparty fees. Rules are evaluated at quote creation and the resulting platform fee is collected in real time during settlement.

id · string · required

System-generated unique identifier

Example:

"FeeRule:019c6a2b-4f8e-7d01-0000-000000000001"

transactionType · enum<string> · required

The type of transaction the fee rule applies to. Platform fee rules are scoped to a single transaction type — only one rule per type is allowed.

Available options: TRANSFER_IN, TRANSFER_OUT, RAMP_ON, RAMP_OFF, CROSS_BORDER_PAYOUT

Example:

"CROSS_BORDER_PAYOUT"

feeType · enum<string> · required

Determines which fee components apply. FIXED charges a flat amount per transaction. PERCENTAGE charges a rate of the transaction amount. HYBRID applies both a fixed amount and a percentage rate.

Available options: FIXED, PERCENTAGE, HYBRID

Example:

"HYBRID"

enabled · boolean · required

Whether this fee rule is actively applied to new transactions. Disabled rules are retained for reporting but do not affect new quotes.

Example:

true

createdAt · string<date-time> · required

When the fee rule was created

Example:

"2026-01-15T00:00:00Z"

updatedAt · string<date-time> · required

When the fee rule was last modified

Example:

"2026-02-01T12:30:00Z"

fixedFee · integer<int64>

Fixed fee in the smallest unit of USD (cents). Applied per transaction. Required when feeType is FIXED or HYBRID.

Required range: x >= 0

Example:

150

variableFeeRate · number<double>

Variable fee as a decimal rate of the transaction amount (e.g., 0.005 = 0.5%). Applied to the sending amount at quote creation. Required when feeType is PERCENTAGE or HYBRID.

Required range: 0 <= x <= 0.2

Example:

0.005