# CustomField

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

## Fields
- `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)
  Fields of each item:
  - `id` (string(uuid))
  - `enteredBy` (string(uuid))
  - `timestamp` (string(date-time))
  - `enteredByName` (string): Denormalized display name of the user who created the note.  Populated at creation time from `ICurrentUser` to avoid N+1 lookups when rendering. (nullable)
  - `content` (string): (nullable, min length 0, max length 1000)
- `tags` (array<[EntityTag](https://devportal.demo.winkpg.io/docs/api/models/EntityTag.md)>): (nullable)
  Fields of each item:
  - `name` (string): (nullable, min length 0, max length 50)
  - `value` (string): (nullable, min length 0, max length 150)
- `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.
  Fields:
  - `visible` (boolean)
  - `readOnly` (boolean)
  - `acceptApiValue` (boolean): Whether an integrator may attach a value to this field through the hosted-payment-page session  API while the field itself is never rendered to the payer. Off by default, which is the  historical behaviour: a field that is not `visible` is unusable on a hosted page,  so a value for it is either rejected (a page that scopes its custom fields) or accepted and  ignored (a page that does not). (nullable)
- `hostedPaymentPage` ([CustomFieldPresence](https://devportal.demo.winkpg.io/docs/api/models/CustomFieldPresence.md))
  Fields:
  - `visible` (boolean)
  - `readOnly` (boolean)
  - `acceptApiValue` (boolean): Whether an integrator may attach a value to this field through the hosted-payment-page session  API while the field itself is never rendered to the payer. Off by default, which is the  historical behaviour: a field that is not `visible` is unusable on a hosted page,  so a value for it is either rejected (a page that scopes its custom fields) or accepted and  ignored (a page that does not). (nullable)
- `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.
  Fields:
  - `visible` (boolean)
  - `readOnly` (boolean)
  - `acceptApiValue` (boolean): Whether an integrator may attach a value to this field through the hosted-payment-page session  API while the field itself is never rendered to the payer. Off by default, which is the  historical behaviour: a field that is not `visible` is unusable on a hosted page,  so a value for it is either rejected (a page that scopes its custom fields) or accepted and  ignored (a page that does not). (nullable)
- `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)

## See also

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