Wizard-API

Individual integration with maximum customisation

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.

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.

API documentation

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.

Pseudo Code

# 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();

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.

Payment Platform (XS2A.pay)

Analytics Platform (XS2A.risk)

Open Banking Platform (XS2A.api)

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

Example Response

{
    "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": []
    }
}

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.

Example Request

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