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

# BANK- (bank data)

> The tags for entering and managing bank details: data fields with their suffixes, saved accounts, page states and SEPA mandates.

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.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{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}
```

> [!NOTE]
>
> 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

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
<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}
```

> [!NOTE]
>
> 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"`.

> [!NOTE]
>
> 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".

> [!WARNING]
>
> 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 |

> [!WARNING]
>
> 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`.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{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 |

> [!WARNING]
>
> 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.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{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}
```

> [!NOTE]
>
> 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.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{MSG-Bank_Notify}
   ~MSG-Bank_Notify~
   {BANK-SavedIndex}
      <!-- Weiterleitung mit ~BANK-SavedIndex~ als Parameter -->
   {/BANK-SavedIndex}
{/MSG-Bank_Notify}
```

> [!NOTE]
>
> 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.

## Navigation and actions

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

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{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.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{BANK-EditLink}
   <a href="~BANK-EditLink~">Ändern</a>
{/BANK-EditLink}
```

> [!NOTE]
>
> 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`.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{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 |

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{@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}
```

> [!WARNING]
>
> `BANK-DeleteBankNoConfirm` deletes without asking. Use the route via `BANK-ConfirmDelete` and `BANK-DeleteBankConfirm` if the bank details should not disappear with a misclick.

> [!NOTE]
>
> 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 |

> [!NOTE]
>
> 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 |

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{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)}
```

> [!NOTE]
>
> 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.

> [!NOTE]
>
> 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.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{BANK-IBAN_fillin}
   IBAN: ~BANK-IBAN_fillin~
{/BANK-IBAN_fillin}

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

> [!WARNING]
>
> 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.

## Related topics

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


## Related topics

- [CC- (credit card data)](https://dokumentation.websale.de/en/v8s/referenz/tags/cc.md)
- [Buttons for payment methods](https://dokumentation.websale.de/en/v8s/referenz/tags/bt/zahlungsarten.md)
- [API reference customer data](https://dokumentation.websale.de/en/schnittstellen/admin-interface-api/api-referenz-kundendaten.md)
- [SUBS- (managing subscriptions)](https://dokumentation.websale.de/en/v8s/referenz/tags/subs/abos-verwalten.md)
- [Styles for customer and addresses](https://dokumentation.websale.de/en/v8s/referenz/styles/kunde-und-adressen.md)


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