SurchargeResult
A model the API reference uses in a request or a response. The operation pages link every field typed as this model here.
The surcharge decision recorded on a transaction: whether a surcharge was applied, the reason when it was not, the amounts and rates used, and the outcome of each evaluation stage.
Values
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
Fields
| Field | Type | Description |
|---|---|---|
surcharged
required |
boolean | Whether this transaction was surcharged.
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
ineligibilityReason
required |
string | Stable string reason code (e.g. `nameof(SurchargeIneligibilityReason.DebitCard)`) for why
the transaction was not surcharged; `null` when `surcharged` is true.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
baseAmount
required |
number (double) | The transaction base amount the surcharge rate was applied against, in the transaction currency.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
baseComponents
required |
string | Which amount components formed `baseAmount`: `Base` (the base amount alone,
the default) or `Base+Shipping` (the merchant elected a shipping-inclusive surcharge base).
`null` on a decision recorded before the component was captured, which was
always the base amount alone.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
surchargeAmount
required |
number (double) | The computed surcharge amount, in the transaction currency; null when not surcharged.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
appliedRate
required |
number (double) | The rate actually applied, as a decimal fraction (0.03 = 3%): the lesser of `merchantRate`
and the caps below.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
merchantRate
required |
number (double) | The merchant-configured surcharge rate at evaluation time, as a decimal fraction (0.03 = 3%).
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
networkCap
required |
number (double) | The card network's rate cap at evaluation time, as a decimal fraction, if applicable.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
stateCap
required |
number (double) | The governing state's rate cap at evaluation time, as a decimal fraction, if applicable.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
costOfAcceptanceCap
required |
number (double) | The merchant's cost-of-acceptance rate cap at evaluation time, as a decimal fraction, if applicable.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
winningCapSource
required |
string | Which of `merchantRate`/`networkCap`/`stateCap`/`costOfAcceptanceCap` produced `appliedRate`.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
cardFundingSource
required |
string | The card's funding source at evaluation time (e.g. "Credit", "Debit", "Prepaid").
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
cardBrand
required |
string | The card brand at evaluation time (e.g. "Visa", "Mastercard").
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
billingStateCode
required |
string | The cardholder billing address state code at evaluation time.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
merchantStateCode
required |
string | The merchant's state code at evaluation time.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
governingStateCode
required |
string | The state whose surcharge rules actually governed this evaluation.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
channel
required |
string | The originating channel (e.g. "VirtualTerminal", "HostedPaymentPage", "Api").
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
configurationId
required |
string (uuid) | The surcharge configuration evaluated against.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
configurationVersion
required |
integer (int32) | The version of the surcharge configuration evaluated against, for audit reproducibility.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
requiresDisclosure
required |
boolean | Whether the caller must present a surcharge disclosure to the cardholder.
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
evaluatedAt
required |
string (date-time) | UTC timestamp of when the evaluation was performed.
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
auditTrail
required |
array of SurchargeStageOutcome array of SurchargeStageOutcome | Full per-stage audit trail from the eligibility pipeline, in execution order.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
Fields of each SurchargeStageOutcome: This body has no documented fields. | ||
This model has no documented fields.