# CustomFieldsSettingsDto

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

DTO for merchant self-service custom field management. Carries the merchant's
custom field definitions plus a concurrency stamp for optimistic concurrency on save.

## Fields
- `customFields` (array<[CustomField](https://devportal.demo.winkpg.io/docs/api/models/CustomField.md)>): The merchant's custom field definitions. (nullable)
  Fields of each item:
  - `id` (string(uuid))
  - `name` (string) required: (nullable, min length 3, max length 50, pattern ^[A-Za-z0-9]+(?:_[A-Za-z0-9]+)*$)
  - `notes` (array<[EntityNote](https://devportal.demo.winkpg.io/docs/api/models/EntityNote.md)>): (nullable)
  - `tags` (array<[EntityTag](https://devportal.demo.winkpg.io/docs/api/models/EntityTag.md)>): (nullable)
  - `isNumeric` (boolean): Conditional: When IsMultiValue is true.
  - `decimalPlaces` (integer(int32)): Conditional: When IsNumeric is true. Range: 0 to 2.
  - `maxLength` (integer(int32)): Conditional: When IsNumeric is false. Range: 0 to 300.
  - `regEx` (string): Conditional: When RegEx is not empty. (nullable)
  - `regExErrorMessage` (string): Conditional: When RegExErrorMessage is not empty. Max length: 100. (nullable, max length 100)
  - `isRequired` (boolean)
  - `isEnabled` (boolean)
  - `description` (string): Conditional: When Description is not empty. Max length: 100. (nullable)
  - `numericMinValue` (number(double)): For numeric fields, the minimum value allowed. Negative minimums are permitted: a custom  field is merchant-defined metadata rather than a monetary amount, so ranges that span or sit  below zero (adjustments, offsets, deltas, temperatures) are legitimate. The value is inert  unless `isNumeric` is set, and is validated only in that case. Conditional: When IsNumeric is true. Range: -1000000000 to 1000000000.
  - `numericMaxValue` (number(double)): For numeric fields, the maximum value allowed. It must be greater than or equal to  `numericMinValue` but is not required to be positive, since a field whose whole  range is negative is valid. The value is inert unless `isNumeric` is set, and is  validated only in that case. Conditional: When IsNumeric is true. Range: -1000000000 to 1000000000.
  - `position` (integer(int32)): (min 0)
  - `virtualTerminal` ([CustomFieldPresence](https://devportal.demo.winkpg.io/docs/api/models/CustomFieldPresence.md)): Presence settings for the Virtual Terminal, which collects this field from the operator when  `visible` is set.
  - `hostedPaymentPage` ([CustomFieldPresence](https://devportal.demo.winkpg.io/docs/api/models/CustomFieldPresence.md))
  - `transactionReports` ([CustomFieldTransactionReportsPresence](https://devportal.demo.winkpg.io/docs/api/models/CustomFieldTransactionReportsPresence.md)): Presence settings for the surfaces that list a transaction's captured custom fields: the  transaction detail page and the receipt. Only `visible` is  honoured.
  - `showOnSaveCardSessions` (boolean): Whether this field is offered on a save-card hosted payment page session (one that stores the  card without charging it). Defaults to off: most custom fields carry charge metadata (invoice  number, purchase order, department) that is meaningless on a page whose only outcome is a  stored card, so a field is suppressed on those sessions unless the merchant opts it in. (nullable)
  - `legacyNumber` (integer(int64)): The integer key the v1 API addresses this definition by. Server-owned: allocated once, when  the definition is first saved, and never reassigned afterwards. (nullable)
  - `isMultiValue` (boolean): Whether a transaction carries a list of values for this field rather than a single value.  A multi-value field is submitted through `TrxCustomField.Values`, prefilled on a hosted  page session through `prefilledListFields`, and captured one value per line on the  Virtual Terminal. The single `value` member keeps working on a multi-value definition:  it is carried unchanged and mirrored into the list as its one item. (nullable)
  - `maxValues` (integer(int32)): For a multi-value field, the largest number of values a transaction may carry. Unset reads as  `DefaultMaxValues`; the platform ceiling is  `MaxValuesCeiling`. Inert unless `isMultiValue` is set,  and validated only in that case. Conditional: When IsMultiValue is true and MaxValues is not null. Range: 1 to 250. (nullable)
- `concurrencyStamp` (string): Concurrency stamp for optimistic concurrency control. (nullable)
- `isFeatureEnabled` (boolean): Whether the `AllowCustomFieldConfig` feature is enabled for this merchant.  Read-only: set by the server, ignored on update.

## See also

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