# VirtualTerminalFields

A model the API reference uses in a request or a response. The operation pages link every field typed as this model here.

## Fields
- `customer` ([VirtualTerminalCustomerField](https://devportal.demo.winkpg.io/docs/api/models/VirtualTerminalCustomerField.md))
  Fields:
  - `fieldKey` (string): (nullable, read only)
  - `enabled` (boolean)
  - `required` (boolean)
  - `allowAddNew` (boolean)
- `invoiceNumber` ([VirtualTerminalInvoiceNumField](https://devportal.demo.winkpg.io/docs/api/models/VirtualTerminalInvoiceNumField.md))
  Fields:
  - `fieldKey` (string): (nullable, read only)
  - `enabled` (boolean)
  - `required` (boolean)
- `purchaseOrderNumber` ([VirtualTerminalPurchaseOrderNumField](https://devportal.demo.winkpg.io/docs/api/models/VirtualTerminalPurchaseOrderNumField.md))
  Fields:
  - `fieldKey` (string): (nullable, read only)
  - `enabled` (boolean)
  - `required` (boolean)
- `billingAddress` ([VirtualTerminalBillingAddressFieldGroup](https://devportal.demo.winkpg.io/docs/api/models/VirtualTerminalBillingAddressFieldGroup.md))
  Fields:
  - `fieldKey` (string): (nullable, read only)
  - `enabled` (boolean)
  - `required` (boolean)
  - `requireOnlyAvsFields` (boolean)
- `shippingAddress` ([VirtualTerminalShippingAddressFieldGroup](https://devportal.demo.winkpg.io/docs/api/models/VirtualTerminalShippingAddressFieldGroup.md))
  Fields:
  - `fieldKey` (string): (nullable, read only)
  - `enabled` (boolean)
  - `required` (boolean)
  - `defaultToSameAsBilling` (boolean)
- `contactPhone` ([VirtualTerminalPhoneField](https://devportal.demo.winkpg.io/docs/api/models/VirtualTerminalPhoneField.md))
  Fields:
  - `fieldKey` (string): (nullable, read only)
  - `enabled` (boolean)
  - `required` (boolean)
  - `maskField` (boolean)
  - `maskExpression` (string): (nullable)
- `level3Amount` ([VirtualTerminalLevel3AmountField](https://devportal.demo.winkpg.io/docs/api/models/VirtualTerminalLevel3AmountField.md))
  Fields:
  - `fieldKey` (string): (nullable, read only)
  - `enabled` (boolean)
  - `required` (boolean)
  - `defaultAmount` (number(double)): (nullable, min 0)
- `shippingAmount` ([VirtualTerminalShippingAmountField](https://devportal.demo.winkpg.io/docs/api/models/VirtualTerminalShippingAmountField.md))
  Fields:
  - `fieldKey` (string): (nullable, read only)
  - `enabled` (boolean)
  - `required` (boolean)
  - `defaultAmount` (number(double)): (nullable, min 0)
- `convenienceAmount` ([VirtualTerminalConvenienceFeeField](https://devportal.demo.winkpg.io/docs/api/models/VirtualTerminalConvenienceFeeField.md))
  Fields:
  - `fieldKey` (string): (nullable, read only)
  - `enabled` (boolean)
  - `required` (boolean)
  - `autoCalculate` (boolean): (deprecated)
  - `calculationPercentage` (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`. (nullable, deprecated, min 0)
  - `mode` ([ConvenienceFeeMode](https://devportal.demo.winkpg.io/docs/api/models/ConvenienceFeeMode.md)): Selects the fee shape. `null` is treated as `Fixed`  for documents written before the discriminated model (see `GetEffectiveMode`). (nullable)
    Values:
    - `Fixed`: A single fixed amount. The only shape permitted under the card brands' general convenience-fee program.
    - `Percentage`: A percentage of the transaction base amount. Permitted only under the card-brand Government / Higher-Education service-fee program, and therefore gated behind the merchant Government/Education attestation. The per-network applicability guard (block on Visa, allow where the network permits) is enforced separately at transaction time.
  - `percentage` (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). (nullable, min 0)
  - `govEducationAttested` (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)
  - `govEducationAttestedBy` (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). (nullable, read only)
  - `govEducationAttestedOn` (string(date-time)): Timestamp `govEducationAttested` was last set. Recorded for audit. Server-owned on  the same terms as `govEducationAttestedBy`. (nullable, read only)
  - `visaServiceFeeRegistered` (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)
  - `visaServiceFeeRegisteredOn` (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)
  - `visaServiceFeeRegistrationRecordedBy` (string): User who last set `visaServiceFeeRegistered`. Recorded for audit, mirroring  `govEducationAttestedBy`, and server-owned on the same terms (`readOnly` on  the published schema). (nullable, read only)
  - `visaServiceFeeRegistrationRecordedOn` (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. (nullable, read only)
  - `attestedCostOfAcceptanceRate` (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. (nullable, min 0, max 1)
  - `costOfAcceptanceAttestedBy` (string): User who last set `attestedCostOfAcceptanceRate`. Recorded for audit. Server-owned  on the same terms as `govEducationAttestedBy` (`readOnly` on the published  schema). (nullable, read only)
  - `costOfAcceptanceAttestedOn` (string(date-time)): Timestamp `attestedCostOfAcceptanceRate` was last set. Recorded for audit.  Server-owned on the same terms as `costOfAcceptanceAttestedBy`. (nullable, read only)
  - `exemptDebit` (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)
  - `exemptPrepaid` (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)
  - `legacyPercentageNeedsReview` (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)
  - `standardChannel` ([ConvenienceFeePaymentChannel](https://devportal.demo.winkpg.io/docs/api/models/ConvenienceFeePaymentChannel.md)): 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:
    - `InPerson`: Face-to-face, cardholder physically present. A standard channel; never an alternative.
    - `Mail`: Mail order (the cardholder mails payment). A standard channel; never an alternative.
    - `Check`: Payment by check. A standard channel; never an alternative.
    - `Online`: Online / e-commerce. A qualifying alternative channel; never a standard channel.
    - `Phone`: Telephone order. Valid as either a standard channel or a qualifying alternative channel.
    - `Kiosk`: Self-service kiosk / unattended terminal. A Card-Present Environment per Visa's glossary, so it is not a qualifying alternative channel and cannot bear a convenience fee. Retained only for persisted-document / OpenAPI-schema compatibility; never a standard channel.
  - `alternativeChannel` ([ConvenienceFeePaymentChannel](https://devportal.demo.winkpg.io/docs/api/models/ConvenienceFeePaymentChannel.md)): 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:
    - `InPerson`: Face-to-face, cardholder physically present. A standard channel; never an alternative.
    - `Mail`: Mail order (the cardholder mails payment). A standard channel; never an alternative.
    - `Check`: Payment by check. A standard channel; never an alternative.
    - `Online`: Online / e-commerce. A qualifying alternative channel; never a standard channel.
    - `Phone`: Telephone order. Valid as either a standard channel or a qualifying alternative channel.
    - `Kiosk`: Self-service kiosk / unattended terminal. A Card-Present Environment per Visa's glossary, so it is not a qualifying alternative channel and cannot bear a convenience fee. Retained only for persisted-document / OpenAPI-schema compatibility; never a standard channel.
  - `alternativeChannelAttested` (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)
  - `alternativeChannelAttestedBy` (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). (nullable, read only)
  - `alternativeChannelAttestedOn` (string(date-time)): Timestamp `alternativeChannelAttested` was last set. Recorded for audit.  Server-owned on the same terms as `alternativeChannelAttestedBy`. (nullable, read only)
  - `offlineChannelExceptionGranted` (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)
  - `offlineChannelExceptionGrantedBy` (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. (nullable, read only)
  - `offlineChannelExceptionGrantedOn` (string(date-time)): Timestamp (UTC) `offlineChannelExceptionGranted` was last set. Server-owned on the  same terms as `offlineChannelExceptionGrantedBy`. (nullable, read only)
  - `offlineChannelExceptionReason` (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)
  - `customName` (string): Conditional: When CustomName is not null. (nullable)
  - `customDescription` (string): Conditional: When CustomDescription is not null. (nullable)
  - `readOnly` (boolean)
  - `defaultAmount` (number(double)): The fixed convenience-fee amount, in the transaction currency, applied when `mode` is  `Fixed`. Also seeds the Virtual Terminal default amount. (nullable, min 0, max 100000)
- `dutyAmount` ([VirtualTerminalDutyAmountField](https://devportal.demo.winkpg.io/docs/api/models/VirtualTerminalDutyAmountField.md))
  Fields:
  - `fieldKey` (string): (nullable, read only)
  - `enabled` (boolean)
  - `required` (boolean)
  - `defaultAmount` (number(double)): (nullable, min 0)
- `tipAmount` ([VirtualTerminalTipAmountField](https://devportal.demo.winkpg.io/docs/api/models/VirtualTerminalTipAmountField.md))
  Fields:
  - `fieldKey` (string): (nullable, read only)
  - `enabled` (boolean)
  - `required` (boolean)
  - `defaultAmount` (number(double)): (nullable, min 0)
- `taxAmount` ([VirtualTerminalTaxField](https://devportal.demo.winkpg.io/docs/api/models/VirtualTerminalTaxField.md))
  Fields:
  - `fieldKey` (string): (nullable, read only)
  - `enabled` (boolean)
  - `required` (boolean)
  - `autoCalculate` (boolean)
  - `defaultRate` (number(double)): (nullable, min 0)
- `emailAddress` ([VirtualTerminalEmailField](https://devportal.demo.winkpg.io/docs/api/models/VirtualTerminalEmailField.md))
  Fields:
  - `fieldKey` (string): (nullable, read only)
  - `enabled` (boolean)
  - `required` (boolean)
  - `validateFormat` (boolean)
  - `validationRegex` (string): (nullable)
  - `placeholder` (string): (nullable)

## See also

- [All documentation](https://devportal.demo.winkpg.io/llms.txt): the machine-readable index of every public page on this site.