Guide to XS2A


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.


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.

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