XS2A Quickstart

Integrate XS2A.pay

XS2A.pay offers a payment solution. The customer uses his online banking credentials. Optional security checks will be executed to counter fraud and other suspicious activity. After that the transfer of a fixed amount and purpose will be sent to a predefined recipient account. The customer authorizes the transaction with a TAN after which the bank is executing the transfer.

To use our API, make sure you have a Test-API key. If you don't have one yet, you can grab one here.

  • 1

    Call XS2A API
    Make a call to our API to create a XS2A.pay object. Don't forget to include the required parameters, such as amount to be paid, currency_id, purpose of the payment, recipient_holder and recipient_iban.
    require 'vendor/autoload.php';
    
    $apiKey = 'your-api-key';
    
    $payload = [
    	'amount' => 35,
    	'currency_id' => 'EUR',
    	'purpose' => 'Order No 123456',
    	'recipient_iban' => 'DE04888888880087654321',
    	'recipient_holder' => 'MyCompany Inc.',
    ];
    
    $response = \Httpful\Request::post('https://api.xs2a.com/v1/payments')
    	->sendsJson()
    	->authenticateWith('api', $apiKey)
    	->body(json_encode($payload))
    	->send();
    
    echo $response->body->transaction;
    echo $response->body->wizard_session_key;
    const request = require("request-promise");
    
    var apiKey = 'YOUR_API_KEY_GOES_HERE';
    const options = { 
    	method: 'POST',
    	url: 'https://api.xs2a.com/v1/payments',
    	headers: { 
    		'Cache-Control': 'no-cache',
    		'Authorization': 'Basic ' + Buffer.from("api:" + apiKey).toString('base64'),
    		'Content-Type': 'application/json' 
    	},
    	body: { 
    		amount: 35,
    		currency_id: 'EUR',
    		purpose: 'Order No. 123456',
    		recipient_iban: 'DE04888888880087654321',
    		recipient_holder: 'MyCompany Inc.'
    	},
    	json: true 
    };
    
    request(options)
    	.then((body) => {
    		console.log(body);
    	})
    	.catch((error) => {
    		throw new Error(error);
    	});
    POST /v1/payments HTTP/1.1
    Host: api.xs2a.com
    Content-Type: application/json
    Authorization: Basic base64("api:YOUR_API_KEY_GOES_HERE")
    Cache-Control: no-cache
    
    {
    	"amount": 35,
    	"currency_id": "EUR",
    	"purpose": "Order No. 123456",
    	"recipient_iban": "DE04888888880087654321",
    	"recipient_holder": "MyCompany Inc."
    }
    OkHttpClient client = new OkHttpClient();
    
    String apiKey = "YOUR_API_KEY_GOES_HERE";
    String auth = "api:" + apiKey;
    
    MediaType mediaType = MediaType.parse("application/json");
    RequestBody body = RequestBody.create(mediaType, "{\n\t\"amount\": 35,\n\t\"currency_id\": \"EUR\",\n\t\"purpose\": \"Order No. 123456\",\n\t\"recipient_iban\": \"DE04888888880087654321\",\n\t\"recipient_holder\": \"MyCompany Inc.\"\n}");
    Request request = new Request.Builder()
    	.url("https://api.xs2a.com/v1/payments")
    	.post(body)
    	.addHeader("Content-Type", "application/json")
    	.addHeader("Authorization", "Basic " + new String(Base64.encodeBase64(auth.getBytes(StandardCharsets.ISO_8859_1))))
    	.addHeader("Cache-Control", "no-cache")
    	.build();
    
    Response response = client.newCall(request).execute();
    The response will look as follows:
    {
    	wizard_session_key: 'FN9UYDbsLEuQI5zcR4HGeFYvRT6uHAMvuOgwdAKI',
    	transaction: '10001-xp-UBTe-9sZw'
    }
  • 2

    Implement xs2a.js on your page
    Both libraries can be embedded into the <head> section of your website. We suggest to hotlink both files directly from our XS2A server. This will ensure you will always use the latest build of both files.
    <script src="https://api.xs2a.com/xs2a.js"></script>
    <link rel="stylesheet" href="https://api.xs2a.com/xs2a.css">
  • 3

    Include the Wizard Container
    To display the xs2a wizard, you have to include a container inside your HTML body.
    <div id="XS2A-Form" data-xs2a="<your-wizard-session-key-here>"></div>
  • 4

    Start the Payment Session
    With the wizard_session_key from the response from step 1, start the session by using the key as described in step 3. Save the transaction id from the response to get details about it later.
    <div id="XS2A-Form" data-xs2a="FN9UYDbsLEuQI5zcR4HGeFYvRT6uHAMvuOgwdAKI"></div>
    											
    <script>
    xs2a.finish(function() {
    	// Called when the session is finished
    	document.location.href = 'your-success-link';
    });
    
    xs2a.abort(function() {
    	// Called when the session is aborted
    	document.location.href = 'your-abort-link';
    });
    
    // Start the wizard
    xs2a.init();
    </script>
  • 5

    Let the User finish the Payment Session
    The user is now clicking through the xs2a wizard and makes the payment. In the background, we initiate the payment for you.

Integrate XS2A.risk

XS2A.risk allows you to collect and validate a bank connection. Additionally a range of predefined checks can be applied using the retrieved account information.

To use our API, make sure you have a Test-API key. If you don't have one yet, you can grab one here.

  • 1

    Decide which Risk Checks you want to use
    From our documentation, find the right risk check you want to use for your application. Available Checks
  • 2

    Call XS2A API
    Make a call to our API and include the chosen risk checks from step 1 in the body. In this example, xs2a_account_snapshot is used.
    require 'vendor/autoload.php';
    
    $apiKey = 'your-api-key';
    
    $payload = [
    	'xs2a_account_snapshot' => [
    		'days' => 365,
    	],
    ];
    
    $response = \Httpful\Request::post('https://api.xs2a.com/v1/risks')
    	->sendsJson()
    	->authenticateWith('api', $apiKey)
    	->body(json_encode($payload))
    	->send();
    
    echo $response->body->transaction;
    echo $response->body->wizard_session_key;
    const request = require("request-promise");
    
    var apiKey = 'YOUR_API_KEY_GOES_HERE';
    const options = { 
    	method: 'POST',
    	url: 'https://api.xs2a.com/v1/risks',
    	headers: {
    		'Cache-Control': 'no-cache',
    		'Authorization': 'Basic ' + Buffer.from("api:" + apiKey).toString('base64'),
    		'Content-Type': 'application/json' 
    	},
    	body: { 
    		xs2a_account_snapshot: { 
    			days: 365 
    		} 
    	},
    	json: true
    };
    
    request(options)
    	.then((body) => {
    		console.log(body);
    	})
    	.catch((error) => {
    		throw new Error(error);
    	});
    POST /v1/risks HTTP/1.1
    Host: api.xs2a.com
    Content-Type: application/json
    Authorization: Basic base64("api:YOUR_API_KEY_GOES_HERE")
    Cache-Control: no-cache
    
    {
    	"xs2a_account_snapshot":{
    	"days":365
    	}
    }
    OkHttpClient client = new OkHttpClient();
    String apiKey = "YOUR_API_KEY_GOES_HERE";
    String auth = "api:" + apiKey;
    
    MediaType mediaType = MediaType.parse("application/json");
    RequestBody body = RequestBody.create(mediaType, "{\n\t\"xs2a_account_snapshot\":{\n\t\"days\":365\n\t\t\n\t}\n}");
    Request request = new Request.Builder()
    	.url("https://api.xs2a.com/v1/risks")
    	.post(body)
    	.addHeader("Content-Type", "application/json")
    	.addHeader("Authorization", "Basic " + new String(Base64.encodeBase64(auth.getBytes(StandardCharsets.ISO_8859_1))))
    	.addHeader("Cache-Control", "no-cache")
    	.build();
    
    Response response = client.newCall(request).execute();
    The response will look as follows:
    { 
    	wizard_session_key: '5m60tWWUZcT2lSTuZbZ7bRa8mJ3Axm8ki44HaBHV',
    	transaction: '10001-xr-L8Ub-keuK' 
    }
  • 3

    Implement xs2a.js on your page
    Both libraries can be embedded into the <head> section of your website. We suggest to hotlink both files directly from our XS2A server. This will ensure you will always use the latest build of both files.
    <script src="https://api.xs2a.com/xs2a.js"></script>
    <link rel="stylesheet" href="https://api.xs2a.com/xs2a.css">
  • 4

    Include the Wizard Container
    To display the xs2a wizard, you have to include a container inside your HTML body.
    <div id="XS2A-Form" data-xs2a="<your-wizard-session-key-here>"></div>
  • 5

    Start the Wizard Session
    With the wizard_session_key from the response from step 2, start the session by using the key as described in step 4. Save the transaction id from the response to retrieve the results later.
    <div id="XS2A-Form" data-xs2a="5m60tWWUZcT2lSTuZbZ7bRa8mJ3Axm8ki44HaBHV"></div>
    
    <script>
    xs2a.finish(function() {
    	// Called when the session is finished
    	document.location.href = 'your-success-link';
    });
    
    xs2a.abort(function() {
    	// Called when the session is aborted
    	document.location.href = 'your-abort-link';
    });
    
    // Start the wizard
    xs2a.init();
    </script>
    											
  • 6

    Let the User finish the Wizard Session
    The user is now clicking through the xs2a wizard and logs into his bank account. We collect the requested checks for you.
  • 7

    Retrieve your Results
    After the user finished the session, you can retrieve the results for your requested check. Use the transaction id from step 5 for retrieving them. There are 3 different endpoints for retrieving results, depending on the checks you have requested:
    • GET /v1/risks/{transaction-id}/accountSnapshot?format=json
      If you requested an xs2a_account_snapshot, you can retrieve the results for it at this endpoint.
    • GET /v1/risks/{transaction-id}/factSheet?format=json
      If you requested an xs2a_fact_sheet, you can retrieve the results for it at this endpoint.
    • GET /v1/risks/{transaction-id}
      For all other risk checks, use this endpoint.

Dive in deeper?

Here you can view the complete XS2A documentation in the Swagger format. It is also possible to generate a client from it using the Swagger file which you can download at the top of the documentation.