A custom field is a field you define yourself and attach to a payment. You choose the name, the format, and where it appears; WinkPG collects the value alongside the payment and carries it on the transaction record from then on. An order number, an invoice reference, a customer account code, a department, a booking id: anything your business needs to see next to the money is a good candidate.

Custom fields are defined per merchant, so one set of definitions applies to every payment page and every API call for that merchant.

Defining your fields

There are two places definitions are managed, and they edit the same list.

On the merchant record. A reseller managing a merchant opens the merchant's record and edits its custom fields there, in a grid with a popup editor for each field.

In your own settings. If your reseller allows merchant self-service configuration (it's on by default), you'll find Tools > Custom Fields in the menu, at /MerchantSettings/CustomFields. It's the same grid and the same popup editor, scoped to your own merchant, and it saves with the Save button in the page toolbar. If self-service configuration isn't turned on for your merchant, the page explains that and your reseller can make the changes for you.

Either way, adding a field opens a popup with the options below.

What you can configure on a field

Option	What it does
Name	The field's identifier: 3 to 50 characters, letters and numbers only. This is the name the API expects and the key the value is stored under.
Description	Up to 100 characters. It doubles as the label a payer sees on a payment page, so write it for the payer. When it's blank, the name is used instead.
Form Position	A number that sets display order (lower numbers first). Fields with the same position fall back to alphabetical order by name.
Required	Whether a payer must fill the field in before a payment page will submit.
Enabled	Whether the field is active. Turning a field off retires it without losing the values already captured on past transactions.
Numeric	Restricts the field to numbers and switches on the numeric options below.
Min Value / Max Value	For numeric fields, the accepted range. Negative bounds are allowed, since a custom field is your own metadata rather than a monetary amount.
Decimal Places	For numeric fields, 0, 1, or 2. Zero means whole numbers only.
Max Length	For text fields, the longest value you want to accept.
Regex and Regex Message	For text fields, a regular expression the value must match, plus the message to show when it doesn't. A pattern like ^INV-[0-9]+$ is the usual way to pin a field to a house format.
Hosted Payment Pages	Presence settings for the payment page surfaces: Visible puts the field on the page, and ReadOnly displays it without letting the payer edit it.
Transaction Reports	Visible lists the field on the transaction detail page and on receipts. Clearing it hides the field from those views without affecting what is captured: the value stays on the transaction record and on the API response.
Show on save card pages	Whether the field is offered on a page whose purpose is to store a card rather than charge it. Off by default, since charge details such as an invoice number rarely apply when nothing is being charged.

Where values are captured

Hosted Payment Pages. Both the Classic and the Streamlined public forms render your enabled, page-visible custom fields, in Form Position order, labelled with each field's description. Read-only fields are shown but not editable, which makes them a good fit for a value you prefill through the session or the query string and want the payer to see but not change.

The transaction API. A create request carries a customFields collection, each entry a name and a value. The name is the name from your definition; matching ignores case.

Scoping a page to a subset of your fields

Definitions are merchant-wide, but an individual payment page doesn't have to show all of them. Every page builder has a Custom Fields step (a step in Guided Setup, a section in the Classic and Streamlined editors) with two choices: show all of the merchant's custom fields, which is the default, or show a selected subset. Pick the subset when a page has a narrow job: a donation page probably wants a campaign code and nothing else, even though your merchant defines a dozen fields for the main checkout.

Only enabled, page-visible fields are offered for selection. If one of a page's selected fields later stops being available (renamed, disabled, or hidden from payment pages), the builder says which selections it removed the next time you open the page.

How values are validated

Two layers apply, and a value that satisfies the page also satisfies the API.

Everywhere a value is submitted:

• The name must match one of your enabled definitions once you have at least one. Matching ignores case, so OrderNumber and ordernumber reach the same field.
• Names are accepted up to 50 characters and values up to 25 characters.
• Control characters are rejected in both the name and the value. Ordinary printable punctuation is accepted, which is what lets an identifier like INV-2026-1010 through.
• On a public payment page, the accepted set is narrowed further to the fields that page is scoped to, so a page that shows three fields accepts exactly those three.

On a payment page, each field's own rules apply as well:

• A required field has to be filled in.
• A text value has to fit the field's Max Length, up to the 25 character ceiling above, and match the field's regex if one is set. When it doesn't match, the payer sees your Regex Message.
• A numeric value has to parse as a number, sit within Min Value and Max Value, and stay inside the configured decimal places.

A payment page trims leading and trailing spaces from an entered value before checking it, so a stray space never costs the payer a submit.

Where values appear

Once captured, the values travel with the transaction:

• The transaction detail page lists each field's name and value alongside the rest of the transaction.
• Receipts include a custom fields block whenever the transaction carries any, so a payer's copy shows the order number they entered.
• The API returns the same customFields collection on the transaction record, so a system that reads transactions back gets the values without a second lookup.

Clearing a field's Transaction Reports > Visible setting removes it from the first two: the detail page and the receipt stop listing it, and a transaction whose every field is hidden shows no custom fields section at all. Nothing else changes. The value is still captured, still stored on the transaction, and still returned by the API, so an integration reading transactions back is unaffected.

Two details are worth knowing:

• A receipt is frozen when it is issued, so changing the setting later does not rewrite a receipt a payer already has.
• Hiding applies by name. A value captured under a name you have since renamed or deleted keeps showing, which is deliberate: a definition change made today should never quietly erase a value from a payment taken months ago.

Choosing good field names

A few habits pay off, since the name is both an API contract and a storage key:

• Keep names stable. Renaming a definition doesn't rewrite the values already stored on past transactions, and any integration posting the old name needs updating at the same time.
• Put the human-readable wording in the description rather than the name. Names are limited to letters and numbers, so PoNumber with the description "Purchase order number" reads better on a payment page than trying to make the name itself presentable.
• Retire a field by clearing Enabled rather than deleting it. Historical transactions keep their values, and you can bring the field back later. A disabled field stops being offered on payment pages, so switch any integration that still sends it over first.

Custom fields on invoices

Invoicing has its own, separate custom field definitions, managed at /Invoicing/CustomFieldDefinitions and used on invoices. They're configured independently of the transaction custom fields described here, so defining a field in one place doesn't create it in the other. If you want the same piece of data on both an invoice and a payment, define it in both.

See also

• Transaction Lifecycle and Settlement for what happens to the transaction your custom field values are attached to.
• Setting Up a Hosted Payment Page for building the page whose Custom Fields step scopes the fields above.