BANK- (bank data) - WEBSALE Dokumentation

Bank data is captured in two places in the shop: in the customer account under bank details, and in the checkout process when the buyer pays by direct debit. Both paths lead to the same template ws_bank_manage.htm, supplemented by tags that are also available on the order overview ws_place_order.htm. The tags with the prefix BANK- fall into five groups:

Data fields such as account holder, IBAN or bank code, each with a family of suffixes for input field, label and error.
Saved bank details, i.e. loop, selection list and whether multiple accounts are allowed.
Navigation and actions, i.e. the links for creating, editing and deleting.
Page states, which determine which part of the template is currently shown.
SEPA, i.e. mandate type, mandate number and the masked IBAN for the mandate PDF.

The framework of the management page

Depending on its state, the template shows either the overview of saved accounts or the input form. These two states are mutually exclusive.

{BANK-Overview}

   {BANK-Data}
      Sie haben ~BANK-Data~ Bankverbindungen hinterlegt.
      {@BANK-Data}
         ~BANK-Position~. {BANK-UserDescr}~BANK-UserDescr~{/BANK-UserDescr}
         {BANK-IBAN}~BANK-IBAN~{/BANK-IBAN}
         {BANK-EditLink}<a href="~BANK-EditLink~">Ändern</a>{/BANK-EditLink}
         {BANK-DeleteBankNoConfirm}<a href="~BANK-DeleteBankNoConfirm~">Löschen</a>{/BANK-DeleteBankNoConfirm}
      {/@BANK-Data}
   {/BANK-Data}

   {!BANK-Data}
      Sie haben noch keine Bankverbindung hinterlegt.
   {/!BANK-Data}

   {BANK-NewBankLink}<a href="~BANK-NewBankLink~">Neue Bankverbindung anlegen</a>{/BANK-NewBankLink}

{/BANK-Overview}

{BANK-Edit}
   <form action="~FORM-BankManage~" method="POST">

      {BANK-InputStepOne}
         <!-- Schritt 1 der Eingabe -->
      {/BANK-InputStepOne}

      {BANK-InputStepTwo}
         <!-- Schritt 2 der Eingabe -->
      {/BANK-InputStepTwo}

   </form>
{/BANK-Edit}

{BANK-ConfirmDelete}
   Wollen Sie diese Bankverbindung wirklich löschen?
   <a href="~BANK-DeleteBankConfirm~">Ja, löschen</a>
{/BANK-ConfirmDelete}

Use BANK-Mode_Manage and BANK-Mode_Order to distinguish whether the page was called from the customer account or from the checkout process. You need this distinction mainly for the buttons at the end of the form: in the checkout process the buyer continues to the order afterwards, in the customer account they return to the overview.

The data fields

Eight fields make up a set of bank details. Each follows the same pattern: the tag name without a suffix returns the value, and the suffixes return everything else a complete input field needs.

Field	Meaning
`BANK-Owner`	account holder
`BANK-UserDescr`	freely chosen name for these bank details
`BANK-IBAN`	IBAN
`BANK-BIC`	BIC
`BANK-KoNbr`	account number
`BANK-BLZ`	bank code
`BANK-Bank`	name of the bank
`BANK-Country`	country of the bank

The suffixes

Suffix	Returns	Single tag	Area tag	Negative area tag
no suffix	the value of the field	yes	yes	yes
`_input`	the technical name of the input field	yes	–	–
`_text`	the label from the `shop.config`	yes	yes	yes
`_error`	the string `_error` in case of an error	yes	yes	yes
`_errortext`	the error text from the `shop.config`	yes	yes	yes
`_list`	a ready-made selection list	yes	–	–

None of these tags is a loop tag. They are permitted on ws_bank_manage.htm and ws_place_order.htm.

Which combinations exist

Not every field has every suffix. The following overview shows which combinations are documented.

Field	`_input`	`_text`	`_error`	`_errortext`	`_list`
`BANK-Owner`	yes	yes	yes	yes	–
`BANK-UserDescr`	yes	yes	yes	yes	–
`BANK-IBAN`	yes	–	yes	yes	–
`BANK-BIC`	yes	–	yes	yes	–
`BANK-KoNbr`	yes	yes	yes	yes	–
`BANK-BLZ`	yes	yes	yes	yes	–
`BANK-Bank`	–	yes	yes	yes	yes
`BANK-Country`	yes	yes	yes	–	yes

The IBAN additionally has the suffix _fillin; see the section on SEPA.

A complete input field

<label for="~BANK-Owner_input~" class="~BANK-Owner_error~">
   {BANK-Owner_text}~BANK-Owner_text~{/BANK-Owner_text}
</label>

<input type="text"
       id="~BANK-Owner_input~"
       name="~BANK-Owner_input~"
       value="~BANK-Owner~"
       class="~BANK-Owner_error~">

{BANK-Owner_errortext}
   <span class="fehler">~BANK-Owner_errortext~</span>
{/BANK-Owner_errortext}

As a single tag, _error outputs the string _error and nothing else. This means it can be appended directly to a class name: in case of an error, class="eingabe~BANK-Owner_error~" becomes class="eingabe_error".

The negative area of _error and _errortext applies in two cases: when the form is first called, i.e. before it is submitted, and after a successful validation. It is therefore suitable for a success message, but not as a statement that “this field has been validated and is fine”.

An empty mandatory field triggers the same error as an incorrect entry. _error does not distinguish between the two. The more precise information is in the error text, which differs depending on the check.

The selection lists

BANK-Country_list generates a selection list with the countries of the bank. BANK-Bank_list behaves differently depending on the available data:

Situation	Result
several banks to choose from	a selection list
exactly one bank to choose from	the name as text plus a hidden input field
no bank to choose from	a free input field

Design the area around BANK-Bank_list so that it works in all three cases. A fixed label such as “Please select your bank” does not fit if an input field ends up there.

Saved bank details

Tag	Single tag	Area tag	Negative area tag	Loop tag
`BANK-Data`	yes	yes	yes	yes
`BANK-Position`	yes	–	–	–
`BANK-BankSelection`	–	yes	yes	–
`BANK-AccountSelected`	–	yes	yes	–
`BANK-MultipleDataInput`	–	yes	yes	–
`BANK-MultipleDataInputSelection`	yes	yes	yes	–
`BANK-SingleDataInput`	–	yes	yes	–
`BANK-SavedIndex`	yes	yes	yes	–
`BANK-ExternalID`	yes	yes	yes	–

BANK-Data

As a single tag, the number of saved bank details; as an area tag, the bracket around the list; as a loop, one iteration per set of bank details. It is the only tag in this group that is permitted in all templates.

BANK-Position

Outputs the sequential number within the loop.

BANK-BankSelection

The area is displayed when saved bank data is available for selection. Within this bracket you build the selection list from the loop over BANK-Data.

{BANK-BankSelection}
   <select name="~BANK-BankSelection_input~">
      {@BANK-Data}
         <option value="~BANK-BankSelection_code~" ~BANK-BankSelection_selected~>
            {BANK-UserDescr}~BANK-UserDescr~{/BANK-UserDescr}
            {BANK-IBAN}~BANK-IBAN~{/BANK-IBAN}
         </option>
      {/@BANK-Data}
   </select>
{/BANK-BankSelection}

Four suffixes belong to it:

Tag	Returns
`BANK-BankSelection_input`	the technical name of the selection list
`BANK-BankSelection_code`	the value for an option’s `value`
`BANK-BankSelection_selected`	the `selected` attribute for the chosen bank details
`BANK-BankSelection_error`	the string `_error` if the selection was invalid

These four suffix tags work exclusively within the positive bracket {BANK-BankSelection}. Outside it they are invalid. The same applies to the data field tags that you display in the selection list.

BANK-AccountSelected

The area is displayed when the buyer has selected saved bank details. The negative area applies if none was selected or none is available.

BANK-MultipleDataInput and BANK-SingleDataInput

These two tags distinguish whether the buyer can save multiple sets of bank details or only enters a single one.

{BANK-MultipleDataInput}
   <!-- Auswahl aus gespeicherten Konten und Möglichkeit, ein weiteres anzulegen -->
{/BANK-MultipleDataInput}

{BANK-SingleDataInput}
   <!-- Einfaches Eingabeformular für eine einmalige Eingabe -->
{/BANK-SingleDataInput}

The difference depends on the customer account: only logged-in users can save multiple sets of bank details. A guest buyer enters their data once, so BANK-SingleDataInput applies to them.

BANK-MultipleDataInputSelection

The selection list of saved bank details on the order overview.

BANK-SavedIndex

Outputs the index of the bank details that were saved or updated with the last action. The area only applies if something was actually saved.

{MSG-Bank_Notify}
   ~MSG-Bank_Notify~
   {BANK-SavedIndex}
      <!-- Weiterleitung mit ~BANK-SavedIndex~ als Parameter -->
   {/BANK-SavedIndex}
{/MSG-Bank_Notify}

The tag is mainly used in the subscription module to redirect back to the product detail view after bank details have been created, passing along the new bank details.

BANK-ExternalID

Outputs the external identifier of the bank details, i.e. the identifier from a connected third-party system.

Tag	Single tag	Area tag	Negative area tag	Permitted in
`BANK-NewBankLink`	yes	yes	yes	both templates
`BANK-EditLink`	yes	yes	yes	both templates
`BANK-OverviewLink`	yes	–	–	`ws_bank_manage.htm`
`BANK-ToOrderLink`	yes	–	–	`ws_bank_manage.htm`
`BANK-ConfirmDelete`	–	yes	yes	`ws_bank_manage.htm`
`BANK-DeleteBankConfirm`	yes	yes	yes	`ws_bank_manage.htm`
`BANK-DeleteBankNoConfirm`	yes	yes	yes	`ws_bank_manage.htm`

BANK-NewBankLink

Returns the link for creating new bank details. As an area tag, it only applies if new bank details may be created.

{BANK-NewBankLink}
   <a href="~BANK-NewBankLink~">Neue Bankverbindung anlegen</a>
{/BANK-NewBankLink}

BANK-EditLink

Returns the link for editing the bank details. As an area tag, it only applies if they may be edited.

{BANK-EditLink}
   <a href="~BANK-EditLink~">Ändern</a>
{/BANK-EditLink}

Both links belong inside their bracket. The shop decides whether editing or creating is allowed, and a link to a forbidden action leads nowhere.

BANK-OverviewLink and BANK-ToOrderLink

BANK-OverviewLink leads back to the overview of bank details; BANK-ToOrderLink cancels the input and leads back to ws_place_order.htm.

{BANK-Mode_Manage}
   <a href="~BANK-OverviewLink~">Zur Übersicht</a>
{/BANK-Mode_Manage}

{BANK-Mode_Order}
   <a href="~BANK-ToOrderLink~">Weiter zur Bestellung</a>
{/BANK-Mode_Order}

Deleting

There are two ways to delete, with and without a confirmation prompt.

Tag	Role
`BANK-DeleteBankNoConfirm`	link that deletes immediately
`BANK-ConfirmDelete`	area containing the confirmation prompt
`BANK-DeleteBankConfirm`	button that confirms the deletion after the prompt

{@BANK-Data}
   {BANK-DeleteBankNoConfirm}
      <a href="~BANK-DeleteBankNoConfirm~">Löschen</a>
   {/BANK-DeleteBankNoConfirm}
{/@BANK-Data}

{BANK-ConfirmDelete}
   Wollen Sie diese Bankverbindung wirklich löschen?
   <a href="~BANK-DeleteBankConfirm~">Ja, löschen</a>
   <a href="~BANK-OverviewLink~">Abbrechen</a>
{/BANK-ConfirmDelete}

BANK-DeleteBankNoConfirm deletes without asking. Use the route via BANK-ConfirmDelete and BANK-DeleteBankConfirm if the bank details should not disappear with a misclick.

The negative areas of the two delete tags are intended for an error message if deletion was not possible. The positive area of BANK-DeleteBankConfirm, on the other hand, is the success message after deletion. The two tags therefore have a different meaning depending on their form.

Page states

These six tags are pure area tags and determine which part of the template currently applies. None of them can be used as a single tag.

Tag	Applies when
`BANK-Overview`	the overview of bank details was selected
`BANK-Edit`	bank details are being edited
`BANK-InputStepOne`	step 1 of the input is displayed
`BANK-InputStepTwo`	step 2 of the input is displayed
`BANK-Mode_Manage`	the page was called from the customer account
`BANK-Mode_Order`	the page was called from the checkout process

The two steps separate entering the account data from confirming it. You decide in the template which fields appear in which step. Both areas belong in the same form.

SEPA

Tag	Single tag	Area tag	Negative area tag
`BANK-SEPAMode`	–	yes	yes
`BANK-SEPADirectMandateType()`	yes	yes	yes
`BANK-SEPALastDirectMandate`	yes	yes	yes
`BANK-NoSEPABankDataExists`	–	yes	yes
`BANK-IBAN_fillin`	yes	yes	yes

BANK-SEPAMode

The area is displayed when SEPA mode is active, i.e. set to on or test. The negative area applies for off.

BANK-SEPADirectMandateType()

Without a parameter, the single tag outputs the type of the mandate. With a parameter, you check for a specific type.

Parameter	Positive area applies when
0	there is no mandate
1	there is a one-off mandate
2	there is a recurring mandate

{BANK-SEPADirectMandateType(2)}
   Für diese Bankverbindung liegt ein wiederkehrendes Mandat vor.
{/BANK-SEPADirectMandateType(2)}

{BANK-SEPADirectMandateType(0)}
   Für diese Bankverbindung liegt noch kein Mandat vor.
{/BANK-SEPADirectMandateType(0)}

The negative area reverses the respective statement. {!BANK-SEPADirectMandateType(0)} therefore applies when there is a mandate, regardless of its type.

BANK-SEPALastDirectMandate

Outputs the most recently used mandate number.

BANK-NoSEPABankDataExists

The area is displayed when account data exists for this customer that does not correspond to the SEPA format, i.e. still uses account number and bank code instead of IBAN and BIC.

Use this to remind existing customers that they should switch their bank details to IBAN before the old data can no longer be used.

BANK-IBAN_fillin

Outputs the IBAN partially masked, in the form DE123456______123.

At least five characters are masked.
Up to twelve characters at the beginning remain in plain text.
Three characters at the end remain in plain text.
The length of the entered IBAN is preserved.

{BANK-IBAN_fillin}
   IBAN: ~BANK-IBAN_fillin~
{/BANK-IBAN_fillin}

{!BANK-IBAN_fillin}
   Keine IBAN vorhanden.
{/!BANK-IBAN_fillin}

This tag is intended exclusively for the SEPA mandate PDFs, i.e. for the templates entered in the shop.config in the <CustomerMail> section under SEPACustomerPDFTemplate and SEPACompanyPDFTemplate, for example pdf_sepa_customer.htm and pdf_sepa_company.htm. Do not use it as general masking on shop pages.

Guide: Direct debit
Guide: Customer account
Guide: Subscription module
Reference: CustomerMail section

​The framework of the management page

​The data fields

​The suffixes

​Which combinations exist

​A complete input field

​The selection lists

​Saved bank details

​BANK-Data

​BANK-Position

​BANK-BankSelection

​BANK-AccountSelected

​BANK-MultipleDataInput and BANK-SingleDataInput

​BANK-MultipleDataInputSelection

​BANK-SavedIndex

​BANK-ExternalID

​Navigation and actions

​BANK-NewBankLink

​BANK-EditLink

​BANK-OverviewLink and BANK-ToOrderLink

​Deleting

​Page states

​SEPA

​BANK-SEPAMode

​BANK-SEPADirectMandateType()

​BANK-SEPALastDirectMandate

​BANK-NoSEPABankDataExists

​BANK-IBAN_fillin

​Related topics

The framework of the management page

The data fields

The suffixes

Which combinations exist

A complete input field

The selection lists

Saved bank details

BANK-Data

BANK-Position

BANK-BankSelection

BANK-AccountSelected

BANK-MultipleDataInput and BANK-SingleDataInput

BANK-MultipleDataInputSelection

BANK-SavedIndex

BANK-ExternalID

Navigation and actions

BANK-NewBankLink

BANK-EditLink

BANK-OverviewLink and BANK-ToOrderLink

Deleting

Page states

SEPA

BANK-SEPAMode

BANK-SEPADirectMandateType()

BANK-SEPALastDirectMandate

BANK-NoSEPABankDataExists

BANK-IBAN_fillin

Related topics