Sie sind auf Seite 1von 76

Manual integration sofort Gateway

Version 1.1 22 Dec 2011

PAYMENT NETWORK AG. All rights reserved.

It is prohibited to reproduce parts of this documentation or to process, copy or distribute parts of it using electronic equipment without the written approval of the PAYMENT NETWORK AG. The PAYMENT NETWORK AG does not assume any liability for the functioning of individual programs or parts thereof. In particular, no liability is assumed for possible damages resulting from use.

Manual Integration sofort Gateway

Seite 2

Table of contents
1.GENERAL..............................................................................................................................................8 1.1 The sofort Gateway.......................................................................................................................8 1.2 Possible payment methods with sofort Gateway..............................................................................8 1.3 General course of transaction via sofort Gateway............................................................................9 2.GENERAL PROCEDURE FOR THE INTEGRATION OF SOFORT PRODUCTS................................................10 2.1 Integration steps.........................................................................................................................10 2.2 Approach for integration with this guide........................................................................................10 3.CREATING A NEW PROJECT.................................................................................................................11 3.1 Creating a project........................................................................................................................11 3.1.1.Generall Settings..................................................................................................................11 3.1.2.Address...............................................................................................................................11 3.1.3.Bank account.......................................................................................................................11 3.1.4.Settings for all payment methods .........................................................................................12 3.1.5.Payment Methods................................................................................................................13 3.2 Settings in your sofort Gateway project.........................................................................................15 3.2.1.Base settings.......................................................................................................................15 3.3 API-Key.......................................................................................................................................17 4.INTEGRATING A PAYMENT METHOD....................................................................................................18 4.1 Possibilities of integration.............................................................................................................18 4.1.1.Payment selection in the shop...............................................................................................18 4.1.2.Payment selection in the sofort Gateway...............................................................................18 4.2 Communication with the sofort Gateway....................................................................................18 4.2.1.Authentication with API Key..................................................................................................19 4.2.2.Call of the interface..............................................................................................................19 4.2.3.Response of the sofort Gateway............................................................................................21 4.2.4.Transaction notification.........................................................................................................22 4.2.5.Request for the transaction details........................................................................................22 4.2.6.Response of the sofort Gateway to an request for transaction details......................................23 4.2.7.Error Codes..........................................................................................................................23 4.3 Product-speficic characteristics.....................................................................................................24 4.3.1.sofortbanking.......................................................................................................................24 4.3.2.Rechnung by sofort..............................................................................................................25 4.3.3.Confirm/change of Rechnung by sofort..................................................................................25 4.3.4.sofortlastschrift....................................................................................................................29 4.3.5.Lastschrift by sofort..............................................................................................................29 4.3.6.Vorkasse by sofort................................................................................................................30 4.3.7.sofortdauerauftrag................................................................................................................31 5.TESTING............................................................................................................................................33 5.1 Test invoice by sofort ..................................................................................................................33

Manual Integration sofort Gateway

Seite 3

6.REFUNDS...........................................................................................................................................34 6.1 Refunds via the customer menu (manually)...................................................................................34 6.1.1.Prepare refunds ..................................................................................................................35 6.1.2.Consolidate refunds .............................................................................................................35 6.1.3.Complete refunds ................................................................................................................35 6.2 Refunds via the XML interface (automatically) ..............................................................................35 6.2.1.Generall...............................................................................................................................35 6.2.2.Authentication.....................................................................................................................36 6.2.3.Prepare refunds...................................................................................................................36 6.2.4.Consolidate refunds..............................................................................................................37 6.2.5.Complete refunds.................................................................................................................38 6.2.6.Testing refunds....................................................................................................................38 6.2.7.Error codes..........................................................................................................................39 7.ANNEXE..............................................................................................................................................41 7.1 Explanation of the view in the following tables...............................................................................41 7.2 Call of the interface......................................................................................................................41 7.2.1.Transaction request to the sofort Gateway.............................................................................41 7.2.2.Response to a transaction request.........................................................................................47 7.3 Notification about a status change of a transaction........................................................................48 7.3.1.Notification about a status change.........................................................................................48 7.3.2.Transaction detail request.....................................................................................................48 7.3.3.Response to a transaction detail request................................................................................49 7.4 Status messages of the respective product....................................................................................54 7.4.1.sofortbanking.......................................................................................................................54 7.4.2.Rechnung by sofort..............................................................................................................54 7.4.3.sofortlastschrift/Lastschrift by sofort......................................................................................55 7.4.4.Vorkasse by sofort................................................................................................................56 7.4.5.sofortdauerauftrag................................................................................................................56 7.5 Special parameters for Rechnung by sofort....................................................................................56 7.5.1.Parameter to confirm/change................................................................................................57 7.5.2.Response parameter.............................................................................................................57 7.6 Special parameters for sofortdauerauftrag.....................................................................................57 7.6.1.Parameters for deleting a subscription...................................................................................57 7.6.2.Response parameter.............................................................................................................58 7.7 Error Case...................................................................................................................................58 7.7.1.Parameters for the error message / warning...........................................................................58 7.7.2.Possible error messages/warnings.........................................................................................59 7.7.3.Status-Codes of the Api.........................................................................................................63 7.8 Refunds......................................................................................................................................63 7.8.1.Parameters for preparing a refund.........................................................................................64 7.8.2.Response parameters...........................................................................................................64 7.8.3.Errors..................................................................................................................................65 8.IMPLEMENTATION EXAMPLES..............................................................................................................67

Manual Integration sofort Gateway

Seite 4

8.1 The Sofort library........................................................................................................................67 8.2 sofortbanking..............................................................................................................................67 8.2.1.Call of the interface..............................................................................................................67 8.2.2.Transaction notification.........................................................................................................67 8.2.3.Request of the transaction details.........................................................................................68 8.3 Rechnung by sofort ....................................................................................................................68 8.3.1.Call of the interface..............................................................................................................68 8.3.2.Transaction notification.........................................................................................................69 8.3.3.Request of the transaction details.........................................................................................69 8.3.4.Confirm/change a Rechnung by sofort ..................................................................................69 8.3.5.Confirm/change of Rechnung by sofort..................................................................................69 8.4 sofortlastschrift...........................................................................................................................70 8.4.1.Call of the interface..............................................................................................................70 8.4.2.Transaction notification.........................................................................................................70 8.4.3.Request of the transaction details.........................................................................................71 8.5 Lastschrift by sofort.....................................................................................................................71 8.5.1.Call of the interface..............................................................................................................71 8.5.2.Transaction notification.........................................................................................................71 8.5.3.Request of the transaction details.........................................................................................72 8.6 Vorkasse by sofort.......................................................................................................................72 8.6.1.Call of the interface..............................................................................................................72 8.6.2.Transaction notification.........................................................................................................73 8.6.3.Request of the transaction details.........................................................................................73 8.7 sofortdauerauftrag.......................................................................................................................73 8.7.1.Call of the interface..............................................................................................................73 8.7.2.Transaction notification.........................................................................................................74 8.7.3.Request of the transaction details..........................................................................................74 9.SUPPORT............................................................................................................................................75 10.IMPRINT...........................................................................................................................................76

Manual Integration sofort Gateway

Seite 5

List of tables
Table 1: Transaction numbers to simulate error codes for refunds.............................................................40 Table 2: Parameters request to the sofort Gateway..................................................................................47 Table 3: Return parameters sofort Gateway after a transaction request ....................................................47 Table 4: Parameter of the notification sofort Gateway...............................................................................48 Table 5: Parameters transaction data request sofort Gateway...................................................................48 Table 6: Status messages of transactions for sofortbanking......................................................................54 Table 7: Status messages of transactions for Rechnung by sofort..............................................................55 Table 8: Status messages about the payment behaviour of the debitor......................................................55 Table 9: Status messages of transactions for sofortlastschrift/Lastschrift by sofort.....................................55 Table 10: Status messages of transactions for Vorkasse by sofort ............................................................56 Table 11: Status messages of transactions for sofortddauerauftrag...........................................................56 Table 12: Parameter Rechnung by sofort confirm/change sofort Gateway..................................................57 Table 13: Response parameter Rechnung by sofort confirm/change sofort Gateway...................................57 Table 14: Parameters for deleting a subscription sofort Gateway...............................................................58 Table 15: Response parameters deleting a subscription sofort Gateway.....................................................58 Table 16: Parameter of the error message/warning sofort Gateway...........................................................59 Table 17: Common errors sofort Gateway................................................................................................59 Table 18: Errors/warnings at the request of the sofort Gateway................................................................62 Table 19: Errors at the request of the transaction details sofort Gateway...................................................62 Table 20: Errors at the cancellation of a sofortdauerauftrag......................................................................62 Table 21: Error Rechnung by sofort.........................................................................................................63 Table 22: Parameters for preparing a refund............................................................................................64 Table 23: Response parameters for refunds.............................................................................................65 Table 24: Specific error for refunds.........................................................................................................66

Manual Integration sofort Gateway

Seite 6

Table of examples
Example HTTP-Header...........................................................................................................................19 XML call sofort of the Gateway for multiple products................................................................................21 XML call of the sofort Gateway for one product.......................................................................................21 XML response of the Gateway................................................................................................................22 XML request for transaction details ........................................................................................................23 XML response of the sofort Gateway to an request for transaction details.................................................23 XML error code of the sofort Gateway ....................................................................................................24 XML confirmation request for Rechnung by sofort ...................................................................................25 XML change request for Rechnung by sofort ...........................................................................................26 XML response to a confirmation request for Rechnung by sofort...............................................................26 XML request for a cancellation of sofortdauerauftrag...............................................................................31 XML response to a cancellation request for sofortdauerauftrag.................................................................32 XML request to prepare refunds..............................................................................................................36 Error message after a request for preparing refunds................................................................................36 XML request of the refund interface........................................................................................................37 XML test request for refunds..................................................................................................................39

Manual Integration sofort Gateway

Seite 7

General

1. General
1.1 The sofort Gateway
The sofort Gateway is an integrated solution for our products in combination with a bank account with the Sofort Bank. You create a project and all of our payment methods are optionally available to you. Your end users can make their payment selection, either in your ecommerce application or at our site. This saves you time and gives you maximum flexibility for ecommerce payments. All payments are transacted in Euros.

1.2 Possible payment methods with sofort Gateway


Through the sofort Gateway, there is the possibility to integrate several forms of payment in one project. The payment methods are introduced below and in the following guide; these are collectively referred to as sofort products. sofortbanking Your clients must not register for sofortbanking: They pay quickly and easily using their own online banking data. Thanks to real time confirmation of the bank transfer order, as a merchant, you can ship the goods or provide the services immediately. In addition, you can optionally offer buyer protection, which provides the customers additional security . Rechnung by sofort Through Rechnung by sofort, you offer payment by invoice without risk. The sofort Bank assumes the risk in case of payment default for Rechnung by sofort. You receive the payment guaranteed. sofortlastschrift sofortlastschrift is a logical further development of the classic direct debit. With the consent of the customer, the system logs into their bank account, checks the credit limit and thus makes sure there are no transposed digits in the account number and the entry of false accounts is impossible. Sofortlastschrift drastically minimises the risk of reverse charges and cancellations due to insufficient funds. Lastschrift by sofort In addition to sofortlastschrift, there is also the option of the classic direct debit, which allows you to execute ordinary direct debits for your customers. Vorkasse by sofort

Manual Integration sofort Gateway

Seite 8

General

Through Vorkasse by sofort, the customer can pay later or directly at his/her bank branch. As a merchant, you can send the customer who has ordered but not paid an automated reminder email through our system. You can also build trust with your customers through our buyer protection program. sofortdauerauftrag With sofortdauerauftrag, the customer can immediately set up a standing order in his/her online banking account while ordering. The standing order will be confirmed immediately.

1.3 General course of transaction via sofort Gateway


A transaction through the sofort Gateway is divided into the following steps: As soon as a customer wants to pay, our interface is called up with the respective payment data. In response, you receive a link, which you can transfer to the customer for payment. If you want to offer multiple sofort products, you can decide if the customer should decide about the payment method at your side or if the customer should choose the payment method from our form. Depending on the product, the customer must enter his/her banking data at our payment site to process payment and thereafter, will be redirected to the appropriate success/abort page or if no entry is necessary, directly to the appropriate success/abort page. After successful transaction, we will automatically notify you. You can receive the information as an email or as an XML-HTTP message, which informs you automatically of the status change. You can access transaction details at any time.

Manual Integration sofort Gateway

Seite 9

General procedure for the integration of sofort products

2. General procedure for the integration of sofort products


2.1 Integration steps
In order to integrate the sofort products in your system, the following steps are necessary. The individual steps are explained in detail in the following chapters: 1. Registration with Payment Network AG 2. Create a new project for the sofort Gateway. 2.1. Select the desired sofort products 2.2.Configure your project 2.3.Generate an API Key 3. Integrate the sofort products in your shop 3.1.Integrate the payment instructions in your shop 3.2.Create the success / termination page 3.3.Configure the shop so that it can receive messages and initiate status inquiries

2.2 Approach for integration with this guide


You receive all the information you need about how to integrate the products of the sofort Gateway in your system in this guide. In chapter 3. Creating a new Project we explain how you can create a new project in your customer menu and which settings are possible. Communication with our system takes place in XML. To access our system, your must authenticate with your API Key. In chapter 4. Integrating a payment method you learn how to design the communication with the sofort Gateway and which product specific characteristics must be observed. If you make an inquiry to our interface, you must transfer certain required parameters or you can transfer optional parameters. You also receive a response with certain values back from our system. You will find a detailed list of global and product specific parameters in chapter 7. Annexe. Chapter 8. Implementation examples provides implementation examples in PHP with help from the programming library sofortlib, which is available to you at our site.

Manual Integration sofort Gateway

Seite 10

Creating a new Project

3. Creating a new Project


After logging in to your account, you can create a new project. If you don't have a account at Payment Net work you can register on this page for our services: https://www.sofortueberweisung.de/payment/users/register

In order to use the products of the sofort Gateway you have to create a new project at first. In a project you can define the settings for the used products. In order to create a new project, please follow these steps: Log in to your account at Payment Network In the left column in the category Project click New projects Choose your project type by clicking on the button Create sofort Gateway You can configure your project now. The possible setting for the chosen payment methods will be explained hereafter.

3.1 Creating a project 3.1.1.Generall Settings


In the Generall Settings you can define the details for your shop/project. Project name: Custom name for this project Shop system: Choose your shop system Industry: Choose your industry Website: Enter your website

3.1.2.Address
The entered address will be shown to the customer during the payment process. The address can be replaced by your logo. For more details see chapter Project logo

3.1.3.Bank account
Enter the bank account where the payments of the customers should be transferred to.

Manual Integration sofort Gateway

Seite 11

Creating a new Project

You need a Sofort Bank account in order to create a new sofort Gateway project. You can apply for a Sofort Bank account during the project creation.

3.1.4.Settings for all payment methods


The following settings are optional and will affect all payment methods. Alternatively you can provide these settings every time you call the XML interface. The settings you provide to the interface will overwrite the project settings.

Provider profile
Merchant/Shopowner: Choose this profile if you are sending goods Content provider: this profile should be chosen for download products and services

Success link
A success link is the page where a customer is redirected to after a successful transaction. You can enter a success link for all products or pass it every time as a parameter when calling our payment form (see parameter list in the Annexe) Attention! If you want your customers being redirected automatically after a successful transaction to the success link please activate the automatic redirection. Otherwise a summary of the payment details will be shown to the customer on our site and he will only redirected to the success link after clicking the button Back to shop.

Abort link
On every page on our payment form a button Terminate the session will be shown. Fill the Abort link field to tell us, where we should direct your customer after aborting a transaction.

XML-HTTP-Notification
We use the XML-HTTP-notification to inform you about a successful transaction. Please pay attention that you are only notified about successful transactions. With this notification our system informs your shop about changes of the payment status of a transaction. If you have been notified about a change of the pay ment status you have the possibility to request details for this transaction. You have the possibility to enter a

Manual Integration sofort Gateway

Seite 12

Creating a new Project

notification URL for all products or pass the notification URL as a parameter when calling our payment form (see parameter list in the Annexe). For further details about possible payment status please refer to chapter 7.4. Status messages of the respective product

E-Mail notification
If you want to be notified via e-mail enter your e-mail address here.

Timeout in seconds
Enter the maximum period in which the payment process must be completed. If a timeout isn't needed for technical reasons we recommend not to set any value. Please note that for some products it is necessary to enter the online bank data on our payment form. Maybe the customers hasn't this data directly in reach so please don't set a too short period.

Timeout Link
Define the URL where the customer should be redirected to in case of a timeout. You have the possibility to enter a timeout link for all products or pass the timeout link as a parameter when calling our payment form.

3.1.5.Payment Methods
In order to use a payment method just set a check mark at the designated product. To view the conditions for the respective product click on the link in the first line. After you have chosen the designated products and made all settings click on the button save at the end of the page to create the project.

Sofortbanking
Testmode: Activate the test mode for sofortbanking. For more details about the test mode see chapter 5. Testing. Sender country locked: If checked the customer can't change the passed country. Terms and condition: Please accept the terms and conditions in order to use this product. Attention! For details how to offer the buyer protection please refer to chapter

Manual Integration sofort Gateway

Seite 13

Creating a new Project

sofortlastschrift
Testmode: Activate the test mode for sofortlastschrift. For more details about the test mode see chapter 5. Testing. Terms and condition: Please accept the terms and conditions in order to use this product.

sofortdauerauftrag
Testmode: Activate the test mode for sofortdauerauftrag. For more details about the test mode see chapter 5. Testing. Terms and condition: Please accept the terms and conditions in order to use this product.

Vorkasse by sofort
Testmode: Activate the test mode for Vorkasse by sofort. For more details about the test mode see chapter 5. Testing. Cancellation after: Enter the period after which the status of a payment should be changed to not re ceived (loss) () between 7 and 14 days. Payment reminder after: Enter the period after which we should send a payment reminder to the cus tomer (between 7 and 14 days). Terms and condition: Please accept the terms and conditions in order to use this product.

Lastschrift by sofort
Testmode: Activate the test mode for Lastschrift by sofort. For more details about the test mode see chapter 5. Testing. Terms and condition: Please accept the terms and conditions in order to use this product.

Rechnung by sofort
Testmode: Activate the test mode for Lastschrift by sofort. For more details about the test mode see chapter 5. Testing.

Manual Integration sofort Gateway

Seite 14

Creating a new Project

Automatic redirect to abort link: If you check this box the customer will be automatically forwarded to the set abort link in case of an error during the processing of the invoice data. Max. monthly volume of sales: Enter the estimated monthly volume of sale with Rechnung by sofort. Return-/credit ratio: Enter the estimated return-/credit ratio in percent. Average shopping cart: Enter the estimated average amount of a shopping cart in Euro. Minimum amount: Enter the minimum amount of shopping cart for Rechnung by sofort. Terms and condition: Please accept the terms and conditions in order to use this product. If you have chosen Rechnung by sofort when creating a project, a factoring agreement will be sent to your e-mail address after finishing the project creation. Please send the completed factoring agreement to Sofort Bank Hirtenweg 14 82031 Mnchen If you already have a factory agreement you can add the new project to the existing agreement

3.2 Settings in your sofort Gateway project


After creating a project you can edit the settings of your project and define extended settings. You can find your project by clicking on My projects in the category Projects in the left column of the menu. To edit your project click on the name of your project.

3.2.1.Base settings
All settings made during the project creation can be edited here (see also 3. Creating a new Project). For example you can change your address or add new products. Furthermore you can view your configuration key and activate the buyer protection. Attention! If you activated the product Rechnung by sofort it is not possible to change your bank account.

Configuration Key
The configuration key is composed of your user id, project id and the API-Key. You can use the configuration key for a integration with the Sofort Library. Otherweise use for the authentication your customer id and APIKey (see 4.2.1. Authentication with API Key)

Manual Integration sofort Gateway

Seite 15

Creating a new Project

Buyer protection
If you want to offer the buyer protection to your customers you can activate it in the settings for sofortbanking or Vorkasse by sofort. Activating the buyer protection: If you want to activate the buyer protection set a check mark here. Please enter a valid e-mail address and accept the buyer protection policies for merchants of Sofort Bank. Further information about buyer protection banners can be found in the linked manual for upgrading buyer protection.

Extended Settings
In addition to the base settings there are extended settings for further settings of your project. You will get to the extended settings by clicking on the tab extended settings on the top of the site after you have chosen the respective project.

Project logo
Here you can upload your own company logo which we show during the payment process to your customer. In order to have your logo blended in on the payment form, please navigate to "Your project Extended settings Project logo". Size of your company logo: If possible exactly 150x60 Pixels. We do also accept other sizes, but they will be resized by our system which might cause a decline in quality. File type of your company logo: *.gif, *.png or *.jpg

Notifications
We use the notification methods to inform you about a successful transaction. Please pay attention that you are only notified about successful transactions. In order to configure a notification, please click Add new notification". You can choose between the following types of notifications which are going to be explained afterwards: E-mail with payment status Seite 16

Manual Integration sofort Gateway

Creating a new Project

XML HTTP Post

E-mail with payment status You have the option to be notified about the status of a payment via e-mail. You can choose in which cases you want to be notified about the status. Alternatevely you can pass the designated adress when calling our payment form. For more details refer to the Annexe. XML HTTP Post The http-notification calls a script on your webserver and informs you about status changes of your payments. Every try to call your script will be recorded in the notification logfiles. This information, i.e. a status code or your return code (HTML page) will be provided in the notification logfiles. Please pay attention that the HTML Body is only downloaded in test mode. A notification is successful, if your webserver sends a status code 200. The HTTP-notification-URL is only called up in case of success. Should we not reach your webserver the first time or receive a different status than 200, we make up to 40 further attempts in 24h. The notification contains the transaction id and the date and time of the payment. If you need further trans action data you can answer this notification with a transaction data request. You also have the opportunity to choose for which status of the payment a notification will be sent. This can also be passed on every call of the interface. For details, see the Annexe.

Master Password
By setting a master password you are able to save your project settings. Only people that know the master password are able to change the setting in the project. This is helpful especially if a colleague is only sup posed to check the payments.

3.3 API-Key
In order to use the sofort Gateway you need to authenticate with your API-Key. Your API-Key can be found in your account menu in the category services API-Key. Further details about the authentication with API-Key can be fount in chapter 4.2.1. Authentication with API Key.

Manual Integration sofort Gateway

Seite 17

Integrating a payment method

4. Integrating a payment method


After having seen the necessary settings in your customer account in the last chapter we have a look at the integration possibilities and the implementation of the products.

4.1 Possibilities of integration


In order to give your customers the possibility to pay please call our interface via XML with the data in the annexe. Depending on what you transmit to our interface you are able to show the payment selection to the customer in your shop or in the sofort Gateway. For the integration a library in PHP is provided. This library automates the authentication, the call of the interface and the import of the answer. Examples for the implementation and and a quick guide how to use the library can be found in chapter 8. Implementation examples

4.1.1.Payment selection in the shop


A payment selection in the shop is recommended if you provide other payment methods besides the sofort payment methods. Of course you are able to integrate more sofort payment methods at once in your shop. If your customer chooses one of the payment methods you pass only the block for the payment method to us when calling our interface. If a customer aborts the payment process he is redirected to your shop via the abort link.

4.1.2.Payment selection in the sofort Gateway


If you would like to offer only the sofort payment methods to your customer you are able to relocate the payment selection directly to the sofort Gateway. Therefore please activate the according payment methods and pass multiple correct xml blocks to us. If your customer clicks on the abort button or the payment is rejected he gets back to the payment selection in the sofort Gateway. The rejected payment method is deactivated.

4.2 Communication with the sofort Gateway


Communication with the sofort Gateway always follows the same principle for all products: Access our interface and transfer the transaction parameters Response from our server with the payment URL Notification about changed transaction status Possible request of transaction data

Manual Integration sofort Gateway

Seite 18

Integrating a payment method

Response to the retrieval of the transaction data

There are additional options available for some products and there are extended processes, which are explained in more detail from chapter ??? forward for individual products.

4.2.1.Authentication with API Key


You need your API Key and your customer number for the use of the sofort Gateway. You can access your API Key under your customer account under Services -> API Key. Please be aware of the following points: You have to send the correct authentication key. You have to enter the correct Content-Type Header. You have to call the correct URL and use the HTTPS protocol. You data has to be formatted correctly as XML (RFC 3023, see parameter description) and sent via POST.

With every request application/xml has to be passed as Content-Type and Accept Header. For the authentication the Basic-HTTP-Authentification (RFC 2617) is used. As user name please enter your customer id and as password your Api-Key. To calculate the necessary authentication keys, follow these steps: Enter the customer number followed by the API Key, separated by a colon, and then code Base64. If your customer number is 12345 and your API Key 123467890, your key would be calculated as follows: base64(12345:123467890). The corresponding authentication key would be MTIzNDU2Nzg5MDoxMjM0NTY3ODkw.

Example HTTP-Header
Authorization: Basic MTIzNDU2Nzg5MDoxMjM0NTY3ODkw Content-Type: application/xml; charset=UTF-8 Accept: application/xml; charset=UTF-8

4.2.2.Call of the interface


To call the sofort Gateway interface please use the following URL:
https://api.sofort.com/api/xml

To access, various parameters must be transferred to the sofort Gateway. When calling the interface some parameters must be passed. Possible parameters for a call can be found in Table Transaction request to the sofort Gateway including a short description of the parameter. Since there are differences for the sofort products in some access parameters, special parameters for each product are listed in the annexe. An exemplary access for a sofort bank transfer could look like this formatted in XML

Manual Integration sofort Gateway

Seite 19

Integrating a payment method

<?xml version="1.0" encoding="UTF-8"?> <multipay> <project_id>53245</project_id> <language_code>de</language_code> <interface_version>pn_test_1</interface_version> <preselection>su</preselection> <amount>2.20</amount> <currency_code>EUR</currency_code> <reasons> <reason>testberweisung</reason> </reasons> <user_variables> <user_variable>blablub</user_variable> </user_variables> <success_url>http://www.test.de</success_url> <abort_url>http://www.direct-ebanking.com/test/test2.php</abort_url> <notification_urls> <notification_url notify_on="loss">http://test.de/test3.php</notification_url> <notification_url notify_on="pending,refunded">http://test.de/test4.php</notification_url> </notification_urls> <su> <amount>2.30</amount> <reasons> <reason>testberweisung mit SU</reason> </reasons> </su> <sv> <reasons> <reason>testberweisung mit SV</reason> </reasons> </sv> <sl></sl> <sr> <customer_id>123</customer_id> <order_id>65464123</order_id> <invoice_address> <salutation>1</salutation> <firstname>Max</firstname> <lastname>Mustermann</lastname> <street>teststrae</street> <street_number>42</street_number> <zipcode>12345</zipcode> <city>testhausen</city> <country_code>DE</country_code> </invoice_address> <shipping_address> <salutation>1</salutation> <firstname>Max</firstname> <lastname>Mustermann</lastname> <street>teststrae</street> <street_number>42</street_number> <zipcode>12345</zipcode> <city>testhausen</city> <country_code>DE</country_code> </shipping_address> <items> <item> <product_number>32654</product_number> <title>testartikel</title> <description>toller artikel</description> <quantity>1</quantity> <unit_price>1.50</unit_price>

Manual Integration sofort Gateway

Seite 20

Integrating a payment method

<tax>19</tax> </item> <item> <product_number>32687</product_number> <title>Versandkosten</title> <quantity>1</quantity> <unit_price>5.90</unit_price> <tax>19</tax> </item> </items> </sr> </multipay>

XML call sofort of the Gateway for multiple products


This access transfers parameters for multiple products, i.e. the payment method occurs on a form at our site. If you want to make the payment method choice at your shop, then please only transfer the parameter for one product. Access might look as follows:
<?xml version="1.0" encoding="UTF-8"?> <multipay> <project_id>53245</project_id> <language_code>de</language_code> <interface_version>pn_test_1</interface_version> <preselection>su</preselection> <amount>2.20</amount> <currency_code>EUR</currency_code> <reasons> <reason>testberweisung</reason> </reasons> <user_variables> <user_variable>blablub</user_variable> </user_variables> <success_url>http://www.test.de</success_url> <abort_url>http://www.direct-ebanking.com/test/test2.php</abort_url> <notification_urls> <notification_url notify_on="loss">http://test.de/test3.php</notification_url> <notification_url notify_on="pending,refunded">http://test.de/test4.php</notification_url> </notification_urls> <su> <amount>2.30</amount> <reasons> <reason>testberweisung mit SU</reason> </reasons> </su> </multipay>

XML call of the sofort Gateway for one product

4.2.3.Response of the sofort Gateway


In response to this call, you receive a transaction ID and the URL to process the payment to which you can transfer the customer.

Manual Integration sofort Gateway

Seite 21

Integrating a payment method

Depending on the product and setting, the customer is either directed to the payment of the Payment Network after he/she has been requested to enter his/her bank data or he/she will be redirected directly to the passed or provided success link. Whether or not the entry of account data on our form is necessary is dependent on the product used (see also chapter 4.3. Product-speficic characteristics). The parameter a response contains can be found in table Response to a transaction request. A response to a call typically looks as follows:
<?xml version="1.0" encoding="UTF-8"?> <new_transaction> <transaction>1324-1234-5483-4891</transaction> <payment_url>https://www.sofort.com/payment/go/10000-50514-4D11FB0C864B</payment_url> </new_transaction>

XML response of the Gateway


You can direct your customer to the parameter "payment_url" provided page. The transaction ID is trans ferred in the "transaction" parameter. You should save the transaction ID with the respective order in order to, for example, access transaction data at a later point in time.

4.2.4.Transaction notification
If your customer has paid successfully a notification is sent to you. A notification URL on your server will be called and the transaction id will be passed. This URL can be set directly in your project or passed on every call. A notification looks like this:
<?xml version="1.0" encoding="UTF-8"?> <status_notification> <transaction>1324-1234-5483-4891</transaction> <time>2010-04-14T19:01:08+02:00</time> </status_notification>

XML notification from the sofort Gateway

You will get this message also on each status change of your transaction. In order to see what has changed please start a transaction detail request. Possible parameters a transaction motification contains can be found in table Notification about a status change.

4.2.5.Request for the transaction details


As a reaction to a notification or for a special period you can request the transaction data. Mandatory parameters for a transaction detail request can be found in table Transaction detail request. Two examples for a request:
<?xml version="1.0" encoding="UTF-8"?> <transaction_request version="1.0"> <transaction>1324-1234-5483-4891</transaction> <transaction>1324-1234-5483-4729</transaction> </transaction_request>

Manual Integration sofort Gateway

Seite 22

Integrating a payment method

or:
<?xml version="1.0" encoding="UTF-8"> <transaction_request version="1.0"> <from_time>2010-04-10</from_time> <to_time>2010-04-11</to_time> <number>10</number> <page>2</page> </transaction_request>

XML request for transaction details

4.2.6.Response of the sofort Gateway to an request for transaction details


Depending on the payment type, different data is available for a transaction. All respective data regarding a respective transaction is transferred. You can find explanations regarding the individual parameters in the table Response to a transaction detail request. The status of each product's transaction is transferred back. In the annexe all possible status for each product are listed (see also 7.4. Status messages of the respective product).
<?xml version="1.0" encoding="UTF-8"?> <transactions> <transaction_details> <transaction>1324-1234-5483-4891</transaction> <time>2010-04-14T19:01:08+02:00</time> <status>pending</status> <status_reason>not_credited_yet</status_reason> <payment_method>su</payment_method> <test>1</test> <language_code>de</language_code> <amount>2.20</amount> <currency_code>EUR</currency_code> <reasons> <reason>testberweisung mit SU</reason> </reasons> <user_variables> <user_variable>blablub</user_variable> </user_variables> </transaction_details> </transactions>

XML response of the sofort Gateway to an request for transaction details

4.2.7.Error Codes
If an request to the sofort Gateway is erroneous, you will receive an error code. An overview with an explanation of the error codes can be found in the Error Case. An error code might look like the following:
<new_transaction> ... <warnings> <warning> <code>8002</code> <message>invalid preselection. Valid values are: su,sv,sl,ls,sa,sr</message>

Manual Integration sofort Gateway

Seite 23

Integrating a payment method

<field>preselection</field> </warning> </warnings> <sa> <errors> <error> <code>8002</code> <message>product only supports German sender accounts.</message> <field>sender.country_code</field> </error> </errors> <warnings> <warning> <code>8002</code> <message>will be replaced by transaction ID</message> <field>reasons.reason.2</field> </warning> </warnings> </sa> </new_transaction>

XML error code of the sofort Gateway

4.3 Product-speficic characteristics 4.3.1.sofortbanking


You will find a detailed list of parameters in the annexe in the global parameter list. As a specific setting for sofortbanking there is a parameter for buyer protection. You will find this parameter in the annexe in table Transaction request to the sofort Gateway.

Refunds
Information about refunds can be found in chapter 6. Refunds.

Check list for the integration


Project created Payment method activated in the project Test transaction executed Notification for test transaction received Transaction data requested and received Refunds implemented and tested (optionally)

Manual Integration sofort Gateway

Seite 24

Integrating a payment method

4.3.2.

Rechnung by sofort

A detailed parameter list can be found in the annexe under global parameters. For invoice by sofort, addi tional parameters are necessary when accessing. These are listed in the annexe in Table Transaction request to the sofort Gateway. Important! Please note that your customers must approve the data processing as is defined in your contract. We recommend that the customer accept the data processing indications before completing the order. This requires a "check box" be integrated, which is not active. It is activated only after the customer clicks on it. Ensure that the customer cannot continue the payment process without this active consent. The text, which the customer must consent to, can be found under the following URL http://documents.sofort.com/de/sr/privacy_de

4.3.3.Confirm/change of Rechnung by sofort


Since the purchase contract generally only comes into effect when the goods are shipped, a transaction/in voice with Rechung by sofort must first be billed before it can be adjusted in the credit controll. Therefore, the original shopping cart cannot be altered subsequently or be completely set to zero (cancellation). The total value of the shopping cart may not exceed the original value of the shopping cart. Changing the shopping cart (partial or complete cancellation) is possible for the end customer for a certain amount of time even after payment of the invoice. Changing the customer number and order number is only possible until activation of the invoice. Invoicing can be executed manually through the merchant portal or automatically by accessing the interface. Mandatory parameters can be found in table Special parameters for Rechnung by sofort. The automated request to confirm the invoice is structured as follows in XML:
<?xml version="1.0" encoding="UTF-8"?> <confirm_sr> <transaction>1324-1234-5483-4891</transaction> </confirm_sr>

XML confirmation request for Rechnung by sofort


If the parameter transaction is passed without any further parameters the invoice will be confirmed. This is possible for 30 days after the order has been received.

Manual Integration sofort Gateway

Seite 25

Integrating a payment method

If the parameter items is passed, the original shopping cart will be replaced. If items is passed without any further entries the value of the shopping cart will be set to 0 (cancelation). The total amount can't ex ceed the original amount of the shopping cart. In order to change an invoice use this kind of request:
<?xml version="1.0" encoding="UTF-8"?> <confirm_sr> <transaction>1324-1234-5483-4891</transaction> <items> <item> <product_number>32654</product_number> <title>testartikel</title> <description>toller artikel</description> <quantity>1</quantity> <unit_price>1.50</unit_price> <tax>19</tax> </item> <item> <product_number>32687</product_number> <title>testartikel 2</title> <quantity>2</quantity> <unit_price>5.90</unit_price> <tax>19</tax> </item> </items> </confirm_sr>

XML change request for Rechnung by sofort


You receive a link to download the invoice as a PDF file in the answer to the confirmation request for Rechung by sofort. The link is in the parameter "download_url".
<?xml version="1.0" encoding="UTF-8"?> <invoice> <download_url>https://api.sofort.com/a4Kv7e.pdf</download_url> </invoice>

XML response to a confirmation request for Rechnung by sofort

Manual Integration sofort Gateway

Seite 26

Integrating a payment method

Attention! Please only send this invoice to your customers because the relevant data for the settlement of Rechnung by sofort is included. When the invoice is confirmed, the purchasing claims are completed by the Sofort Bank immediately. It is also possible to download this invoice in the customer menu Payment Network. If you want to create your own invoice, it must meet our requirements which are described in 8.1 in the general term of agreement of your contract. A self created invoice must contain the data from our system. You will receive this data in a transaction detail message (see also table Response to a transaction detail request). The mandatory parameters are green coloured. In order to jump directly to the corresponding entry in the table simply click on the following entries. We recommend to use our example invoice as template. It is absolutely necessary that the following data are shown on the created invoice because if not the factoring may not completed. - Date of Invoice (Parametername: invoice_date) - Invoice number (Note that this number must be our invoice number not yours Parametername: invoice_number) - Bank account (This has to be the only bank account which is shown on the invoice. Parameternamen: recipient_bank_account, holder, account_number, bank_code, bank_name) - Reason which must be shown on the invoice (Parametername: reason_1, reason_2) - Text about the factoring (Parametername: debitor_text)

Manual Integration sofort Gateway

Seite 27

Integrating a payment method

Manual Integration sofort Gateway

Seite 28

Integrating a payment method

Check list for the integration


Project created Payment method activated in the project Test transaction executed (with all possible status messages) Notification for test transaction received Transaction data requested and received Invoice edited/confirmed

4.3.4.sofortlastschrift
A detailed parameter list can be found in the annexe under global parameters. Specific parameters for sofortlastschrift are listed in the annexe in chapter Transaction request to the sofort Gateway.

Refunds
Information about refunds can be found in chapter 6. Refunds.

Check list for the integration


Project created Payment method activated in the project Test transaction executed Notification for test transaction received Transaction data requested and received

4.3.5.Lastschrift by sofort
A detailed parameter list can be found in the annexe under global parameters. Specific parameters for Lasts chrift by sofort are listed in the annexe in chapter Transaction request to the sofort Gateway. In contrast to sofortlastschrift, no PIN is needed for Lastschrift by sofort. When accessing the interface, you can transfer the sender account. In this case, you must transfer the account data (account holder, sort code and account number). If no account information is submitted, the enquiry takes place at our site.

Manual Integration sofort Gateway

Seite 29

Integrating a payment method

Important! Please note that your customers must approve the data processing as is defined in your contract. We recommend that the customer accept the data processing indications before completing the order. This requires a "check box" be integrated, which is not active. It is activated only after the customer clicks on it. Ensure that the customer cannot continue the payment process without this active consent. The text, which the customer must consent to, can be found under the following URL http://documents.sofort.com/de/ls/privacy_de

Refunds
Information about refunds can be found in chapter 6. Refunds.

Check list for the integration


Project created Payment method activated in the project Test transaction executed Notification for test transaction received Transaction data requested and received

4.3.6.Vorkasse by sofort
You will find a detailed list of parameters in the annexe in the global parameter list. As a specific setting for Vorkasse by sofort there is a parameter for buyer protection. You will find this parameter in the annexe in chapter Transaction request to the sofort Gateway. Specialities: For the product Vorkasse by sofort, the account data of your internal billing account with the sofort Bank is attached to the success link. You can choose this account data and give them to your customer for the bank transfer. The following parameters are transmitted through the success link: holder, account_number, iban, bank_code, bic, amount, reason_1, reason_2

Manual Integration sofort Gateway

Seite 30

Integrating a payment method

Important! Please note that your customers must approve the data processing as is defined in your contract. We recommend that the customer accept the data processing indications before completing the order. This requires a "check box" be integrated, which is not active. It is activated only after the customer clicks on it. Ensure that the customer cannot continue the payment process without this active consent. The text, which the customer must consent to, can be found under the following URL http://documents.sofort.com/de/sv/privacy_de

Refunds
Information about refunds can be found in chapter 6. Refunds.

Check list for the integration


Project created Payment method activated in the project Test transaction executed Notification for test transaction received Transaction data requested and received Refunds implemented and tested (optionally)

4.3.7.sofortdauerauftrag
A detailed parameter list can be found in the annexe under global parameters. Specific parameters for sofortdauerauftrag are listed in the annexe in chapter Transaction request to the sofort Gateway.

Cancel of a sofortdauerauftrag
A subscription entered via sofortdauerauftrag can only be cancelled by the customer. Therefore the initial transaction id is passed. As an answer a link is generated which redirects to a form where the customer is able to cancel his subscription. Here an example:
<?xml version="1.0" encoding="UTF-8"?> <cancel_sa version="1.0"> <transaction>1324-1234-5483-4891</transaction> </cancel_sa>

XML request for a cancellation of sofortdauerauftrag


As an answer you get a link where you can redirect your customer to: Manual Integration sofort Gateway Seite 31

Integrating a payment method

<?xml version="1.0" encoding="UTF-8"?> <subscription> <cancel_url>http://pay.sofort.de/deletesubscription/e83x1ae</cancel_url> </subscription>

XML response to a cancellation request for sofortdauerauftrag

Check list for the integration


Project created Payment method activated in the project Test transaction executed Notification for test transaction received Transaction data requested and received Cancellation of subscription tested

Manual Integration sofort Gateway

Seite 32

Testing

5. Testing
To test the integration of a sofort product, activate the test mode of the respective product settings in your sofort Gateway project. Enter 88888888 as sort code on the payment form (or sort code 88888888 e.g. for direct debits by sofort with the entry of the account data in the shop). You can choose all other data arbitrarily. After the transaction, check if your project is correctly configured: Are you routed to the success page after the transaction? Were all notifications received correctly? Is the order status set correctly or has the order been generated correctly?

5.1 Test invoice by sofort


Please activate the test mode. Enter the first name and surname respectively in the invoice address: success decline correction

Manual Integration sofort Gateway

Seite 33

Refunds

6. Refunds
Refunds are possible for the following products: sofortbanking Vorkasse by sofort sofortlastschrift Lastschrift by sofort

We offer two different procedures for refunds: Refunds via XML-Interface (automatically) Refunds via the customer menu (manually)

Important notes: Refunds can only be processed and registered as such if the following conditions are met: Domestic transaction (e.g. sender DE -> recipient DE) - Account holder of the account of the sender could be determined (The account holder is only determined from the online banking, the returning account holder is ignored for return to the vendor) - Bank identification number - Account number Cross-border SEPA transactions (e.g. sender DE -> recipient AT) additionally: - BIC - IBAN If this data is not complete, transfer the amount manually.

You can only execute a reverse booking for transactions for which the money has been credited to your sofort Bank account (green dot in front of the transaction).

6.1 Refunds via the customer menu (manually)


In the customer menu you can mark transactions manually, save them and transfer them to your Sofort Bank account.

Manual Integration sofort Gateway

Seite 34

Refunds

6.1.1.Prepare refunds
Markieren Sie eine oder mehrere Transaktionen wie folgt: Please mark one or more transactions for sofortbanking: Step 1: Choose in the customer menu Transactions for sofortbanking Step 2: Search for the transaction and click on the icon "Prepare for refunding" (blue arrow)

Generally a transaction can be prepared for refunding until the total sum is reached.

6.1.2.Consolidate refunds
Step 1: Choose in the customer menu "Services / Refunds" Step 2: On the following page you can check the booked transactions Step 3: You can edit refunds (amount, reference, recipient account) or delete them from the list.

Step 4: Choose a sender account, insert a file name and "Save" the refunds

6.1.3.Complete refunds
Step 1: Choose in the customer menu "Services / Refunds" Step 2: The refund files are listed at the end of the screen

Step 3: Start the automatic transfer to Sofort Bank (click "computer icon") Step 4: With your account details you can login to the Sofort Bank online banking Step 5: Enter the required TAN to confirm the refund

6.2 Refunds via the XML interface (automatically) 6.2.1.Generall


Furthermore, refunds can be prepared and retrieved via a XML interface automatically. Data for a payment is sent directly from your server to the server of Payment Network. Following guideline applies: Manual Integration sofort Gateway Seite 35

Refunds

You have to send the correct authentication key You need to send the correct Content-Type header You have to call the correct URL and have to use https as protocol Your data has to be formatted as XML (specified below, according to RFC 3023) and has to be sent via POST

6.2.2.Authentication
Authentication is done with basic-http-authentication (RFC 2617). As user name please use your customer id and as password your API-key. For more details about authentication see chapter 4.2.1. Authentication with API Key.

6.2.3.Prepare refunds
Use the following URL: https://www.sofortueberweisung.de/payment/refunds The request must be formatted according to the following example:
<?xml version="1.0" encoding="UTF-8" ?> <refunds> <title>test</title> <sender> <holder>Max Mustermann</holder> <account_number>9999999999</account_number> <bank_code>88888888</bank_code> </sender> <refund> <transaction>00000-00000-00000000-0000</transaction> <amount>1.11</amount> <comment>Order cancelled by user. Commodities already sent back</comment> </refund> <refund> <transaction>00000-00000-00000000-0001</transaction> <amount>1.12</amount> </refund> </refunds>

XML request to prepare refunds


A list of possible parameters can be found in the Annexe.

Response
If an error occurs a message like this will be returned:
<?xml version="1.0" encoding="UTF-8" ?> <error> <code>7000</code> <message>Invalid XML</message> </error>

Error message after a request for preparing refunds


Manual Integration sofort Gateway Seite 36

Refunds

If there is no general error, all parameters of the request, as well as status and error code will be returned. You can find an overview of the possible error notifications in the Annexe:
<?xml version="1.0" encoding="UTF-8" ?> <refunds> <title>test</title> <sender> <holder>Max Mustermann</holder> <account_number>9999999999</account_number> <bank_code>88888888</bank_code> </sender> <refund> <transaction>00000-00000-00000000-0000</transaction> <amount>1.11</amount> <comment>Order cancelled by user. Commodities already sent back</comment> <status>ok</status> </refund> <refund> <transaction>00000-00000-00000000-0001</transaction> <amount>1.12</amount> <status>error</status> <error> <code>5002</code> <message>Transaction not found</message> </error> </refund> <dta>Inhalt fuer DTA-Datei</dta> <dtazv>Inhalt fuer DTAZV-Datei</dtazv> </refunds>

XML request of the refund interface


A list of parameters can be found Annexe.

6.2.4.Consolidate refunds

a) Automatically
As soon as the sender-block is transferred at the request of the XML interface, the refunds are consolid ated automatically. In the response you get the consolidated refunds in the parameters dta and dtazv.

b) Manually
If the sender-block isnt transferred at the request of the XML interface, the refunds are marked automatically, but arent consolidated. In this case you can consolidate the refunds manually in the customer menu. Further information can be found in chapter 6.1.Refunds via the customer menu (manually).

Manual Integration sofort Gateway

Seite 37

Refunds

6.2.5.Complete refunds

a) Via Sofort Bank interface


This option is only available for those transactions, which have as sender account an account at the Sofort Bank: Step 1: Choose in the customer menu "Services / Refunds" Step 2: The refund files are listed at the end of the screen Step 3: Start the automatic transfer to Sofort Bank (click "computer icon")

Step 4: With your account details you can login to the Sofort Bank online banking Step 5: Enter the required TAN to confirm the refunds

Customers of the Sofort Bank can do the upload of the refunds also via the DTA(ZV) interface (if the sender-block at the request of the XML interface was transferred).

b) Via DTA(ZV) interface


Step 1: Save the content of the XML block dta in a DTA file (.dta) and the content of the XML block dtazv in a DTAZV file (.dtazv). Step 2: Upload the file to your online banking (for help please contact your bank) Step 3: Complete the transaction in your online banking and confirm the refunds with your TAN

6.2.6.Testing refunds
In order to test refunds, you have to make at first a sofortbanking or Vorkasse by sofort test transaction. Af terwards you can test the manual as well as the automatic refund. In the customer menu you can find the prepared and consolidated test refunds at Services/Refunds/Test refunds. For a test with the automatic method (XML interface) please use following bank account:
<sender> <holder>Bei Tests beliebig</holder> <account_number>9999999999</account_number> <bank_code>88888888</bank_code> </sender>

The request must be formatted according to the following example:

Manual Integration sofort Gateway

Seite 38

Refunds

<?xml version="1.0" encoding="UTF-8" ?> <refunds> <title>test</title> <sender> <holder>Max Mustermann</holder> <account_number>9999999999</account_number> <bank_code>88888888</bank_code> </sender> <refund> <transaction>00000-00000-00000000-0000</transaction> <amount>1.11</amount> <comment>Order cancelled by user. Commodities already sent back</comment> </refund> <refund> <transaction>00000-00000-00000000-0001</transaction> <amount>1.12</amount> </refund> </refunds>

XML test request for refunds


The test transactions will be marked as refunds and in the response you will get the consolidated refunds in the blocks dta and dtazv. In the customer menu you can find the refunds at Services / Refunds / Test refunds. Please note that it isnt possible to mix real and test transactions in one request.

6.2.7.Error codes
If the request is invalid, the response contains an errors element which contains code and message elements with detailed information. Following table shows, how you can simulate different error codes with specific transaction IDs: Transaction 00000-00000-00000000-0000 00000-00000-00000000-5002 00000-00000-00000000-5003 00000-00000-00000000-5004 00000-00000-00000000-5005 00000-00000-00000000-5006 00000-00000-00000000-5009 00000-00000-00000000-5012 00000-00000-00000000-5018 Manual Integration sofort Gateway Status ok error error error error error error error error 5002 5003 5004 5005 5006 5009 5012 5018 Code Transaction could not be found Amount must not exceed Transaction amount Transaction has not been received yet (nur mit Konto bei der Sofort Bank mglich) Transaction is marked as test transaction and cannot be marked as cancelled No refund elements provided Transaction could not be marked as cancelled. An unknown error occured. Invalid amount Invalid BIC Seite 39 Message

Refunds

Transaction

Status

Code

Message

00000-00000-00000000-5019

error

5019

Invalid IBAN

Table 1: Transaction numbers to simulate error codes for refunds

Manual Integration sofort Gateway

Seite 40

Annexe

7. Annexe
If you do not use the library (sofortLib) you find a detailed interface documentation here.

7.1 Explanation of the view in the following tables


Table column parameter: Name of the parameter Table column quantity: [1] [0,1] [0..20] = mandatory parameter = optional parameter, only one or no value can be passed = optional parameter, up to 20 values can be passed

7.2 Call of the interface


The interface is always called with a POST request to the following URL https://api.sofort.com/api/xml As authentication you have to use the Basic-HTTP-Authentification and your customer id as your username and your Api-Key as your password. See chapter 4.2.1. Authentication with API Key. The messages must be correctly formatted as XML. Examples for the XML-messages can be found in the previous chapter

7.2.1.Transaction request to the sofort Gateway


This table contains all possible parameters which can be used in order to initiate a transaction. Parameter multipay project_id interface_version language_code timeout Amount Typ (Length) [1] [1] [0,1] [0,1] [0,1] Container Integer String (255) String (2) Integer Description Containername, encloses the complete message Project number Version of the shop interface Language of the payment form, according to ISO 639-1 Availability of a transaction in seconds from the creation of the message new_transaction on our side until the placing of the bank transfer/debit/...; at least: 120; default: unlimited

Manual Integration sofort Gateway

Seite 41

Annexe

Parameter email_customer phone_customer preselection user_variables user_variable sender holder account_number bank_code country_code iban bic amount

Amount Typ (Length) [0,1] [0,1] [0,1] [0,1] [0..20] [0,1] [0,1] [0,1] [0,1] [0,1] [0,1] [0,1] [1] String (255) String (255) String (2) Container String (255) Container String (27) String (30) String (30) String (2) String (34) String (11)

Description Email address of your customer Telephone number of your customer Values: su, sr, sa, sl, kk, sf List of user variables User variable Sender account Sender account holder Sender account number Sender bank code Sender country code (ISO 3166-1 e.g. de) IBAN BIC

Decimal (8,2) Amount, format: no thousands separator, two decimal placed, separated with a point. Example: 150.00 (150 Euro) String (3) Container String (27) String (255) String (255) String (255) Container String (255) Container String (255) Currency according to ISO 4217 e.g.: EUR List with subjects, optional Subject Success link Abort link Timeoutlink List with notification urls Notification url List with notification email addresses Notification email address

currency_code reasons reason success_url abort_url timeout_url notification_urls notification_url notification_emails notification_email

[1] [1] [0..2] [0,1] [0,1] [0,1] [0,1] [0..5] [0,1] [0..10]

su amount

[0,1] [0,1]

Container

Containername, sofortbanking

Decimal (8,2) Amount, optional, overwrites the one passed at

Manual Integration sofort Gateway

Seite 42

Annexe

Parameter

Amount Typ (Length) <pn>

Description

reasons reason success_url abort_url timeout_url notification_urls notification_url notification_emails

[1] [0..2] [0,1] [0,1] [0,1] [0,1] [0..5] [0,1]

Container String (27) String (255) String (255) String (255) Container String (255) Container String (255) Boolean

List with subjects, optional Subject Success link Abort link Timeoutlink List with notification urls Notification url List with notification email addresses Notification email address 1 = buyer protection (if activated in the project)

notification_email [0..10] customer_protection [0,1]

sv amount reasons reason success_url abort_url timeout_url notification_urls notification_url notification_emails

[0,1] [0,1] [1] [0..2] [0,1] [0,1] [0,1] [0,1] [0..5] [0,1]

Container

Containername, Vorkasse by sofort

Decimal (8,2) Amount, optional, overwrites the one passed at <pn> Container String (27) String (255) String (255) String (255) Container String (255) Container String (255) Boolean List with subjects, optional Subject Success link Abort link Timeoutlink List with notification urls Notification url List with notification email addresses Notification email address 1 = buyer protection (if activated in the project)

notification_email [0..10] customer_protection [0,1]

ls bzw. sl

[0,1]

Container

Containername, Lastschrift by sofort oder sofortlastschrift (Fr beide Produkte identische

Manual Integration sofort Gateway

Seite 43

Annexe

Parameter

Amount Typ (Length) Parameter)

Description

amount reasons reason success_url abort_url timeout_url notification_urls notification_url notification_emails

[0,1] [1] [0..2] [0,1] [0,1] [0,1] [0,1] [0..5] [0,1]

Decimal (8,2) Amount, optional, overwrites the one passed at <pn> Container String (27) String (255) String (255) String (255) Container String (255) Container String (255) Container Integer String (255) String (255) String (255) String(255) String (255) String (255) String (2) List with subjects, optional Subject Success link Abort link Timeoutlink List with notification urls Notification url List with notification email addresses Notification email address Address Salutation, 1=Sir, 2=Madam First name Last name Sreet Street Number Zipcode City Country Code (ISO 3166-1)

notification_email [0..10]

invoice_address
salutation firstname lastname street street_number zipcode city country_code

[0,1] [0,1] [0,1] [0,1] [0,1] [0,1] [0,1] [0,1] [0,1]

sa amount reasons reason success_url

[0,1] [0,1] [1] [0..2] [0,1]

Container

Containername, sofortdauerauftrag

Decimal (8,2) Amount, optional, overwrites the one passed at <pn> Container String (27) String (255) List with subjects, optional Subject Success link

Manual Integration sofort Gateway

Seite 44

Annexe

Parameter abort_url timeout_url notification_urls notification_url notification_emails

Amount Typ (Length) [0,1] [0,1] [0,1] [0..5] [0,1] String (255) String (255) Container String (255) Container String (255) String (10) Abort link Timeoutlink

Description

List with notification urls Notification url List with notification email addresses Notification email address Start date of the subscription; has to be in the future according to ISO 8601 in the format YYYYMM-DD Amount of the payments that have to be done; 0 = infinite Minimum payment receipts; after this number the removal interface can be used (the customer is then able to delete the subscription via our API) Interval of the subscription, values can be: 1 = monthly (12 times a year) 3 = quarterly (4 times a year) 6 = biannual (2 times a year) 12 = yearly (once a year)

notification_email [0..10] start_date [0,1]

total_payments minimum_payments

[0,1] [0,1]

Integer Integer

interval

[0,1]

Integer

sr amount reasons reason success_url abort_url timeout_url notification_urls notification_url

[0,1] [0,1] [1] [0..2] [0,1] [0,1] [0,1] [0,1] [0..5]

Container

Containername, Rechnung by sofort

Decimal (8,2) Amount, optional, overwrites the one passed at <pn> Container String (27) String (255) String (255) String (255) Container String (255) List with subjects, optional Subject Success link Abort link Timeoutlink List with notification urls Notification url

Manual Integration sofort Gateway

Seite 45

Annexe

Parameter notification_emails

Amount Typ (Length) [0,1] Container String (255) String (255) String (255) Container Integer String (255) String (255) String (255) String(255) String (255) String (255) String (2) Container Integer String (255) String (255) String (255) String(255) String (255) String (255) String (2) Container Container Integer String (255) String (255)

Description List with notification email addresses Notification email address Customer number of the merchants end customer Order number of the order Billing Address Salutation, 1=Sir, 2=Madam First Name Surname Street House number Postcode City ISO 3166-1 country code, e.g.: DE Shipping Address Salutation, 1=Sir, 2=Madam First Name Surname Street House number Postcode City ISO 3166-1 country code, e.g.: DE shopping cart Items in shopping cart Database ID of the item item number Type of item number (possible values: EAN,

notification_email [0..10] customer_id order_id invoice_address salutation firstname lastname street street_number zipcode city country_code shipping_address salutation firstname lastname street street_number zipcode city country_code items item item_id [0,1] [0,1] [1] [0,1] [0,1] [0,1] [0,1] [0,1] [0,1] [0,1] [0,1] [1] [0,1] [0,1] [0,1] [0,1] [0,1] [0,1] [0,1] [0,1] [1] [0..n] [1]

product_number [0,1] number_type [0,1]

Manual Integration sofort Gateway

Seite 46

Annexe

Parameter

Amount Typ (Length)

Description ISBN). Self defined number if no value is give.

product_type

[0,1]

Integer

Class of goods, if known, possible values: 1= shipping costs 2 = credit / discount 0 = (shipped item)

title description quantity unit_price

[1] [0,1] [1] [1]

String (255) String (255) Integer

The name of the item and the respective article number Note, size, description, etc. Quantity of each item

Decimal(8,2) Gross unit price of the respective item. Format: no thousand separator, two decimal places separated by a full stop. Example: 150.00 (150 Euro) Decimal(2,2) The VAT of the item in percent, e.g. 19.00

tax

[1]

Table 2: Parameters request to the sofort Gateway

7.2.2.Response to a transaction request


As a response to a transaction request you will receive a transaction ID and an Url where the customer must be redirected to in order to finish the payment. The response may contain warnings. Parameter new_transaction transaction payment_url warnings warning code message Amount [1] [1] [1] [0,1] [1..n] [1] [1] Typ (Length) Container String (27) String (255) Container Container Int String(255) Description A new transaction is generated. Transaction number Url of the payment form List with warnings Warning, non critical errors Warning code Warning message

Table 3: Return parameters sofort Gateway after a transaction request

Manual Integration sofort Gateway

Seite 47

Annexe

7.3 Notification about a status change of a transaction 7.3.1. Notification about a status change

After a finished transaction or in case of a status change you will receive a notification which includes the following parameters. Parameter status_notification transaction time Amount [1] [1] [1] Typ (Length) Container String (27) String (25) Description The status of the transaction has changed. Transaction id Date and time (with time zone) according to ISO 8601 in the Format YYYY-MM-DDThh:mm:ss+HH:mm e.g. 2010-0617T18:30:00+02:00

Table 4: Parameter of the notification sofort Gateway

7.3.2.Transaction detail request


If you need more details about a transaction you can request details of a transaction whenever you want after you received a notification about a status change for the first time. A transaction detail request con tains the following parameters. Parameter transaction_request transaction from_time Amount [1] [0..100] [0,1] Typ (Length) Container String (27) String (25) Description Request of transaction details Transaction number, more than one can be queried Start of a period if no transaction ID has been passed. Default: request day 0:00 o'clock. Format ISO 8601 YYYY-MM-DD or YYYY-MM-DDThh:mm:ss+HH:mm End of a period if no transaction id has been passed. Default: request point of time. Format YYYY-MM-DD or YYYY-MM-DDThh:mm:ss+HH:mm Amount of transactions that should be passed (at request of a period). Default: 100 If number is used you are able to request the following transactions with this parameter Default: 1 e.g.: number=10, page=2 => transactions 11-20 are passed

to_time

[0,1]

String (25)

number page

[0,1] [0,1]

Integer Integer

Table 5: Parameters transaction data request sofort Gateway


Manual Integration sofort Gateway Seite 48

Annexe

7.3.3.

Response to a transaction detail request

The table shows all possible parameters a transaction detail message may contain. If you want to create your own invoice for Rechnung by sofort you have to use the green highlighted parameters. (see also Confirm/change of Rechnung by sofort) Parameter transactions transaction_details project_id transaction test time Amount Typ (Length) [1] [0..n] [1] [1] [1] [1] Container Container Integer String (27) Boolean String (25) Description List of multiple transactions Details of one transaction Project number Transaction id 1 for test transaction Date and time (with time zone) according to ISO 8601 in the Format YYYY-MMDDThh:mm:ss+HH:mm e.g. 2010-0617T18:30:00+02:00 Status code of the transaction; different statuses possible depending on the cash receipt (pending, received, refunded, loss) Reason for the status (more detailed) Date and time (with time zone) of the last status change according to ISO 8601 in the Format YYYY-MM-DDThh:mm:ss+HH:mm e.g. 2010-06-17T18:30:00+02:00 Payment method that has been used (su, sr, sa, sl, ls, sv) Language, according to ISO 639-1 Amount Refunded amount Currency according to ISO 4217 e.g.: EUR List with subjects Subject List of user variables

status

[1]

String (20)

status_reason status_modified

[1] [1]

String (255) String (25)

payment_method language_code amount amount_refunded currency_code reasons reason user_variables

[1] [1] [1] [0..1] [1] [1] [0..2] [1]

String (2) String (2) Decimal (8,2) Decimal (8,2) String (3) Container String (255) Container

Manual Integration sofort Gateway

Seite 49

Annexe

user_variable sender holder account_number bank_code bank_name bic iban country_code recipient holder account_number bank_code bank_name bic iban country_code email_customer phone_customer exchange_rate costs fees currency_code exchange_rate

[0..20] [1] [1] [1] [1] [1] [1] [1] [1] [1] [1] [1] [1] [1] [1] [1] [1] [1] [1] [1] [1] [1] [1] [1]

String (255) Container String (27) String (30) String (30) String (255) String (11) String (34) String (2) Container String (27) String (30) String (30) String (255) String (11) String (34) String (2) String (255) String (255) Decimal (8,4) Container Decimal (8,2) String (3) Decimal (8,4)

User variable Sender account Sender account holder Sender account number Sender bank code Sender country code (ISO 3166-1 e.g. de) IBAN BIC ISO 3166-1 country code, e.g.: DE Recipient account Recipient account holder Recipient account number Recipient bank code Recipient country code (ISO 3166-1 e.g. de) IBAN BIC ISO 3166-1 country code, e.g.: DE Email address of your customer Telephone number of your customer Exchange rate Information about the current fees for this transaction Fees Currency according to ISO 4217 e.g.: EUR Exchange rate

Manual Integration sofort Gateway

Seite 50

Annexe

sr customer_number

[0..1] [1]

Container Integer Integer String (255) String (20) String (20) String (255) String (45) String (10) String (8) String (10) Container String (27) String (30) String (30) String (255) Container Integer String (255) String (255) String (255) String (5) String (20) String (255) String (2) Container integer

Rechnung by Sofort Merchant ID Customer ID of the shop Order ID of the shop Status of payment by customers Type of invoice (OR, LS) URL of the PDF-invoice Customer objection, exact text Date of invoice (empty if unconfirmed) Invoicenumber (empty if unconfirmed) Due date(empty if unconfirmed) Recipient account Recipient account holder Recipient account number Recipient bank code Name of the bank Billing address Salutation, 1=Sir, 2=Madam First Name Surname Street House number Postcode City ISO 3166-1 country code, e.g.: DE Shipping address Salutation, 1=Sir, 2=Madam

shop_customer_number [1] shop_order_number invoice_status invoice_type invoice_url invoice_objection invoice_date invoice_number due_date [1] [1] [1] [1] [1] [1] [1] [1]

recipient_bank_account [0..1] holder account_number bank_code bank_name invoice_address saluation firstname lastname street street_number zipcode city country_code shipping_address saluation [1] [1] [1] [1] [1] [1] [1] [1] [1] [1] [1] [1] [1] [1] [1]

Manual Integration sofort Gateway

Seite 51

Annexe

firstname lastname street street_number zipcode city country_code reason_1 reason_2 credits credit credit_number amount tax_amount tax currency_code comment logo_url debitor_text items item item_id

[1] [1] [1] [1] [1] [1] [1] [1] [1] [1] [0..n] [1] [1] [1] [1] [1] [1] [1] [1] [1] [0..n] [1]

String (255) String (255) String (255) String (5) String (20) String (255) String (2) String (27) String (27) Container Container String (8) Decimal (8,2) Decimal (8,2) Decimal (8,2) String (3) String (255) String (255)

First Name Surname Street House number Postcode City ISO 3166-1 country code, e.g.: DE Reason 1 Reason 2 List of credits Credit Credit number Credit amount VAT amount Rate of VAT Currency according to ISO 4217 e.g.: EUR Comment URL for Trust'nPay Logo

String (1000) Text about the factoring Container Container String (32) String (255) Integer String (255) Shopping cart, Container Items in shopping cart Item-ID Item number Class of goods Type of item number (Possible values: EAN, ISBN) Self defined if empty

product_number [1] product_type number_type [1] [1]

Manual Integration sofort Gateway

Seite 52

Annexe

title description quantity unit_price tax

[1] [1] [1] [1] [1]

String (255) String (255) Integer Decimal (8,2) Decimal (2,2)

Name of item Comments, Size, Description, etc. Quantity of the item Price of the item (pre-tax) VAT of the item in percent (0.00, 7.00, 19.00)

sv received_amount consumer_protection

[0..1] [1] [1]

Container Decimal (8,2) Boolean

Vorkasse by Sofort Received amount Buyer protection activated

sa start_date payments payment

[0..1]

Container String (10)

sofortdauerauftrag Start date of the standing order (YYYY-MM-DD) List of payments The amount of the single <payment> objects refers to all received payments until now + running payments at the moment <serial> Declares every cash receipt; consecutive counting beginning with 1 This is the important status of each payment resp. cash receipt It should be evaluated by you!

[1] [0..n]

Container Container

serial status

[1] [1]

Integer String (20)

expected received interval

[1] [1] [1]

String (10) String (10) Integer

Date of the expected cash receipt, based on <start_date> and <interval> Date of the cash receipt; can be empty if the payment is still awaited Interval of the subscription, values can be: 1 = monthly (12 times a year) 3 = quarterly (4 times a year) 6 = biannual (2 times a year) 12 = yearly (1 time a year)

minimum_payments

[1]

Integer

Minimum payment receipts

Manual Integration sofort Gateway

Seite 53

Annexe

removed payments_received total_payments

[1] [1] [1]

Boolean Integer Integer

The subscription has been cancelled Number of payments received The amount of payments that have to be received

su consumer_protection

[0..1] [1]

Container Boolean

sofortberweisung Buyer protection activated

7.4 Status messages of the respective product


A transaction detail message also contains the status of a payment. Depending on the product there are dif ferent possible status.

7.4.1.sofortbanking
status pending loss refunded received received loss refunded status_reason not_credited_yet not_credited refunded credited consumer_protection complaint compensation Money not received yet. Money not received. Money has been refunded (complete refund of the full amount). Money received. The money has been credited to the trust account. The buyer protection has been claimed. The money has been refunded (partly refund). Description

Table 6: Status messages of transactions for sofortbanking

7.4.2.Rechnung by sofort

For the merchant


status pending refunded status_reason not_credited_yet refunded Description The payment has not arrived. The invoice was credited in full (after invoice confirmation).

Manual Integration sofort Gateway

Seite 54

Annexe

status received loss pending loss

status_reason credited canceled confirm_invoice

Description The payment has been received. The invoice was cancelled (before invoice confirmation). The invoice must be confirmed.

confirmation_period_ex The period (30 days) to confirm the invoice has expired. pired

Table 7: Status messages of transactions for Rechnung by sofort

About the payment behaviour of the debitor


invoice_status pending canceled reminder 1-3 delcredere refunded Description The invoice has not yet been paid. Status of the invoice cancellation (before invoice confirmation) Dunning level 1-3 Collections (VAT refund can be requested) Full credit note after invoice confirmation (to be offset against outstanding claims or if already paid, credited)

Table 8: Status messages about the payment behaviour of the debitor

7.4.3.sofortlastschrift/Lastschrift by sofort
status refunded received refunded loss status_reason refunded credited compensation rejected Description Money has been refunded (complete refund of the full amount). Money received. The money has been refunded (partly refund). The direct debit has been charged back by the customer.

Table 9: Status messages of transactions for sofortlastschrift/Lastschrift by sofort

Manual Integration sofort Gateway

Seite 55

Annexe

7.4.4.Vorkasse by sofort
status pending status_reason wait_for_money Description Please wait for the receipt of payment.

loss refunded received received loss refunded

not_credited refunded credited consumer_protection complaint compensation

Money not received. Money has been refunded (complete refund of the full amount). Money received. The money has been credited to the trust account. The buyer protection has been claimed. The money has been refunded (partly refund).

Table 10: Status messages of transactions for Vorkasse by sofort

7.4.5.sofortdauerauftrag
status pending loss received loss status_reason not_credited_yet not_credited credited canceled Money not received yet. Money not received. Money received. The subscription has been cancelled. Description

Table 11: Status messages of transactions for sofortddauerauftrag

7.5 Special parameters for Rechnung by sofort


In order to confirm an invoice or in order to edit the shopping cart of an invoice you have to send a special request. The necessary parameters are listed here. If the parameter transaction is passed without any further parameters the invoice will be confirmed. This is possible for 30 days after the order has been received.

Manual Integration sofort Gateway

Seite 56

Annexe

If the parameter items is passed, the original shopping cart will be replaced. If items is passed without any further entries the value of the shopping cart will be set to 0 (cancelation). The total amount can't ex ceed the original amount of the shopping cart.

7.5.1.
Parameter confirm_sr

Parameter to confirm/change
Amount [1] Typ Description (Length) Contain- Container, er Change and confirm an invoice [1] [0,1] [0,1] [0,1] [0,1] String (255) String (255) String (255) String (255) Container confirm_sr Parameter

transaction customer_id order_id comment items

Transaction number of the invoice. new customer number new order number Comment field for credit if the invoice was changed after confirmation. Changed shopping cart, Container

Table 12: Parameter Rechnung by sofort confirm/change sofort Gateway

7.5.2.
Parameter invoice

Response parameter
Amount [1] Typ (Length) Container Description Change and confirm an invoice

download_url [1]

String (255) Download link of the generated invoice (PDF)

Table 13: Response parameter Rechnung by sofort confirm/change sofort Gateway

7.6 Special parameters for sofortdauerauftrag


In order to delete a sofortdauerauftrag you have to send a special request.

7.6.1.
Parameter cancel_sa

Parameters for deleting a subscription


Amount [1] Typ (Length) Container Description Deleting a subscription, Container

Manual Integration sofort Gateway

Seite 57

Annexe

Parameter transaction success_url abort_url timeout_url

Amount [1] [0,1] [0,1] [0,1]

Typ (Length)

Description

String (255) Transaction number of the subscription String (255) Success link String (255) Abort link String (255) Timeoutlink

Table 14: Parameters for deleting a subscription sofort Gateway

7.6.2.
Parameter subscription cancel_url

Response parameter
Amount [1] [1] Typ (Length) Container Description Container, deleting a subscription

String (255) Url of the form

Table 15: Response parameters deleting a subscription sofort Gateway

7.7 Error Case 7.7.1.


Parameter errors error code

Parameters for the error message / warning


Amount Typ (Length) [1] [1..n] [1] Container Container Integer String (255) String (255) Container Container Integer String (255) String (255) Warning id Warning message Field to which the error relates Error number Error message Field to which the error relates List of warnings, container Error list, container Description

message [1] field warnings warning code [1] [1] [1..n] [1]

message [1] field [1]

Manual Integration sofort Gateway

Seite 58

Annexe

Table 16: Parameter of the error message/warning sofort Gateway

7.7.2.

Possible error messages/warnings

Common errors
Code 7000 7001 7002 7004 7005 7006 7007 7008 7009 7010 7011 7012 7013 7014 Invalid XML Invalid project ID Project disabled Xml parameter not provided in request Project has no Sofort Bank account Service temporarily unavailable due to maintenance Amount required. Invalid amount. Reason required. Invalid sender country id. Invalid recipient country id Invalid sender bank code Sender account equals recipient account Invalid hash Message

Table 17: Common

errors sofort Gateway

Fehler/Warnungen beim Aufruf sofort Gateway


Code 8000 8001 No project ID provided Unknown project Message

Manual Integration sofort Gateway

Seite 59

Annexe

Code 8002 8003 8004 8006 8010 8011

Message Validation error (Fieldname + Validationerrormessage) Request could not be processed No product is selected Logic error (i.e. product not activated and not in test mode) must not be empty (The listed field must not be empty) not in list of valid values (The passed value is not in the list valid values. I.e. With the Tag <preselection> a requested payment method can be preselected. If the value for possible payment methods hasn't been passed, an error code for the field preselection will be issued.(for example su for sofortbanking)

8012 8013 8014 8015 8016 8017 8018 8019 8020 8021 8022 8023 8024 8025 8026 8027

must be a positive number (The passed value isn't a positive number. For example the amount of items of a shopping cart entry.) unsupported currency (The passed currency is not supported. At the moment only EUR will be accepted.) invalid amount (The passed amount must be positive and must have only two decimal places. As decimal separator a . or a , will be accepted. amount is out of range (The passed amount is too big or too small.) must be a valid url (The passed URL is invalid.) invalid chars (The passed value has characters which are not accepted. For example only certain characters are accepted in the reason.) maximum length of 27 chars exceeded invalid email address invalid phone number invalid country code (Value must be passed according ISO-3166.) unsupported country code (The passed country code is not supported by our system.) invalid BIC only German addresses (DE) are supported must be 1 or 2 // salutation (Sir = 1, Madam = 2) must be a boolean, either 0 or 1 product not activated and not in testmode (The requested payment method is not avaivable beSeite 60

Manual Integration sofort Gateway

Annexe

Code

Message cause the test mode is not activated and the payment method is not unlocked.

8028

locked_sender_country_id is activated in project settings, but not provided (In the settings of the payment method, the sender country is marked as not changeable but no sender country has been passed. The sender country must be passed. product only supports German sender accounts cart amount differs from invoice amount cart items missing (No cart items passed) factoring contract missing (You don't have a factoring contract yet) invoice amount is higher than amount limit in factoring contract invoice amount is lower than minimum amount defined in project settings invalid date, expecting YYYY-MM-DD Interval must be one of 1, 3, 6 or 12 start_date has expired start_date not acceptable, choosing next valid date item_id may not be longer than 32 characters item_id must be alphanumeric invalid tax, allowed values are: 7, 19 consumer protection is only available for sender accounts from DE, AT and CH

8029 8030 8031 8032 8033 8034 8035 8036 8037 8038 8039 8040 8041 8042

8044 8045 8046 8047 8048 8049 8050

the provided sender.bank_code is a test bank code (but product is not in testmode) product in testmode and given bank_code is not a test bank code validation of given bank account and bank code failed maximum length of 255 chars exceeded invalid date format, expecting YYYY-MM-DD HH:MM::SS unsupported language (The passed language is not supported by our system.) value too small. setting timeout to minimum value. (The passed value for the duration of the payment was too short and will be changed too the shortest possible value.(120 seconds))

Manual Integration sofort Gateway

Seite 61

Annexe

Code 8051 8053 8054 8055 8056 8057 8058 8059 8060

Message invalid items found (Your request had invalid cart items) will be replaced by transaction ID (The passed value will be replaced with the transaction id) all products deactivated due to errors. Initiation aborted will be replaced by transaction ID sender email must be provided for consumer protection (If buyer protection is enabled, a sender E-Mailaddress must be passed (multipay -> email_customer)) activate this product in your project settings (The requested payment method is not activated for this project. The merchant has to activate the payment method in his project settings. payment not possible with this service

sender country not supported for this currency


blacklisted

Table 18:

Errors/warnings at the request of the sofort Gateway

Error at the request of the transaction details


Code 8005 Too many transactions requested Message

Table 19:

Errors at the request of the transaction details sofort Gateway

Error at the request of the transaction details


Code 8100 8101 8102 8103 Requested transaction not found Request could not be processed Transaction already marked as removed Transactions period of time has not been reached yet Message

Table 20:

Errors at the cancellation of a sofortdauerauftrag

Manual Integration sofort Gateway

Seite 62

Annexe

Error Rechnung by sofort


Code 9000 9001 9002 9003 9004 9005 9006 9007 9008 9009 9010 9011 9012 No invoice transaction found Can not confirm invoice Incoming total exceeds liability Can not cancel invoice. Invalid cart items Unable to update cart items Can not access interface beyond 30 days after receiving payment Invoice has been canceled Incoming sales-tax-amount is too high Sales-tax conflict of cart items Changing of cart items not possible. No comment provided for cart update. Adding cart items or increasing quantity is not possible. Message

Table 21: Error Rechnung by sofort

7.7.3.

Status-Codes of the Api

200 OK: message accepted 401 Unauthorized: no authorisation, e.g. false API-Key

7.8 Refunds
In order to mark and consolidate a transaction as refund you have to use the following parameters in you request.

Manual Integration sofort Gateway

Seite 63

Annexe

7.8.1.

Parameters for preparing a refund


Amount Typ (Length) [1] [0..1] [0..1] Container String Container List of refunds Name of file If the refund should be executed from another bank account instead of the account which is saved in the project settings Name of account holder Number of the sender account sort code of the sender account refund Transaction id of the transaction you are refunding Description

Parameter refunds title sender

holder

[0..1]

String String String Container String

account_number [0..1] bank_code refund transaction amount comment [0..1] [1..n] [1] [1] [0..1]

Double (8.2) Amount to be transferred, formatted as : 12345.24 String (255) Optional comment, will be displayed in your admin menu

Table 22: Parameters for preparing a refund

7.8.2.

Response parameters
Amount Typ (Length) [0..n] [1] [1] Container Integer String (255) Description of error Error code Error message Description

Parameter error code message

refunds title sender

[1] [0..1] [0..1]

Container String Container Dateiname If the refund should be executed from another bank account instead of the account which is saved in the project settings Name of account holder

holder

[1]

String

Manual Integration sofort Gateway

Seite 64

Annexe

Parameter

Amount Typ (Length) String String Container String Double (8.2) String (255) String Container Integer String (255) String String Error code

Description Number of the sender account sort code of the sender account

account_number [1] bank_code refund transaction amount comment status error code message dta dtazv [1] [1..n] [1] [1] [0..1] [1] [0..n] [1] [1] [0..1] [0..1]

Transaction ID of the original transaction Amount to be transferred, formatted as : 12345.24 Optional comment, will be displayed in your admin menu ok or error

Detailed error message Refunds in DTA format (for German domestic payment transactions) Refunds in DTAZV format (for foreign payment transactions)

Table 23: Response parameters for refunds

7.8.3.
Code 5000 5001 5002 5003 5004 5005 5006 5007

Errors
Message Transaction ID missing Amount missing Transaction could not be found Amount must not exceed transaction amount Transaction has not been received yet Transaction is marked as test transaction and cannot be marked as cancelled No refund elements provided Consumer Protection not closed

Manual Integration sofort Gateway

Seite 65

Annexe

Code 5008 5009 5010 5011 5018 5019 5020 5021 5018 5019 5020 5021 5022 5023 Product not supported

Message

The Transaction could not be inserted due to an internal error. Invalid bank code Invalid account number Invalid BIC Invalid IBAN Invalid holder Refunding of test and real transactions must not be mixed Invalid BIC Invalid IBAN Invalid holder Refunding of test and real transactions must not be mixed Transaction isn't a EUR transaction. Only EUR transactions may be refunded. Sender-Block contains a real account and the records are test transactions. Real sender account and test transactions must not be mixed.

5024 5025 5026

Sender-Block contains a test account and the records are real transactions Test sender account and real transactons must not be mixed. No sender for this transaction Transaction has no account holder Reason validation failed. Invalid reason.

Table 24: Specific error for refunds

Manual Integration sofort Gateway

Seite 66

Implementation examples

8. Implementation examples
8.1 The Sofort library
To make the integration into your system simple and convenient, you will find the file sofortlib_1.3.0.zip at our site. This contains the class library sofortLib for PHP programming language to make the implementa tion in PHP easier. Furthermore, you will also find detailed implementation examples and the instructions for using the sofort Library. Following, we have provided a short implementation example of every payment method with the support of the sofortLib.php. Please note that these are just examples for illustration. Detailed instructions and ex amples are in the instructions for the Sofort Library.

8.2 sofortbanking 8.2.1.Call of the interface


A call of the sofort Gateway:
require_once('sofortLib.php'); $sofort = new SofortLib_Multipay('yourconfigkey'); //set all parameters $sofort->setAmount(1.23, 'EUR'); $sofort->setReason('testueberweisung', 'verwendungszweck 2'); $sofort->setSofortueberweisung(); $sofort->sendRequest();

You configuration key is used in this case for authentication, which you can access in your project settings. (see chapter . Configuration Key ) As an response you will get a transaction id and a URL, shis code snippet shows how the response can be processed in php:
if($sofort->isError()) { echo $sofort->getError(); } else { $url = $sofort->getPaymentUrl(); $transactionId = $sofort->getTransactionId(); echo $url; }

8.2.2.Transaction notification
If your customer has paid successfully a notification is sent to you. A notification URL on your server will be called and the transaction id will be passed. This URL can be set directly in your project or passed on every call. This code snippet shows how the transaction id can be processed in php:
$sofort = new SofortLib_Notification();

Manual Integration sofort Gateway

Seite 67

Implementation examples

$transactionId = $sofort->getNotification();

You will get this message also on each status change of your transaction. In order to see what has changed please start a transaction detail request.

8.2.3.Request of the transaction details


As a reaction to a notification or for a special period you can request the transaction data. The example shows how the request can be realized in php:
$sofort = new SofortLib_TransactionData('configkey'); $sofort->setTransaction($transactionId)->sendRequest();

The response can be processed with this php-code:


$status = $sofort->getStatus(); $amount = $sofort->getAmount();

8.3 Rechnung by sofort 8.3.1.Call of the interface


A call of the sofort Gateway:
require_once('sofortLib.php'); $sofort = new SofortLib_Multipay('yourconfigkey'); //set all parameters $sofort->setAmount(1.23, 'EUR'); $sofort->setReason('testueberweisung', 'verwendungszweck 2'); $sofort->setSofortrechnung(); $sofort->setSofortrechnungCustomerId(123); $sofort->setSofortrechnungOrderId(456); $sofort->setSofortrechnungInvoiceAddress('firstname', 'lastname', 'teststr.', '12', '13254','city','1'); $sofort->setSofortrechnungShippingAddress('firstname', 'lastname', 'teststr.', '12', '13254','city','1'); $sofort->addSofortrechnungItem('artikelnummer', 'artikelbezeichnung', '1.23');

You configuration key is used in this case for authentication, which you can access in your project settings. (see chapter . Configuration Key ) As an response you will get a transaction id and a URL, shis code snippet shows how the response can be processed in php:
if($sofort->isError()) { echo $sofort->getError(); } else { $url = $sofort->getPaymentUrl(); $transactionId = $sofort->getTransactionId(); echo $url; }

Manual Integration sofort Gateway

Seite 68

Implementation examples

8.3.2.Transaction notification
If your customer has paid successfully a notification is sent to you. A notification URL on your server will be called and the transaction id will be passed. This URL can be set directly in your project or passed on every call. This code snippet shows how the transaction id can be processed in php:
$sofort = new SofortLib_Notification(); $transactionId = $sofort->getNotification();

You will get this message also on each status change of your transaction. In order to see what has changed please start a transaction detail request.

8.3.3.Request of the transaction details


As a reaction to a notification or for a special period you can request the transaction data. The example shows how the request can be realized in php:
$sofort = new SofortLib_TransactionData('yourconfigkey'); $sofort->setTransaction($transactionId)->sendRequest();

The response can be processed with this php-code:


$status = $sofort->getStatus(); $amount = $sofort->getAmount();

8.3.4.Confirm/change a Rechnung by sofort 8.3.5.Confirm/change of Rechnung by sofort


Since the purchase contract generally only comes into effect when the goods are shipped, a transaction/in voice with Rechung by sofort must first be billed before it can be adjusted in the credit controll. Therefore, the original shopping cart cannot be altered subsequently or be completely set to zero (cancellation). The total value of the shopping cart may not exceed the original value of the shopping cart. Changing the shopping cart (partial or complete cancellation) is possible for the end customer for a certain amount of time even after payment of the invoice. Changing the customer number and order number is only possible until activation of the invoice. Invoicing can be executed manually through the merchant portal or automatically by accessing the interface. Here an example in php for the call of the interface in order to pass a new shopping cart:
$sofort = new SofortLib_ConfirmSr('yourconfigkey'); $sofort->setTransaction($transactionId); $sofort->addItem('artikelnummer','artikelbezeichnung', '1.23'); $sofort->sendRequest();

Here an example in php for the call of the interface to confirm an invoice without changing the shopping cart:

Manual Integration sofort Gateway

Seite 69

Implementation examples

$sofort = new SofortLib_ConfirmSr('yourconfigkey'); $sofort->setTransaction($transactionId); $sofort->confirmInvoice()->sendRequest();

As response you get a downloadlink with the generated invoice for the customer:
$url = $sofort->getInvoiceUrl();

Attention! Please only send this invoice to your customers because the relevant data for the settlement of Rechnung by sofort is included. When the invoice is confirmed, the purchasing claims are completed by the Sofort Bank immediately. It is also possible to download this invoice in the customer menu Payment Network.

8.4 sofortlastschrift 8.4.1.Call of the interface


A call of the sofort Gateway:
require_once('sofortLib.php'); $sofort = new SofortLib_Multipay('yourconfigkey'); //set all parameters $sofort->setAmount(1.23, 'EUR'); $sofort->setReason('testlastschrift', 'verwendungszweck 2'); $sofort->setSofortlastschrift(); $sofort->sendRequest();

You configuration key is used in this case for authentication, which you can access in your project settings. (see chapter . Configuration Key ) As an response you will get a transaction id and a URL, shis code snippet shows how the response can be processed in php:
if($sofort->isError()) { echo $sofort->getError(); } else { $url = $sofort->getPaymentUrl(); $transactionId = $sofort->getTransactionId(); echo $url; }

8.4.2.Transaction notification
If your customer has paid successfully a notification is sent to you. A notification URL on your server will be called and the transaction id will be passed. This URL can be set directly in your project or passed on every call. This code snippet shows how the transaction id can be processed in php:
$sofort = new SofortLib_Notification(); $transactionId = $sofort->getNotification();

Manual Integration sofort Gateway

Seite 70

Implementation examples

You will get this message also on each status change of your transaction. In order to see what has changed please start a transaction detail request.

8.4.3.Request of the transaction details


As a reaction to a notification or for a special period you can request the transaction data. The example shows how the request can be realized in php:
$sofort = new SofortLib_TransactionData('configkey'); $sofort->setTransaction($transactionId)->sendRequest();

The response can be processed with this php-code:


$status = $sofort->getStatus(); $amount = $sofort->getAmount();

8.5 Lastschrift by sofort 8.5.1.Call of the interface


For Lastschrift by sofort you have the possibility to pass the account data of the customer when calling the interface (Sender holder, account number, bank code). If you don't send this data, the customer must complete his data on our payment form. A call of the sofort Gateway:
require_once('sofortLib.php'); $sofort = new SofortLib_Multipay('yourconfigkey'); $sofort->setLastschrift(); $sofort->setReason('Testzweck', 'Testzweck2'); $sofort->setAmount(10); $sofort->sendRequest();

You configuration key is used in this case for authentication, which you can access in your project settings. (see chapter . Configuration Key ) As an response you will get a transaction id and a URL, shis code snippet shows how the response can be processed in php:
if($sofort->isError()) { echo $sofort->getError(); } else { $url = $sofort->getPaymentUrl(); $transactionId = $sofort->getTransactionId(); echo $url; }

8.5.2.Transaction notification
If your customer has paid successfully a notification is sent to you. A notification URL on your server will be called and the transaction id will be passed. This URL can be set directly in your project or passed on every call. This code snippet shows how the transaction id can be processed in php: Manual Integration sofort Gateway Seite 71

Implementation examples

$sofort = new SofortLib_Notification(); $transactionId = $sofort->getNotification();

You will get this message also on each status change of your transaction. In order to see what has changed please start a transaction detail request.

8.5.3.Request of the transaction details


As a reaction to a notification or for a special period you can request the transaction data. The example shows how the request can be realized in php:
$sofort = new SofortLib_TransactionData('configkey'); $sofort->setTransaction($transactionId)->sendRequest();

The response can be processed with this php-code:


$status = $sofort->getStatus(); $amount = $sofort->getAmount();

8.6 Vorkasse by sofort 8.6.1.Call of the interface


A call of the sofort Gateway:
require_once('sofortLib.php'); $sofort = new SofortLib_Multipay('yourconfigkey'); //set all parameters $sofort->setAmount(1.23, 'EUR'); $sofort->setReason('testvorkasse', 'verwendungszweck 2'); $sofort->setSofortvorkasse(); $sofort->sendRequest();

You configuration key is used in this case for authentication, which you can access in your project settings . (see chapter . Configuration Key ) As an response you will get a transaction id and a URL, shis code snippet shows how the response can be processed in php:
if($sofort->isError()) { echo $sofort->getError(); } else { $url = $sofort->getPaymentUrl(); $transactionId = $sofort->getTransactionId(); echo $url; }

Specialities: For the product Vorkasse by sofort, the account data of your internal billing account with the sofort Bank is attached to the success link. You can choose this account data and give them to your customer for the bank transfer. The following parameters are transmitted through the success link: holder, account_number, iban, bank_code, bic, amount, reason_1, reason_2 Manual Integration sofort Gateway Seite 72

Implementation examples

8.6.2.Transaction notification
If your customer has paid successfully a notification is sent to you. A notification URL on your server will be called and the transaction id will be passed. This URL can be set directly in your project or passed on every call. This code snippet shows how the transaction id can be processed in php:
$sofort = new SofortLib_Notification(); $transactionId = $sofort->getNotification();

You will get this message also on each status change of your transaction. In order to see what has changed please start a transaction detail request.

8.6.3.Request of the transaction details


As a reaction to a notification or for a special period you can request the transaction data. The example shows how the request can be realized in php:
$sofort = new SofortLib_TransactionData('configkey'); $sofort->setTransaction($transactionId)->sendRequest();

The response can be processed with this php-code:


$status = $sofort->getStatus(); $amount = $sofort->getAmount();

8.7 sofortdauerauftrag 8.7.1.Call of the interface


A call of the sofort Gateway:
require_once('sofortLib.php'); $sofort = new SofortLib_Multipay(CONFIGKEY); $sofort->setSofortDauerauftrag(); $sofort->setSofortDauerauftragInterval(1); $sofort->setSofortDauerauftragTotalPayments(10); $sofort->setSofortDauerauftragStartDate('2011-12-01'); $sofort->setAmount(10); $sofort->setReason('Testzweck', 'Testzweck2'); $sofort->sendRequest();

You configuration key is used in this case for authentication, which you can access in your project settings. (see chapter . Configuration Key ) As an response you will get a transaction id and a URL, shis code snippet shows how the response can be processed in php:
if($sofort->isError()) { echo $sofort->getError(); } else { $url = $sofort->getPaymentUrl(); $transactionId = $sofort->getTransactionId(); echo $url; }

Manual Integration sofort Gateway

Seite 73

Implementation examples

8.7.2.Transaction notification
If your customer has paid successfully a notification is sent to you. A notification URL on your server will be called and the transaction id will be passed. This URL can be set directly in your project or passed on every call. This code snippet shows how the transaction id can be processed in php:
$sofort = new SofortLib_Notification(); $transactionId = $sofort->getNotification();

You will get this message also on each status change of your transaction. In order to see what has changed please start a transaction detail request.

8.7.3.Request of the transaction details


As a reaction to a notification or for a special period you can request the transaction data. The example shows how the request can be realized in php:
$sofort = new SofortLib_TransactionData('configkey'); $sofort->setTransaction($transactionId)->sendRequest();

The response can be processed with this php-code:


$status = $sofort->getStatus(); $amount = $sofort->getAmount(); $lastPaymentRecieved = $sofort->getSofortdauerauftragLastPaymentReceived(); $allPaymentsReceived = $sofort->getSofortdauerauftragAllPaymentsReceived();

Manual Integration sofort Gateway

Seite 74

Support

9. Support
The Payment Network team will gladly assist you. You may either e-mail us at support@sofort.com or use our support form under www.payment-network.com. Your message will then be forwarded to the Payment Network Ticket-Support-System, which will ensure your request will promptly be processed by a member of our staff. Telephone: +49 (0)89/2020889-400

Manual Integration sofort Gateway

Seite 75

Imprint

10. Imprint
Payment Network AG Fussbergstr. 1 D-82131 Gauting Tel.: +49 (0)89 20 20 889 400 Fax: +49 (0)89 / 20 20 889 - 499 www.payment-network.com Executive Board: Christoph Klein (CEO), Dr. Jens Ltcke, Georg Schardt Supervisory Board: Dr. Michael Riemenschneider (Chairman) Registered at the County Court Munich: Commercial Registry no. 161963

Manual Integration sofort Gateway

Seite 76