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

# BILLIE- (Billie direct integration)

> The tags for purchase on invoice via the Billie direct integration: create a checkout session, embed the widget, return the response and evaluate it.

With purchase on invoice via Billie, the buyer check does not take place in the shop but in a widget from Billie. For this, the shop creates a checkout session, passes the order data, and the widget reports its result back.

The tags with the prefix `BILLIE-` provide the building blocks for this process. They belong on the order overview page (`ws_place_order.htm`), because that is where the payment method is decided.

Guide: Billie purchase on invoice

## The process in the template

Four steps belong together, and none of them works on its own.

| Step | Tags |
| - | - |
| Create the session and prepare the widget | `BILLIE-SessionID`, `BILLIE-MerchantName` |
| Pass the order data | `BILLIE-OrderData` |
| Send the response back to the shop | `BILLIE-ResponseDataName`, `BILLIE-ResponseErrorName`, `FORM-BillieResponse` |
| Evaluate the response | `BILLIE-WidgetRawResponse`, `BILLIE-SessionConfirmRawResponse` |

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
<script>
   const billie_config_data = {
      'session_id':    '~BILLIE-SessionID~',
      'merchant_name': '~BILLIE-MerchantName~'
   }

   function ws_payWithBillie() {
      BillieCheckoutWidget.mount({
         billie_config_data: billie_config_data,
         billie_order_data:  ~BILLIE-OrderData~
      })
   }
</script>

<form action="~FORM-BillieResponse~" method="post" id="form_billie_response">
   <input name="~BILLIE-ResponseDataName~"  id="billie_response_data"  type="hidden">
   <input name="~BILLIE-ResponseErrorName~" id="billie_response_error" type="hidden">
</form>
```

> [!WARNING]
>
> `~BILLIE-OrderData~` is placed without quotation marks in the JavaScript, while the other two values are in single quotation marks. This is not a mistake: the order data is already a JSON object, whereas the session ID and the merchant name are strings.

## The session

### BILLIE-SessionID

Outputs the Billie session ID.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
const billie_config_data = {
   'session_id': '~BILLIE-SessionID~'
}
```

> [!WARNING]
>
> This tag creates the checkout session at Billie; it does not just read it. Therefore, only use it where purchase on invoice is actually offered, and not as a precaution on every page. Every page build with this tag communicates with Billie.

As an area tag, it applies if the session could be created. This is the right bracketing around the entire Billie block:

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{BILLIE-SessionID}
   <!-- Widget, Formular und Schaltfläche -->
{/BILLIE-SessionID}

{!BILLIE-SessionID}
   Der Rechnungskauf steht im Moment leider nicht zur Verfügung.
{/!BILLIE-SessionID}
```

> [!NOTE]
>
> The negative area is part of it. Otherwise, if Billie cannot be reached, a payment method is offered whose button does nothing.

### BILLIE-MerchantName

Outputs the configured merchant name that the widget displays. As an area tag, it applies if a name is configured.

### BILLIE-OrderData

Outputs the order data as a JSON object, as the Billie widget expects it.

> [!WARNING]
>
> Do not output the order data yourself and do not modify it. The widget checks it against the session, and deviating values lead to rejection.

## Returning the response

The widget runs in the browser. Its result must therefore be sent back to the shop via a form.

| Tag | Returns |
| - | - |
| `BILLIE-ResponseDataName` | the name of the hidden field for the response |
| `BILLIE-ResponseErrorName` | the name of the hidden field for the error case |

The address of the form is provided by `FORM-BillieResponse`.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
<form action="~FORM-BillieResponse~" method="post" id="form_billie_response">
   <input name="~BILLIE-ResponseDataName~"  id="billie_response_data"  type="hidden">
   <input name="~BILLIE-ResponseErrorName~" id="billie_response_error" type="hidden">
</form>
```

> [!NOTE]
>
> The two `id` attributes can be chosen freely; the JavaScript accesses the fields through them. The `name` attributes cannot: they must come from the tags, otherwise the shop does not recognise the response.

Reference: FORM-BillieResponse

## Evaluating the response

| Tag | Single tag | Area tag | Negative area tag | Returns |
| - | - | - | - | - |
| `BILLIE-WidgetRawResponse` | yes | yes | yes | the widget's response as JSON |
| `BILLIE-SessionConfirmRawResponse` | yes | yes | yes | the response to the session confirmation as JSON |

Both output the content unencoded. As area tags, they apply if any response is present.

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

> [!WARNING]
>
> These two tags are intended for troubleshooting, not for display. The responses contain technical details about the process and do not belong on a page that the buyer sees. Bracket them in test mode or remove them again after setup.

## The payment terms

### BILLIE-Duration

Outputs the configured payment period in days.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
Bitte begleichen Sie Ihre Rechnung innerhalb von ~BILLIE-Duration~ Tagen.
```

| Tag | Single tag | Area tag | Negative area tag | Loop tag |
| - | - | - | - | - |
| `BILLIE-Duration` | yes | – | – | – |
| `BILLIE-SessionID` | yes | yes | yes | – |
| `BILLIE-MerchantName` | yes | yes | yes | – |
| `BILLIE-OrderData` | yes | yes | yes | – |
| `BILLIE-ResponseDataName` | yes | – | – | – |
| `BILLIE-ResponseErrorName` | yes | – | – | – |
| `BILLIE-WidgetRawResponse` | yes | yes | yes | – |
| `BILLIE-SessionConfirmRawResponse` | yes | yes | yes | – |

> [!NOTE]
>
> `BILLIE-Duration` is the only tag in this group that you also need outside the order process, for example on an information page about payment methods. The others belong on the order overview page.

## Related topics

* Guide: Billie purchase on invoice
* Guide: Overview of payment and shipping methods
* Reference: FORM-BillieResponse


## Related topics

- [Enabling and disabling shop test modes](https://dokumentation.websale.de/en/v8s/domains/testmodi-des-shops-ein-ausschalten.md)
- [Payment method codes](https://dokumentation.websale.de/en/v8s/materialien/zahlungsarten-codes.md)
- [Integration of FACT-Finder](https://dokumentation.websale.de/en/v8s/integration-von-fact-finder/integration-von-fact-finder.md)
- [Integration of econda](https://dokumentation.websale.de/en/v8s/integration-von-econda/integration-von-econda.md)
- [Payment methods](https://dokumentation.websale.de/en/v8s/referenz/konfigurationen/shopkonfiguration-shop-config/zahlungsarten.md)


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