> ## Documentation Index
> Fetch the complete documentation index at: https://dokumentation.websale.de/llms.txt
> Use this file to discover all available pages before exploring further.

# PAY- (Additional fields for the payment method)

> Payment methods that need more than one click: free input fields, country-specific additional information from the CountryRule section, and the special fields of individual providers.

Most payment methods are done with a click on the radio button. Some are not: a cost center needs a number, an installment purchase in certain countries needs a date of birth, a business customer needs an order number for the invoice. The shop system collects this information directly in the list of payment methods, next to the payment method it belongs to.

This page describes the tags for these additional fields. The loop over the payment methods in which they all appear, as well as the name, costs, and selection field, are described under PAY- (Displaying and selecting payment methods).

Guide: Selecting the payment method

## Three types of additional fields

They come in three forms, which differ in who sets them up and what they depend on.

| Type | What it depends on | Number |
| - | - | - |
| free input fields | set up in the shop for the payment method | up to three |
| country-specific additional information | payment method and delivery country | any number |
| special fields | permanently tied to a specific payment method | per provider |

All three are placed within the payment method loop and visually belong below the name of the payment method. Whether any of them applies to a payment method at all is answered in one go by `PAY-Data_html_container_remarks`.

## Free input fields

Up to three free input fields can be set up for each payment method. Each has the same set of four tags, distinguished by the number.

| Tag | Returns |
| - | - |
| `PAY-Data_InputSuffix1_descr` | the label of the field |
| `PAY-Data_InputSuffix1_input` | the field name for the `input` element |
| `PAY-Data_InputSuffix1` | the value already entered |
| `PAY-Data_InputSuffix1_required` | applies if the field is mandatory |

For the second and third field, the tags are named `PAY-Data_InputSuffix2…` and `PAY-Data_InputSuffix3…` accordingly.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{PAY-Data_InputSuffix1_input}
   <p id="~PAY-Data_html_id(inputsuffix1_name)~"
      class="~PAY-Data_html_class_global(inputsuffix1_name)~">
      ~PAY-Data_InputSuffix1_descr~{PAY-Data_InputSuffix1_required}*{/PAY-Data_InputSuffix1_required}
   </p>

   <input type="text"
          id="~PAY-Data_html_id(inputsuffix1_input)~"
          class="~PAY-Data_html_class_global(inputsuffix1_input)~"
          name="~PAY-Data_InputSuffix1_input~"
          value="~PAY-Data_InputSuffix1~">
{/PAY-Data_InputSuffix1_input}
```

> [!NOTE]
>
> Wrap the block with `PAY-Data_InputSuffix1_input`, not with `PAY-Data_InputSuffix1`. The field name is only available if the field is set up for this payment method at all. The value, on the other hand, is empty on the first call even if the field exists, and the block would then be missing.

> [!NOTE]
>
> The asterisk after the label comes from `PAY-Data_InputSuffix1_required`. This lets you decide yourself how to mark mandatory fields. Regardless of this, the shop system checks the requirement when the form is submitted.

## Country-specific additional information

Some payment methods need information that only applies in certain countries. It is set up in the shop configuration `shop.config` in the `<+CountryRule>` section of the respective payment method. The shop system displays it as soon as the payment method and delivery country match.

Reference: Section +CountryRule

### The loop

`PAY-Data_CountryRule` iterates over the additional information that currently applies to this payment method. As a single tag, it outputs their number.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{PAY-Data_CountryRule}
   {@PAY-Data_CountryRule}
      <div id="~PAY-Data_html_id(paymentcountryrule)~"
           class="~PAY-Data_html_class_countryrule_global(paymentcountryrule)~
                  ~PAY-Data_html_class_global(paymentcountryrule)~">
         <!-- ein Zusatzfeld -->
      </div>
   {/@PAY-Data_CountryRule}
{/PAY-Data_CountryRule}
```

> [!NOTE]
>
> `PAY-Data_html_class_countryrule_global` takes `paymentcountryrule` as its only argument. It returns the class that the block output also sets at this point, thereby supplementing the four general class tags.

### Which type of field

Each piece of additional information is one of four things. Four range tags and a code tell you which one.

| Range tag | Applies to | Code |
| - | - | - |
| `PAY-Data_CountryRule_Type_isListbox` | a selection list | 0 |
| `PAY-Data_CountryRule_Type_isInput` | a text input field | 1 |
| `PAY-Data_CountryRule_Type_isDateOfBirth` | the three lists for the date of birth | 2 |
| `PAY-Data_CountryRule_Type_isCheckbox` | a checkbox | 3 |

`PAY-Data_CountryRule_Type_code` outputs the same code as a number.

> [!NOTE]
>
> You do not need the code for the template. The four range tags are more readable and keep the template understandable even if a fifth type is added later. The code is intended for cases where you want to pass the type on to JavaScript.

### The common information

These tags apply regardless of the type of field.

| Tag | Returns |
| - | - |
| `PAY-Data_CountryRule_ID` | the technical identifier of the additional information |
| `PAY-Data_CountryRule_descr` | the label from `FieldDescr-Txt` |
| `PAY-Data_CountryRule_input` | the field name for the input element |
| `PAY-Data_CountryRule_value` | the technical value already entered |
| `PAY-Data_CountryRule_required` | applies if the information is mandatory |
| `PAY-Data_CountryRule_maxlength` | the permitted maximum length |
| `PAY-Data_CountryRule_error` | applies if the input was incorrect |
| `PAY-Data_CountryRule_errormessage` | the stored error message |

> [!NOTE]
>
> `PAY-Data_CountryRule_maxlength` only applies if a maximum length is set up for the field at all. Therefore, set the attribute wrapped in a range tag, otherwise there will be an empty `maxlength` in the markup.

> [!NOTE]
>
> `PAY-Data_CountryRule_errormessage` only applies if there is an input error **and** an error message is stored for this additional information. For the case without a stored text, you should provide a general note via `PAY-Data_CountryRule_error`.

### Text input field and checkbox

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{PAY-Data_CountryRule_Type_isInput}
   <label>
      ~PAY-Data_CountryRule_descr~{PAY-Data_CountryRule_required}*{/PAY-Data_CountryRule_required}
      <input type="text"
             name="~PAY-Data_CountryRule_input~"
             value="~PAY-Data_CountryRule_value~"
             {PAY-Data_CountryRule_maxlength}maxlength="~PAY-Data_CountryRule_maxlength~"{/PAY-Data_CountryRule_maxlength}>
   </label>
{/PAY-Data_CountryRule_Type_isInput}

{PAY-Data_CountryRule_Type_isCheckbox}
   <label>
      <input type="checkbox" name="~PAY-Data_CountryRule_input~" ~PAY-Data_CountryRule_value~>
      ~PAY-Data_CountryRule_descr~
   </label>
{/PAY-Data_CountryRule_Type_isCheckbox}

{PAY-Data_CountryRule_error}
   <p class="fehler">~PAY-Data_CountryRule_errormessage~</p>
{/PAY-Data_CountryRule_error}
```

> [!NOTE]
>
> `PAY-Data_CountryRule_value` behaves differently depending on the type. For the text input field, it is the buyer's input; for the checkbox, it outputs `checked`; and for a selection list, it outputs the technical value of the selected entry. This one tag therefore covers all cases; you just place it at the appropriate point in the markup.

### Selection list

Retrieve the entries of the list with a second loop.

| Tag | Returns |
| - | - |
| `PAY-Data_CountryRule_listbox` | the loop over the entries, as a single tag their number |
| `PAY-Data_CountryRule_listbox_value` | the technical value of the entry |
| `PAY-Data_CountryRule_listbox_value_txt` | the displayed text from `Entry-Txt` |
| `PAY-Data_CountryRule_listbox_selected` | applies to the selected entry |
| `PAY-Data_CountryRule_value_txt` | the displayed text of the entry already selected |

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{PAY-Data_CountryRule_Type_isListbox}
   <label>
      ~PAY-Data_CountryRule_descr~
      <select name="~PAY-Data_CountryRule_input~">
         {@PAY-Data_CountryRule_listbox}
            <option value="~PAY-Data_CountryRule_listbox_value~"
                    ~PAY-Data_CountryRule_listbox_selected~>
               ~PAY-Data_CountryRule_listbox_value_txt~
            </option>
         {/@PAY-Data_CountryRule_listbox}
      </select>
   </label>
{/PAY-Data_CountryRule_Type_isListbox}
```

> [!WARNING]
>
> As a single tag, `PAY-Data_CountryRule_listbox_selected` outputs the word `selected` without a leading space. Unlike the `checked` tags of the payment method selection, you have to take care of the spacing to the preceding attribute yourself here.

> [!NOTE]
>
> `PAY-Data_CountryRule_value` returns the technical value of the selection, `PAY-Data_CountryRule_value_txt` the corresponding display text. For a country list, this would be `DEU` and `Deutschland`. For displaying the choice made elsewhere on the page, `value_txt` is the right tag; for hidden fields and JavaScript, use `value`.

> [!NOTE]
>
> `PAY-Data_CountryRule_value_txt` is only filled for selection lists. For the other three types, it remains empty, and the range tag does not apply.

> [!NOTE]
>
> The three `listbox_` tags work exclusively within `{@PAY-Data_CountryRule_listbox}`. Outside of it, they are treated as an invalid tag.

### Date of birth

For the date of birth type, the shop system creates the three selection lists for day, month, and year itself.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{PAY-Data_CountryRule_Type_isDateOfBirth}
   <label>
      ~PAY-Data_CountryRule_descr~{PAY-Data_CountryRule_required}*{/PAY-Data_CountryRule_required}
      ~PAY-Data_CountryRule_dateofbirth_list~
   </label>
{/PAY-Data_CountryRule_Type_isDateOfBirth}
```

> [!WARNING]
>
> `PAY-Data_CountryRule_dateofbirth_list` is exclusively a single tag and works exclusively for the date of birth type. As a range tag or for another type, it is treated as an invalid tag. The previous documentation lists it as a range tag; this is not correct. The check whether the case applies at all is handled by `PAY-Data_CountryRule_Type_isDateOfBirth`.

> [!NOTE]
>
> The lists are prefilled with the date of birth from the billing address, if one is stored there. The buyer then does not have to enter it again.

## Special fields of individual payment methods

Three payment methods bring their own fields that only appear with them.

### Cost center

With the cost center payment method, the buyer specifies a cost center number and the email address of the approver. Both fields have the same set of four tags.

| Tag | Returns |
| - | - |
| `PAY-Data_Special_costcenter_number_descr` | the label of the number field |
| `PAY-Data_Special_costcenter_number_input` | its field name |
| `PAY-Data_Special_costcenter_number` | the value entered |
| `PAY-Data_Special_costcenter_number_required` | applies if the number is mandatory |
| `PAY-Data_Special_costcenter_email_descr` | the label of the email field |
| `PAY-Data_Special_costcenter_email_input` | its field name |
| `PAY-Data_Special_costcenter_email` | the address entered |
| `PAY-Data_Special_costcenter_email_required` | applies if the address is mandatory |

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{PAY-Data_Special_costcenter_number_input}
   <p id="~PAY-Data_html_id(costcenternumber_name)~"
      class="~PAY-Data_html_class_global(costcenternumber_name)~">
      ~PAY-Data_Special_costcenter_number_descr~{PAY-Data_Special_costcenter_number_required}*{/PAY-Data_Special_costcenter_number_required}
   </p>

   <input type="text" maxlength="64"
          id="~PAY-Data_html_id(costcenternumber_input)~"
          class="~PAY-Data_html_class_global(costcenternumber_input)~"
          name="~PAY-Data_Special_costcenter_number_input~"
          value="~PAY-Data_Special_costcenter_number~">
{/PAY-Data_Special_costcenter_number_input}
```

> [!NOTE]
>
> The two fields can be set up individually. Therefore, wrap each one separately with its `_input` tag instead of wrapping both together. Otherwise, the configured field disappears as soon as the other one is missing.

> [!NOTE]
>
> The maximum length of both fields is 64 characters. Set `maxlength` yourself; there is no tag for it.

### Bank selection with PayEx

`PAY-Data_Special_payexbankselection` creates the ready-made selection of the bank. It only appears for the direct debit via PayEx payment method.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{PAY-Data_Special_payexbankselection}
   <div id="~PAY-Data_html_id(payexbank)~"
        class="~PAY-Data_html_class_global(payexbank)~">
      ~PAY-Data_Special_payexbankselection~
   </div>
{/PAY-Data_Special_payexbankselection}
```

### Container for the PayPal payment methods

`PAY-Data_Special_PayPalMethodsDivContainerID` returns the ID of the container into which PayPal loads its own payment method selection.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{PAY-Data_Special_PayPalMethodsDivContainerID}
   <div id="~PAY-Data_Special_PayPalMethodsDivContainerID~"></div>
{/PAY-Data_Special_PayPalMethodsDivContainerID}
```

> [!NOTE]
>
> The container remains empty until the PayPal script fills it. Therefore, create it without any content of its own and without a fixed height, and always take the ID from the tag.

## The tags at a glance

| Tag | Single tag | Range tag | Negative range tag | Loop tag |
| - | - | - | - | - |
| `PAY-Data_InputSuffix1` to `3` | yes | yes | yes | – |
| `PAY-Data_InputSuffix1_descr` to `3_descr` | yes | yes | yes | – |
| `PAY-Data_InputSuffix1_input` to `3_input` | yes | yes | yes | – |
| `PAY-Data_InputSuffix1_required` to `3_required` | – | yes | yes | – |
| `PAY-Data_CountryRule` | yes | yes | yes | yes |
| `PAY-Data_CountryRule_ID` | yes | yes | yes | – |
| `PAY-Data_CountryRule_Type_code` | yes | yes | yes | – |
| `PAY-Data_CountryRule_Type_isInput` | – | yes | yes | – |
| `PAY-Data_CountryRule_Type_isListbox` | – | yes | yes | – |
| `PAY-Data_CountryRule_Type_isDateOfBirth` | – | yes | yes | – |
| `PAY-Data_CountryRule_Type_isCheckbox` | – | yes | yes | – |
| `PAY-Data_CountryRule_descr` | yes | yes | yes | – |
| `PAY-Data_CountryRule_input` | yes | yes | yes | – |
| `PAY-Data_CountryRule_value` | yes | yes | yes | – |
| `PAY-Data_CountryRule_value_txt` | yes | yes | yes | – |
| `PAY-Data_CountryRule_required` | – | yes | yes | – |
| `PAY-Data_CountryRule_maxlength` | yes | yes | yes | – |
| `PAY-Data_CountryRule_error` | – | yes | yes | – |
| `PAY-Data_CountryRule_errormessage` | yes | yes | yes | – |
| `PAY-Data_CountryRule_listbox` | yes | yes | yes | yes |
| `PAY-Data_CountryRule_listbox_value` | yes | yes | yes | – |
| `PAY-Data_CountryRule_listbox_value_txt` | yes | yes | yes | – |
| `PAY-Data_CountryRule_listbox_selected` | yes | yes | yes | – |
| `PAY-Data_CountryRule_dateofbirth_list` | yes | – | – | – |
| `PAY-Data_Special_costcenter_number` | yes | yes | yes | – |
| `PAY-Data_Special_costcenter_number_descr` | yes | yes | yes | – |
| `PAY-Data_Special_costcenter_number_input` | yes | yes | yes | – |
| `PAY-Data_Special_costcenter_number_required` | – | yes | yes | – |
| `PAY-Data_Special_costcenter_email` | yes | yes | yes | – |
| `PAY-Data_Special_costcenter_email_descr` | yes | yes | yes | – |
| `PAY-Data_Special_costcenter_email_input` | yes | yes | yes | – |
| `PAY-Data_Special_costcenter_email_required` | – | yes | yes | – |
| `PAY-Data_Special_payexbankselection` | yes | yes | yes | – |
| `PAY-Data_Special_PayPalMethodsDivContainerID` | yes | yes | yes | – |

All tags apply on the payment and shipping method page `ws_pay_deliv.htm` within the `@PAY-Data` loop. The `listbox_` tags additionally apply only within `{@PAY-Data_CountryRule_listbox}`.

## Related topics

* Reference: PAY- (Displaying and selecting payment methods)
* Reference: Section +CountryRule
* Guide: Selecting the payment method
* Guide: Creating payment methods


## Related topics

- [PAY- (Displaying and selecting payment methods)](https://dokumentation.websale.de/en/v8s/referenz/tags/pay/zahlungsarten-anzeigen-und-auswaehlen.md)
- [payment - Payment methods](https://dokumentation.websale.de/en/konfiguration/payment-zahlungsmethoden.md)
- [Payment methods](https://dokumentation.websale.de/en/v8s/referenz/konfigurationen/shopkonfiguration-shop-config/zahlungsarten.md)
- [Validation and checking services](https://dokumentation.websale.de/en/konfiguration/validierungs-und-prufservices.md)
- [$wsConfig - Configuration](https://dokumentation.websale.de/en/frontend/referenz/module/wsconfig.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.