# Wizard-API

{% hint style="warning" %}
Please note that you can only use this option if you have a valid eIDAS certificate. 

Keep in mind that this method of integration requires much more effort than the integration via the Javascript-Widget. Every form, every help text, and every SCA method has to be implemented on your side.
{% endhint %}

## Overview

The Wizard-API is the REST-API alternative to the Javascript-Widget. Instead of integrating a tiny Javascript library on your page, the Wizard-API allows for full control of the customer-facing process.

For more information about the Wizard-API please read our technical documentation.

{% content-ref url="/pages/-MMGaQ6tzY9EXRzTEQcW" %}
[API documentation](/xs2a/integration-cs/getting-started/api-documentation.md)
{% endcontent-ref %}

## How to use

### Basic understanding

The Wizard-API is essentially a series of forms. Every form has to be rendered to the user, the user has to make their inputs. The inputs then have to be sent to the Wizard-API endpoint and the next form has to be rendered.

{% tabs %}
{% tab title="Pseudo Code" %}

```bash
# Step 1: Create a session
let session = createSessionWithXS2A();
let input = [];

# Step 2: Display forms as long as required
while (true) {
    let response = callWizardAPIwithXS2A(session, input);
    
    if (!response.form) {
        # no more forms required
        break;
    }
    
    input = displayFormToUser(response.form);
}

# Step 3: transaction completed
let transaction = fetchTransactionFromXS2A();
```

{% endtab %}
{% endtabs %}

After creating a session the first step would be to initially call the Wizard-API. The following guides will provide information on how a session is generated for a specific product.

{% content-ref url="/pages/-MMGZISLew-2pzZ8yizy" %}
[Payment Platform (XS2A.pay)](/xs2a/integration-cs/platforms/pay.md)
{% endcontent-ref %}

{% content-ref url="/pages/-MMGZLotDlDTXSMT-ne0" %}
[Analytics Platform (XS2A.risk)](/xs2a/integration-cs/platforms/risk.md)
{% endcontent-ref %}

{% content-ref url="/pages/-MMGZN6bQ0XOFqIj0OPM" %}
[Open Banking Platform (XS2A.api)](/xs2a/integration-cs/platforms/api.md)
{% endcontent-ref %}

If the API response contains a form, display that form to the user, collect the inputs and send them off to the Wizard-API endpoint again. If the API response then contains a form, repeat the process. The transaction is finished, if the Wizard-API endpoint does not contain any more forms.

### Example of a form received by the Wizard-API

{% tabs %}
{% tab title="Example Response" %}

```javascript
{
    "code": 200,
    "message": "ok",
    "error": [],
    "polling": {},
    "form": {
        "name": "bank",
        "elements": [
            {
                "type": "select",
                "name": "country_id",
                "selected": "",
                "options": {
                    "DE": "Deutschland",
                    "AT": "\u00d6sterreich",
                    "ES": "Spanien",
                    "FR": "Frankreich",
                    "CH": "Schweiz",
                    "IT": "Italien"
                },
                "label": "Land",
                "validation": "required|in:DE,AT,ES,FR,CH,IT",
                "invalid": false,
                "failed_validation_rules": "",
                "validation_error": ""
            },
            {
                "type": "text",
                "name": "bank_code",
                "value": "",
                "label": "Bankname, BLZ oder IBAN",
                "validation": "required",
                "invalid": false,
                "failed_validation_rules": "",
                "validation_error": ""
            }
        ],
        "parameters": []
    }
}
```

{% endtab %}
{% endtabs %}

All received objects in `elements` must be provided to the user via frontend to give the user the possibility to provide this data. 

### Example of an answer to a form by the Wizard-API

After the data is submitted you need to send this back to the API.

{% tabs %}
{% tab title="Example Request" %}

```bash
curl -X POST --user api:<your_api_key> https://api.xs2a.com/v1/wizard \
 -d key=<your_wizard_session_key> \
 -d country_id=DE \
 -d bank_code=88888888
```

{% endtab %}
{% endtabs %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://guide.xs2a.com/xs2a/integration-cs/integration-variants/wizard-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.