OnlineBankingXS2A: Examples

Initiation of a single payment

The initiation of a single payment is a use case that directly involves the PSU (payment services user). The following figure shows the different steps of the process (ok-case). The process steps that are part of the communication with the ASPSP (account holding payment services provider) are marked in red.

It should be noted that both an interaction between TPP (third party provider) and ASPSP via REST calls and a direct communication between ASPSP and PSU (SCA redirect approach) takes place during the process.

The above figure contains two REST operations.

POST /v1/{payment-service}/{payment-product} initiates a payment at aspsp.
GET /v1/{payment-service}/{payment-product}/{paymentId} retrieves the status of the payment initiation.

Example

Request

POST /v1/payments/sepa-credit-transfers HTTP/1.1
Content-Type: application/json
X-Request-ID: e298b732-efb9-46b3-bac9-cebc48966226
PSU-IP-Address: 123.456.789.000
TPP-Redirect-URI: https://tpp-ok-redirect-uri.com
TPP-Nok-Redirect-URI: https://tpp-nok-redirect-uri.com

{
	"instructedAmount": {
		"currency": "EUR", 
		"amount": "12.34"
	},
	"debtorAccount": {
		"iban": "DE12345678901234567890"
	},
	"creditorName": "Max Muster",
	"creditorAccount": {
		"iban": "DE09876543210987654321"
	},
	"remittanceInformationUnstructured": "This text contains remittance information"
}

The TPP initiates a payment at the ASPSP and passes a URL for the redirect of the PSU after successful authorization as header parameter TPP-Redirect-URI (amongst others).

Response

HTTP/1.1 201 Created
X-Request-ID: e298b732-efb9-46b3-bac9-cebc48966226
ASPSP-SCA-Approach: ASPSP-SCA-Approach
Content-Type: application/json

{
	"transactionStatus": "RCVD",
	"paymentId": "8db85f44-5832-4ae1-b0bb-596bc253694a",
	"_links": {
		"scaStatus": {
			"href": "/v1/payments/sepa-credit-transfers/8db85f44-5832-4ae1-b0bb-596bc253694a/authorisations/43f29432-dc81-4fb1-9335-f5ae0572b995"
		},
		"scaRedirect": {
			"href": "https://aspspurl.com/xs2a/auth/login?auuid=43f29432-dc81-4fb1-9335-f5ae0572b995"
		},
		"self": {
			"href": "/v1/payments/sepa-credit-transfers/8db85f44-5832-4ae1-b0bb-596bc253694a"
		},
		"status": {
			"href": "/v1/payments/sepa-credit-transfers/8db85f44-5832-4ae1-b0bb-596bc253694a/status"
		}
	}
}

Once the payment initiation has been accepted, the interface responds accordingly and provides several links to the TPP. In addition to REST endpoints for accessing the created resources (a payment resource, a payment status resource and a SCA status resource), the response also contains the URL of the authorization website to which the TPP forwards the PSU. On this website the PSU can authenticate himself and authorize the payment. Afterwards the PSU is redirected to the URL previously provided by the TPP.

To query the status of the created payment initiation resource, the TPP can make the corresponding call.

Example

Request

GET /v1/payments/sepa-credit-transfers/8db85f44-5832-4ae1-b0bb-596bc253694a/status HTTP/1.1
X-Request-ID: eebee5a1-e0f5-4611-a125-c3640d21e162

Response

HTTP/1.1 200 OK
X-Request-ID: eebee5a1-e0f5-4611-a125-c3640d21e162
Content-Type: application/json

{
	"transactionStatus": "ACSP"
}

To retrieve account information (see Get accounts, Get balances for a given account), the TPP must pass a valid consent id. To do this, a consent resource must first be created. This method directly involves the PSU and is similar to the initiation of a payment.

A consent is valid for a maximum of 180 days. If a higher date is specified in the field validUntil, the consent is automatically created with the maximum validity period.

If the consent is used to query transactions, please note: In general, the transactions on the corresponding account of the last 90 days are returned. An exception exists if the PSU has performed a SCA immediately before. In this case, a query returns all available transactions.

Consents can be explicitly defined by the TPP or specified within the redirect UI by the PSU.

Explicit consent creation

Example

Request

POST /v1/consents HTTP/1.1
Content-Type: application/json
X-Request-ID: aebee5a1-e0f5-4611-a125-c3640d21e162
PSU-IP-Address: 123.456.789.000
TPP-Redirect-URI: https://tpp-ok-redirect-uri.com
TPP-Nok-Redirect-URI: https://tpp-nok-redirect-uri.com

{
	"access": {

		"accounts": [
			{ "iban": "DE12345678901234567890" },
			{ "iban": "DE11112222333344445555" }
		],
		"balances": [
			{ "iban": "DE12345678901234567890" }
		],
		"transactions": [
			{ "iban": "DE99998888777766665555" }
		]
	},
	"recurringIndicator": true,
	"validUntil": "9999-04-04",
	"frequencyPerDay": "4",
	"combinedServiceIndicator": false
}

To create a consent resource explicitly, the TPP must specify the corresponding account identifiers (IBANs) and dedicate them to the requested information (account information, balances and/or transactions). In addition, information on the type and scope of the queries can be provided (see Method description and Consents data type).

Response

HTTP/1.1 201 Created
X-Request-ID: aebee5a1-e0f5-4611-a125-c3640d21e162
ASPSP-SCA-Approach: ASPSP-SCA-Approach
Content-Type: application/json

{
	"consentStatus": "received",
	"consentId": "26bc083e-b241-4f15-807a-48736d150426",
	"_links": {
		"scaStatus": {
			"href": "/v1/consents/26bc083e-b241-4f15-807a-48736d150426/authorisations/bebee5a1-e0f5-4611-a125-c3640d21e162"
		},
		"scaRedirect": {
			"href": "https://efdis-online.de/xs2a/auth/login?auuid=bebee5a1-e0f5-4611-a125-c3640d21e162"
		},
		"self": {
			"href": "/v1/consents/26bc083e-b241-4f15-807a-48736d150426"
		},
		"status": {
			"href": "/v1/consents/26bc083e-b241-4f15-807a-48736d150426/status"
		}
	}
}

Once the consent creation has been accepted, the interface responds accordingly and provides several links to the TPP. In addition to REST endpoints for accessing the created resources (a consent resource, a consent status resource and a SCA status resource), the response also contains the URL of the authorization website to which the TPP forwards the PSU. On this website the PSU can authenticate himself and authorize the consent creation. Afterwards the PSU is redirected to the URL previously provided by the TPP.

Consent specification by PSU

Alternatively it is possible to pass the parameters accounts, balances and transactions empty. In this case, the PSU can make a selection from its accounts after authentication within the redirect UI (link to the authorization website is provided in response). The accounts for which a consent has been issued can subsequently be retrieved by the TPP via GET.

Example

Request

POST /v1/consents HTTP/1.1
Content-Type: application/json
X-Request-ID: aebee5a1-e0f5-4611-a125-c3640d21e162
PSU-IP-Address: 123.456.789.000
TPP-Redirect-URI: https://tpp-ok-redirect-uri.com
TPP-Nok-Redirect-URI: https://tpp-nok-redirect-uri.com

{
	"access": {

		"accounts": [],
		"balances": [],
		"transactions": []
	},
	"recurringIndicator": true,
	"validUntil": "9999-04-04",
	"frequencyPerDay": "4",
	"combinedServiceIndicator": false
}

Response

HTTP/1.1 201 Created
X-Request-ID: aebee5a1-e0f5-4611-a125-c3640d21e162
ASPSP-SCA-Approach: ASPSP-SCA-Approach
Content-Type: application/json

{
	"consentStatus": "received",
	"consentId": "26bc083e-b241-4f15-807a-48736d150426",
	"_links": {
		"scaStatus": {
			"href": "/v1/consents/26bc083e-b241-4f15-807a-48736d150426/authorisations/bebee5a1-e0f5-4611-a125-c3640d21e162"
		},
		"scaRedirect": {
			"href": "https://efdis-online.de/xs2a/auth/login?auuid=bebee5a1-e0f5-4611-a125-c3640d21e162"
		},
		"self": {
			"href": "/v1/consents/26bc083e-b241-4f15-807a-48736d150426"
		},
		"status": {
			"href": "/v1/consents/26bc083e-b241-4f15-807a-48736d150426/status"
		}
	}
}

Get accounts

To retrieve the information of all accounts regarding a specific consent, the /accounts endpoint can be called.

Example

Request

GET /xs2a/rest/v1/accounts?withBalance=true HTTP/1.1
X-Request-ID: ffbee5a1-e0f5-4611-a125-c3640d21e162
Consent-ID: 26bc083e-b241-4f15-807a-48736d150426

Response

HTTP/1.1 200 OK
X-Request-ID: ffbee5a1-e0f5-4611-a125-c3640d21e162
Content-Type: application/json

{
	"accounts": [
		{
			"resourceId": "DE12345678901234567890",
			"iban": "DE12345678901234567890",
			"currency": "EUR",
			"product": "KK-Konto",
			"bic": "BIC123456",
			"balances": [
				{
					"balanceAmount": {
						"currency": "EUR",
						"amount": "12345.67"
					},
					"balanceType": "interimAvailable"
				}
			],
			"_links": {
				"balances": {
					"href": "/v1/accounts/DE12345678901234567890/balances"
				}
			}
		},
		{
			"resourceId": "DE99998888777766665555",
			"iban": "DE99998888777766665555",
			"currency": "EUR",
			"product": "KK-Konto",
			"bic": "BIC123456",
			"_links": {
				"transactions": {
					"href": "/v1/accounts/DE99998888777766665555/transactions"
				}
			}
		},
		{
			"resourceId": "DE11112222333344445555",
			"iban": "DE11112222333344445555",
			"currency": "EUR",
			"product": "KK-Konto",
			"bic": "BIC123456"
		}
	]
}

Get balances for a given account

In order to retrieve balances (or other account information) for a given account, a valid consent is required (see Establish account information consent).

Example

Request

GET /v1/accounts/DE12345678901234567890/balances HTTP/1.1
X-Request-ID: febee5a1-e0f5-4611-a125-c3640d21e162
Consent-ID: 26bc083e-b241-4f15-807a-48736d150426

Response

HTTP/1.1 200 OK
X-Request-ID: febee5a1-e0f5-4611-a125-c3640d21e162
Content-Type: application/json

{
	"account": {
		"iban": "DE12345678901234567890"
	},
	"balances": [
		{
			"balanceAmount": {
				"currency": "EUR",
				"amount": "12345.67"
			},
			"balanceType": "interimAvailable"
		}
	]
}

The TPP can revoke a valid consent using the DELETE method on the resource.

Example

Request

DELETE /v1/consents/26bc083e-b241-4f15-807a-48736d150426 HTTP/1.1
X-Request-ID: 123e4567-e98b-12d3-a456-556642440000

Response

HTTP/1.1 204 No Content
X-Request-ID: 123e4567-e98b-12d3-a456-556642440000
Content-Type: application/json

Examples

Initiation of a single payment

Example

Example

Establish account information consent

Explicit consent creation

Example

Consent specification by PSU

Example

Get accounts

Example

Get balances for a given account

Example

Revoke consent

Example