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.
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
- Go to WooCommerce → Settings → Payments.
- Click Manage on your gateway.
- Scroll to Custom Form.
- 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
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 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.
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
Select a field in the preview to edit settings in the Field settings panel on the right.
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)
- Options — list of choices customers can pick from
Settings for Date fields
- Date format — display format (for example,
mm/dd/yy,dd/mm/yy,yy-mm-dd)
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
| 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
Text
Single-line text input.
Example use case: Company name, purchase order number, payment reference.
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
Multi-line text area.
Example use case: Additional order notes, special billing instructions.
Email address with format validation.
Example use case: Billing contact email, accounts payable address.
URL
Website URL with format validation.
Example use case: Company website or vendor portal link.
Number
Numeric value with validation.
Example use case: Internal account number, quantity reference.
Currency
Amount-style numeric field.
Example use case: Expected payment amount or budget code reference.
Phone
Phone number field.
Example use case: Accounts payable phone number.
Time
Time picker.
Example use case: Preferred callback time for payment follow-up.
Date
Date picker with configurable format.
Example use case: Required delivery date, preferred pickup date.
Checkbox
Multiple options; customer can select more than one.
Example use case: “I agree to payment terms” plus “Send copy to procurement.”
Radio
Single choice from a list of options.
Example use case: Select invoice delivery method (Email / Post).
Select
Dropdown with one choice.
Example use case: Select cost center or department.
Customer Signature
Drawing pad for customer signature.
Example use case: Sign acceptance of payment terms or purchase authorization.
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
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
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 |
| Billing contact email | Yes | Where to send the invoice |
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
Test required fields with debug mode before customers see the gateway.
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).