# SurchargeConfigurationDto

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

Full read model for a merchant's surcharge configuration: lifecycle status, rate, channel and
network policy, notice / waiting-period state, and the cost-of-acceptance attestation. Rates are
decimal fractions (0.03 = 3%). Carries `concurrencyStamp` so a client can round-trip
it into `UpdateSurchargeConfigurationDto` for optimistic concurrency.

## Fields
- `id` (string(uuid))
- `creationTime` (string(date-time)): The date and time when this entity was created.
- `creatorId` (string(uuid)): The ID of the user who created this entity. (nullable)
- `lastModificationTime` (string(date-time)): The date and time when this entity was last modified. (nullable)
- `lastModifierId` (string(uuid)): The ID of the user who last modified this entity. (nullable)
- `isDeleted` (boolean): Indicates whether this entity has been deleted.
- `deleterId` (string(uuid)): The ID of the user who deleted this entity, if it is deleted. (nullable)
- `deletionTime` (string(date-time)): The date and time when this entity was deleted, if it is deleted. (nullable)
- `merchantId` (string(uuid)): The merchant this configuration belongs to.
- `tenantId` (string(uuid)): Owning tenant (null in the host tenant). (nullable)
- `isEnabled` (boolean): Whether surcharging is currently enabled for the merchant. (nullable)
- `status` ([SurchargeConfigurationStatus](https://devportal.demo.winkpg.io/docs/api/models/SurchargeConfigurationStatus.md)): Persisted lifecycle status of the configuration. (nullable)
  Values:
  - `NotConfigured`: No surcharging has been set up for the merchant.
  - `PendingNotice`: Configuration exists but the required card-brand notice has not been filed.
  - `WaitingPeriod`: Notice filed; the mandatory waiting period is still running.
  - `Active`: Surcharging is live.
  - `Disabled`: Surcharging was turned off after having been configured.
- `waitingPeriodExpiresAt` (string(date-time)): The instant surcharging becomes permitted, i.e. when the mandatory notice waiting period  elapses. Surcharging is blocked until this is in the past. (nullable)
- `noticeFiledAt` (string(date-time)): When the most recent notice was recorded in WinkPG. (nullable)
- `noticeFiledBy` (string): The user who filed the most recent notice. (nullable)
- `noticeAttestedDate` (string(date-time)): The calendar date the merchant attested they filed the most recent notice with the card  networks, when that predates `noticeFiledAt`. Null when the notice was filed as of  the record date, and on every notice recorded before this fact existed. (nullable)
- `defaultRate` (number(double)): Default surcharge rate (decimal fraction) when no network override applies. (nullable)
- `channelRestrictions` ([SurchargeChannelFlags](https://devportal.demo.winkpg.io/docs/api/models/SurchargeChannelFlags.md)): The channels surcharging applies to. 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. (nullable)
  Values:
  - `None`: No channels enabled.
  - `VirtualTerminal`: Merchant-operated virtual terminal.
  - `Api`: Direct API integrations.
  - `HostedPaymentPage`: Hosted payment pages.
  - `RecurringBilling`: Recurring / scheduled billing.
- `processorAccountId` (string): The processor account under which the current notice / waiting period was established. (nullable)
- `disclosureCopyTemplate` (string): The merchant's own surcharge disclosure copy in the `SurchargeDisclosureCopy` token  grammar, or null when the platform default copy applies. (nullable)
- `attestedCostOfAcceptanceRate` (number(double)): The merchant's attested effective cost of acceptance (decimal fraction), a hard ceiling. (nullable)
- `costOfAcceptanceAttestedAt` (string(date-time)): When the cost-of-acceptance rate was attested. (nullable)
- `costOfAcceptanceAttestedBy` (string): The user who attested the cost-of-acceptance rate. (nullable)
- `differentialNetworkRatesAttested` (boolean): Whether differing surcharge rates across the allowed card networks have been attested as  carrying documented legal signoff. Required before such a rate set can be saved. (nullable)
- `differentialNetworkRatesAttestedAt` (string(date-time)): When the differential-rate signoff was attested. (nullable)
- `differentialNetworkRatesAttestedBy` (string): The user who attested the differential-rate signoff. (nullable)
- `forceEnabledAt` (string(date-time)): When surcharging was activated through the non-production waiting-period bypass, if it ever  was. Null on every configuration activated the normal way, so a non-null value is the signal  that this merchant's notice waiting period was not actually served. (nullable)
- `forceEnabledBy` (string): The user who activated surcharging through the non-production bypass. (nullable)
- `promotionHeldAt` (string(date-time)): When an explicit promotion hold was placed on this configuration, or null when none is in  force. While it is set, the waiting-period sweep will not promote the configuration and both  enable and force enable are refused with `Surcharging:PromotionHeld`. (nullable)
- `promotionHeldBy` (string): The user who placed the promotion hold currently in force. (nullable)
- `promotionHoldReason` (string): Why the promotion hold currently in force was placed, when a reason was given. (nullable)
- `disabledAt` (string(date-time)): When surcharging was last disabled on this configuration, or null when it has not been disabled  since it was last enabled. While it is set, the waiting-period sweep will not promote the  configuration, even after a notice filed since the disable has returned `status` to  `WaitingPeriod`. Enabling or force enabling the configuration clears it. (nullable)
- `disabledBy` (string): The user who applied the disable currently in force. (nullable)
- `autoPromotionBlockedReason` ([SurchargeAutoPromotionBlockReason](https://devportal.demo.winkpg.io/docs/api/models/SurchargeAutoPromotionBlockReason.md)): Why the deployment's auto-promotion source policy is refusing to promote this configuration, or  null when it is not refusing. (nullable)
  Values:
  - `NoApiFiledNotice`: The policy is ApiFiledOnly and none of the notices the waiting period counts was filed under an API key. Filing a fresh notice over the API clears it; the waiting period runs again from that notice.
  - `PolicyNone`: The policy is None, so nothing promotes on this deployment whatever the notices say. Only an operator changing the policy clears it.
- `networkPolicies` (array<[SurchargeNetworkPolicyDto](https://devportal.demo.winkpg.io/docs/api/models/SurchargeNetworkPolicyDto.md)>): Per-network surcharge policies. (nullable)
  Fields of each item:
  - `network` (string) required: The card network this policy applies to. Required, and it must be one of these spellings: Visa;  Mastercard, Master Card or MC; Discover; Amex or American Express; JCB; Diners, Diners Club or  Diners Club International; UnionPay, Union Pay, China Union Pay, China UnionPay or CUP; Interac.  Case and surrounding spaces are ignored, and the name is stored and returned as sent. A  configuration names each network once: two spellings of one network (Mastercard and MC) are the  same network. (nullable, max length 64)
  - `isAllowed` (boolean) required: Whether surcharging is allowed on this network. (nullable)
  - `customRate` (number(double)): Optional network-specific rate override (decimal fraction); null uses the default rate. Conditional: When CustomRate is not null. Range: 0 to 0.03. (nullable)
- `statePolicies` (array<[SurchargeStatePolicyDto](https://devportal.demo.winkpg.io/docs/api/models/SurchargeStatePolicyDto.md)>): Per-state surcharge policies. (nullable)
  Fields of each item:
  - `stateCode` (string) required: Two-letter US state code (e.g. "CO", "NY"). (nullable)
  - `restrictionType` ([SurchargeStateRestrictionType](https://devportal.demo.winkpg.io/docs/api/models/SurchargeStateRestrictionType.md)) required: How the state restricts surcharging. (nullable)
    Values:
    - `Prohibited`: Surcharging is prohibited outright in the state.
    - `Restricted`: Surcharging is allowed but constrained (e.g. a state cap or disclosure rules).
    - `Permissive`: Surcharging is permitted with no state-specific restriction beyond network rules.
  - `capRate` (number(double)): Optional state-imposed maximum rate (decimal fraction). Null means the state applies no numeric  cap beyond network rules. Conditional: When CapRate is not null. Must be >= 0. (nullable)
- `notices` (array<[SurchargeNoticeRecordDto](https://devportal.demo.winkpg.io/docs/api/models/SurchargeNoticeRecordDto.md)>): Filed card-brand notices (per network). (nullable)
  Fields of each item:
  - `noticeId` (string(uuid)): The notice's identifier, used to name it in an amendment. Null on a notice recorded before  notice identifiers were assigned; such a notice cannot be amended and is corrected by filing a  new one. (nullable)
  - `network` (string): The card network the notice covers; null for an all-network notice. (nullable)
  - `filedAt` (string(date-time)): When this record was created in WinkPG. (nullable)
  - `attestedNoticeDate` (string(date-time)): The calendar date the merchant attested they filed notice with the card networks, when that  predates `filedAt`. Null when the notice was filed as of the record date. (nullable)
  - `effectiveAt` (string(date-time)): When the notice becomes effective (the network is surchargeable at/after this instant). (nullable)
  - `filedByUserId` (string): The user who filed the notice. (nullable)
  - `filedByApiKeyId` (string(uuid)): The API key the notice was filed under, or null when it was not filed over the API (a notice  filed from the portal records neither this nor `filedByApiKeyName`, and so does every  notice recorded before provenance was captured). (nullable)
  - `filedByApiKeyName` (string): The display name the API key carried when the notice was filed. Never re-resolved, so a key  renamed since keeps naming itself here the way it was named at the time. (nullable)
  - `referenceNumber` (string): The notice reference number issued by the network / processor. The only field an amendment  changes. (nullable)
  - `amendedAt` (string(date-time)): When the reference number was last amended, or null when it never has been. (nullable)
  - `amendedBy` (string(uuid)): The user who last amended the reference number, or null when it has never been amended or the  amending caller carried no user id. (nullable)
  - `processorAccountId` (string): The processor account the notice was filed under: a processor profile id from the merchant's  processing settings, or null for a notice that covers every processor. A value recorded before  filing checked it against the merchant's profiles reads back exactly as it was written. (nullable)
  - `coversAllProcessors` (boolean): Whether the notice covers every card processor the merchant is boarded on, which is true when it  names no processor account.
  - `coveredProcessorProfileIds` (array<string(uuid)>): The card processor profiles the notice covers: the one it names, or every card processor profile  on the merchant for a notice that names none. Empty when the stored processor account is not a  profile id, or when the merchant's profiles could not be read for an all-processor notice. (nullable)
- `cardProcessorCoverage` (array<[SurchargeCardProcessorCoverageDto](https://devportal.demo.winkpg.io/docs/api/models/SurchargeCardProcessorCoverageDto.md)>): Every card processor profile the merchant is boarded on, and whether a filed notice covers each  one. Null when the merchant's processing settings could not be read for this response. (nullable)
  Fields of each item:
  - `processorProfileId` (string(uuid)): The processor profile id from the merchant's processing settings.
  - `processorId` (string): The processor the profile routes to, for example `tsys`. (nullable)
  - `processorName` (string): The processor's display name. (nullable)
  - `isActive` (boolean): Whether the profile is active. Only an active profile needs a covering notice before surcharging  is activated, and only while the platform requires notice coverage per processor.
  - `isCovered` (boolean): Whether a counted notice covers this profile.
- `concurrencyStamp` (string): Optimistic-concurrency token; supply the value read here when updating. (nullable)

## See also

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