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.

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

// Create a PayService Instance
PayService payService = new PayService(apiKey);

// Build your Pay Session Request
Xs2aPay pay = new Xs2aPay(
	35,
	CurrencyId.EUR,
	"Flowers",
	"Max Mustermann",
	"DE04888888880087654321",
	// other properties such as metadata, language ...
);

// Fire the request and get a response
WizardSessionResponse response = payService.create(pay);
System.out.println(response.getWizardSessionKey());

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

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>

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

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

// Create a RiskService Instance
RiskService riskService = new RiskService(apiKey);

// Build a Risk Request
Xs2aRisk risk = new Xs2aRisk();

Xs2aAccountSnapshot accountSnapShot = new Xs2aAccountSnapshot(
	10,
	LocalDate.parse("2021-01-01"),
	LocalDate.parse("2021-01-10"),
	List.of("income"),
	true,
	true
);
risk.setXs2aAccountSnapshot(accountSnapShot);
// add more risk checks as necessary ...

// Fire the request and get a response
WizardSessionResponse response = riskService.create(risk);

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

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>

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

SDKs available!

Integrate XS2A.pay

Call XS2A API

Implement xs2a.js on your page

Include the Wizard Container

Start the Payment Session

Let the User finish the Payment Session

Update payment status

Integrate XS2A.risk

Decide which Risk Checks you want to use

Call XS2A API

Implement xs2a.js on your page

Include the Wizard Container

Start the Wizard Session

Let the User finish the Wizard Session

Retrieve your Results

Dive in deeper?

Serverside Libraries

XS2A Node.js

XS2A PHP

XS2A Java

API Reference

Clientside Libraries

XS2A iOS

XS2A Android

XS2A React Native

XS2A JS