PAY- (Additional fields for the payment method)

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.

{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}

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.

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.

{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}

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.

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

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.

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

{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}

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

{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}

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.

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.

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.

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.

{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}

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.

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

{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}

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.

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.

{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.

{PAY-Data_Special_PayPalMethodsDivContainerID}
   <div id="~PAY-Data_Special_PayPalMethodsDivContainerID~"></div>
{/PAY-Data_Special_PayPalMethodsDivContainerID}

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}.

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

​Three types of additional fields

​Free input fields

​Country-specific additional information

​The loop

​Which type of field

​The common information

​Text input field and checkbox

​Selection list

​Date of birth

​Special fields of individual payment methods

​Cost center

​Bank selection with PayEx

​Container for the PayPal payment methods

​The tags at a glance

​Related topics

Three types of additional fields

Free input fields

Country-specific additional information

The loop

Which type of field

The common information

Text input field and checkbox

Selection list

Date of birth

Special fields of individual payment methods

Cost center

Bank selection with PayEx

Container for the PayPal payment methods

The tags at a glance

Related topics