Fees and Total Debit

Quote customer-paid service fees, understand provider-cost recovery, and use total debit fields returned by Payflow client APIs.

Payflow client APIs now return fee snapshots for card and ACH flows. The fee model separates the principal payment amount from the customer debit amount, so your app can display a clear service fee before a customer confirms.

Key fields

Field	Meaning
`amountMinor`	Principal payment or transfer amount in the smallest currency unit.
`platformFeeMinor`	Payflow provider-cost recovery fee for the selected provider/channel.
`organizationFeeMinor`	Organization-configured service fee for the selected provider/channel.
`feeMinor`	Combined service fee: platform fee plus organization fee.
`totalDebitMinor`	Total amount charged or debited from the customer: principal plus fees.
`fee` / `breakdown`	Versioned fee breakdown used to audit how the fee was calculated.

For customer-facing checkout screens, show both the principal amount and service fee. Charge or debit totalDebitMinor, but keep amountMinor as the underlying payment, invoice, or transfer amount in your own records.

Quote fees before preparing payment

Use POST /client/v1/fees/quote when you need to show the fee before creating a payment preparation.

curl -X POST "$PAYFLOW_CLIENT_API_URL/fees/quote" \
  -H "Authorization: Bearer $PAYFLOW_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amountMinor": "2500",
    "currency": "USD",
    "paymentMethod": "web_card",
    "flow": "payment_component",
    "metadata": {
      "cartId": "cart_789"
    }
  }'

The endpoint requires a secret key because it evaluates routing and fee configuration for the application environment.

Response:

{
  "success": true,
  "data": {
    "amountMinor": "2500",
    "currency": "USD",
    "platformFeeMinor": "103",
    "organizationFeeMinor": "50",
    "feeMinor": "153",
    "totalDebitMinor": "2653",
    "breakdown": {
      "version": 1,
      "provider": "stripe",
      "paymentMethod": "web_card",
      "currency": "USD",
      "channel": "none",
      "layers": [
        {
          "scope": "platform",
          "enabled": true,
          "fixedFeeMinor": "30",
          "percentFeeBps": 290,
          "minimumFeeMinor": null,
          "capFeeMinor": null,
          "feeMinor": "103"
        },
        {
          "scope": "organization",
          "enabled": true,
          "fixedFeeMinor": "0",
          "percentFeeBps": 200,
          "minimumFeeMinor": null,
          "capFeeMinor": null,
          "feeMinor": "50"
        }
      ]
    },
    "routing": {
      "provider": "stripe",
      "channel": "web_card",
      "matchedRuleId": null,
      "matchedConditionIds": [],
      "fallback": true
    }
  },
  "message": null
}

Flow selection

For web_card quotes, set flow to:

Flow	Use when
`payment_component`	You will prepare an embedded card component.
`hosted_checkout`	You will create a hosted checkout session.

If omitted, Payflow treats the quote as payment_component.

Payment preparation snapshots

Hosted checkout and payment component preparation responses include the same fee fields returned by the quote endpoint. Quote responses call the versioned detail object breakdown; payment preparation responses expose that same detail as fee. Payflow also stores the fee snapshot with the preparation and resulting transaction, so later provider callbacks and support investigations can reconcile the original amount, fee, and total debit.

For card flows, Stripe or Square is asked to charge totalDebitMinor; the Payflow transaction still records amountMinor as the principal amount.

ACH preview and transfer fees

ACH transfer preview returns fee details under a nested fee object:

{
  "success": true,
  "data": {
    "amountMinor": "12500",
    "currency": "USD",
    "fee": {
      "platformFeeMinor": "25",
      "organizationFeeMinor": "100",
      "feeMinor": "125"
    },
    "totalDebitMinor": "12625"
  },
  "message": null
}

The transfer creation response includes the same values on data.transaction. Always show the previewed fee and total debit before creating the ACH transfer, then reuse the same idempotencyKey if you retry the same business action.

Configuration behavior

Fees are selected by environment, currency, provider, payment method, and channel. Card fees are configured once per provider and shared by hosted checkout and payment component flows. ACH fees can differ by provider and channel, such as Standard ACH, Same Day ACH, or instant/RTP-style rails.