VirtualTerminalConvenienceFeeField
A model the API reference uses in a request or a response. The operation pages link every field typed as this model here.
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 | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
fieldKey
required |
string |
nullableread only
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.
| ||||||||||||
enabled
required |
boolean |
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.
| ||||||||||||
required
required |
boolean |
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.
| ||||||||||||
autoCalculate
required |
boolean |
deprecated
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.
| ||||||||||||
calculationPercentage
required |
number (double) | Legacy: the percentage a configuration written before `mode` existed carried, as a whole
percent (2.5 means 2.5%). Nothing is charged from it; it is kept only so the merchant review
banner can show the old value. Use `percentage`.
nullabledeprecatedmin 0
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.
| ||||||||||||
mode
required |
ConvenienceFeeMode ConvenienceFeeMode | Selects the fee shape. `null` is treated as `Fixed`
for documents written before the discriminated model (see `GetEffectiveMode`).
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.
| ||||||||||||
percentage
required |
number (double) | Whole percent (2.5 means 2.5%). Unlike `attestedCostOfAcceptanceRate`, this is not a
fraction. Send a value greater than 1: a value of 1 or less is read as a fraction and charged
100 times over (0.5 is charged as 50%, 1 as 100%), and is refused when that exceeds the
configured maximum percentage. The percentage of the transaction base applied when `mode` is
`Percentage`. Permitted only when `govEducationAttested` is set; the per-network
applicability guard is applied separately at transaction time.
Required: Conditional (see validator source).
nullablemin 0
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.
| ||||||||||||
govEducationAttested
required |
boolean | Merchant self-declared attestation that it qualifies as a Government or Education entity
under the card-brand Service Fee / Government-Education Convenience Fee program. Must be set
before a `Percentage` fee (and the debit/prepaid exemptions
added by the merchant-config story) can be configured.
Conditional: Conditional (see validator source). Must equal True.
Conditional: When ExemptDebit is true or ExemptPrepaid is true. Must equal 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.
| ||||||||||||
govEducationAttestedBy
required |
string | User who last set `govEducationAttested`. Recorded for audit. Server-owned:
the server stamps it from the authenticated caller, so a value sent by a client is discarded
(`readOnly` on the published schema).
nullableread only
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.
| ||||||||||||
govEducationAttestedOn
required |
string (date-time) | Timestamp `govEducationAttested` was last set. Recorded for audit. Server-owned on
the same terms as `govEducationAttestedBy`.
nullableread only
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.
| ||||||||||||
visaServiceFeeRegistered
required |
boolean | Merchant self-declared record that its account is registered with the acquirer for the Visa
Service Fee program. Distinct from `govEducationAttested`: that attestation is the
merchant's claim to qualify as a Government or Education entity (and gates percentage mode plus
the debit/prepaid exemptions), whereas this records the Visa-specific registration the program
requires on top of qualifying. A Gov/Ed-attested merchant without this registration is
<b>not blocked</b>; the mismatch surfaces as a non-blocking save warning and an inline warning
in the convenience-fee editor, because the registration happens outside the platform and the
operator may be recording it after the fact.
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.
| ||||||||||||
visaServiceFeeRegisteredOn
required |
string (date-time) | The date the acquirer registered this merchant for the Visa Service Fee program, as supplied by
the operator. Required once `visaServiceFeeRegistered` is set; a merchant save
without it is rejected.
This is a <b>calendar date, not an instant</b>: it is the acquirer's registration date, so
it must never be timezone-converted for display. The audit timestamp for when the flag itself
was recorded is `visaServiceFeeRegistrationRecordedOn`, which is a UTC instant.
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.
| ||||||||||||
visaServiceFeeRegistrationRecordedBy
required |
string | User who last set `visaServiceFeeRegistered`. Recorded for audit, mirroring
`govEducationAttestedBy`, and server-owned on the same terms (`readOnly` on
the published schema).
nullableread only
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.
| ||||||||||||
visaServiceFeeRegistrationRecordedOn
required |
string (date-time) | Timestamp `visaServiceFeeRegistered` was last set (UTC). Recorded for audit,
mirroring `govEducationAttestedOn`, and server-owned on the same terms. Distinct
from `visaServiceFeeRegisteredOn`, which is the acquirer's registration date and
stays caller-writable.
nullableread only
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.
| ||||||||||||
attestedCostOfAcceptanceRate
required |
number (double) | Merchant self-declared cost of acceptance, as a decimal fraction of the transaction base
(e.g. `0.025m` = 2.5%). Some jurisdictions (e.g. Georgia, New York) require a convenience
fee to be capped at the merchant's actual cost of acceptance; this rate is the cap basis. At
transaction time the ceiling is `AttestedCostOfAcceptanceRate x base amount`, and the
resolved fee is reduced to it when it exceeds it and the governing state requires the cap
(#3211). Mirrors the surcharge side's
`MerchantSurchargeConfiguration.AttestedCostOfAcceptanceRate` (#1585). Null (or a
non-positive value) means the merchant has not attested a cost of acceptance, so no numeric cap
is applied. Consumed only when the state-override rollout gate
(`ConvenienceFee:EnforceStateOverrides`) is enabled.
nullablemin 0max 1
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.
| ||||||||||||
costOfAcceptanceAttestedBy
required |
string | User who last set `attestedCostOfAcceptanceRate`. Recorded for audit. Server-owned
on the same terms as `govEducationAttestedBy` (`readOnly` on the published
schema).
nullableread only
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.
| ||||||||||||
costOfAcceptanceAttestedOn
required |
string (date-time) | Timestamp `attestedCostOfAcceptanceRate` was last set. Recorded for audit.
Server-owned on the same terms as `costOfAcceptanceAttestedBy`.
nullableread only
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.
| ||||||||||||
exemptDebit
required |
boolean | Stored merchant preference to exempt debit-funded transactions from the convenience fee.
<b>Configuration only: not enforced at payment time yet.</b> No per-transaction
evaluator consumes this flag today; it is persisted and gated here so the runtime
suppression can be wired later (the separate convenience-fee evaluator story) with no
schema change. Until that lands, setting this does not change what a cardholder is charged.
When the evaluator ships it will suppress the fee on debit-funded transactions per the
card-brand rules.
Permitted only under the card-brand Government / Higher-Education service-fee program, so it
is gated behind `govEducationAttested` (enforced by the validator and disabled in
the editor until the attestation is set). Independent of `exemptPrepaid` so a
merchant can exempt debit only, prepaid only, or both. `null` is treated as "not exempt".
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.
| ||||||||||||
exemptPrepaid
required |
boolean | Stored merchant preference to exempt prepaid-funded transactions from the convenience fee.
<b>Configuration only: not enforced at payment time yet</b>, same status as
`exemptDebit`: the consuming per-transaction evaluator is not wired yet, so
setting this does not currently change what is charged. Gated behind
`govEducationAttested` exactly like `exemptDebit`, and independent of
it. `null` is treated as "not exempt".
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.
| ||||||||||||
legacyPercentageNeedsReview
required |
boolean | Set by normalization when a legacy percentage configuration (`AutoCalculate` +
`CalculationPercentage`) was found that cannot be auto-migrated to the
`Percentage` shape (which now requires the attestation).
The merchant must explicitly choose a fixed amount or attest to gov/education registration.
Surfaced as a review banner in the settings UI; never causes a silent percentage migration.
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.
| ||||||||||||
standardChannel
required |
ConvenienceFeePaymentChannel ConvenienceFeePaymentChannel | The merchant's standard (non-alternative) payment channel: the channel the fee-bearing
alternative is an alternative to. Only a `IsStandardEligible`
value forms a valid pairing; an `Online` standard is
treated as internet-only and blocked. `null` means the merchant has not declared it.
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.
| ||||||||||||
alternativeChannel
required |
ConvenienceFeePaymentChannel ConvenienceFeePaymentChannel | The qualifying alternative payment channel the convenience fee is charged on. Must be a
`IsQualifyingAlternative` value and distinct from
`standardChannel`. `null` means the merchant has not declared it.
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.
| ||||||||||||
alternativeChannelAttested
required |
boolean | Merchant self-declared attestation that a genuine alternative payment channel exists for the
cardholder (the card-brand justification for the fee). Distinct from
`govEducationAttested`: that attestation gates the debit/prepaid exemptions and the
percentage option; this one gates the channel justification. A merchant may need both. Required
(with a qualifying channel pairing) before the convenience fee can be enabled: enforced by the
save gate. `null` means the merchant has not attested.
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.
| ||||||||||||
alternativeChannelAttestedBy
required |
string | User who last set `alternativeChannelAttested`. Recorded for audit. Server-owned
on the same terms as `govEducationAttestedBy`: the server stamps it from the
authenticated caller, so a value sent by a client is discarded (`readOnly` on the
published schema).
nullableread only
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.
| ||||||||||||
alternativeChannelAttestedOn
required |
string (date-time) | Timestamp `alternativeChannelAttested` was last set. Recorded for audit.
Server-owned on the same terms as `alternativeChannelAttestedBy`.
nullableread only
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.
| ||||||||||||
offlineChannelExceptionGranted
required |
boolean | Operator-granted exception to the two card-not-present platform proxies, recording that this
merchant genuinely operates a standard payment channel WinkPG cannot observe (typically
payment by cheque or by post). Read through `HasOfflineChannelException`.
This does <b>not</b> replace the channel declaration: the merchant still declares
`standardChannel` / `alternativeChannel` normally (e.g. Check plus
Online) and `alternativeChannelAttested` still applies. The grant asserts that the
declared offline standard channel really exists despite the platform having no evidence of
it.
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.
| ||||||||||||
offlineChannelExceptionGrantedBy
required |
string | User who granted `offlineChannelExceptionGranted`. Server-owned: the server stamps
it from the authenticated caller and keeps the stored value on any save that does not change
the grant, so a client cannot author it.
nullableread only
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.
| ||||||||||||
offlineChannelExceptionGrantedOn
required |
string (date-time) | Timestamp (UTC) `offlineChannelExceptionGranted` was last set. Server-owned on the
same terms as `offlineChannelExceptionGrantedBy`.
nullableread only
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.
| ||||||||||||
offlineChannelExceptionReason
required |
string | The operator's statement of the unobserved channel, for example "Merchant accepts cheques by
post; verified with the reseller on the onboarding call". Required (non-blank) whenever the
grant is set; a merchant save without it is rejected. This is the compliance record of
<em>why</em> the platform proxies were waived, so it is deliberately free text rather than a
picklist.
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.
| ||||||||||||
additionalTenders
required |
array of string array of | The payment types the same fee also applies to besides card, named by their processor payment
type names. Card is always covered, so the list names only the extra tenders; `null` or
empty means card only. Allowed values are `Ach` and `Echeck`, matched ignoring case
and stored in that spelling, each once.
Card-brand rules require a general-program convenience fee to apply to every form of
payment the merchant accepts in the channel. A merchant whose processor profiles accept ACH or
eCheck can enable the fee only when each of those types is listed here, so the same flat fee is
charged on those payments too. A fee that applies to ACH or eCheck must be a fixed amount.
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.
| ||||||||||||
customName
required |
string | Conditional: When CustomName is not null.
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.
| ||||||||||||
customDescription
required |
string | Conditional: When CustomDescription is not null.
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.
| ||||||||||||
readOnly
required |
boolean |
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.
| ||||||||||||
defaultAmount
required |
number (double) | The fixed convenience-fee amount, in the transaction currency, applied when `mode` is
`Fixed`. Also seeds the Virtual Terminal default amount.
nullablemin 0max 100000
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.
|
This model has no documented fields.