FlintflintDocs

Processing Fees

Flint charges one fee to process a payment: the processing fee. It is the complete price, calculated from a percentage of the payment plus a fixed amount. It is not a processor's cost with a Flint margin stacked on top, so there is no second fee to look up, reconcile, or subtract.

Two fields carry it. processing_fee_money on the payment is the non-negative fee for that payment once it is final. An explicitly zero-priced rule reports zero. fee_money on the corresponding balance transaction is the same fee as it hits your balance, carried as a negative number because it reduces the balance.

What You Net#

The arithmetic is the same everywhere, always in the payment's own currency:

text
processing fee = captured_money * rate percentage + fixed amount
net            = captured_money - processing_fee_money

The percentage applies to the amount you actually captured or collected, and the fixed amount applies once per payment, never once per capture or per line item.

Bash
curl https://api.withflintpay.com/v1/payment-intents/pi_1kmn0aExample \
  -H "Authorization: Bearer YOUR_API_KEY"
JSON
{
  "data": {
    "payment_intent_id": "pi_1kmn0aExample",
    "status": "succeeded",
    "amount_money": { "amount": 5000, "currency": "USD" },
    "captured_money": { "amount": 5000, "currency": "USD" },
    "processing_fee_money": { "amount": 175, "currency": "USD" }
  }
}

That payment collected $50.00 and cost $1.75 to process, so you netted $48.25. Read the fee from the payment rather than recomputing it from your rates: it is the amount actually charged, already rounded half-up to the minor unit, and it reflects the pricing that was locked in when the payment was processed.

processing_fee_money is absent until the fee is final, so treat a missing field as "not charged yet" rather than as a zero fee. A deliberate zero is possible if your schedule prices a rule at zero, and it comes back as an explicit {"amount": 0}.

When the Fee Becomes Final#

The fee is decided before Flint contacts the processor and becomes final at exactly one moment per payment method:

  • Card payments: at capture. With automatic capture that is when the payment succeeds. With manual capture it is when you capture, and the percentage applies to the amount you actually captured, so a partial capture is charged on the partial amount.
  • ACH debit: when the payment succeeds. ACH takes days to clear, so processing_fee_money is not final on the day you confirm. See ACH Debit Payments.

Payments that never reach that moment are never charged. An authorization you let expire, a payment you cancel before capture, and a card that declines all have no final processing fee.

Because the fee follows capture rather than authorization, poll or listen for the payment reaching succeeded before recording the fee. An authorized-but-uncaptured payment has no processing_fee_money at all.

When Pricing Rejects a Payment#

Flint prices a payment before it reaches the processor, and it never falls back to a nearby rate or quietly drops the fee to zero. If no authorized price covers the payment, the request fails and nothing is submitted:

  • PROCESSING_FEE_PRICING_NOT_AUTHORIZED (400) means no rule covers this payment. Either nothing matches its product, feature, payment option, and currency, or the amount is below the matching rule's minimum_payment_money. Retrying the same amount will not help.
  • PROCESSING_FEE_PRICING_UNAVAILABLE (503) means Flint could not resolve pricing right now. Retry the same logical request with the same idempotency key.

The trap worth planning for is the minimum on a partial capture. The minimum applies to the amount being priced, so authorizing $50.00 and then capturing $0.40 against a rule with a $0.50 minimum fails at capture, with the authorization already placed. If you capture variable amounts, read the minimum first and either capture at or above it or cancel the authorization instead.

The same floor applies at confirmation, so a payment below the minimum is rejected before the buyer is charged.

Refunds Do Not Return the Fee#

Refunding a payment returns the buyer's money. It does not return or recalculate the processing fee Flint already charged on the original payment, and it does not add a new one.

A $50.00 payment that cost $1.75 to process and is then fully refunded leaves you at negative $1.75 on that order: you are out the fee, not the principal. Partial refunds work the same way, with the original fee untouched.

Disputes and ACH returns behave the same. Each one posts its own balance movement for the principal, and none of them revises the original payment's fee. Flint charges no separate refund, dispute, return, or ACH return fee.

Reading Fees on Your Balance#

Every payment that moves your balance produces a balance transaction, and it carries the same fee as a signed amount:

  • amount_money: the gross movement.
  • fee_money: the Flint fee on that movement, negative because it reduces your balance.
  • net_money: the actual effect on your balance.

Because fee_money is already signed, the three add up rather than subtract:

text
net_money = amount_money + fee_money
5000 gross + (-175) fee = 4825 net

That is the same $1.75 the payment reports as processing_fee_money, with the sign flipped to match the direction of the movement. Refund, dispute, return, and standard payout transactions carry no Flint fee, so their fee_money is 0.

Sum net_money over a period to get what actually reached your balance. Do not subtract fee_money from net_money: it is already accounted for, and subtracting a negative would add the fee back instead of removing it. See Money & Currency and the Money Movement API Reference.

Confirming Your Rates#

Your authorized pricing is readable on effective settings. It is on GET /v1/settings/effective, not on the raw GET /v1/settings:

Published plan pricing is maintained on the Flint pricing page. The response below demonstrates the API shape only. Its example numbers are not Flint's published rates. Your effective settings report the schedule actually assigned to your merchant environment.

Bash
curl https://api.withflintpay.com/v1/settings/effective \
  -H "Authorization: Bearer YOUR_API_KEY"
JSON
{
  "data": {
    "effective_processing_pricing": {
      "schedule_version": "example-only",
      "agreement_version": "example-only",
      "effective_at": "2026-03-17T14:30:00Z",
      "rules": [
        {
          "product": "payments",
          "feature": "api",
          "payment_option": "card",
          "currency": "USD",
          "percentage": 1.23,
          "flat_money": { "amount": 45, "currency": "USD" },
          "minimum_payment_money": { "amount": 50, "currency": "USD" }
        },
        {
          "product": "payments",
          "feature": "checkout",
          "payment_option": "ach_debit",
          "currency": "USD",
          "percentage": 0.45,
          "flat_money": { "amount": 12, "currency": "USD" },
          "minimum_payment_money": { "amount": 50, "currency": "USD" }
        }
      ]
    }
  }
}

Each rule is an exact selector on four fields:

  • product: the Flint product being priced. Payment processing rules use payments.
  • feature: where the payment originated, one of api, checkout, payment_link, subscription, or virtual_terminal. This is the selector most people miss: the same card can be priced differently depending on whether it came through a payment link or a direct API confirm, so match on the origin your integration actually uses.
  • payment_option: card, apple_pay, google_pay, ach_debit, and so on.
  • currency.

percentage and flat_money give the price. percentage is in percent units, so 1.23 means 1.23%, not 123% and not 0.0123%. minimum_payment_money is the smallest amount the rule will price, and it is a rejection boundary rather than a surcharge: see When Pricing Rejects a Payment.

Matching is exact and rules never stack or fall back to a nearby rate. A payment is priced by the one rule that matches it on all four selectors, and a payment with no match is rejected rather than priced at zero.

effective_processing_pricing is read-only. Pricing is set for your merchant environment and cannot be changed through the API, so treat it as something to verify (particularly before going live) rather than something to configure. Test and live modes are priced independently; test-mode rates are fixtures and are not your live pricing.

What This Fee Is Not#

  • Not a processor passthrough. Flint never exposes a separate processor or network cost as a deduction from your payment. What Flint pays its providers is Flint's cost, not a line on your payment.
  • Not the buyer-facing charges you set. Delivery, service, and convenience charges you add to an order increase what the buyer pays and are part of the payment amount. They are not processing fees. See Tips & Fees.
  • Not a subscription's plan fees. setup_fee_money and early_termination_fee_money on a subscription plan are prices you charge your customer. See Subscription Billing.
Rate this doc