API Documentation
Refunds
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
- Account holder
Note:
If the aforementioned data for a refund is not available, please transfer the refund amount directly with your bank.
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.
Note:
Generally, a transaction can be prepared for (partial) refund until the total transaction amount has been reached.
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.
Note:
Refunds for different currencies can not be mixed
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.
Note:
Refunds for different currencies can not be mixed
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:
Sender Account Country | Refund Bank Details |
DE | <sender> <holder>Max Samplemerchant</holder> <iban>DE71700111109999999999</iban> </sender> Optional BIC: <bic>DEKTDE7GXXX</bic> |
CH | <sender> <holder>Max Samplemerchant</holder> <iban>CH0600000000023456789</iban> </sender> Optional BIC: <bic>SFRTCH20XXX</bic> |
PL | <sender> <holder>Max Samplemerchant</holder> <iban>PL71000000000000000023456789</iban> </sender> Optional BIC: <bic>SFRTPL20XXX</bic> |
HU | <sender> <holder>Max Samplemerchant</holder> <iban>HU19000000000000000023456789</iban> </sender> Optional BIC: <bic>SFRTHU20XXX</bic> |
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.
Note: You have to use the URL specified above for every API call described in the following and authenticate yourself as described.
5.1.2. (API step 1) Prepare refunds
The parameters required to prepare or consolidate a transaction via our interface are specified in the following tables.
Parameter | Number | Type (length) | Description | ||
refunds (with attribute version="3") | [1] | Container | Container with any number of individual refunds | ||
sender | [0,1] | Container | The bank account of the merchant that should be used as sender account for the refund. Is only necessary for consolidation of the refund. Otherwise the transaction will only be prepared for refund. | ||
holder | [1] | String (27) | Name of account holder | ||
iban | [1] | String (34) | IBAN of sender account | ||
bic | [1] | String (11) | BIC of sender account | ||
title | [0,1] | String (255) | File name of the refund file | ||
refund | [1..n] | Container | Container for data of an individual refund | ||
transaction | [1] | String (27) | Transaction number of the original transaction | ||
amount | [1] | Double (8.2) | Amount to be refunded. If this is less than the total amount of the transaction then a partial refund will be processed. No thousands separators, two digits behind the decimal point, separated by a point, e.g. 12.24 | ||
comment | [0,1] | String (255) | Optional comment on the refund to be displayed in the admin menu subsequently | ||
reason_1 | [0,1] | String (27) |
Reason line 1 Please assign a unique value (e.g. the order id) while the following characters are allowed: '0-9', 'a-z', 'A-Z', ' ', '+', ',', '-', '.'. Umlauts will be replaced, e.g. ä -> ae, ö ->oe, etc. Some banks do not display the entire characters of both reasons, e.g. on the account statements the last characters are cut off. Therefore, the important data should be inserted at the beginning of the first reason field. If this parameter is omitted, the transaction's reason will be used for the refund. |
||
reason_2 | [0,1] | String (27) |
Reason line 2 See 'reason_1' |
||
partial_refund_id | [0,1] | String (50) | Used to identify different partial refunds of a transaction. If this parameter is omitted, a random value is generated. |
5.1.3. (API step 2) API response with refund data including status
Parameter | Number | Type (Length) | Description | ||||
refunds (with attribute version="3") | [0,1] | Container | Either the result of a refund request or an error (<errors>) will be returned. | ||||
sender | [0,1] | Container | Bank account of the merchant - will be returned if the refunds are consolidated | ||||
holder | [1] | String (27) | Name of merchant | ||||
bank_name | [1] | String (255) | Bank name of the merchant's bank | ||||
iban | [1] | String (34) | IBAN of sender account | ||||
bic | [1] | String (11) | BIC of sender account | ||||
title | [0,1] | String (255) | File name | ||||
pain | [0,1] | String |
Consolidated refunds in PAIN format pain.001.001.03 encoded as base64 string, provided that the <sender> block has been transferred. For details of the PAIN specification please refer to Appendix 3 of the interface specification for the remote data transmission between customer and credit institution according to the DFÜ agreement version 2.7 that is valid from November 4, 2013. |
||||
refund | [1..n] | Container | Refund | ||||
recipient | [0,1] | Container | Bank details of the buyer who receives the refunded amount. Will only be returned, if <status> has the value "accepted". | ||||
holder | Name of buyer | ||||||
bank_name | Bank name of the buyer's bank | ||||||
iban | IBAN of recipient account | ||||||
bic | BIC of recipient account | ||||||
transaction | [1] | String (27) | Transaction number of the original transaction | ||||
amount | [1] | Double (8.2) | Amount to be refunded, no thousands separators, two digits behind the decimal point, separated by a point, e.g. 12.24 | ||||
comment | [0,1] | String (255) | Optional comment on the refund to be displayed in the admin menu subsequently | ||||
reason_1 | [0,1] | String (27) | Reason line 1 | ||||
reason_2 | [0,1] | String (27) | Reason line 2 | ||||
time | [0,1] | String (25) | Date and time of the creation of the refund. Formatted according to ISO 8601: YYYY-MM-DDThh:mm:ss+HH:mm. Will only be returned, if <status> has the value "accepted". | ||||
partial_refund_id | [1] | String (50) | Unique identifier for a partial refund | ||||
status | [1] | String (10) | "accepted" or "error" (in case the refund could not be prepared) | ||||
errors | [0,1] | Container | Container for error messages concerning a specific refund | ||||
error | [1..n] | Container | Error description | ||||
code | [1] | Integer | Error code | ||||
message | [1] | String (255) | Exact error description | ||||
errors | [0,1] | Container | Error - may be alternatively returned instead of the tag <refund> | ||||
error | [1..n] | Container | Error description | ||||
code | [1] | Integer | Exact error | ||||
message | [1] | String (255) | Exact error description |
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
Code | Message | Description | Simulation |
1000 | Invalid request. | Invalid request | |
1001 | Technical error. | Technical error | |
7000 | Invalid XML | XML structure is incorrect. | Call with invalid XML document e.g. xyz (as sole POST content) |
7004 | XML parameter not provided in request | Parameter "xml" not provided in request. | Call without POST content |
7006 | Service temporarily unavailable due to maintenance | This service is temporarily unavailable due to maintenance. |
Transaction Request: Call with <reason> value 00000-00000-00000000-7006 Refunds Request: Call with <transaction> value 00000-00000-00000000-7006 |
5.2.2. Specific errors
Code | Message | Description | Simulation |
5000 | Transaction ID missing | No transaction ID transferred | Call with missing or empty <transaction> tag |
5001 | Amount missing | The amount is missing | Call with missing or empty <amount> tag |
5002 | Transaction could not be found | The transaction could not be found | Call with <transaction> value 00000-00000-00000000-5002 |
5003 | Amount must not exceed transaction amount | The amount must not exceed the transaction amount | Call with <transaction> value 00000-00000-00000000-5003 |
5004 | Transaction has not been received yet | The transaction amount has not been received yet on the reconciled bank account | Call with <transaction> value 00000-00000-00000000-5004 |
5006 | No refund elements provided | No corresponding XML tag transferred | Call with missing <refund> tag in the <refunds> container |
5008 | Product not supported | The product is not supported or has not been enabled/activated yet | Call with <transaction> value 00000-00000-00000000-5008 |
5009 | Refund request could not be issued. An unknown error occurred. | The refund could not be carried out. Unknown error | Call with <transaction> value 00000-00000-00000000-5009 |
5010 | Invalid bank code | Invalid or missing sort code | Call with invalid <bank_code> value, e.g. xyz |
5011 | Invalid account number | Invalid or missing account number | Call with invalid <account_number> value, e.g. 0 |
5012 | Invalid amount | Invalid amount | Call with <transaction> value 00000-00000-00000000-5012 |
5013 | Invalid record data. | Invalid characters in the fields reason or comment | Call with <transaction> value 00000-00000-00000000-5013 |
5018 | Invalid BIC | Invalid or missing BIC | Call with <transaction> value 00000-00000-00000000-5018 |
5019 | Invalid IBAN | Invalid or missing IBAN | Call with <transaction> value 00000-00000-00000000-5019 |
5020 | Invalid holder | Invalid holder | Call with missing or empty <holder> tag, or if more than 27 characters are used |
5021 | Refunding of test and real transactions must not be mixed. | Refunding of test and real transactions must not be mixed | Call with <transaction> value 00000-00000-00000000-5021 |
5022 | The currency of the transaction is not supported. | Only EUR, CHF, PLN or HUF transactions may be refunded. | Call with <transaction> value 00000-00000-00000000-5022 |
5023 | Sender-Block contains a real account and the records are test transactions. Real sender account and test transactions must not be mixed. | A real sender account (former recipient account) was specified for the refund, but a test transaction tries to carry out the refund | Call with <transaction> value 00000-00000-00000000-5023 |
5024 | Sender-Block contains a test account and the records are real transactions. Test sender account and real transactions must not be mixed. | A test sender account (former recipient account) was specified for the refund, but a real transaction tries to carry out the refund | Call with <transaction> value 00000-00000-00000000-5024 |
5025 | No sender for this transaction | The account holder of the original transaction could not be determined | Call with <transaction> value 00000-00000-00000000-5025 |
5027 | Refund for given partial_refund_id already exists | The ID for the partial refund has already been assigned | Sending the same call twice (with <partial_refund_id>) |
5028 | Refund request could not be issued. Transaction too old. No refundable data available | The refund could not be carried out. The data is no longer available. | Call with <transaction> value 00000-00000-00000000-5028 |
5029 | Request could not be processed. Refund API v1 not supported anymore. | An old API request has been used that is not supported anymore. Please update your integration. | Call with <refunds version="1"> |
5030 | Sender country not supported for refunds or for this currency. | A bank account has been specified in the sender block located in a country which is not supported for refunds or the currency is not supported for refunds | Call with no Euro, CHF, PLN or HUF currency |
5033 | Refunding of transaction with different currencies must not be mixed | Refunds for different currencies can not be mixed | Call with <transaction> value "00000-00000-00000000-5033" |
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.