---
title: Custom Checkout Field Builder
description: "The **Custom Form** section on each gateway settings page includes the **Custom checkout field builder**. Use it to collect extra information from customers when they choose your custom payment method. Table of Contents [Toggle](#) - [What the field builder is used for](#What_the_field_builder_is_used_for) -…"
url: "https://wpruby.com/knowledgebase/custom-checkout-field-builder/"
updated: "2026-07-07"
category: WooCommerce Custom Payment Gateway Pro
---

# Custom Checkout Field Builder

The **Custom Form** section on each gateway settings page includes the **Custom checkout field builder**. Use it to collect extra information from customers when they choose your custom payment method.

Table of Contents

 [Toggle](#)

- [What the field builder is used for](#What_the_field_builder_is_used_for)
- [How to open the field builder](#How_to_open_the_field_builder)
- [Field Palette](#Field_Palette)
- [Checkout Preview](#Checkout_Preview)
- [Field Settings](#Field_Settings)
  - [Common field settings](#Common_field_settings)
  - [Settings for choice fields (Checkbox, Radio, Select)](#Settings_for_choice_fields_Checkbox_Radio_Select)
  - [Settings for Date fields](#Settings_for_Date_fields)
  - [Settings for File Upload fields](#Settings_for_File_Upload_fields)
  - [Settings for Instructions fields](#Settings_for_Instructions_fields)
- [Field types in detail](#Field_types_in_detail)
  - [Text](#Text)
  - [Password](#Password)
  - [Textarea](#Textarea)
  - [Email](#Email)
  - [URL](#URL)
  - [Number](#Number)
  - [Currency](#Currency)
  - [Phone](#Phone)
  - [Time](#Time)
  - [Date](#Date)
  - [Checkbox](#Checkbox)
  - [Radio](#Radio)
  - [Select](#Select)
  - [Customer Signature](#Customer_Signature)
  - [File Upload](#File_Upload)
  - [Instructions](#Instructions)
- [Example form: Pay by Invoice](#Example_form_Pay_by_Invoice)
  - [Example field configuration](#Example_field_configuration)
- [Tips](#Tips)

## What the field builder is used for

[https://github.com/wsenjer/woocommerce-custom-payment-gateway/blob/docs-cursor/docs/custom-checkout-field-builder.md#what-the-field-builder-is-used-for](https://github.com/wsenjer/woocommerce-custom-payment-gateway/blob/docs-cursor/docs/custom-checkout-field-builder.md#what-the-field-builder-is-used-for)

- Collect business details (company name, tax ID, purchase order number)
- Gather payment references or confirmation numbers
- Accept uploaded payment receipts or proof of payment
- Show read-only instructions inside the checkout form
- Capture signatures for terms acceptance

Fields appear on the checkout page only when your gateway is selected.

## How to open the field builder

[https://github.com/wsenjer/woocommerce-custom-payment-gateway/blob/docs-cursor/docs/custom-checkout-field-builder.md#how-to-open-the-field-builder](https://github.com/wsenjer/woocommerce-custom-payment-gateway/blob/docs-cursor/docs/custom-checkout-field-builder.md#how-to-open-the-field-builder)

1. Go to **WooCommerce → Settings → Payments**.
2. Click **Manage** on your gateway.
3. Scroll to **Custom Form**.
4. Use the three panels: **Field palette**, **Checkout preview**, and **Field settings**.

Click **Save changes** in the field builder (or the main **Save changes** button at the bottom of the page) to save your fields.

## Field Palette

[https://github.com/wsenjer/woocommerce-custom-payment-gateway/blob/docs-cursor/docs/custom-checkout-field-builder.md#field-palette](https://github.com/wsenjer/woocommerce-custom-payment-gateway/blob/docs-cursor/docs/custom-checkout-field-builder.md#field-palette)

The **Field palette** on the left lists every field type you can add. Click a field type to add it to your form.

Available field types match the plugin code:

| Field type | Description |
| --- | --- |
| Text | Single-line text input |
| Password | Masked text input |
| Textarea | Multi-line text area |
| Email | Email address field |
| URL | Website link field |
| Number | Numeric value field |
| Currency | Amount/currency style field |
| Phone | Phone number field |
| Time | Time picker field |
| Date | Date picker field |
| Checkbox | Multiple selectable options |
| Radio | Single choice from options |
| Select | Dropdown list of options |
| Customer Signature | Signature drawing field |
| File Upload | File upload for receipts or documents |
| Instructions | Display-only instructions block |

> **Note:** The legacy **Credit Card** field cannot be added to new gateways. Existing gateways that still use it show a deprecation warning. See [Security and Sensitive Payment Data](https://wpruby.com/knowledgebase/security-and-sensitive-payment-data/).

## Checkout Preview

[https://github.com/wsenjer/woocommerce-custom-payment-gateway/blob/docs-cursor/docs/custom-checkout-field-builder.md#checkout-preview](https://github.com/wsenjer/woocommerce-custom-payment-gateway/blob/docs-cursor/docs/custom-checkout-field-builder.md#checkout-preview)

The center **Checkout preview** panel shows how fields will appear at checkout.

From the preview you can:

- **Select** a field to edit its settings
- **Move** fields up or down
- **Duplicate** a field
- **Delete** a field

The preview is a layout guide. Always test on the live checkout page before going live.

## Field Settings

[https://github.com/wsenjer/woocommerce-custom-payment-gateway/blob/docs-cursor/docs/custom-checkout-field-builder.md#field-settings](https://github.com/wsenjer/woocommerce-custom-payment-gateway/blob/docs-cursor/docs/custom-checkout-field-builder.md#field-settings)

Select a field in the preview to edit settings in the **Field settings** panel on the right.

### Common field settings

[https://github.com/wsenjer/woocommerce-custom-payment-gateway/blob/docs-cursor/docs/custom-checkout-field-builder.md#common-field-settings](https://github.com/wsenjer/woocommerce-custom-payment-gateway/blob/docs-cursor/docs/custom-checkout-field-builder.md#common-field-settings)

| Setting | What it does |
| --- | --- |
| **Field label** | The label shown to the customer |
| **Help text** | Short hint shown next to the field (displayed as an info icon on checkout) |
| **Field size** | Input width: Small, Medium, or Large |
| **Default value** | Pre-filled value (Text, Email, Number, and similar fields) |
| **Required** | Yes or No — blocks checkout if empty when Yes |
| **CSS classes** | Optional CSS classes for theme styling |
| **API parameter** | Key name used when sending this field's value in API requests |

### Settings for choice fields (Checkbox, Radio, Select)

[https://github.com/wsenjer/woocommerce-custom-payment-gateway/blob/docs-cursor/docs/custom-checkout-field-builder.md#settings-for-choice-fields-checkbox-radio-select](https://github.com/wsenjer/woocommerce-custom-payment-gateway/blob/docs-cursor/docs/custom-checkout-field-builder.md#settings-for-choice-fields-checkbox-radio-select)

- **Options** — list of choices customers can pick from

### Settings for Date fields

[https://github.com/wsenjer/woocommerce-custom-payment-gateway/blob/docs-cursor/docs/custom-checkout-field-builder.md#settings-for-date-fields](https://github.com/wsenjer/woocommerce-custom-payment-gateway/blob/docs-cursor/docs/custom-checkout-field-builder.md#settings-for-date-fields)

- **Date format** — display format (for example, `mm/dd/yy`, `dd/mm/yy`, `yy-mm-dd`)

### Settings for File Upload fields

[https://github.com/wsenjer/woocommerce-custom-payment-gateway/blob/docs-cursor/docs/custom-checkout-field-builder.md#settings-for-file-upload-fields](https://github.com/wsenjer/woocommerce-custom-payment-gateway/blob/docs-cursor/docs/custom-checkout-field-builder.md#settings-for-file-upload-fields)

| Setting | What it does |
| --- | --- |
| **Allowed file extensions** | Comma-separated list (default: `jpg,jpeg,png,webp,pdf`) |
| **Max file size (MB)** | Maximum upload size (default: 5 MB) |
| **Show in admin order details** | Whether the file link appears on the order screen |
| **Show in emails** | Whether the file link appears in order emails |
| **Store with order** | Whether the file is saved with the order |

### Settings for Instructions fields

[https://github.com/wsenjer/woocommerce-custom-payment-gateway/blob/docs-cursor/docs/custom-checkout-field-builder.md#settings-for-instructions-fields](https://github.com/wsenjer/woocommerce-custom-payment-gateway/blob/docs-cursor/docs/custom-checkout-field-builder.md#settings-for-instructions-fields)

| Setting | What it does |
| --- | --- |
| **Field label** | Optional heading for the instruction block |
| **Instructions** | HTML content shown to the customer (HTML tags allowed) |
| **CSS classes** | Optional styling classes |

Instructions fields are display-only — customers do not submit a value.

---

## Field types in detail

[https://github.com/wsenjer/woocommerce-custom-payment-gateway/blob/docs-cursor/docs/custom-checkout-field-builder.md#field-types-in-detail](https://github.com/wsenjer/woocommerce-custom-payment-gateway/blob/docs-cursor/docs/custom-checkout-field-builder.md#field-types-in-detail)

### Text

[https://github.com/wsenjer/woocommerce-custom-payment-gateway/blob/docs-cursor/docs/custom-checkout-field-builder.md#text](https://github.com/wsenjer/woocommerce-custom-payment-gateway/blob/docs-cursor/docs/custom-checkout-field-builder.md#text)

Single-line text input.

**Example use case:** Company name, purchase order number, payment reference.

### Password

[https://github.com/wsenjer/woocommerce-custom-payment-gateway/blob/docs-cursor/docs/custom-checkout-field-builder.md#password](https://github.com/wsenjer/woocommerce-custom-payment-gateway/blob/docs-cursor/docs/custom-checkout-field-builder.md#password)

Masked text input (characters hidden).

**Example use case:** Internal reference codes where you want input hidden on screen. **Do not use for credit card numbers or CVV codes.**

### Textarea

[https://github.com/wsenjer/woocommerce-custom-payment-gateway/blob/docs-cursor/docs/custom-checkout-field-builder.md#textarea](https://github.com/wsenjer/woocommerce-custom-payment-gateway/blob/docs-cursor/docs/custom-checkout-field-builder.md#textarea)

Multi-line text area.

**Example use case:** Additional order notes, special billing instructions.

### Email

[https://github.com/wsenjer/woocommerce-custom-payment-gateway/blob/docs-cursor/docs/custom-checkout-field-builder.md#email](https://github.com/wsenjer/woocommerce-custom-payment-gateway/blob/docs-cursor/docs/custom-checkout-field-builder.md#email)

Email address with format validation.

**Example use case:** Billing contact email, accounts payable address.

### URL

[https://github.com/wsenjer/woocommerce-custom-payment-gateway/blob/docs-cursor/docs/custom-checkout-field-builder.md#url](https://github.com/wsenjer/woocommerce-custom-payment-gateway/blob/docs-cursor/docs/custom-checkout-field-builder.md#url)

Website URL with format validation.

**Example use case:** Company website or vendor portal link.

### Number

[https://github.com/wsenjer/woocommerce-custom-payment-gateway/blob/docs-cursor/docs/custom-checkout-field-builder.md#number](https://github.com/wsenjer/woocommerce-custom-payment-gateway/blob/docs-cursor/docs/custom-checkout-field-builder.md#number)

Numeric value with validation.

**Example use case:** Internal account number, quantity reference.

### Currency

[https://github.com/wsenjer/woocommerce-custom-payment-gateway/blob/docs-cursor/docs/custom-checkout-field-builder.md#currency](https://github.com/wsenjer/woocommerce-custom-payment-gateway/blob/docs-cursor/docs/custom-checkout-field-builder.md#currency)

Amount-style numeric field.

**Example use case:** Expected payment amount or budget code reference.

### Phone

[https://github.com/wsenjer/woocommerce-custom-payment-gateway/blob/docs-cursor/docs/custom-checkout-field-builder.md#phone](https://github.com/wsenjer/woocommerce-custom-payment-gateway/blob/docs-cursor/docs/custom-checkout-field-builder.md#phone)

Phone number field.

**Example use case:** Accounts payable phone number.

### Time

[https://github.com/wsenjer/woocommerce-custom-payment-gateway/blob/docs-cursor/docs/custom-checkout-field-builder.md#time](https://github.com/wsenjer/woocommerce-custom-payment-gateway/blob/docs-cursor/docs/custom-checkout-field-builder.md#time)

Time picker.

**Example use case:** Preferred callback time for payment follow-up.

### Date

[https://github.com/wsenjer/woocommerce-custom-payment-gateway/blob/docs-cursor/docs/custom-checkout-field-builder.md#date](https://github.com/wsenjer/woocommerce-custom-payment-gateway/blob/docs-cursor/docs/custom-checkout-field-builder.md#date)

Date picker with configurable format.

**Example use case:** Required delivery date, preferred pickup date.

### Checkbox

[https://github.com/wsenjer/woocommerce-custom-payment-gateway/blob/docs-cursor/docs/custom-checkout-field-builder.md#checkbox](https://github.com/wsenjer/woocommerce-custom-payment-gateway/blob/docs-cursor/docs/custom-checkout-field-builder.md#checkbox)

Multiple options; customer can select more than one.

**Example use case:** "I agree to payment terms" plus "Send copy to procurement."

### Radio

[https://github.com/wsenjer/woocommerce-custom-payment-gateway/blob/docs-cursor/docs/custom-checkout-field-builder.md#radio](https://github.com/wsenjer/woocommerce-custom-payment-gateway/blob/docs-cursor/docs/custom-checkout-field-builder.md#radio)

Single choice from a list of options.

**Example use case:** Select invoice delivery method (Email / Post).

### Select

[https://github.com/wsenjer/woocommerce-custom-payment-gateway/blob/docs-cursor/docs/custom-checkout-field-builder.md#select](https://github.com/wsenjer/woocommerce-custom-payment-gateway/blob/docs-cursor/docs/custom-checkout-field-builder.md#select)

Dropdown with one choice.

**Example use case:** Select cost center or department.

### Customer Signature

[https://github.com/wsenjer/woocommerce-custom-payment-gateway/blob/docs-cursor/docs/custom-checkout-field-builder.md#customer-signature](https://github.com/wsenjer/woocommerce-custom-payment-gateway/blob/docs-cursor/docs/custom-checkout-field-builder.md#customer-signature)

Drawing pad for customer signature.

**Example use case:** Sign acceptance of payment terms or purchase authorization.

### File Upload

[https://github.com/wsenjer/woocommerce-custom-payment-gateway/blob/docs-cursor/docs/custom-checkout-field-builder.md#file-upload](https://github.com/wsenjer/woocommerce-custom-payment-gateway/blob/docs-cursor/docs/custom-checkout-field-builder.md#file-upload)

Secure file upload for documents and images.

**Example use case:** Upload purchase order PDF, payment receipt, or proof of bank transfer.

Allowed extensions are validated. Files are stored in the WordPress media library.

### Instructions

[https://github.com/wsenjer/woocommerce-custom-payment-gateway/blob/docs-cursor/docs/custom-checkout-field-builder.md#instructions](https://github.com/wsenjer/woocommerce-custom-payment-gateway/blob/docs-cursor/docs/custom-checkout-field-builder.md#instructions)

Read-only HTML block inside the form.

**Example use case:** Remind customers to include their order number on bank transfers.

---

## Example form: Pay by Invoice

[https://github.com/wsenjer/woocommerce-custom-payment-gateway/blob/docs-cursor/docs/custom-checkout-field-builder.md#example-form-pay-by-invoice](https://github.com/wsenjer/woocommerce-custom-payment-gateway/blob/docs-cursor/docs/custom-checkout-field-builder.md#example-form-pay-by-invoice)

Add these fields for a typical B2B invoice checkout:

| Field type | Field label | Required | Notes |
| --- | --- | --- | --- |
| Text | Company name | No | Legal business name |
| Text | VAT / Tax ID | No | Tax registration number |
| Text | Purchase order number | No | Customer PO reference |
| Email | Billing contact email | Yes | Where to send the invoice |

### Example field configuration

[https://github.com/wsenjer/woocommerce-custom-payment-gateway/blob/docs-cursor/docs/custom-checkout-field-builder.md#example-field-configuration](https://github.com/wsenjer/woocommerce-custom-payment-gateway/blob/docs-cursor/docs/custom-checkout-field-builder.md#example-field-configuration)

**Company name**

- Field label: `Company name`
- Help text: `Enter your registered company name`
- Required: No

**VAT / Tax ID**

- Field label: `VAT / Tax ID`
- Help text: `Your tax or VAT registration number`
- Required: No

**Purchase order number**

- Field label: `Purchase order number`
- Help text: `Required for invoice matching`
- Required: No

**Billing contact email**

- Field label: `Billing contact email`
- Help text: `We will send the invoice to this address`
- Required: Yes

Click **Save changes** when finished.

> **Tip:** Gateways created from the **Pay by Invoice** template include these fields by default. You can adjust labels and requirements to match your process.

## Tips

[https://github.com/wsenjer/woocommerce-custom-payment-gateway/blob/docs-cursor/docs/custom-checkout-field-builder.md#tips](https://github.com/wsenjer/woocommerce-custom-payment-gateway/blob/docs-cursor/docs/custom-checkout-field-builder.md#tips)

Test required fields with debug mode before customers see the gateway.[https://github.com/wsenjer/woocommerce-custom-payment-gateway/blob/docs-cursor/docs/custom-checkout-field-builder.md#custom-checkout-field-builder](https://github.com/wsenjer/woocommerce-custom-payment-gateway/blob/docs-cursor/docs/custom-checkout-field-builder.md#custom-checkout-field-builder)

Keep forms short — only ask for information you need.

Use **Instructions** fields for text customers read but do not type.

Set **API parameter** names if you send data to an external system (see [API requests](https://wpruby.com/knowledgebase/sending-payment-data-to-an-external-api/)).