Transfer

The transfer flow can be used to transfer money from a consumer's account to another specifiable account. A transfer flow is only possible for transfer type DOMESTIC or FULL.

Once the flow is finished one "Transfer" object can be obtained. This information can differ depending on the selected bank, as some banks provide more information than others.

Reliability of the Transfer Flow

Please consider that Open Banking. by Klarna provides a Payment Initiation Service and therefore can not guarantee that a successfully initialized payment will be executed by the bank, which might reject the payment later due to various reasons.

Additionally - due to technical restrictions of a few banks - the abort of the transfer flow cannot be guaranteed, even if the initiation was not fully authorized yet.

Starting a Transfer Flow

When initiating a transfer several pieces of information have to be specified in the payload, that is defined as follows:

{
    "iban": ?string,
    "account_id": ?string,
    "amount": Amount,
    "reference": string,
    "transfer_method": ?enum<"sct" | "sct_instant">,
    "preferred_date": string,
    "to": {
        "iban": string,
        "holder_name": string,
        "holder_address": AddressData,
        "bic": string,
        "bank_name": string,
        "bank_address": AddressData
    }
}

iban String, optional

The IBAN of the sender account for which the transfer flow should be executed.

Some banks provide the customer with an option to change the account from which the money is sent during the payment authorization. This could happen even if an account was already selected through this field.

account_id String, optional

The account identifier - as provided in the result of an accounts flow - of the sender account for which the transfer flow should be executed.

Some banks allow the customer to change the account from which the money is sent during the payment authorization.

amount Amount, required

The amount that should be transferred.

reference String, required

The reference for the transfer. The actual reference for the transfer might differ from this and can be found in the adjusted_reference property in the response (see below).

The reference for this transfer will be visible to the recipient of the funds. There are several things to be aware of when setting references:

  • In some cases the reference could be received in an altered or incomplete way, depending on the banks involved. Best practice is to put the most relevant information at or near the beginning of the reference string. Furthermore, some banks restrict the content of the reference. Therefore the XS2A API strips or replaces special characters such as "ä","ö" and "ü" (RegEx: [^a-z0-9-+.]).
  • The reference should be unique as some banks reject transactions with identical references as duplicate.

transfer_method Enum, optional

The transfer_method property sets the type of the transfer being made (default: "sct") :

  • choose sct when using the SEPA Credit Transfer
  • choose sct_instant for starting a SEPA Instant Credit Transfer

preferred_date Date (String: "YYYY-MM-DD"), optional

The date for which the transfer should be scheduled. The date for which the transfer was actually scheduled might differ from this and can be found in the adjusted_date property in the response (see below).

The default value for preferred_date is the current date in the GMT timezone.

to Object, required

The to property acts as a wrapper object for the information on the receiving party.

to.iban String, required

The IBAN of the receiving account.

This property is validated with regard to correctness and structure.

to.holder_name String, required

The holder name of the receiving account.

to.holder_address AddressData, optional

The address of the holder of the receiving account.

to.bic String, required

The BIC of the bank of the receiving account.

This property is validated with regard to correctness and structure.

to.bank_name String, required

The name of the bank (branch) for which the receiver account is registered.

to.bank_address AddressData, required

The address of the bank of the receiving account.

Response Structure of a successful Transfer Flow

{
    "data": {
        "state": enum<'PROCESSING', 'CONSUMER_INPUT_NEEDED', 'ABORTED', 'EXCEPTION', 'FINISHED'>,
        "result": ?{
            "type": string,
            "adjusted_date": ?string,
            "adjusted_reference": ?string,
            "from": ?Account,
            "to": {
                "iban": string,
                "holder_name": string,
                "holder_address": ?AddressData,
                "bic": ?string,
                "bank_name": ?string,
                "bank_address": ?AddressData
            },
            "to_fee": ?Amount,
            "authentication_method": enum<'UNKNOWN', 'NONE', 'OTHER', 'CLASSIC_TAN', 'ITAN', 'MTAN', 'CHIPTAN_MANUAL', 'CHIPTAN_FLICKER', 'SMARTTAN', 'SMARTTAN_PLUS', 'PHONE_TAN', 'PASSWORD', 'PHOTO_TAN', 'USB_DONGLE', 'EMAIL_TAN', 'PUSH_TAN', 'TAN_SELECTION', 'HBCI_SMARTCARD', 'HBCI_KEYFILE', 'APP_TAN'>
        }
    }
}

data.result.type String, always present

For successful flows the type property always holds the value transfer.

data.result.adjusted_date Date (String: "YYYY-MM-DD"), optional

The adjusted_date property contains the date on which the transaction will be executed as provided by the bank. This date may differ from the one provided in the preferred_date property provided in the request.

data.result.adjusted_reference String, optional

The adjusted_reference property contains the reference as displayed and possibly modified by the bank.

data.result.from Account, optional

The from property holds information about the account from which the money was sent.

This account might be empty if the banks don't provide the account which was used for the transfer.

This account might differ from the one selected when starting the transfer.

Furthermore it has to be noted that in this case the data.result.from.id field is not always provided. All other properties behave as documented in the account object.

data.result.to Object, always present

The to property holds information about the account to which the money was sent.

data.result.to.iban String, always present

The IBAN of the receiving account.

data.result.to.holder_name String, always present

The holder name of the receiving account.

data.result.to.holder_adress AddressData, optional

The address of the holder of the receiving account.

data.result.to.bic String, optional

The BIC of the bank of the receiving account.

data.result.to.bank_name String, optional

The name of the bank (branch) for which the receiver account is registered.

data.result.to.bank_address AddressData, optional

The address of the bank of the receiving account.

data.result.to_fee Amount, optional

The to_fee property denotes the fee on the sender that incurred for the executed transaction.

data.result.authentication_method Enum, always present

The authentication_method property indicates which authentication method was used for the transfer. Most of them involve transaction numbers (TANs) that are one-time passwords (OTPs) used for authentication.

  • CLASSIC_TAN - The OTP was given to the user by the bank on a sheet of paper that holds many of these OTPs, hence the OTP is not generated on the consumer-side. CLASSIC_TAN is one of the oldest authentication methods.

  • ITAN - The OTP was given to the user by the bank on a sheet of paper that holds many of these OTPs, like CLASSIC_TAN, but in this case the OTPs are denoted with an index that is referred to during the transaction process.

  • MTAN - The OTP is sent to the consumer via text message.

  • CHIPTAN_MANUAL - The OTP is generated on the consumer-side by means of a card-reader device. The consumer has to insert their debit/credit card into the device and also input a number provided during the transaction process. The device is not connected to the consumer's computer/smartphone.

  • CHIPTAN_FLICKER - The OTP is generated on the consumer-side by means of a card-reader device, like CHIPTAN_MANUAL, but instead of entering a number manually the consumer has to hold the device up to the screen to enable an optical transmission of information from their computer to the device. The optical transmisson is realized via the flicker method. The device might be connected to the consumer's computer.

  • SMARTTAN - The OTP is generated utilizing a dedicated device that may or may not require the consumer's ec card. No data about the transaction is entered into the device.

  • SMARTTAN_PLUS - The OTP is generated utilizing a dedicated device that may or may not require the consumer's ec card. Additionally data about the transaction is entered into the device.

  • PHONE_TAN - The OTP will be communicated via speech synthesis in an automatic call to the consumer's phone.

  • PASSWORD - The consumer has to enter a password (different to the login password) to authenticate the transaction. Consequentially the password will be the same for all transactions of a specfic consumer.

  • PHOTO_TAN - The OTP is generated on the consumer's smartphone or hardware device which is used to scan an image file provided by the bank. There are also cases in which the consumer confirms the transaction in the smartphone app and does not have to enter an OTP. The image that is to be scanned is not animated and in most cases made up of a pattern that includes multiple colors.

  • USB_DONGLE - The USB-Dongle is a device that is connected to the consumer's computer via USB and either displays an OTP or enables the consumer to confirm the transaction by pushing a button.

  • EMAIL_TAN - The OTP is sent to the consumer via e-mail.

  • PUSH_TAN - A specific app on the consumer's smartphone receives a push notification stating that the OTP is available in the app. In most cases a password is required to enter the app.

  • TAN_SELECTION - A mostly internal step which indicates that the customer has to select an authentication method. Usually this state will be overwritten by the actual authentication method, but if it does not then this indicates that the consumer did not make a selection and aborted the process.

  • HBCI_KEYFILE - The consumer used an HBCI keyfile to authenticate. Along with the file a PIN and optionally a username have to be provided.

  • APP_TAN - A specific app on the consumer's smartphone receives a push notification which the consumer can interact with and confirm the payment within the app. This process does not involve an OTP.

  • UNKNOWN - The authentication method was unknown or could not be determined.

  • OTHER - The authentication method is known. However, it does not fit into one of the other categories and it is also not common enough to demand a seperate category.

  • NONE - Authentication was not required.

Example Response for a successful Transfer Flow

{
    "data": {
        "state": "FINISHED",
        "result": {
            "type": "transfer",
            "adjusted_date": "2018-10-30",
            "adjusted_reference": "reference accepted by bank",
            "from": {
                "id": "123e4567-e89b-12d3-a456-426655440000",
                "alias": "Girokonto",
                "account_number": "123456789",
                "iban": "DE44500105175407324931",
                "holder_name": "Max Mustermann",
                "holder_address": {
                    "street_address": "Konrad-Adenauer-Straße 21",
                    "street_address2": "Backside of the House, Floor 2",
                    "postalcode": "35440",
                    "city": "Linden",
                    "region": "Hesse",
                    "country": "DE"
                },
                "bank_code": "51091700",
                "bic": "VRBUDE51XXX",
                "bank_name": "VR Bank Untertaunus eG",
                "bank_address": {
                    "street_address": "Konrad-Adenauer-Straße 21",
                    "street_address2": "Backside of the House, Floor 2",
                    "postalcode": "35440",
                    "city": "Linden",
                    "region": "Hesse",
                    "country": "DE"
                },
                "transfer_type": "FULL",
                "account_type": "DEFAULT",
                "balance": {
                    "amount": 12345,
                    "currency": "EUR"
                }
            },
            "to": {
                "iban": "DE44500105175407324931",
                "holder_name": "Max Mustermann",
                "holder_address": {
                    "street_address": "Konrad-Adenauer-Straße 21",
                    "street_address2": "Backside of the House, Floor 2",
                    "postalcode": "35440",
                    "city": "Linden",
                    "region": "Hesse",
                    "country": "DE"
                },
                "bic": "VRBUDE51XXX",
                "bank_name": "VR Bank Untertaunus eG",
                "bank_address": {
                    "street_address": "Konrad-Adenauer-Straße 21",
                    "street_address2": "Backside of the House, Floor 2",
                    "postalcode": "35440",
                    "city": "Linden",
                    "region": "Hesse",
                    "country": "DE"
                }
            },
            "to_fee": {
                "amount": 12345,
                "currency": "EUR"
            },
            "authentication_method": "MTAN"
        }
    }
}

results matching ""

    No results matching ""