# 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.signapay-sbx.winkpg.io/docs/api/models/VirtualTerminalCustomerField.md))
  Fields:
  - `fieldKey` (string): (nullable, read only)
  - `enabled` (boolean)
  - `required` (boolean)
  - `allowAddNew` (boolean)
- `invoiceNumber` ([VirtualTerminalInvoiceNumField](https://devportal.signapay-sbx.winkpg.io/docs/api/models/VirtualTerminalInvoiceNumField.md))
  Fields:
  - `fieldKey` (string): (nullable, read only)
  - `enabled` (boolean)
  - `required` (boolean)
- `purchaseOrderNumber` ([VirtualTerminalPurchaseOrderNumField](https://devportal.signapay-sbx.winkpg.io/docs/api/models/VirtualTerminalPurchaseOrderNumField.md))
  Fields:
  - `fieldKey` (string): (nullable, read only)
  - `enabled` (boolean)
  - `required` (boolean)
- `billingAddress` ([VirtualTerminalBillingAddressFieldGroup](https://devportal.signapay-sbx.winkpg.io/docs/api/models/VirtualTerminalBillingAddressFieldGroup.md))
  Fields:
  - `fieldKey` (string): (nullable, read only)
  - `enabled` (boolean)
  - `required` (boolean)
  - `requireOnlyAvsFields` (boolean)
- `shippingAddress` ([VirtualTerminalShippingAddressFieldGroup](https://devportal.signapay-sbx.winkpg.io/docs/api/models/VirtualTerminalShippingAddressFieldGroup.md))
  Fields:
  - `fieldKey` (string): (nullable, read only)
  - `enabled` (boolean)
  - `required` (boolean)
  - `defaultToSameAsBilling` (boolean)
- `contactPhone` ([VirtualTerminalPhoneField](https://devportal.signapay-sbx.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.signapay-sbx.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.signapay-sbx.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.signapay-sbx.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.signapay-sbx.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.signapay-sbx.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.signapay-sbx.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)
  - `additionalTenders` (array<string>): 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)
  - `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.signapay-sbx.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.signapay-sbx.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.signapay-sbx.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.signapay-sbx.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.signapay-sbx.winkpg.io/llms.txt): the machine-readable index of every public page on this site.