Transfer

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

The flow is not available for all accounts. Please check the capabitilies of the account to see if it's available.

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.

Transfer Types

We offer a variety of different Transfer Types:

The default Transfer (SEPA) and its SEPA Instant specialization are described below:

Executing a SEPA/SEPA Instant Transfer

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

{
    "iban": ?String,
    "account_id": ?String,
    "account_number": ?String,
    "allowed_accounts": ?AllowedAccounts,
    "amount": Amount,
    "reference": String,
    "bank_references": ?{
        "unstructured": ?String,
        "structured": ?String,
        "end_to_end": ?String,
        "message": ?String,
        "opposing_message": ?String,
        "national": ?String
    },
    "merchant_category_code": ?String,
    "purpose_code": ?String,
    "transfer_method": ?Enum<"sct" | "sct_instant">,
    "preferred_date": Date,
    "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.

account_number String, optional

The account number - 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.

allowed_accounts AllowedAccounts, optional

A configuration for filtering the options at the account selection for the consumer. This can't be used in combination with the iban and account_id fields.

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.

Note for Klarna Branded Integrations: This is the reference, which will be shown to the customer when being requested to authorize the payment within the Klarna Branded Open Banking App.

bank_references Object, optional

Additional references that should be used for a transfer. In case an additional bank reference is not supported by the bank we use the reference field as a fallback.

bank_references.unstructured String, optional

The unstructured reference will be shown on debtor and creditor account and will be ignored if not supported by the bank interface. Even if the debtor bank supports the unstructured reference it is possible that it is not supported by the creditor bank and not available there.

bank_references.structured String, optional

The structured reference will be shown on debtor and creditor account and will be ignored if not supported by the bank interface. Even if the debtor bank supports the structured reference it is possible that it is not supported by the creditor bank and not available there.

bank_references.end_to_end String, optional

The end_to_end reference will be shown on debtor and creditor account and will be ignored if not supported by the bank interface. Even if the debtor bank supports the end_to_end reference it is possible that it is not supported by the creditor bank and not available there.

bank_references.message String, optional

The message reference will exclusively be shown on the debtor account and will be ignored if not supported by the bank interface.

bank_references.opposing_message String, optional

The opposing_message reference will be shown on debtor and creditor account and will be ignored if not supported by the bank interface. Even if the debtor bank supports the opposing_message reference it is possible that it is not supported by the creditor bank and not available there.

bank_references.national String, optional

A reference used for a national transfer. The format for this parameter could vary for countries/banks and is not supported by all banks. For now a national reference is only supported by Finnish banks.

Example: In Finland banks support a national reference with a specific format including a checksum which leads to a lower fee amount for national transfers.

If you would like to use a national bank reference for a country other than Finland please look up information on country / bank standards or get in contact with us.

merchant_category_code String, optional

The Merchant Category Code that should be used for the transfer. The expected format is a String of 3 or 4 numbers (\d{3,4}). Information follows the ISO-18245 Standard.

purpose_code String, optional

The Purpose Code that should be used for the transfer. The expected format is a String of 4 letters.

The Purpose Code is not supported by all banks.

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 or if it's not supported by the Integration for preferred_date is the current date in the UTC timezone.

This feature is not available for all Integrations at the moment. Please reach out to us before using this field.

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.

Some banks might reject transfers without the holder_address, especially international transfers. This mostly concerns the to.holder_address.street_address, to.holder_address.postalcode, to.holder_address.city and to.holder_address.country.

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,
            "adjusted_bank_references": ?{
                "unstructured": ?String,
                "structured": ?String,
                "end_to_end": ?String,
                "message": ?String,
                "opposing_message": ?String,
                "national": ?String
            },
            "adjusted_merchant_category_code": ?String,
            "adjusted_purpose_code": ?String,
            "amount": Amount,
            "identifier": ?String,
            "bank_transfer_id": ?String,
            "transfer_id": String,
            "transfer_token": ?String,
            "transfer_state": Enum<'AUTHORIZED', 'COMPLETED_DEBTOR', 'COMPLETED_CREDITOR'>,
            "bank_transfer_state": ?String,
            "from": ?Account,
            "to": {
                "iban": String,
                "holder_name": String,
                "holder_address": AddressData,
                "bic": String,
                "bank_name": String,
                "bank_address": AddressData
            },
            "to_fee": ?Amount,
            "transfer_method": Enum<'SCT','SCT_INSTANT','SE_BANKGIROT','SE_PLUSGIROT','GB_DOMESTIC'>,
            "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.adjusted_bank_references Object, optional

The adjusted_bank_references property contains information about the used and possibly modified references.

data.result.adjusted_bank_references.unstructured String, optional

The adjusted unstructured reference.

data.result.adjusted_bank_references.structured String, optional

The adjusted structured reference.

data.result.adjusted_bank_references.end_to_end String, optional

The adjusted end_to_end reference.

data.result.adjusted_bank_references.message String, optional

The adjusted message reference.

data.result.adjusted_bank_references.opposing_message String, optional

The adjusted opposing_message reference.

data.result.adjusted_bank_references.national String, optional

The adjusted national reference.

data.result.adjusted_merchant_category_code String, optional

The adjusted Merchant Category Code provided by the bank.

data.result.adjusted_purpose_code String, optional

The adjusted Purpose Code provided by the bank.

data.result.identifier String, optional

[deprecated] Please use the property bank_transfer_id instead.

data.result.bank_transfer_id String, optional

The bank_transfer_id property contains the transfer reference that was used internally by the bank. This could be useful for further turnover matching. The values of this object 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.

data.result.transfer_id String, always present

The transfer_id property contains a generated id by Klarna. It can be used to fetch the transfer state via the Consent Transfer-State API.

data.result.transfer_token String, optional

The transfer_token property contains a transfer token to fetch the state of a payment. This Token is only present for PSD2 integrations and can be used via the Consent Transfer-State API.

data.result.transfer_state Enum, optional

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.

data.result.bank_transfer_state String, optional

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.

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.amount Amount, always present

The amount that was transferred.

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.transfer_method Enum, always present

The transfer_method property indicates which transfer method was used for the transfer.

  • SCT - SEPA Credit Transfer

  • SCT_INSTANT - SEPA Instant Credit Transfer

  • SE_BANKGIROT - Bankgiro Transfer in Sweden

  • SE_PLUSGIROT - Plusgiro Transfer in Sweden

  • GB_DOMESTIC - Domestic Transfers in Great Britain

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",
            "adjusted_bank_references": {
                "national": "national reference accepeted by bank"
             },
            "adjusted_merchant_category_code": "5967",
            "adjusted_purpose_code": "BONU",
            "bank_transfer_id": "internal_bank_identifier-123",
            "transfer_id": " jlufj5a5u6d0i37ur3uh9fvfgpvp6et7",
            "transfer_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0cmFuc2Zlcl90b2tlbiI6InRyYW5zZmVyMTIzNDU2Nzg5MCJ9.YcdKaz2hRyW1wPqH8bYka4EF7dVkferaNexzk7PfHnQ",
            "amount": {
                "amount": 1234,
                "currency": "EUR"
            },
            "transfer_state": "AUTHORIZED",
            "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"
            },
            "transfer_method": "SCT",
            "authentication_method": "MTAN"
        }
    }
}

results matching ""

    No results matching ""