Test Mode Transactions in Easy Pay Direct
API Documentation
Direct Bank Transfer
1. Introduction to Direct Bank Transfer
Customers (end customers) do not have to register for Direct Bank Transfer: They make a fast and easy payment using their online banking details. Thanks to real time acknowledgement of the transfer order, you as a merchant can immediately ship the goods or provide services.
From your customer's perspective, an Direct Bank Transfer transaction consists of the following steps:
As soon as payment by Direct Bank Transfer is requested, the customer is redirected to an Direct Bank Transfer page.
Below the overview of the transfer data (recipient, reason, amount), your customer is requested to enter the sort code.
Subsequently, your customer is asked to log on by entering the online banking details.
After successful logon, the customer has to confirm and release the transfer by entering a valid confirmation code.
If a valid confirmation code has been entered, the transfer is authorized and your customer will receive a summary of the executed transaction.
Finally, the customer is redirected to your online shop with one click.
2. Integration steps
The following steps are basically required to integrate Direct Bank Transfer in your system. A detailed description of the individual steps is provided subsequently:
- Register as a merchant on our website https://sofort.com/register.
- Create a new Direct Bank Transfer Gateway Project.
- Choose the payment method of Direct Bank Transfer.
- Configure your Direct Bank Transfer Project.
(In case you would like to be automatically informed by Sofort GmbH on incoming transfers to your account, please use your Deutsche Handelsbank Account). - After you have created and configured a project, you will receive an API key.
- Integrate Direct Bank Transfer in your shop
- Integrate the payment method of Direct Bank Transfer for selection in the checkout.
- As soon as a customer requests to pay by Direct Bank Transfer, call our interface by entering the respective payment data. In response, you will receive a link to a Sofort GmbH page to redirect the customer for payment.
- The customer processes the payment on our page and is subsequently redirected to the success or abort page of your shop which you have defined.
- In case of a successful transaction (i.e. the transfer was initiated by your customer), you will automatically be notified of this transaction by Sofort GmbH. Subsequently, you can immediately initiate further steps such as shipping of goods or activation of the online offer. You will be notified of the successful transaction by email and via XML HTTP notification, which automatically informs your system of a status change. You may retrieve details on the transaction at any time (through an automated process).
Note:
Please ensure during the integration that it is necessary to redirect the buyer directly on the payment form so that the URL and the SSL certificate of the Direct Bank Transfer are visible. That means a framed solution for example with <iframe> is not allowed due to legal reasons.
3. Integration of Direct Bank Transfer
As a first step, you have to integrate Direct Bank Transfer in the checkout of your shop to offer your customer Direct Bank Transfer as a payment method to be selected. If the customer selects Direct Bank Transfer as a payment method and confirms the order, communication between your shop and our interface (API) is initiated. Prior to the description of the individual Direct Bank Transfer process steps and the corresponding API calls, several framework conditions are explained that are required for successful execution of Direct Bank Transfer.
3.1 Integration of Direct Bank Transfer in the checkout
To integrate Direct Bank Transfer in the checkout, it is necessary to add an additional option for Direct Bank Transfer to the selection of the payment methods (for example as a new radio button, link, etc. - Details on this topic can be found in the documentation of your shop system). Logos, banners, information texts and links on detailed information for your customers are provided in the Integration Centre in Advertising Media to ensure optimal integration of Direct Bank Transfer.
3.2 Communication with the Direct Bank Transfer interface
Our interface (API) can be called from your shop by a HTTP POST with attached XML parameters. The responses for calls of our interface are formatted in XML as well.
Direct communication with our interface via XML-HTTP messages always follows the same pattern:
• (API step 1) Initial API call and transaction parameter transfer
• (API step 2) API response with payment URL to redirect the customer to
• (API step 3) Transaction status change notification
• (API step 4) Transaction data request
• (API step 5) Response to transaction data request
If you use PHP or Java as programming language for the integration, we provide code libraries (SofortLib) to considerably facilitate the implementation in your system. Implementation examples and short instructions on how to use the SofortLib can be found on our Integration Center.
3.3 Initial API call and transaction parameter transfer (API step 1)
3.3.1 API call and authentication
To prevent abuse of the interface, authentication must be performed for every interface call, using your customer number as user name and the API key as password. The API key is provided in the merchant menu at Additional services → API key. Please note the following before using the interface:
- You have to call the correct URL using HTTPS as a protocol.
- You have to transfer the correct authentication information. For authentication, the basic HTTP authentication (RFC 2617) is used.
- You have to enter the correct content type headers.
- Your data must be correctly formatted in XML (RFC 3023, see parameter description) and sent by HTTP POST.
The interface is called via the following URL:
https://api.sofort.com/api/xml
3.3.2 Transfer of transaction data
Various parameters must be transferred to our API for the call. Some parameters are mandatory, some are optional. Details on the use of the individual parameters are listed in the overview of parameters.
Note
The Interface version logic used in all cases is in the following:
<interface_version>shopsystem name_shopsystem version/payment module name_payment module version</interface_version>
An example can be such as the following:
<interface_version>Magento_2.1.4/Sofort_2.3.3</interface_version>
In case that you have built your own shop system, we recommend to use the same interface version logic.
An example can be:
<interface_version>MyShop/Sofort_0.1</interface_version>
Or
<interface_version>OwnShop/Sofort_0.2</interface_version>
In the following, there will be shown only the logic used for the interface version in order not to use any example given as the interface version that you have to transmit.
An example of an Direct Bank Transfer call formatted in XML might look as follows:
<?xml version="1.0" encoding="UTF-8" ?> <multipay> <project_id>53245</project_id> <interface_version>shopsystem name_shopsystem version/payment module name_payment module version</interface_version> <amount>2.20</amount> <currency_code>EUR</currency_code> <reasons> <reason>Testueberweisung</reason> <reason>-TRANSACTION-</reason> </reasons> <user_variables> <user_variable>test</user_variable> </user_variables> <success_url>https://www.example.com/payment/success.php?trx=-TRANSACTION-</success_url> <success_link_redirect>1</success_link_redirect> <abort_url>https://www.example.com/payment/abort.php</abort_url> <notification_urls> <notification_url>https://www.example.com/notify.php</notification_url> <notification_url notify_on="received,loss">https://www.example.com/erp/payment_notification.php</notification_url> </notification_urls> <su /> </multipay>
Transfer of the reason for Belgian banks
Some Belgian banks use a separate field for the reason when the first 12 characters of the parameter reason contain only numbers.
Due to this, the reason on the bank statement can be falsified and important information on the bank statement may not be shown anymore.
We recommend to use at least one letter in the first 12 characters of the reason parameter for transactions from Belgium. Special characters like hyphen will only be seen as a subdivision of the numbers and don't prevent the usage of the separate field.
3.3.3 Transfer of the beneficiary for the Wire Transfer Regulation 2017
When you have to set the beneficiary for each transaction for the Wire Transfer Regulation (since 26.06.2017) you can use the beneficiary parameters for this.
Note:
As banks don't provide a specific field for the beneficiary we add these values to the usage. The usage is than containing the values <reasons> and <beneficiary>.
The usage field might not be long enough at every bank to show the whole beneficiary informations.
An example of an Direct Bank Transfer call formatted in XML might look as follows:
<?xml version="1.0" encoding="UTF-8" ?> <multipay> <project_id>53245</project_id> <interface_version>pn_test_1</interface_version> <amount>2.20</amount> <currency_code>EUR</currency_code> <beneficiary> <identifier>John Doe</identifier> <country_code>DE</country_code> </beneficiary> <reasons> <reason>Testueberweisung</reason> <reason>-TRANSACTION-</reason> </reasons> <user_variables> <user_variable>test</user_variable> </user_variables> <success_url>https://www.example.com/payment/success.php?trx=-TRANSACTION-</success_url> <success_link_redirect>1</success_link_redirect> <abort_url>https://www.example.com/payment/abort.php</abort_url> <notification_urls> <notification_url>https://www.example.com/notify.php</notification_url> <notification_url notify_on="received,loss">https://www.example.com/erp/payment_notification.php</notification_url> </notification_urls> <su /> </multipay>
3.4 API response with payment URL to redirect the customer to (API step 2)
As a response of this call, you will receive a transaction ID and the URL to process the payment (payment wizard) by the customer. Direct your customer on the returned URL of the payment form. There, your customer will be requested to enter the online banking details and to authorize the transfer. Subsequently, your customer will be directly forwarded to the transferred success page (back in your shop) or specified abort page in case of cancellation. The parameters and their descriptions which might be included in a response are listed in the overview of parameters.
An example of the interface response formatted in XML might look as follows:
<?xml version="1.0" encoding="UTF-8" ?> <new_transaction> <transaction>99999-53245-5483-4891</transaction> <payment_url>https://www.sofort.com/payment/go/508712aa8572615d6151de6111349bc5872435987c23c</payment_url> </new_transaction>
You should then redirect your customer to the page transferred in the parameter "payment_url". The transaction ID is transferred in the parameter "transaction". You should store this transaction ID with the corresponding order to request for example transaction data at a later point of time.
3.5 Redirecting your customer to the success/abort page
After successful execution of Direct Bank Transfer, your customer will be redirected to the success link stored with the project or transferred with the call (API step 1). Ideally, the order will be confirmed in a final summary including the successful execution of Direct Bank Transfer in the customer's online banking. In the background, your shop system should meanwhile have received a confirmation of the transaction (see API steps 3, 4, and 5), emptied the shopping cart, and stored the order with the corresponding status.
In case Direct Bank Transfer has not been carried out successfully, your customer will be redirected to the abort link. This link should ideally redirect the customer to the selection of payment methods with the shopping cart still being filled.
3.6 Transaction status change notification (API step 3)
After successful execution of Direct Bank Transfer, you will be notified of the executed transaction while the customer is redirected to the success page. This is done by calling the notification URL either stored with the project or already transferred when initially calling the API (API step 1). This notification includes the transaction ID of the transaction whose status changed.
An example of an interface notification formatted in XML might look as follows:
<?xml version="1.0" encoding="UTF-8" ?> <status_notification> <transaction>99999-53245-5483-4891</transaction> <time>2010-04-14T19:01:08+02:00</time> </status_notification>
You will receive a notification of every transaction status change. Please initiate a transaction data request (see API step 4) to learn the reason for the status change (see API step 4).
3.7 Transaction data request (API step 4)
You should respond to a notification by requesting transaction data. You may either request transaction data on specified transaction IDs or all transaction data of transactions carried out in a specified time.
Two examples of transaction data requests formatted in XML might look as follows:
<?xml version="1.0" encoding="UTF-8" ?> <transaction_request version="2"> <transaction>99999-53245-5483-4891</transaction> <transaction>99999-53245-5741-1896</transaction> </transaction_request>
oder:
<?xml version="1.0" encoding="UTF-8" ?> <transaction_request version="2"> <from_time>2013-01-01</from_time> <to_time>2013-03-07</to_time> <number>10</number> <page>2</page> <product>payment</product> </transaction_request>
3.8 Response to transaction data request (API step 5)
Any data available on requested transactions will be transmitted. The parameters and their descriptions which might be included in a response are listed in the overview of parameters. If no transactions match the assigned search parameters of API-step 4 the response contains only an empty <transactions/> tag.
<?xml version="1.0" encoding="UTF-8" ?> <transactions> <transaction_details> <project_id>53245</project_id> <transaction>99999-53245-5483-4891</transaction> <test>1</test> <time>2013-06-03T10:48:52+02:00</time> <status>untraceable</status> <status_reason>sofort_bank_account_needed</status_reason> <status_modified>2013-06-03T10:48:52+02:00</status_modified> <payment_method>su</payment_method> <language_code>de</language_code> <amount>2.20</amount> <amount_refunded>0.00</amount_refunded> <currency_code>EUR</currency_code> <reasons> <reason>Testueberweisung</reason> <reason>99999-53245-5483-4891</reason> </reasons> <user_variables> <user_variable>test</user_variable> </user_variables> <sender> <holder>Max Mustermann</holder> <account_number>23456789</account_number> <bank_code>00000</bank_code> <bank_name>Demo Bank</bank_name> <bic>SFRTDE20XXX</bic> <iban>DE06000000000023456789</iban> <country_code>DE</country_code> </sender> <recipient> <holder>Erika Mustermann</holder> <account_number>9999999999</account_number> <bank_code>00000</bank_code> <bank_name>Demo Bank</bank_name> <bic>SFRTDE20XXX</bic> <iban>DE98000000009999999999</iban> <country_code>DE</country_code> </recipient> <email_customer /> <phone_customer /> <exchange_rate>1.0000</exchange_rate> <costs> <fees>0.00</fees> <currency_code>EUR</currency_code> <exchange_rate>1.0000</exchange_rate> </costs> <su> <consumer_protection>0</consumer_protection> </su> <status_history_items> <status_history_item> <status>untraceable</status> <status_reason>sofort_bank_account_needed</status_reason> <time>2013-06-03T10:48:52+02:00</time> </status_history_item> </status_history_items> </transaction_details> </transactions>
Status messages
The response of the transaction data includes the notification of the current status of the requested transaction(s).
A transaction will not be created with Direct Bank Transfer until the online banking details have been successfully entered and the customer's bank has confirmed and listed the transfer in the customer's online banking. If this has not yet taken place (for example when the payment process is still on-going or the payment could not be made by Direct Bank Transfer), you will receive a response with an empty <transactions /> tag when requesting transaction data on a transferred transaction ID. The final failure of a transaction cannot be established before the period of validity has expired (<timeout> from API step 1).
After successful execution of Direct Bank Transfer, a distinction must be made whether you have set up an account with Deutsche Handelsbank as a recipient account or not. In the first case, Sofort GmbH can immediately confirm the receipt of the money on your account and notify you if the money has not been received within a certain period of time. In the second case, if you have not set up an account with Deutsche Handelsbank as a recipient account, the status "untraceable" will be displayed after successful execution of Direct Bank Transfer.
Detailed information on possible statuses and their descriptions can be found in the Appendix.
Error messages
When a call of the interface is made incorrectly, you will receive different error messages.
HTTP error codes
HTTP error messages (for example 401 (-> unauthorised, HTTP authentication via customer number, API key failed), 404, ...)
Error code 401 Unauthorized is displayed when you entered incorrect authentication data (Base64-coded combination of customer number and API key)
Error code 404 Not Found is displayed when you call an incorrect URL
API error codes
If the HTTP call including authentication was successful (HTTP 200 OK), errors within the transferred XML data may generate additional error messages. The individual XML error codes and their descriptions which might be included in a response are listed in the overview of errors.
An example of a response including an error code and description formatted in XML might look as follows:
<?xml version="1.0" encoding="UTF-8" ?> <errors> <error> <code>8054</code> <message>All products deactivated due to errors, initiation aborted.</message> </error> <su> <errors> <error> <code>8014</code> <message>Invalid amount.</message> <field>amount</field> </error> </errors> </su> </errors> bzw. <?xml version="1.0" encoding="UTF-8" ?> <errors> <error> <code>7000</code> <message>Mismatched tag. line: 24, char: 29, tag: multipay->su->reasons</message> </error> </errors> bzw. <?xml version="1.0" encoding="UTF-8" ?> <new_transaction> ... <warnings> <warning> <code>8049</code> <message>Unsupported language.</message> <field>language_code</field> </warning> </warnings> </new_transaction>
4. Testing
In order to fully test the functionality of the integration of the installed payment methods, please carry out a test transfer directly in your (shop-)system. Please note the following steps:
- Activate test mode
- Carry out test transaction
- Check redirection to shop and notification
Please note that no real transfers will be made if you activate the test mode and use one of the specified test sort codes.
The test mode however allows real transfers when using a valid sort code.
Make sure to deactivate the test mode for productive use.
4.1 Activate test mode
Activate the test mode in your project in the merchant area on the Sofort GmbH website.
4.2 Carry out test transaction
- Carry out an order from your (shop-)system and select the respective payment method (Direct Bank Transfer).
- After having been redirected to the Direct Bank Transfer payment, check the transferred data (recipient including address, reason, amount).
- Then enter 88888888 (8 times the number "8") in the payment wizard as the sort code for German sender accounts, choose "Others" for Belgium and then 999 (3 times the number "9") and for all other countries 00000 (5 times the number "0") or select "Demo Bank". (Instead of the test bank code a country specific test BIC will shortly be available: "SFRT{ISO-country code}20XXX", e.g. "SFRTDE20XXX" for Germany. Via the API you can already transfer the test BIC as <sender><bic>)
- You can freely enter the other data requested, but make sure you observe a minimum length of 4 characters.
4.3 Check redirection/notification
If you set up a redirection to a success/abort page or a notification, check whether they are performed correctly and whether your system responds properly.
- Is the customer redirected to the confirmation page after the transaction?
- Do you get all notifications correctly provided that they have been activated and transferred?
- Are the order details recorded and loaded correctly?
- Is the order/payment status set correctly and is the order created correctly?
4.4 Checklist for the integration
- Activate product
- Create project
- Activate payment method in project
- Carry out test transaction
- Receive notification for test transaction
- Request and receive transaction data
- Implement and test potential refunds
5. Overview of parameters
If you do not use the code library (SofortLib), you will find the detailed XML interface documentation here.Description of the table columns of the subsequent tables
- Parameter: XML tag name which is transferred (<parameter>parameter-content</parameter>) The logical structure of an XML document is a tree structure, thus featuring a hierarchical organization. The hierarchy is illustrated by indentation in the tables. Parameters marked in boldface symbolizes parent nodes with one or more child nodes.
- Number: specifies how frequently a parameter may be used under its higher-level parameter
- [1] = mandatory parameter
- [0,1] = optional parameter, a maximum of one value can be transferred
- [0..20] = optional parameter, up to 20 values can be transferred
- [n] = optional parameter, any number of parameters can be transferred
- [1..n] = mandatory parameter, a minimum of one parameter must and any number of parameters can be transferred
- Type (length): specifies the data type of the parameter content; if this is a string, the maximum permissible number of characters is stated
- Description: detailed description of the use of the parameter
5.1 (API step 1) Initial API call and transaction parameter transfer
5.1.1 API call and authentication
The interface is called via the following URL:
https://api.sofort.com/api/xml
The basic http authentication (RFC 2617) is used for authentication. Please enter your customer number as user name (for example 99999) and your API key as password (for example a12b34cd567890123e456f7890123456), separated by ":" and coded by Base64 (base64(99999:a12b34cd567890123e456f7890123456)).For every call, the field Content-Type and the field Accept in the HTTP header requires an input of "application/xml".An example of a HTTP header might look as follows:
Authorization: Basic OTk5OTk6YTEyYjM0Y2Q1Njc4OTAxMjNlNDU2Zjc4OTAxMjM0NTYgContent-Type: application/xml; charset=UTF-8Accept: application/xml; charset=UTF-8
After successful authentication, the server will confirm your API call with HTTP 200 OK.The content of the messages must be correctly formatted in XML. The possible parameters are described in detail in the following.Note: You have to use the URL specified above for every API call described in the following and authenticate yourself as described.
5.1.2 Payment data transfer
This table contains all possible parameters which you can transfer to our system in a call.
| Parameter | Number of | Type (Length) | Description | ||
| multipay | [1] | Container | Identifies the Direct Bank Transfer API call, encloses the entire message | ||
| project_id | [1] | Integer | Project number | ||
| interface_version | [0,1] | String (255) | Identifies the Shop system version and Payment module by requesting the data in this format: <interface_version>shopsystem name_shop system version/module name_payment-module version</interface_version> | ||
| language_code | [0,1] | String (2) | Language of payment wizard, according to ISO 639-1 e.g. "DE"; is interdependent with <sender><country_code> and should only be used if a certain language should be forced. Otherwise, dynamic parameters like the browser language are used to determine the language of the payment wizard. | ||
| timeout | [0,1] | Integer | Transaction validity in seconds from the generation of the message new_transaction in the Direct Bank Transfer Gateway to the listing of the transfer / direct debit / etc.; default: unlimited | ||
| email_customer | [0,1] | String (255) | Email address of your customer, e.g. for invoice, cash in advance | ||
| phone_customer | [0,1] | String (255) | Phone number of your customer (begins with "+"; possible characters: "0-9 , - / ( )", no letters! ) | ||
| user_variables | [0,1] | Container | List of user variables | ||
| user_variable | [0..20] | String (255) | User variable | ||
| sender | [0,1] | Container | Data of the sender (bank account of your customer) | ||
| holder | [0,1] | String (27) | Account holder | ||
| iban | [0,1] | String (34) | IBAN | ||
| bic | [0,1] | String (11) | BIC | ||
| account_number | [0,1] | String (30) | DEPRECATED: Account number, please use <iban> | ||
| bank_code | [0,1] | String (30) | DEPRECATED: Sort code, please use <bic> | ||
| country_code | [0,1] | String (2) | Country code according to ISO 3166-1; e.g. "de" | ||
| amount | [1] | Decimal (8.2) | Amount, format: no thousands separators, two digits behind the decimal point, separated by a point ".", e.g. "1150.00" (1.150,00 EUR)Please note that if the currency_code is "HUF" and a float value is assigned the amount will be rounded to the nearest integer value. (e.g. 1000.50 > 1001 and 1000.49 > 1000). | ||
| currency_code | [1] | String (3) | Currency according to ISO 4217, e.g. "EUR" | ||
| reasons | [1] | Container | List of reasons | ||
| reason | [1..2] | String (27) | Reason; please transfer a unique value (e.g. order ID and customer ID, "OID018293 CID00131"), only the following characters are allowed: '0-9', 'a-z', 'A-Z', ' ', '+', ',', '-', '.'. Umlauts are replaced, e.g. ä -> ae. Other characters will be removed for the display on our payment page and for notifications. Therefore, a modified string for reason may be transmitted for redirections (success and abort link and notifications). If the transaction ID of Direct Bank Transfer should be used as a reason, the parameter '-TRANSACTION-' can be inserted in the reason String.Important: Some banks do not display the entire characters of both reasons, e.g. on the account statements the last characters are cut off. Therefore, the important data should be inserted at the beginning of the first reason field.* Banks of Great Britain (GB) only support 18 digits per reason so we encourage to consider this for integrations that are used in this market. | ||
| success_url | [0,1]* | String (255) | Success link, overwrites the default value from the project settings. Is called when your customer successfully executed Direct Bank Transfer and the transfer has been listed in the customer's online banking. If the transaction ID of Direct Bank Transfer should be used as part of the URL, the parameter '-TRANSACTION-' can be inserted in the URL String.* If no success link is defined in the project settings this parameter becomes mandatory | ||
| success_link_redirect | [0,1] | Boolean | Automatic redirection to success page. If this has not been activated, a summary page of Sofort GmbH will be displayed to the customer. Overwrites project settings. | ||
| abort_url | [0,1]* | String (255) | Abort link, overwrites the default value from the project settings. Is called when Direct Bank Transfer could not be completed successfully (e.g. upon cancellation by the customer or insufficient funds). If the transaction ID of Direct Bank Transfer should be used as part of the URL, the parameter '-TRANSACTION-' can be inserted in the URL String.* If no abort link is defined in the project settings this parameter becomes mandatory | ||
| timeout_url | [0,1] | String (255) | Timeout link, overwrites the default value from the project settings. Is called when the timeout value stored in the project settings has been expired on the payment wizard. If the transaction ID of Direct Bank Transfer should be used as part of the URL, the parameter '-TRANSACTION-' can be inserted in the URL String. | ||
| notification_urls | [0,1] | Container | List of notification links | ||
| notification_url | [0..5] | String (255) | Notification link. If the transaction ID of Direct Bank Transfer should be used as part of the URL, the parameter '-TRANSACTION-' can be inserted in the URL String. | ||
| notification_url notify_on="xyz" | [0..5] | String (255) | Notification link; by replacing the part "xyz" by a special status, only this URL is used for notifications with this status. It is possible to enter several statuses separated by commas, e.g <notification_url notify_on="pending, loss">. Possible statuses are "received", "loss", "refunded", and "pending" (whereupon "pending" matches the equivalent status "pending - not_credited_yet" and "untraceable - sofort_bank_account_needed". Details can also be found in the corresponding section. | ||
| notification_emails | [0,1] | Container | List of notification email addresses | ||
| notification_email | [0..10] | String (255) | Notification email addresses | ||
| notification_email notify_on="xyz" | [0..10] | String (255) | Notification email; by replacing the part "xyz" by a special status, only this email is used for notifications with this status. It is possible to enter several statuses separated by commas, e.g <notification_url notify_on="pending, loss">. Possible statuses are "received", "loss", "refunded", and "pending" (whereupon "pending" matches the equivalent status "pending - not_credited_yet" and "untraceable - sofort_bank_account_needed". Details can also be found in the corresponding section. | ||
| su | [1] | Container | Container for special parameters regarding Direct Bank Transfer. Is mandatory for each Direct Bank Transfer API call and might be transferred empty: <su /> | ||
| beneficiary | [0,1] | Container | Container for special parameters regarding Direct Bank Transfer. | ||
| identifier | [0,1] | String (27) | beneficiary | ||
| country_code | [0,1] | String (2) | country of the beneficiary | ||
Table 1: Parameter definition of the initial call and transaction parameter transfer (API step 1)
5.2 (API step 2) API response with payment URL to redirect the customer to
The response to the API call includes a transaction number and a URL to redirect the customer to. The response may also include warnings.
| Parameter | Number of | Type (Length) | Description | ||||
| new_transaction | [0,1] | Container | Identifies the response to the initial call to transfer the transaction parameters, encloses the entire message | ||||
| transaction | [1] | String (27) | Generated transaction number | ||||
| payment_url | [1] | String (255) | Payment wizard URL | ||||
| su | [0,1] | Container | Sofort | ||||
| warnings | [0,1] | Container | List of warnings | ||||
| warning | [1..n] | Container | Warning, non-critical errors | ||||
| code | [1] | Int | Warning number | ||||
| message | [1] | String(255) | Warning message | ||||
| errors | [0,1] | Container | Error (find definition below) - may be alternatively returned instead of the tag <new_transaction> | ||||
| ... | |||||||
Table 2: Parameter definition of the response with payment URL (API step 2)
5.3 (API step 3) Transaction status change notification
Upon completion of a transaction or in case of a status change, you will receive a message containing the following parameters.
| Parameter | Number of | Type (Length) | Description | |
| status_notification | [1] | Container | Identifies a transaction status change, encloses the entire message | |
| transaction | [1] | String (27) | Transaction number | |
| time | [1] | String (25) | Date and time (with time zone) according to ISO 8601 in the format YYYY-MM-DDThh:mm:ss+HH:mm, e.g. 2013-03-14T11:38:00+02:00 | |
Table 3: Parameter definition of the transaction status change notification (API step 3)
5.4 (API step 4) Transaction data request
If you want to learn more about status changes, submit a transaction detail request containing the following parameters. You may either request details on specific transaction numbers (<transaction>) or on a specific period of time and more filter criteria, in which the transactions were generated.
Note on data requests on a specific period of time:You cannot request more than 100 transaction data records at a time, even if you omit the <number> parameter (in this case the default value 100 takes effect).Periods comprising more than 100 transactions require iterative requests with <page>1</page>, <page>2</page> etc.
| Parameter | Number of | Type (Length) | Description | |
| transaction_request (with attribute version="2") | [1] | Container | Identifies the transaction data request, encloses the entire message. Please take care to send also the attribute version="2". Otherwise you will receive different status codes as described in this manual. | |
| transaction | [0..100] | String (27) | Transaction number; it is possible to request several transaction numbers at a time | |
| from_time | [0,1] | String (25) | Start of a time interval if no transaction number was transferred. Default: [date of call] 0:00 hrsFormatted according to ISO 8601 YYYY-MM-DD or YYYY-MM-DDThh:mm:ss+HH:mm | |
| to_time | [0,1] | String (25) | End of a time interval if no transaction number was transferred. Default: [time of call]Formatted according to ISO 8601 YYYY-MM-DD or YYYY-MM-DDThh:mm:ss+HH:mm | |
| from_status_modified_time | [0,1] | String (25) | Start of a time interval if no transaction number was transferred. This interval refers to transactions which have undergone the latest status change within this period of time.Default: date of call 0:00 hrs.Formatted according to ISO 8601: YYYY-MM-DD or YYYY-MM-DDThh:mm:ss+HH:mm | |
| to_status_modified_time | [0,1] | String (25) | End of a time interval if no transaction number was transferred. This interval refers to transactions which have undergone the latest status change within this period of time.Default: date of call 0:00 hrs.Formatted according to ISO 8601: YYYY-MM-DD or YYYY-MM-DDThh:mm:ss+HH:mm | |
| status | [0,1] | String | Statuses to which the returned transactions are to be limited | |
| status_reason | [0,1] | String | Status reasons to which the returned transactions are to be limited | |
| product | [0,1] | String | Product to which the returned transactions are to be limited ("payment": Direct Bank Transfer, "paycode": Paycode) | |
| number | [0,1] | Integer | Number of transactions to be transmitted (for request of time period). Default/Max: 100 | |
| page | [0,1] | Integer | If number is used, the following transactions can be requested with this parameter. Default: 1e.g. number=10, page=2 → transactions 11-20 are displayed | |
Table 4: Parameter definition of transaction data request (API step 4)
5.5 (API step 5) Response to transaction data request
The table provides an overview of all parameters which a transaction detail request may contain.
| Parameter | Number of | Type (Length) | Description | ||||||
| transactions | [0,1] | Container | Identifies the response to a transaction data request, encloses the entire message. | ||||||
| transaction_details | [0..n] | Container | Details of a transaction | ||||||
| project_id | [1] | Integer | Project number | ||||||
| transaction | [1] | String (27) | Transaction number | ||||||
| test | [1] | Boolean | Test transaction ("0" for false, "1" for true) | ||||||
| time | [1] | String (25) | Date and time of transaction generation (with time zone) according to ISO 8601 in the format YYYY-MM-DDThh:mm:ss+HH:mm , e.g. "2013-03-14T13:02:10+01:00" | ||||||
| status | [1] | String (20) | Status code of the transaction (see status codes) | ||||||
| status_reason | [1] | String (255) | Status reason | ||||||
| status_modified | [1] | String (25) | Date and time of the latest status change (with time zone) according to ISO 8601 in the format YYYY-MM-DDThh:mm:ss+HH:mm, e.g. "2013-03-14T13:17:10+01:00" | ||||||
| payment_method | [1] | String (7) | Payment method used ("su" for Direct Bank Transfer - others: paycode) | ||||||
| language_code | [1] | String (2) | Language according to ISO 639-1 | ||||||
| amount | [1] | Decimal (8.2) | Transfer amountPlease note that if the currency_code is "HUF" and a float value has been assigned in API-step 1 the returned amount is rounded to the nearest integer value. (e.g. 1000.50 > 1001 and 1000.49 > 1000). | ||||||
| amount_refunded | [0,1] | Decimal (8.2) | Refund amount | ||||||
| currency_code | [1] | String (3) | Currency according to ISO 4217, e.g. "EUR" | ||||||
| reasons | [1] | Container | List of reasons | ||||||
| reason | [0..2] | String (255) | Reason | ||||||
| user_variables | [1] | Container | List of user variables | ||||||
| user_variable | [0..20] | String (255) | User variable | ||||||
| sender | [1] | Container | Sender data (bank account of your customer) - These values might be completed or calculated from the customer's data, therefore we can not guarantee for their correctness. | ||||||
| holder | [1] | String (255) | Account holder | ||||||
| account_number | [1] | String (30) | Account number | ||||||
| bank_code | [1] | String (30) | Sort code | ||||||
| bank_name | [1] | String (255) | Name of bank | ||||||
| bic | [1] | String (11) | BIC | ||||||
| iban | [1] | String (34) | IBAN | ||||||
| country_code | [1] | String (2) | Country code according to ISO 3166-1 | ||||||
| recipient | [1] | Container | Recipient data (bank account of merchant) | ||||||
| holder | [1] | String (27) | Account holder | ||||||
| account_number | [1] | String (30) | Kontonummer | ||||||
| bank_code | [1] | String (30) | Sort code | ||||||
| bank_name | [1] | String (255) | Name of bank | ||||||
| bic | [1] | String (11) | BIC | ||||||
| iban | [1] | String (34) | IBAN | ||||||
| country_code | [1] | String (2) | Country code according to ISO 3166-1 | ||||||
| email_customer | [1] | String (255) | End customer email address, e.g. for invoice | ||||||
| phone_customer | [1] | String (255) | End customer phone number (starts with "+"; possible characters: "0-9 , - / ( )" – no letters! ) | ||||||
| exchange_rate | [1] | Decimal (8.4) | Exchange rate | ||||||
| costs | [1] | Container | Data on fees | ||||||
| fees | [1] | Decimal (8.2) | Fees associated with the requested transaction | ||||||
| currency_code | [1] | String (3) | Currency according to ISO 4217, e.g. "EUR" | ||||||
| exchange_rate | [1] | Decimal (8.4) | Exchange rate | ||||||
| su | [0,1] | Container | Direct Bank Transfer | ||||||
| status_history_items | [1] | Container | Container for status history items | ||||||
| status_history_item | [0...n] | Container | Sub-category for individual, previous status items | ||||||
| status | [1] | String (20) | Status code of the transaction (see status codes) | ||||||
| status_reason | [1] | String (255) | Status reason | ||||||
| time | [1] | String (25) | Time of the set status according to ISO 8601 in the format YYYY-MM-DDThh:mm:ss+HH:mm, e.g. "2013-03-14T13:02:10+01:00" | ||||||
| errors | [0,1] | Container | Error (find definition below) - may be alternatively returned instead of the tag <transactions> | ||||||
| ... | |||||||||
Table 5: Parameter definition of response to transaction data request (API step 5) Status messages A transaction detail message always includes a transaction status and a status reason. Provided that a Deutsche Handelsbank account is defined as recipient account for the Direct Bank Transfer transactions the following status can occur:
| Parameter <status> | Parameter <status_reason> | Description |
| loss | not_credited | The money has not been received. |
| pending | not_credited_yet | The money has not yet been received. |
| received | credited | The money has been received. |
| refunded | compensation | The money has been refunded (partial refund). |
| refunded | refunded | The money has been refunded (complete refund of total amount). |
Table 6: Status messages for transactions with Direct Bank Transfer and Deutsche Handelsbank accountIn case the recipient account of the Direct Bank Transfer account is not a Deutsche Handelsbank account the following status can occur:
| Parameter <status> | Parameter <status_reason> | Description |
| untraceable | sofort_bank_account_needed | The Direct Bank Transfer transaction was successfully completed. Additional status messages on the receipt of the amount on the account are only possible if a Deutsche Handelsbank account exists.Note: if the API call <transaction_request> is transmitted without the version attribute with value "2", the <status> value "untraceable" is replaced by "pending" with <status_reason> "not_credited_yet". This version 1 transaction request is deprecated. |
| refunded | compensation | The money has been refunded (partial refund). |
| refunded | refunded | The money has been refunded (complete refund of total amount). |
Table 7: Status messages for transactions with Direct Bank Transfer without Deutsche Handelsbank account
Please keep in mind that if a Direct Bank Transfer transaction has been successfully finished and Sofort GmbH has received the confirmation from the buyer's bank, Sofort GmbH reports the status "untraceable - sofort_bank_account_needed" (without Deutsche Handelsbank account) or "pending - not_credited_yet" (with Deutsche Handelsbank account). Both status messages have the equivalent meaning and represent the real-time transaction confirmation that should be processed by the merchant's online shop system.
5.6 Error messages/Warning
In case of an error/warning, you will receive the corresponding error code in the message.
| Parameter | Number of | Type (Length) | Meaning | ||||
| errors | [0,1] | Container | List of errors | ||||
| error | [1..n] | Container | Individual error | ||||
| code | [1] | Integer | Error number | ||||
| message | [1] | String (255) | Error message | ||||
| field | [0,1] | String (255) | Field the errors refers to | ||||
| su | [0,1] | Container | List of Direct Bank Transfer specific errors | ||||
| errors | [1] | Container | List of errors | ||||
| error | [1..n] | Container | Individual error | ||||
| code | [1] | Integer | Error number | ||||
| message | [1] | String (255) | Error message | ||||
| field | [0,1] | String (255) | Field the errors refers to | ||||
| warnings | [0,1] | Container | List of warnings | ||||
| warning | [1..n] | Container | Individual warning | ||||
| code | [1] | Integer | Warning number | ||||
| message | [1] | String (255) | Warning message | ||||
| field | [0,1] | String (255) | Field the warning refers to | ||||
Table 8: Response to errors Error codes General errors upon a call
| Code | Message | Meaning |
| 1000 | Invalid request. | Invalid request |
| 1001 | Technical error. | Technical Error |
| 7000 | Invalid XML | Invalid XML |
| 7004 | XML parameter not provided in request | Empty POST data |
| 7005 | Project has no Deutsche Handelsbank account. | No Deutsche Handelsbank account stored with the project. |
| 7006 | Service temporarily unavailable due to maintenance | The service of Sofort GmbH/Deutsche Handelsbank is temporarily unavailable due to maintenance. |
Table 9: General errors Specific errors/warnings upon a call
| Code | Message | Meaning |
| 8000 | No project ID provided | No project ID transferred |
| 8001 | Unknown project | Unknown project |
| 8002 | Validation Error | An assigned parameter causes an error during validation |
| 8003 | Request could not be processed | Response to the transaction request not possible due to an error |
| 8004 | No product is selected | No product element (<su/>) was submitted in the call. |
| 8006 | Logic error. | e.g. the project has not been activated and is neither in the test mode, the requested product has not been activated or the data in the call contradict the project settings |
| 8010 | must not be empty | The field listed must not be empty. |
| 8011 | not in list of valid values | The transferred value is not included in the list of possible values. |
| 8012 | must be a positive number | The transferred value is not a positive number, e.g. the number of items of a shopping cart position. |
| 8013 | unsupported currency | The transferred currency is not supported by the system. At this time, only EUR, GBP, CHF, PLN, HUF, and CZK are accepted. |
| 8014 | invalid amount | The transferred amount must be positive and must only have two decimal numbers at the most. A "." or "," is accepted as a decimal separator. |
| 8015 | amount is out of range | The transferred amount is too large or too small. |
| 8016 | must be a valid url | The transferred URL is invalid. |
| 8017 | invalid chars | The transferred value contains characters which are not accepted, e.g. only certain characters are permitted in the field reason. |
| 8018 | maximum length of 27 chars exceeded | Permitted number of characters exceeded, excess characters will be removed where required (e.g. in the field reason) |
| 8019 | invalid email address | Invalid email |
| 8021 | invalid country code | Value must be transferred according to ISO 3166. |
| 8022 | unsupported country code | Transferred country code is not supported by our system. |
| 8023 | invalid BIC | Invalid BIC |
| 8025 | must be 2 or 3 // salutation | Mr. = 2, Mrs. = 3. |
| 8026 | must be a boolean, either 0 or 1 | 0 or 1 must be entered as a value. |
| 8027 | product not activated and not in testmode | The requested payment method is not available as the test mode has been deactivated and the payment method has not yet been released. |
| 8028 | locked_sender_country_id is activated in project settings, but not provided | The settings of the payment method determine that the sender country must not be changed by the end customer during the payment process. When initiating the payment, the sender country must then be stated. |
| 8040 | No amount with comma allowed for HU. | The amount has been transferred with decimal places which has been rounded down/up to the next integer (see also <amount>). |
| 8045 | product in testmode and given bank_code is not a test bank code | Account number, sort code, and account holder were transferred. Since the payment method runs in the test mode, one of the test sort codes must be entered (e.g. 00000). |
| 8046 | validation of given bank account and bank code failed | The settings of the payment method determine that the sender data must not be changed by the end customer during the payment process. The transferred account data could not be validated however. |
| 8047 | Maximum length of 255 characters exceeded. | Maximum number of characters (255) exceeded. |
| 8049 | unsupported language | The transferred language is not supported by the system. |
| 8050 | value too small. setting timeout to minimum value. | The transferred value for the duration of the payment process was too small and will be set to the minimum permissible value (120 seconds) |
| 8051 | invalid items found | The request contained invalid shopping cart items |
| 8054 | all products deactivated due to errors. Initiation aborted | All requested payment methods contained validation errors. The payment session could not be initiated. |
| 8057 | activate this product in your project settings | The requested payment method has not been activated for the project. The merchant must activated the payment method in the merchant menu to be able to use the payment method. |
| 8058 | payment not possible with this service | The payment cannot be used for this service |
| 8059 | sender country not supported for this currency | Payments in the desired currency cannot be made for the specified sender country |
| 8060 | Blacklisted | The payment cannot be executed as either the transferred banking details or the country has been blocked by the merchant. |
| 8063 | No success_url provided in request and in project settings | The success link was neither set in the request nor in the settings. |
| 8064 | No abort_url provided in request and in project settings | The abort link was neither set in the request nor in the settings. |
| 8072 | maximum number of notification exceeded | Too many notification urls or notification email addresses have been assigned. |
| 8073 | Maximum number of user variables exceeded | Too many user variables have been assigned. |
Table 10: Special errors/warnings Errors upon a transaction detail request
| Code | Message | Meaning |
| 7999 | Out of range (Too many entries or invalid values for the site) | Too many entries per page or invalid value for the page |
| 8005 | Too many transactions requested | Too many transactions requested |
| 8007 | Invalid date format. Format is YYYY-MM-DD [HH:MM:SS] | Invalid date format |
| 8008 | from_time equals to_time | The from/to data must be different |
| 8009 | max date range exceeded | Search interval too big (interval covers 30 days at max.) |
Table 11: Error for the transaction detail request Direct Bank Transfer Gateway Possible HTTP status codes of the interface200 OK: message accepted401 Unauthorized: no permission, e.g. wrong API key404 Not Found: called URL does not exist or wrong URL was called
6. Support & Contact
The Direct Bank Transfer team will be available if you need help.
You may send us an email at service@sofort.com.
We are also glad to assist you in case of technical issues:
Technical support:
Phone: +49 (0)89 24 88 37 691
Email: integration@sofort.com
Business hours:
Monday to Thursday: 8:30 a.m. to 6:00 p.m.
Friday: 8:30 a.m. to 5:00 p.m.
7. Legal Notice
Sofort GmbH
Theresienhöhe 12
80339 Munich
Germany
Support for customers
Phone: +49 (0)89 24 88 37 690
Support for merchants
Phone: +49 (0)89 24 88 37 692
info@sofort.com
www.sofort.com
Directors
Felix Würtenberger
Knut Frängsmyr
External Data Protection Officer
Mr. Michael Schramm, LL.M.
For privacy questions please contact us at: datenschutz@sofort.com
Registered at the District Court Munich
HRB 218675
VAT-ID: DE248376956
© Sofort GmbH. All rights reserved, including the translation.
The documentation including all published content is protected by copyright. Reprints or reproduction of any kind and processing, duplication, and distribution using electronic systems of any kind shall only be permitted with prior written consent of Sofort GmbH.
The contents of this documentation and the implementation of the information contained therein may only be used at your own risk. Sofort GmbH assumes no responsibility for the function of individual programmes or of parts of them. In particular, Sofort GmbH assumes no responsibility for possible damages resulting from the use.
Source: https://integration.sofort.com/integrationCenter-eng-DE/content/view/full/2513/
0 Response to "Test Mode Transactions in Easy Pay Direct"
Post a Comment