XS2A Quickstart

Straight to the Docs

SDKs available!

We are working on client- and serverside libraries for easy integration of XS2A. Check them out below:

Serverside Libraries Clientside Libraries

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.
    Please note that following code example is using the composer package nategood/httpful. You have to execute composer require nategood/httpful before you are able to use it. 
    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;
    npm i @fintecsystems/xs2a-node --save
    const { XS2A } = require('@fintecsystems/xs2a-node');

const xs2a = new XS2A('your-api-key');
try {
	const { wizard_session_key } = await xs2a.Pay.create({
		amount: 35,
		currency_id: 'EUR',
		purpose: 'Order No. 123456',
		recipient_iban: 'DE04888888880087654321',
		recipient_holder: 'MyCompany Inc.'
	});

	// Use wizard_session_key as described in the next steps
} catch (e) {
	// ...
}

    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."
}
    The response will look as follows: 
    {
	wizard_session_key: 'FN9UYDbsLEuQI5zcR4HGeFYvRT6uHAMvuOgwdAKI',
	transaction: '10001-xp-UBTe-9sZw'
}
  • 2
    Implement xs2a.js on your page
    The xs2a.js library can be embedded into the <head> section of your website. We strongly urge you to hotlink both files directly from our XS2A server. This will ensure you will always use the latest build. 
    <script src="https://api.xs2a.com/xs2a.js"></script>
  • 3
    Include the Wizard Container
    To display the xs2a wizard, you have to include a container inside your HTML body. 
    <noscript>
  <h2>Your browser does not support JavaScript.</h2>
  Please deactivate JavaScript Blocker, AdBlocker etc. to use the service.
</noscript>
<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. 
    <noscript>
  <h2>Your browser does not support JavaScript.</h2>
  Please deactivate JavaScript Blocker, AdBlocker etc. to use the service.
</noscript>
<div id="XS2A-Form" data-xs2a="your-wizard-session-key-here"></div>

<script>
// Loads the styling of the library on which you can base your custom css on
xs2a.useBaseStyles();

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.
  • 6
    Update payment status
    In cases where you might have information about the reconciliation status of the transaction we kindly ask you to inform us via our manual overwrite status functionality for status lost and received. There are 2 different endpoints in place:

    https://api.xs2a.com/v1/payments/{transaction-id}/received
    https://api.xs2a.com/v1/payments/{transaction-id}/loss
Check full XS2A.pay Docs

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.
    Please note that following code example is using the composer package nategood/httpful. You have to execute composer require nategood/httpful before you are able to use it. 
    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;
    npm i @fintecsystems/xs2a-node --save
    const { XS2A } = require('@fintecsystems/xs2a-node');
const xs2a = new XS2A('your-api-key');
try {
	const { wizard_session_key } = await xs2a.Risk.create({
		xs2a_account_snapshot: {
			days: 365
		}
	});

	// Use wizard_session_key as described in the next steps
} catch (e) {
	// Handle errors ...
}

    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
	}
}
    The response will look as follows: 
    {
	wizard_session_key: '5m60tWWUZcT2lSTuZbZ7bRa8mJ3Axm8ki44HaBHV',
	transaction: '10001-xr-L8Ub-keuK'
}
  • 3
    Implement xs2a.js on your page
    The xs2a.js library can be embedded into the <head> section of your website. We strongly urge you to hotlink both files directly from our XS2A server. This will ensure you will always use the latest build. 
    <script src="https://api.xs2a.com/xs2a.js"></script>
  • 4
    Include the Wizard Container
    To display the xs2a wizard, you have to include a container inside your HTML body. 
    <noscript>
  <h2>Your browser does not support JavaScript.</h2>
  Please deactivate JavaScript Blocker, AdBlocker etc. to use the service.
</noscript>
<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. 
    <noscript>
  <h2>Your browser does not support JavaScript.</h2>
  Please deactivate JavaScript Blocker, AdBlocker etc. to use the service.
</noscript>
<div id="XS2A-Form" data-xs2a="5m60tWWUZcT2lSTuZbZ7bRa8mJ3Axm8ki44HaBHV"></div>

<script>
// Loads the styling of the library on which you can base your custom css on
xs2a.useBaseStyles();

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}
      For all other risk checks, use this endpoint.
Check full XS2A.risk Docs

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.

Full API Docs Guide

Serverside Libraries

XS2A Node.js

Talk to XS2A API from within your Node.js environment.

NPM
XS2A PHP

Talk to XS2A API from within your PHP environment.

Coming Soon

XS2A Java SDK
API Reference

See the detailed reference for all endpoints of XS2A API.

OpenAPI/Swagger Docs

Clientside Libraries

XS2A iOS

Optimized UX for your customers on iOS using our native SDK.

XS2A Android

Optimized UX for your customers on Android using our native SDK.

XS2A React Native

Optimized UX for your customers using our React Native SDK.

XS2A JS

Optimized UX for integration on your website using our JS-Widget.

Documentation