Sign in
XS2A.pay

Create xs2a.pay object

Create a xs2a.pay object and receive Wizard session key in return.

post/payments

Request body

amountnumber float required

The amount to be transferred, either in EUR or CHF (depending on currency_id). This is a float, meaning for i.e. 1,50 Euro, you would send 1.5, and for 15 Euro, you would send 15.0.

currency_id'EUR' | 'CHF' required

The id of the currency to be used.

purposestring required

We suggest to keep the purpose as short as possible (between 5 and 140 characters) and to place critical information at the beginning of the purpose. The reason for this suggestion is that we might have to limit the length of your given purpose. A SEPA purpose can be up to 140 characters. However some banks only offer a reference field which is limited to 35 characters. If your purpose is longer than bank supported purpose field, we will shorten it to the maximum length supported by that bank. Not all characters are supported for the purpose field. Sender banks impose different rules for the purpose field, therefore we suggest to limit the character set to a-z, A-Z, 0-9. If you use other characters please be advised that we might have to remove or replace characters considered invalid by the sender bank. We usually will replace the invalid characters with a whitespace or normalize the characters.

recipient_holderstring required

Sender banks impose different rules for the recipient_holder field, we suggest to limit the character set to a-z, A-Z, 0-9. If you use other characters please be advised that we might have to remove or replace characters considered invalid by the sender bank. We usually will replace the invalid characters with a whitespace or normalize the characters.

recipient_ibanstring required

IBAN of the recipient account

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).

language'de' | 'en'

The initial language.

merchant_idstring

The internal ID of your merchant, if any. You may fill this field with the internal ID your merchant, if you are a PSP.

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.

with_intermissionboolean

If you send true for this flag, the session will be sent into a waiting ('intermission') state after the account step, during which you do any asynchronous operations (i.e. retrieve account snapshot), and then decide to either veto or resume the session.

sender_holderstring

Name of the sender account holder. If this is set, the account holder will be pinned and validated for the current session. The customer will not be able to choose an account with a different name than provided. The name will be compared with our XS2A.name_check module. A match is not only string equals. To a certain point changes in the name will be tolerated. (i.e. a prepending academic title will not break the match). If you have first name and surname separately, you have to pass them with delimiter |||. This will improve the name comparison with account holder. example: Max|||Mustermann

sender_ibanstring

IBAN of the sender account. 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.

sender_bicstring

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

sender_country_id'DE' | 'AT' | 'CH'

The 2-letter country code

sender_bank_codestring

National bank code of the sender account.

recipient_bicstring

BIC of the recipient account

recipient_streetstring

Street of the recipient account. Required if sender_country_id is CH

recipient_zipstring

Zip-code of the recipient account. Required if sender_country_id is CH

recipient_citystring

City of the recipient account. Required if sender_country_id is CH

recipient_country_id'DE' | 'AT' | 'CH'

The 2-letter country code

Example request

{
  "amount": 1.5,
  "currency_id": "EUR",
  "purpose": "Purpose",
  "recipient_holder": "Holder",
  "recipient_iban": "DE04888888880087654321",
  "metadata": {
    "key1": "value1"
  },
  "language": "de",
  "with_intermission": true,
  "easy_onboarding": {
    "success_link": "https://www.xs2a.com/success",
    "abort_link": "https://www.xs2a.com/abort"
  },
  "sender_country_id": "DE",
  "recipient_bic": "TESTDE88XXX",
  "recipient_country_id": "DE"
}

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