Transfer

The transfer flow can be used to transfer money from a consumer's account to another specifiable account.

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.

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

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

iban - The IBAN of the receiver account.

holder_name - The receiver account holder's name.

holder_address - Address of the receiver account's holder.

bic - The BIC of the receiver account's bank.

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

bank_address - Address of the receiver account's bank.

Detailed information on the AddressData object can be found here.

Detailed information on the Amount object can be found here.

The IBAN, BIC, account number and bank code are validated with regard to correctness and structure.

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:

  • Beware that 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 string. Also be aware that some banks have restrictions with regard to 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.

Response Structure of a successful Transfer Flow

{
    "data": {
        "status": enum<'INITIALIZED', 'INTERRUPTED', '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'>
        }
    }
}

The type property always holds the value transfer.

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.

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

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

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

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

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.

Detailed information on the Account object can be found here.

Detailed information on the Amount object can be found here.

Example Response for a successful Transfer Flow

{
    "data": {
        "status": "INITIALIZED",
        "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 ""