Transfer State
For PSD2 integrations the state of an initialized transfer may change over time. The transfer state endpoint can be used to fetch the current state after a successfully finished transfer flow.
The consent-id can be obtained as described here. The transfer-id is provided in the result of the transfer flow.
Lifetime of the transfer token
The transfer state can not be fetched indefinetly but only for a certain period of time. Some banks issue transfer tokens as part of the AIS consent which are subject to AIS consent lifetime. Other banks set a period of time applicable to all transfer state tokens regardless of the session.consent.lifetime, e.g. valid for 24 hours. Most banks are of latter type, setting a defined time and avoiding to add unnecessariy AIS consents and therefore ignoring the AIS consent lifetime. This means that eventhough a consent.lifetime is set to 1 the transfer_token might be valid for more than 1 day.
The transfer token always has the maximum available lifetime the respective bank allows. However, if you experience the transfer token to become invalid unexpectably then we suggest to test to adjust the session.consent.lifetime in the session.
Request
POST /xs2a/v1/consents/{consent-id}/transfers/{transfer-id}/state/get HTTP/1.1
Content-Type: application/json; charset=utf-8
Authorization: Token <Token>
Host: <Host>
{
"consent_token": String,
"transfer_token": String,
"psu": ?{
"user_agent": String,
"ip_address": String
}
}
The psu object is optional, however, if the consumer is present, it is recommended to provide it. Some banks soften their daily consent usage restrictions if the PSU data is available.
The user_agent property holds the user agent string of the consumer's client application, e.g. the web browser.
The ip_address property holds the IP address of the consumer. Both IPv4 and IPv6 are accepted formats.
Response
{
"data": {
"result": ?{
"transfer_state": Enum<'AUTHORIZED', 'COMPLETED_DEBTOR', 'COMPLETED_CREDITOR', 'CANCELED', 'REJECTED'>,
"bank_transfer_state": String,
"transfer_token": String,
},
"consent_token": String
}
}
The transfer_state property contains the current state of the transfer.
AUTHORIZED- The transfer was authorized but not yet booked by the bank.COMPLETED_DEBTOR- The transfer was booked and sent by the debtor bank.COMPLETED_CREDITOR- The transfer was received by the creditor bank.CANCELED- The transfer was canceled by the customer.REJECTED- The transfer was rejected by the bank. This could happen due to transfer validation rules which differ for each bank.
The bank_transfer_state property contains the current state of the transfer as provided by the bank.
The values are not normalized and the meaning and format could differ per PSD2-framework or even per bank. For more information, visit the related PSD2-API documentation of the specific banks.
The response contains a new transfer_token that has to be used in the following request.
The response contains a new consent_token that has to be used in the following request.
Example
Request
POST /xs2a/v1/consents/gp4cb0g6d9r3qf4d68fkrlb7ejo8mqqk/transfers/jlufj5a5u6d0i37ur3uh9fvfgpvp6et7/state/get
{
"consent_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbiI6IjEyMzQ1Njc4OTAifQ.na71ipK8ASvggoM6C5vMjBKgJlZLxV-m6ElgHBrNtlU",
"transfer_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0cmFuc2Zlcl90b2tlbiI6InRyYW5zZmVyMTIzNDU2Nzg5MCJ9.YcdKaz2hRyW1wPqH8bYka4EF7dVkferaNexzk7PfHnQ",
"psu": {
"user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/80.0.3987.162 Safari/537.36",
"ip_address": "192.168.2.1"
}
}
Response
In this example, the transfer is already completed on debtor side. For another payment-state call please use the updated consent token and transfer token.
200 OK
{
"data": {
"result": {
"transfer_state": "COMPLETED_DEBTOR",
"bank_transfer_state": "bank_state_internal_completed",
"transfer_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0cmFuc2Zlcl90b2tlbiI6InVwZGF0ZWRfdG9rZW5fMTIzNDU2Nzg5In0.m029L-HC8u8rybctJk58ms-2HhCUiw6dYbUooAhVI5U"
},
"consent_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbiI6Ijg4OTk3Nzg4In0.QQscn9a6-nQXuVK4Rwbft_LFMF3-r2xzWROEZMS2lW0"
}
}