1. General

Refunds are possible for the following products:

• SOFORT
• SOFORT Paycode

Two different refund methods are offered:

• Refunding via the merchant menu
• Refunding via the XML API (= XML interface)

You can either assign complete refunds or partial refunds to the SOFORT system.

1.1. Requirements for refunds

Refunds can only be carried out provided that the following requirements are met:

• The provider/merchant must hold an account in one of the following countries: AT, BE, CH, DE, ES, FR, GB, HU, IE, IT, NL, PL, SK (CZ is not supported)
• The currency of the original transaction has to be EUR, CHF, PLN, GBP or HUF and the sender bank account (buyer) must be located in one of the following countries: AT, BE, CH, DE, ES, FR, GB, HU, IE, IT, NL, PL, SK (CZ is not supported)
• The original transaction must not be older than 3 months
• The following data of the sender bank account (buyer) must be available in the SOFORT system:
  • Account holder
    Note: The account holder is only determined by means of the online banking data. The transferred account holder will be ignored when being returned to the provider/merchant.
  • BIC
  • IBAN

Special feature for payments with activated bank account reconciliation on Sofort side:

If the payment of a transaction is expected to be reconciled by Sofort, missing information required for a refund (see above) will be supplemented. In this case refunds for transactions cannot be carried out until the money has been received (marked by a green dot in front of the transaction).

1.2. Refund phases

The individual phase steps partly differ depending on the following factors and are described later on in the document in more detail:

• Refund procedure
  • via merchant menu
  • via XML API
• Bank account of the merchant
  • With reconciliation on Sofort side
  • Without reconciliation on Sofort side

Since the merchant can carry out a refund via the merchant menu or the XML API, the individual phases for both scenarios are described.

2. Refunding via the merchant menu

The individual phases of a refund via the merchant menu are described in the following.

2.1. Prepare refunds

Before preparing individual or several transactions for a refund, the corresponding payment should be received on the appropriate account. This condition is mandatory when using a reconciled account! Individual or several transactions can be prepared for a refund via the merchant menu as follows:

Step 1: Go to the merchant menu and select "Transactions for SOFORT"

Step 2a (complete refund): Search the transaction in question and click the icon "Prepare for refund" (blue arrow) – by usage of a reconciled account, the icon is only visible if the payment has been received.

Step 2b (partial refund): Search the transaction in question and click on the link of the transaction ID. You can insert the desired partial amount (<= total amount) in the field "Amount" under "Refunds" on the transaction details view. Afterwards, click "Refund" to prepare this partial refund.

2.2. Consolidate refunds

When consolidating prepared refunds, a SEPA PAIN file is generated. This is a standardised file format for electronic payment processing within banks of the SEPA region. The file can be generated as follows:

• Step 1: Select "Additional Services -> Refunds" in the merchant menu.
• Step 2: Check the prepared refunds listed on the next page.
• Step 3: You can edit individual refunds (amount, reason, etc.) or remove them from the list.
• Step 4: Select an account as sender account, assign a file name and "Save" the refunds.

2.3. Carry out refunds

Before you can carry out prepared and consolidated refunds via batch file transfers in your online banking, you have to transmit the relevant SEPA PAIN file to your bank. A refund can be carried out as follows:

• Step 1: Select "Additional Services -> Refunds" in the merchant menu.
• Step 2: The refund files generated by you are listed at the end of the page.
• Step 3: Save the SEPA PAIN file locally (via link).
  
• Step 4: Upload the SEPA PAIN file in the online banking of your house bank (please contact your bank for any questions).
• Step 5: Carry out the batch file transfer in your online banking and confirm the refunds according to your agreed identification procedure.

3. Integration of refunds via XML API

The individual phases of a refund via the XML API are described in the following, which can be used to automatically list refunds from your (shop) system at SOFORT.

3.1. Communication with the refunds interface

Our API can be called from your (shop) system by a HTTP POST with attached XML parameters. The responses to calls of our API are formatted in XML as well.

Direct communication with our API via XML-HTTP messages always follows the same pattern:

• (API step 1) Prepare refunds
• (API step 2) API response with refund data including status

 Unless already initiated by API step 1, you can manually consolidate the refunds (see previous section) before carrying them out.

3.2. Prepare refunds (API step 1)

3.2.1. API call and authentication

To prevent abuse of the API, authentication must be performed for every API call, using your customer number as user name and the API key as password. The API key is provided in the merchant menu at "Services > API key". Please note the following before using the API:

• You have to call the correct URL using HTTPS as a protocol.
• You have to transfer the correct authentication information. The basic http authentication (RFC 2617) is used for authentication.
• You have to enter the correct content type headers.
• Your data must be correctly formatted in XML (RFC 3023, see parameter description) and sent by HTTP POST.

Additional details on calling the API and on authentication can be found in the annex (see 4.1.1).

The interface is called via the following URL:

https://api.sofort.com/api/xml

3.2.2. Transfer of transaction data

Various parameters must be transferred to our API for the call. Some parameters are mandatory, some are optional. Details on the use of the individual parameters are listed in the overview of parameters in the annex (see 4.1). The differentiation between partial and total refund is based on the assigned amount (partial refund: <amount> < total amount of the transaction).

An example of a refund call formatted in XML might look as follows:

<?xml version="1.0" encoding="UTF-8" ?>
<refunds version="3">
      <sender>
            <holder>Max Samplemerchant</holder>
            <iban>DE71700111109999999999</iban>
            <bic>DEKTDE7GXXX</bic>
      </sender>
      <title>Test Refund December 5, 2013</title>
      <refund>
            <transaction>00000-00000-00000000-0000</transaction>
            <amount>1.11</amount>
            <comment>Order cancelled by user.</comment>
            <reason_1>OrderID 123456</reason_1>
            <reason_2>Refund</reason_2>
      </refund>
      <refund>
            <transaction>00000-00000-00000000-0001</transaction>
            <amount>13.90</amount>
            <reason_1>OrderID 654321</reason_1>
            <reason_2>Refund</reason_2>
            <partial_refund_id>1</partial_refund_id>
      </refund>
</refunds>

3.3. API response with refund data including status (API step 2)

In case of an error, a detailed error description will be returned in addition to the parameters of the call. An overview of potential error messages is listed in the annex (see 4.2).

<?xml version="1.0" encoding="UTF-8" ?>
<refunds version="3">
      <sender>
            <holder>Max Samplemerchant</holder>
            <bank_name>Demo Bank</bank_name>
            <iban>DE71700111109999999999</iban>
            <bic>DEKTDE7GXXX</bic>
      </sender>
      <title>Test Refund December 5, 2013</title>
      <pain>[Base-64 encoded content for PAIN-file]</pain>
      <refund>
            <recipient>
                  <holder>Max Mustermann</holder>
                  <bank_name>Demo Bank</bank_name>
                  <iban>DE06000000000023456789</iban>
                  <bic>SFRTDE20XXX</bic> 
            </recipient>
            <transaction>00000-00000-00000000-0000</transaction>
            <amount>1.11</amount>
            <comment>Order cancelled by user.</comment>
            <reason_1>OrderID 123456</reason_1>
            <reason_2>Refund</reason_2>
            <time>2013-12-05T16:31:59+01:00</time>
            <partial_refund_id>fb1244caad</partial_refund_id>
            <status>accepted</status>
      </refund>
      <refund>
            <transaction>00000-00000-00000000-0001</transaction>
            <amount>13.90</amount>
            <reason_1>OrderID 654321</reason_1>
            <reason_2>Refund</reason_2>
            <partial_refund_id>1</partial_refund_id>
            <status>error</status>
            <errors>
                  <error>
                        <code>5002</code>
                        <message>Transaction could not be found.</message>
                  </error>
            </errors>
      </refund>
</refunds>

If you have transferred the "sender" block with the XML API call, you get the parameter <pain> (in the example, a placeholder is used). It contains the base-64 encoded transfer information of the PAIN XML format (version pain.001.001.03). The decoded content has then to be saved as .pain file before it can be transferred to the bank.

In case of a fatal error, you will receive an error message without the parameters of the previously sent refunds:

<?xml version="1.0" encoding="UTF-8" ?>
<errors>
      <error>
            <code>7000</code>
            <message>Invalid XML</message>
      </error>
</errors>

3.4. Consolidate refunds

The prepared refunds can be consolidated either manually or automatically.

3.4.1. Automatically

As soon as the "sender" block has been transferred with the XML API call (cf. to the example API call above), the refunds will be automatically consolidated. The consolidated refunds are stored as SEPA PAIN files in the merchant area and will be additionally returned to you in the XML parameter "pain" of the API response.

3.4.2. Manually

If the "sender" block is not transferred with the XML API call, the refunds will be prepared, but not consolidated. In this case, you can manually consolidate the refunds in the merchant menu.

Information on this topic can be found in the section "Refunding via the merchant menu" (see section above).

3.5. Carry out refunds

A refund can be carried out as follows by using a PAIN-file.

• Step 1: Decode the content of the XML block "pain" and save the result in a PAIN file (.pain). This procedure can be automated.
• Step 2: Log on to the online banking of your bank with your account data.
• Step 3: Upload the file in the online banking (please contact your bank for any questions)
• Step 4: Carry out the batch file transfer in your online banking and confirm the refunds with the required TAN (or other confirmation)

4. Testing

To test the refund, carry out a SOFORT or SOFORT Paycode test transaction (use sender bank code "88888888" resp. sender BIC "SFRTDE20XXX"). Subsequently, you can test to prepare and consolidate refunds via the XML API. The prepared and consolidated test refunds are listed in the merchant menu under "Services > Refunds > Test Refunds".

Use the following account data in the sender block to test the consolidation via XML API:

The corresponding test transactions will be prepared and consolidated for refund. Please bear in mind that you cannot mix real and test transactions.

5. Annexe

5.1. Overview of parameters

If you do not use the code library (SofortLib), you will find the detailed XML API documentation here.

Description of the table columns of the tables in following sections:

• Parameter: XML tag name which is transferred (<parameter>parameter-content</parameter>)
   The logical structure of an XML document is a tree structure, thus featuring a hierarchical organisation. The hierarchy is illustrated by indentation in the tables. Parameters marked in boldface symbolises parent nodes with one or more child nodes.
• Number: specifies how frequently a parameter may be used under its higher-level parameter
  • [1] = mandatory parameter
  • [0,1] = optional parameter, a maximum of 1 value can be transferred
  • [0..20] = optional parameter, up to 20 values can be transferred
  • [n] = optional parameter, any number of parameters can be transferred
  • [1..n] = mandatory parameter, a minimum of one parameter must and any number of parameters can be transferred
• Type (length): specifies the data type of the parameter content; if this is a string, the maximum permissible number of characters is stated
• Description: detailed description of the use of the parameter

5.1.1. API call and authentication

The API is called via the following URL:

https://api.sofort.com/api/xml

The basic http authentication (RFC 2617) is used for authentication. Please enter your customer number as user name (for example 99999) and your API key as password (for example a12b34cd567890123e456f7890123456), separated by ":" and coded by Base64 (base64(99999:a12b34cd567890123e456f7890123456)).

For every call, the field Content Type and the field Accept in the HTTP header requires input of "application/xml".

An example of a HTTP header might look as follows:

Authorization: Basic OTk5OTk6YTEyYjM0Y2Q1Njc4OTAxMjNlNDU2Zjc4OTAxMjM0NTYg
Content-Type: application/xml; charset=UTF-8
Accept: application/xml; charset=UTF-8

After successful authentication, the server will confirm your API call with HTTP 200 OK.

The content of the messages must be correctly formatted in XML. The possible parameters are described in detail in the following.

5.1.2. (API step 1) Prepare refunds

The parameters required to prepare or consolidate a transaction via our interface are specified in the following tables.

5.1.3. (API step 2) API response with refund data including status

5.2. Errors

If a refund preparation cannot be completed successfully, you will generally only receive an <errors> container. If the error only refers to a specific refund, you will receive the status "error" in the <status> tag as well as the container <errors> within the concerning refund.

5.2.1. General errors

5.2.2. Specific errors

6. Support & Contact

The ''Direct Bank Transfer'' team will be available if you need help.

You may send us an email at service@sofort.com.

We are also glad to assist you in case of technical issues:

Technical support:
Phone: +49 (0)89 24 88 37 691
Email: integration@sofort.com

Business hours:
Monday to Thursday: 8:30 a.m. to 6:00 p.m.
Friday: 8:30 a.m. to 5:00 p.m.

7. Legal Notice

SOFORT GmbH
Theresienhöhe 12
80339 Munich
Germany

Support for customers
Phone: +49 (0)89 24 88 37 690

Support for merchants
Phone: +49 (0)89 24 88 37 692

info@sofort.com
www.sofort.com

Directors

Felix Würtenberger
Wilhelmus Geerling Klaassen

External Data Protection Officer
Mr. Michael Schramm, LL.M. 
For privacy questions please contact us at: datenschutz@sofort.com

Registered at the District Court Munich
HRB 218675
VAT-ID: DE248376956

© SOFORT GmbH. All rights reserved, including the translation.

The documentation including all published content is protected by copyright. Reprints or reproduction of any kind and processing, duplication, and distribution using electronic systems of any kind shall only be permitted with prior written consent of SOFORT GmbH.

The contents of this documentation and the implementation of the information contained therein may only be used at your own risk. SOFORT GmbH assumes no responsibility for the function of individual programmes or of parts of them. In particular, SOFORT GmbH assumes no responsibility for possible damages resulting from the use.