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.
| ||||||||||||
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.