XSxs2a
XS2A.risk

Create xs2a.risk object

Changed on

Create a xs2a.risk object and receive a wizard session key in return.

Please Note: In the following documentation of the request body, all available risk checks are defined. It is important to note that they are optional, and that you simply submit the risk check you need. You can find a more detailed explanation of the risk checks here.

Important Note: Using the request sample, can only be performed if all code sections are fully expanded.

post/risks

Request

Request body

bank_codeinteger

bank code of the customers bank, requires also parameter country_id. If supplied the step/page for entering a bank code will be skipped.

country_id'DE' | 'AT' | 'CH'

The 2-letter country code

account_numberstring

The (national) account number of the customer. Is the account number valid, an IBAN will be calculated using the bank code and the account number. Afterwards the procedure is equal to the following description for iban (see below). If you include this field, you must also include the parameter bank_code.

ibanstring

IBAN of the customer. If it is a valid IBAN, the IBAN will be pinned for the current session. The customer will not be able to choose a different account, even if there are more accounts available to chose from. If the given IBAN is not in the customer list of accounts, the transaction will be aborted. In the case of an invalid IBAN XS2A will return a validation error with HTTP status code 422.

bicstring

BIC of the customer. If the given BIC is valid, the step/page for entering a bank code will be skipped.

check_amountnumber float

The account balance amount to be checked against.

check_currency_id'EUR' | 'CHF'

The id of the currency to be used.

metadataMetadata nullable

An array of data which will be passed back to your application. With this field you can for example pass information about your customer ids, order ids and the like back to your application. Please beware of some restrictions for the metadata field: maximum of 3 values, maximum of a key length of 20 characters, maximum length of values is 128 characters. For privacy protection reason it is not allowed to use this field for transferring personal data (e.g. names or addresses).

merchant_idstring

The internal ID of your merchant, if any.

fints_product_idstring

The fints product ID can be enclosed in the initial request. If you have an eIDAS certificate, then you have to send it with every request.

language'de' | 'en'

The initial language.

xs2a_account_characteristics_checkXs2aAccountCharacteristicsCheck

XS2A.account_characteristics_check allows you to retrieve many possible information about the account, like chargebacks, encashment, loans and other. Simply append an empty object to the XS2A.risk object to indicate you would like this check to be performed.

xs2a_account_linked_offers_checkXs2aAccountLinkedOffersCheck

The Account Linked Offers Check validates with the consent of the user, based on an account view, whether third party offers might be of interest to the user and hands over an advertising link for one-time use to a Tink Germany business partner.

xs2a_age_verification_checkXs2aAgeVerificationCheck

The XS2A.age_verification_check verifies the legal age of the account holder.

xs2a_all_accounts_checkXs2aAllAccountsCheck

XS2A.standing_orders_check allows you to retrieve all standing orders from an account. An XS2A.standing_orders_check has no additional parameters. Simply append an empty object to the XS2A.risk object to indicate you would like this check to be performed.

xs2a_balance_overviewXs2aBalanceOverview

XS2A.balance_overview returns the current running total of the chosen account. An XS2A.balance_overview has no additional parameters. Just append an empty object to the XS2A.risk object to indicate you would like this check to be performed.

xs2a_cashflow_overviewXs2aCashflowOverview

XS2A.cashflow_overview provides an cashflow overview for the requested risk date range. An XS2A.cashflow_overview has no additional parameters. Just append an empty object to the XS2A.risk object to indicate you would like this check to be performed.

xs2a_chargeback_checkXs2aChargebackCheck

XS2A.chargeback_check returns the number of detected chargeback transactions for the account. An XS2A.chargeback_check has no additional parameters. Just append an empty object to the XS2A.risk object to indicate you would like this check to be performed.

xs2a_children_checkXs2aChildrenCheck

The XS2A.children_check gathers payments from governmental facilities, which indicate how many children the account has. This risk-check has no configuration.

xs2a_overdraft_limit_checkXs2aOverdraftLimitCheck

XS2A.overdraft_limit_check returns the number of booking days of the given risk range. The number of days the account used the overdraft limit, the maximum amount of overdraft used, the average and the median used overdraft. An XS2A.overdraft_limit_check has no additional parameters. Just append an empty object to the XS2A.risk object to indicate you would like this check to be performed.

xs2a_profit_loss_checkXs2aProfitLossCheck

The P&L check (profit and loss check) provides a simplified P&L statement for B2B customers as well as an overview of other relevant operational KPIs. These can be, for example, other relevant income, expenses and cash flows from the account. In addition, the tax number is also shown (initially, only in Germany).

xs2a_standing_orders_checkXs2aStandingOrdersCheck

XS2A.standing_orders_check allows you to retrieve all standing orders from an account. An XS2A.standing_orders_check has no additional parameters. Simply append an empty object to the XS2A.risk object to indicate you would like this check to be performed.

Example request

{
  "bank_code": 88888888,
  "country_id": "DE",
  "iban": "DE62888888880012345678",
  "bic": "TESTDE88XXX",
  "check_amount": 100.45,
  "check_currency_id": "EUR",
  "metadata": {
    "key1": "value1"
  },
  "easy_onboarding": {
    "success_link": "https://www.xs2a.com/success",
    "abort_link": "https://www.xs2a.com/abort"
  },
  "language": "de",
  "xs2a_account_characteristics_check": {},
  "xs2a_account_linked_offers_check": {},
  "xs2a_account_snapshot": {
    "days": 365,
    "from": "YYYY-MM-DD",
    "to": "YYYY-MM-DD",
    "all_accounts": true,
    "all_tags": true
  },
  "xs2a_account_status_check": {
    "limit_turnover_days": 365,
    "all_accounts": true
  },
  "xs2a_age_verification_check": {},
  "xs2a_all_accounts_check": {},
  "xs2a_balance_check": {
    "check_amount": 100,
    "check_currency_id": "EUR"
  },
  "xs2a_balance_overview": {},
  "xs2a_cashflow_overview": {},
  "xs2a_chargeback_check": {},
  "xs2a_children_check": {},
  "xs2a_collection_check": {
    "check_amount": 100,
    "check_currency_id": "EUR"
  },
  "xs2a_credit_check": {
    "checks": [
      "income"
    ]
  },
  "xs2a_direct_debit_check": {
    "check_amount": 100,
    "check_currency_id": "EUR",
    "start_date": "2014-03-23",
    "end_date": "2014-03-31"
  },
  "xs2a_fact_sheet_lists": {
    "limit_turnover_days": 365,
    "fields": [
      {
        "tags": [
          "expenditure",
          "banking-fees"
        ],
        "categories": [
          "K.8.2.1"
        ],
        "name": "test",
        "min_amount": -20,
        "max_amount": -2
      }
    ]
  },
  "xs2a_holder_identification_check": {
    "expect_holders": [
      {
        "firstname": "Hartmuth",
        "name": "Mustermann"
      }
    ]
  },
  "xs2a_income_check": {
    "limit_turnover_days": 365
  },
  "xs2a_insurance_contract_check": {
    "days": 365
  },
  "xs2a_name_check": {
    "name": "Mustermann",
    "firstname": "Hartmut"
  },
  "xs2a_overdraft_limit_check": {},
  "xs2a_profit_loss_check": {},
  "xs2a_risk_calculations_check": {
    "calculations": [
      {
        "tags": [
          "transfer"
        ],
        "categories": [
          "K.1.1"
        ],
        "functions": [
          "sum",
          "count",
          "median",
          "average",
          "last",
          "min",
          "max",
          "min_date",
          "max_date",
          "clean_sum",
          "exists",
          "sums_of_every_month",
          "counts_of_every_month",
          "median_of_all_month_sums",
          "average_of_all_month_sums",
          "min_of_all_month_sums",
          "max_of_all_month_sums",
          "distinct_counter_holders"
        ],
        "name": "Example name",
        "days": 180
      }
    ]
  },
  "xs2a_seizure_check": {
    "days": 90
  },
  "xs2a_standing_orders_check": {}
}

Response

Request successfully processed

wizard_session_keystring

Using the wizard_session_key you can now initialize our Wizard which is running on your website

transactionstring

We suggest that you store the internally used XS2A transaction id transaction with your transaction data, because if you later have questions about a transaction, we need this number to be able to quickly assist you.

Example response

{
  "wizard_session_key": "m5A65Cy2lwI1rOXxuvwU4MM47b4tDaV0ME9By6It",
  "transaction": "10001-xv-LEz8-oct7"
}

Changes

  • ae5fbc5feee3Revision changes
    • breaking

      removed the enum value ES of the request property

    • breaking

      removed the enum value FR of the request property

    • breaking

      removed the enum value GB of the request property

    • breaking

      removed the enum value IT of the request property

    • breaking

      removed the enum value es of the request property

    • breaking

      removed the enum value fr of the request property

    • breaking

      removed the enum value it of the request property

    • warning

      removed the request property

    • warning

      removed the request property

    • warning

      removed the request property