Initiation and Authorisation of a Payment in Steps

The following is a sample process walkthrough upon the initiation and authorisation of a single payment, where

payment-product - sepa-credit-transfers
SCA approach - Embedded SCA approach.

More about the payment product and models can be found on Payment Products and Services.

Prerequisites

Your certificate must contain the PSP role = PSP_PI.

Step 1 - Payment Initiation

In this step, a payment initiation request with the payment data is sent to XS2A.

XS2A validates the role from the certificate, PSU-ID, and request syntax. If all the validations have been completed successfully, XS2A returns a paymentId.

It means that a payment resource has been created and must be authorised by the PSU.

Created payment resource will be accessible under the given paymentId during 30 minutes from the moment of creation. Authorisation of the given payment must be completed within this time.

If a payment is not authorised and its validity time has expired, access to this resource will be canceled, and payment initiation flow will be terminated.

Flow

Go to /v1/payments/sepa-credit-transfers.
- See XS2A OpenAPI Reference
Fill in mandatory data

Data field	Value
HTTP-Method	`POST`
Header `PSU-ID`	one of PSU-IDs from (OLD) Sandbox Test Accounts and Test Data
Header `PSU-IP-Address`	valid IP address
Header `X-Request-ID`	Random UUID for this request
URL path variable `{payment-product}`	`sepa-credit-transfers`
URL path variable `{payment-service}`	`payments`

Fill in payment data according to the payment model
Execute the request.
The response should have the HTTP status code: 201 - Created
- For examples of the response payload, see XS2A OpenAPI Reference

Step 2 - Payment authorisation initiation

In this step, payment authorisation is initiated.

XS2A validates the role from the certificate, paymentId, and request syntax. If all the validations have been completed successfully, XS2A returns an authorisationId inside the updatePsuAuthentication link.

It means that an authorisation sub-resource has been created for given paymentId.

The created authorisation sub-resource will be accessible under the given authorisationId for 30 minutes from the moment of creation. Authorisation of the given payment must be completed within this time.

If a payment is not authorised and its validity time is over, access to this resource will be canceled, and the payment initiation flow will be terminated.

Flow

Go to /v1/payments/sepa-credit-transfers/{paymentId}/authorisations or follow the startAuthorisation link from the response in Step 1.
- See XS2A OpenAPI Reference
Fill in mandatory data

Data field	Value
HTTP-Method	`POST`
Header `PSU-ID`	same as in Step 1
Header `X-Request-ID`	Random UUID for this request
URL path variable `{payment-product}`	same as in Step 1
URL path variable `{payment-service}`	same as in Step 1
URL path variable `{paymentId}`	`paymentId` received in response of Step 1

Execute the request.
The response should have the HTTP status code: 201 - Created
- For examples of the response payload, see XS2A OpenAPI Reference

Step 3 - Provide PSU password

In this step, a password from the PSU's side must be provided.

Please, use the corresponding password from (OLD) Sandbox Test Accounts and Test Data.

Flow

Go to /v1/payments/sepa-credit-transfers/{paymentId}/authorisations/{authorisationId} or follow the updatePsuAuthentication link from the response in Step 2.
- See XS2A OpenAPI Reference
Fill in mandatory data

Data field	Value
HTTP-Method	`PUT`
Header `PSU-ID`	same as in Step 1
Header `X-Request-ID`	Random UUID for this request
URL path variable `{payment-product}`	same as in Step 1
URL path variable `{payment-service}`	same as in Step 1
URL path variable `{paymentId}`	`paymentId` received in response of Step 1
URL path variable `{authorisationId}`	`authorisationId` received in response of Step 2

Fill in the body with the PSU data (see examples Update PSU [...] in XS2A OpenAPI Reference)
Execute the request
The response should have the HTTP status code: 200 - OK
- For examples of the response payload see XS2A OpenAPI Reference

Step 4 - Select SCA method

PSU was authenticated successfully with its PSU-ID and password in the previous step, and now XS2A offers a selection of authentication methods.

An authentication method is a format of the 2nd factor that must be provided by PSU in order to complete the authorisation of a payment.

To trigger Decoupled SCA, please use authenticationMethodId where authenticationType = PUSH_OTP in the response in Step 3.

Flow

Go to /v1/payments/sepa-credit-transfers/{paymentId}/authorisations/{authorisationId} or follow the selectAuthenticationMethod link from the response in Step 3.
- See XS2A OpenAPI Reference
Fill in mandatory data

Data field	Value
HTTP-Method	`PUT`
Header `PSU-ID`	same as in Step 1
Header `X-Request-ID`	Random UUID for this request
URL path variable `{payment-product}`	same as in Step 1
URL path variable `{payment-service}`	same as in Step 1
URL path variable `{paymentId}`	`paymentId` received in response of Step 1
URL path variable `{authorisationId}`	`authorisationId` received in response of Step 2

Fill in the body with the chosen authenticationMethodId (see examples Select PSU authentication method [...] in XS2A OpenAPI Reference)
Execute the request
The response should have the HTTP status code: 200 - OK

authoriseTransaction link will only be returned if EMBEDDED SCA has been chosen.

Step 5 - Provide 2nd factor

This is the final step where PSU completes the payment authorisation by providing the 2nd factor.

In real-life operation, a bank will generate and send the 2nd factor to PSU.

In the Sandbox, the behaviour of a bank is simulated: XS2A doesn't generate and sent any challenges but offers a default format of authentication data.

Please refer to (OLD) Sandbox Test Accounts and Test Data for full details.

Flow

Go to /v1/payments/sepa-credit-transfers/{paymentId}/authorisations/{authorisationId} or follow the authoriseTransaction link from the response in Step 4.
- See XS2A OpenAPI Reference
Fill in mandatory data

Data field	Value
HTTP-Method	`PUT`
Header `PSU-ID`	same as in Step 1
Header `X-Request-ID`	Random UUID for this request
URL path variable `{payment-product}`	same as in Step 1
URL path variable `{payment-service}`	same as in Step 1
URL path variable `{paymentId}`	`paymentId` received in response of Step 1
URL path variable `{authorisationId}`	`authorisationId` received in response of Step 2

Fill in scaAuthenticationData according to the authentication method selected in the previous step. Please, see (OLD) Sandbox Test Accounts and Test Data. See examples Transaction authorisation [...] in XS2A OpenAPI Reference.
- Please, see (OLD) Sandbox Test Accounts and Test Data.
Execute the request
The response should have the HTTP status code: 200 - OK