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 response 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: Token <token>

 <payload>

curl -X "PUT" "<session.flows.<flowtype>>" \
         -H "Content-Type: application/json;charset=utf-8" \
         -H "Authorization: Token <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<'PROCESSING', 'CONSUMER_INPUT_NEEDED', 'FINISHED', 'ABORTED', 'EXCEPTION'>,
        "self": URL,
        "client_token": String
    }
}

data Object, always present

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

data.flow_id String, always present

The flow_id property holds a unique identifier for the flow.

data.self URL, always present

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).

data.state Enum, always present

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.

data.client_token String, always present

The client_token property holds a signed 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, transactions 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.

To validate the client_token-JWT you can check the signature against the respective public key. Please note that these keys might change in the future.

Environment Public key sha1sum
Integration integration.pub 1e518b169714d099979a32b4a564b19ee5e8b5f2
Production production.pub cf15d8af302dcdea1bf6c25e5b3b70d291f55f53

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: Token <token>

curl -X "GET" "<session.flows.<flowtype>>" \
         -H "Authorization: Token <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": Enum<'PROCESSING', 'CONSUMER_INPUT_NEEDED', 'FINISHED', 'ABORTED', 'EXCEPTION'>,
        "client_token": String
    }
}

data Object, always present

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

data.state Enum, always present

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

data.result Object, optional

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.

data.client_token String, always present

The client_token property holds the same jwt as returned by the Response of the Flow Start request client_token.

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

A flow that ended with the state EXCEPTION does not necessarily indicate that the session is not usable anymore. When this occurs please call the Session-GET endpoint and check if the state is IDLE. If the session is in the IDLE-state you can try and start a new flow (even a flow with the same configuration as the failed flow), in some cases this will result in a successful flow. To get an idea take a look at the following diagram:

Example Session State Progression with a failed flow

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: Token <token>

curl -X "DELETE" "<flow.self>" \
         -H "Authorization: Token <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. Please note that for the transfer flow these states might not be fully reliable (see Transfer Flow: Reliability). Therefore caution is advised when handling the states of a flow.

results matching ""

    No results matching ""