Flow

A flow is a process within a session that has the goal to either retrieve some specific information about a bank account or execute a transfer.

Starting a Flow

To create a flow one of the links provided in the reponse from the request that started the session needs to be called as a PUT-request:

The Request

PUT <session.flows.<flowtype>> HTTP/1.1
Content-Type: application/json;charset=utf-8
Authorization: Bearer <token>

 <payload>
curl -X "PUT" "<session.flows.<flowtype>>" \
         -H "Content-Type: application/json;charset=utf-8" \
         -H "Authorization: Bearer <token>"  \
         -d $'<payload>'

The payload depends on the specified flow type. To find out what payload to send please have a look at the documentation about the specific flows.

The Response

After a successful call is made the following response is returned with a 201 CREATED status code:

HTTP/1.1 201 Created
Content-Type: application/json
{
    "data":{
        "flow_id": string,
        "state": enum<"INITIALIZED", "PROCESSING", "CONSUMER_INPUT_NEEDED", "FINISHED", "INTERRUPTED",  "ABORTED", "EXCEPTION">,
        "self": url,
        "client_token": jwt
    }
}

The data property wraps the actual information in every response returned by the XS2A-API and has no other purpose.

The flow_id property holds a unique identifier for the flow.

The self property holds a url which refers to the endpoint related to the flow. When called with GET it returns the current information about the executed flow (see "Retrieving Information about a Flow" below). When called with DELETE it aborts the flow (see "Closing a Flow" below).

The state property holds the current state of the flow. It can be one of the following:

  • PROCESSING

The state is PROCESSING when the api processes incoming information or is polling internally for a state change.

  • CONSUMER_INPUT_NEEDED

The flow is waiting for consumer data to be received through the Auth API (e.g. XS2A App).

  • ABORTED

The flow was aborted through a close flow call

  • EXCEPTION

The flow failed with an exception.

  • FINISHED

The flow has finished.

The states ABORTED, EXCEPTION and FINISHED are terminal states, thus apart from requesting the information of the flow through the flow information call the flow cannot be interacted with.

The client_token property holds a JWT (JSON Web Token) which ecapsulates data relevant for the XS2A App and should be passed to it in order to enable the consumer to proceed through the flow.

It also holds the type of the flow, which can currently be accounts, account_details, balances and transfer. The client_token is also needed in the White Label Integration as it contains the URLs needed to communicate with the Auth API.

Retrieving Information about a Flow

Information about the current and all previous flows of a session can be retrieved as long as the session has not been closed.

The Request

In order to obtain information about a flow the self-url that is returned in the CREATE call when initiating a flow needs to be called with GET:

GET <session.flows.<flowtype>> HTTP/1.1
Authorization: Bearer <token>
curl -X "GET" "<session.flows.<flowtype>>" \
         -H "Authorization: Bearer <token>"  \

This should only be done on the server side as it could return information the consumer should not receive.

The Response

After a successful call is made the following response is returned:

HTTP/1.1 200
{
    "data":{
        "result":{
                ...,
             "type": <resulttype>
        },
        "state":"FINISHED"
    }
}

The data property wraps the actual information in every response returned by the XS2A-API and has no other purpose.

The state property holds the current state of the flow. See above (response when starting a flow) for possible values.

The result property holds the data that is currently available in the flow. Its content depends on the flow and on the current step inside the flow. The object holds a type property which identifies the type of the information that the response holds, e. g. if type is accounts then result holds an array of accounts.

Handling Errors

If the flow ends in the EXCEPTION state, a category and a message will be present to provide information about what happened. Such a response might look like this:

{
    "data": {
        "state": "EXCEPTION",
        "result": {
            "category": "TECHNICAL",
            "message": "Es ist ein interner technischer Fehler bei Ihrer Bank aufgetreten.",
            "type": "error"
        }
    }
}

More information on the kinds of errors that may occur can be found here.

Closing a Flow

The behaviour when closing a flow depends on its current state:

Closing a running accounts, account-details, balances or transactions flow always aborts the process immediately, except if the consumer is confirming his login asynchronously. The same is correct for the transfer flow with the exception that the consumer is confirming the transfer asynchronously (e.g. through a mobile device).

As a new flow can not be started and the session can not be closed before the current flow has ended, it is recommended to poll the flow's status to obtain information on whether or not the flow has been closed.

The Request

In order to close a flow the self-url that is returned in the CREATE call when initiating a flow needs to be called as a DELETE request:

DELETE <flow.self> HTTP/1.1
Authorization: Bearer <token>
curl -X "DELETE" "<flow.self>" \
         -H "Authorization: Bearer <token>"  \

The Response

If the flow has ended or had already ended before the following response will be returned:

HTTP/1.1 204 No Content

To make sure that the flow has ended in the correct state make sure to get the current flow information after closing through the flow information call.

In some cases where a flow can not be closed immediately an 202 ACCEPTED is returned:

HTTP/1.1 202 ACCEPTED

In this case the flow will be closed as soon as possible.

Closed Flows

A flow has ended if the state of the flow is either ABORTED, EXCEPTION or FINISHED. The closing request will ultimately lead to the flow ending up in one of these three states, but it can not be guaranteed that the flow will be aborted immediately at the point of the closing request. Therefore caution is advised when handling the states of a flow.

results matching ""

    No results matching ""