Create a Default Custom Rule

Custom field rules let you add merchant-defined fields to the Pay by Link checkout page — for example, a delivery option dropdown or an order reference text field. Default rules apply automatically to all new links you create.

New default custom rules are only applied to payment links created after the rule is added. They do not apply to existing payment links.

After creating a custom field definition, use its id as the definitionId when creating a link with custom rules. See Create a New Link with Custom Rules.

Prerequisites

You must have a Pay by Link-enabled merchant account and valid API credentials. See Get Started with Pay by Link for account requirements.

Examples

Endpoint

POST /ipl/v2/payment-links/{id}

The id in the response is used as definitionId when creating a link with custom rules.

Use this example to create a custom dropdown menu that presents customers with a predefined set of options on the checkout page, such as a delivery method selector.

{  "fieldType": "Select",  "label": "Delivery",  "customerVisible": true,  "readOnly": false,  "merchantDefinedDataIndex": 1,  "possibleValues": "Standard;Next Day"}

{  "id": "5000000000000000693",  "fieldType": "Select",  "label": "Delivery",  "customerVisible": true,  "possibleValues": "Standard;Next Day",  "merchantId": "pbldemo",  "referenceType": "Invoice",  "readOnly": false,  "merchantDefinedDataIndex": 1}

Create a Default Custom Text Field

Use this example to create a custom free-text field that lets customers enter a value on the checkout page, such as an order reference number.

{  "fieldType": "Text",  "label": "Order Reference",  "customerVisible": true,  "readOnly": false,  "textMinLength": 1,  "textMaxLength": 100,  "textDefaultValue": "default text",  "merchantDefinedDataIndex": 15}

{  "id": 1515,  "fieldType": "Text",  "label": "Order Reference",  "customerVisible": true,  "readOnly": false,  "textMinLength": 1,  "textMaxLength": 100,  "textDefaultValue": "default text",  "merchantDefinedDataIndex": 15}

Sending the Request

For environment base URLs, see Endpoints: Pay by Link.

Required Fields

fieldType string

Type of custom field. Values: Select (dropdown) or Text.

label string

Display label for the field.

customerVisible boolean

When true, the field is visible to the customer on the checkout page. When false, the field is visible only in the merchant portal.

merchantDefinedDataIndex integer

Index identifying the custom field slot (integer).

Include these optional fields when creating a dropdown custom rule:

Optional Fields for Select Fields

possibleValues string

Semicolon-separated list of dropdown options. Required when fieldType is Select. For example, Standard;Next Day.

readOnly boolean

When true, the field value is pre-filled and the customer cannot modify it.

Include these optional fields when creating a text input custom rule:

Optional Fields for Text Fields

textMinLength integer

Minimum character length the customer must enter.

textMaxLength integer

Maximum character length the customer can enter.

textDefaultValue string

Default text pre-populated in the field. The customer can edit this value.

readOnly boolean

When true, the field value is pre-filled and the customer cannot modify it.

Was this page helpful?

Last published: October 28, 2026

Prerequisites

Examples

Endpoint

Create a Default Custom Dropdown

Create a Default Custom Text Field

Sending the Request

Not available for your audience