Internetkasse. Title Page. Sparkassen-Internetkasse Connection for traders and integrators

Transcription

1 Internetkasse Title Page Sparkassen-Internetkasse Connection for traders and integrators

2 Connection for traders and integrators This document relates to Sparkassen-Internetkasse version 1.2. Revision: Date of issue: 26/11/2015 Added Section Means of payment verification, p. 21, Section Means of payment verification, credit card, p. 43 and Section Means of payment verification, direct debit, p. 41. Section Transaction details, p. 22 and Section Request message - payments, p. 75: accountholder is mandatory for SEPA direct debits. Section Card number aliases, p. 74: payment_options=generate_ppan_verify_online works without amount or with amount=0. Revision: Date of issue: 10/04/2015 Moved Cartes Bancaires documentation to a separate document. Removed obsolete text concerning SEPA migration. Section Reversal, p. 20: updated statement about period for reversals of credit card payments. Section Card number aliases, p. 17: revised statement about card number aliases and PCI DSS. Section Reserve, credit card, p. 25, Section Reserve/capture, credit card, p. 29: specified when sending the card verification code is mandatory. Revision: Date of issue: 20/06/2014 Added Section Cartes Bancaires. Revision: Date of issue: 16/04/2014 Section Request message - payments, p. 75: improved explanation of amount field, added backendretrycount and notifyurl. Section Refund, p. 20: added note that refunds or credits on current accounts may need to be coordinated with your account-holding institution. Revision: Date of issue: 31/03/2014 Section SEPA Direct Debits, p. 13: international direct debits are allowed with all SEPA countries.

3 Table of Contents 1 About this document 1.1 Labelling and formatting Disclaimer Copyright note Introduction 2.1 Product Target group, purpose of the document Overview of contents Overview 3.1 System and interface overview D-Secure Prerequisites for connection Connection procedure Support contact Choosing the appropriate interface SEPA Direct Debits Shop interface 4.1 Prerequisites Function description Verifying the issuing country of credit cards Card number aliases Access data Interface version Transaction types Reserve Version Date of issue: 26/11/2015 3

4 4.7.2 Reserve/capture Refund Reversal Capture Means of payment verification Diagnosis Transactions with blacklist check Transaction details Card number aliases Reserve, direct debit Reserve, credit card Reserve/capture, direct debit Reserve/capture, credit card Refund, direct debit, initial transaction Refund, credit card, initial transaction Capture, direct debit Capture, credit card Refund, direct debit, follow-up transaction Refund, credit card, follow-up transaction Reversal, direct debit Reversal, credit card Means of payment verification, direct debit Means of payment verification, credit card Reserve, direct debit with blacklist check Reserve/capture, direct debit with blacklist check Diagnosis Creating a Card Number Alias for a Credit Card Creating a Card Number Alias for a Bank Account Removing a Card Number Alias Checking if a Card Number Alias Exists Getting Information about a Card Number Alias Parameter overview Parameters with special significance Parameter details s transaction Sample code Frequently asked questions (FAQ) Form service / 3D-Secure 5.1 Introduction Function description Payments with 3D-Secure Payments without 3D-Secure Version Date of issue: 26/11/2015 4

5 5.2.3 Maestro payments Card number aliases Access data Transaction details Request message - payments Request message - registering a card number alias Shop notification Modification of the forms Configuration of Your Account Credit Card Verification Number FAQ Appendix 6.1 Test data Test data for payment transactions Response messages Sparkassen-Internetkasse messages VÖB-ZVD payment gateway messages Parameter format description MAC - Message Authentication Code HMAC - Keyed-Hashing for Message Authentication s Sample code Glossary Version Date of issue: 26/11/2015 5

6 1.1 Labelling and formatting 1 About this document 1.1 Labelling and formatting Please pay attention to the following labelling in the text: Program listings, source code These are excerpts from the program source code or listings. : Listing 1-1 #!/bin/bash # endless loop while[true] do clear; free; sleep 1; done Parameters All parameter designations appear in the following font: parameter. Caution A note about a situation that demands caution and attention Important An especially important note Note A note referring to context or further information Highlighted text Significant words and essential information requiring emphasis appear in italics. 1.2 Disclaimer The information in this document has been compiled with the utmost diligence. However the documentation neither claims completeness nor accuracy. VÖB-ZVD Processing therefore neither assumes liability for usability or correctness nor - as far as legally allowed - for direct, indirect, accidental or consequential damage arising from the use of the information provided in this document. With the exception of cases of intention and gross negligence, liability is excluded for errors in translation as well as damages resulting from this. Version Date of issue: 26/11/2015 6

7 1.3 Copyright note 1.3 Copyright note This document is copyright protected. The use of text and images, even excerpts, without the prior written permission of VÖB-ZVD Processing is a copyright offence. This especially applies to copying, translation, or use in electronic systems. All rights reserved Version Date of issue: 26/11/2015 7

8 2.1 Product 2 Introduction 2.1 Product Sparkassen-Internetkasse is a management system for the processing, approval, and management of credit card and direct debit payments received by an online trader. The online traders and operators connected to the system receive their own user-specific and fully web-based access. As a result, the relevant management, statistics, and monitoring functions can be used. A trader's account is multi-user enabled. The trader can set up several users for his account. Credit card and direct debit payments are currently supported. Sparkassen- Internetkasse provides online traders with differentiated access for processing individual transactions and differentiated, up-to-the-minute sales statistics. The batch processing function combines transactions and processes them en bloc. The import function enables several payments to be generated automatically. All transactions can be archived using data export. If desired, the transactions you submitted can be made available in an export file by the day. This is an additional service that can be arranged with B+S. This document only deals with connection and does not cover the online trader's Web-based access. For more information on this, see the Merchant view user manual. The following modes are available for handling payments: Manual (via web browser) Shop interface Form service / 3D-Secure All transaction data during transaction processing and data export are transmitted using SSL encryption. 2.2 Target group, purpose of the document This document is intended for online traders and Sparkassen-Internetkasse integrators. You should have basic technical programming knowledge and basic knowledge of HTML and electronic payment transactions. This documentation describes the Sparkassen-Internetkasse interfaces and helps you as you connect your shop or application. Version Date of issue: 26/11/2015 8

9 2.3 Overview of contents 2.3 Overview of contents This document starts with an overview of Sparkassen-Internetkasse. This overview contains information about the prerequisites for connection, details on support, and tips on selecting the suitable interface for integrating your application. This is followed by a detailed description of the connection. Each interface is described in its own chapter. The appendix contains test data and a description of the system's response codes. A glossary can be found at the very end of the document. Version Date of issue: 26/11/2015 9

10 3.1 System and interface overview 3 Overview 3.1 System and interface overview The system includes: You as an online trader with your shop/application and browser access to the Sparkassen-Internetkasse service Your customers the Sparkassen-Internetkasse system, consisting of several components as well as the systems of Credit card organisations Banks for processing payment transactions escore and Bürgel 1 for payment related services You can use a web browser to access the Sparkassen-Internetkasse service in order to check and post-process your transactions and create statistics. You can also import transactions into the system using file import. This function is described in the Sparkassen-Internetkasse user manual. Your customers do not access the Sparkassen-Internetkasse service when connected via the shop interface but communicate exclusively with your shop or application. The Sparkassen-Internetkasse service will check the plausibility of your shop's payment transactions or escore, Bürgel transactions, respectively. From the payment gateway of the Sparkassen-Internetkasse service the transactions are forwarded to the systems of the banks and credit card organisations for payment processing. Credit card transactions and payment-related services are responded to within a few seconds. They are stored, processed and immediately forwarded to your shop by the Sparkassen-Internetkasse service D-Secure The Credit Card Security Cartridge (CCS) was integrated into the Sparkassen- Internetkasse service to secure payment transactions. The CCS corresponds to 1 You can find details on escore and Bürgel in separate documentations. Version Date of issue: 26/11/

11 3.3 Prerequisites for connection the 3D-Secure specification, MPI Distributed Processing. Visa developed this standard for the secure transaction of credit card payments. In cases of disputed transactions, 3D-Secure - normally - guarantees the liability shift in favour of the online trader. Note Contact your credit card acquirer to get details on liablility shift regulations. The CCS has been certified by Visa. Payments made according to the 3D-Secure protocol are supported by Visa as "Verified by Visa" and by MasterCard as "MasterCard SecureCode". The CCS not only allows "Verified by Visa" and "MasterCard SecureCode" payments, but also all credit card and direct debit payments, which you can also implement using the Sparkassen-Internetkasse form service. The CCS therefore offers a uniform interface for all payment types. 3.3 Prerequisites for connection For the settlement of credit card payments, you need a credit card acceptance contract. You should also have a bank account that permits direct debit transfer. For 3D-Secure payments, you as an online trader must also be registered and released for Verified by Visa or MasterCard SecureCode. To do this, contact your credit card acquirer. If you use standard software for your shop or application, ask our customer support whether your software is already supported by Sparkassen-Internetkasse. If it is, the integration effort is low. To connect non-standard shops, you need comprehensive programming knowledge and knowledge of how your shop or application works. A technical prerequisite for connection is the ability to execute scripts, in other words, process data transferred via HTTPS request. A pure HTML shop is therefore not suitable for connection. Depending on the technical circumstances Sparkassen-Internetkasse offers you several interfaces for connection. This documentation assists you in choosing the appropriate interface (see Section Choosing the appropriate interface, p. 12). For detailed requirements of the selected interface, see Chapter Shop interface, p. 15 and Chapter Form service / 3D-Secure, p Connection procedure 1. Contractual agreement The use of the Sparkassen-Internetkasse service by the trader is based on a contractual agreement between you, the trader, and the licensee. 2. Test environment and connection documentation Version Date of issue: 26/11/

12 3.5 Support contact A test environment is made available to you. Use this document to learn how to integrate the Sparkassen-Internetkasse service. 3. Choosing the appropriate interface You choose a connection alternative. Section Choosing the appropriate interface, p. 12 assists you with the decision. 4. Connection You can carry out the connection yourself with little effort. You can get telephone and/or support (see Section Support contact, p. 12). 5. Tests In order to ensure that the connection functions correctly, you can carry out simulated payments in the test environment. 6. Activation The licensee sets up personalised trader access for you. If you have not done so already, you must now inform the licensee of the contract partner number(s) for handling credit card payments and your account number for handling direct debits. You will receive your access data (login and password) by so that you can use your trader access. 7. Configuration With this access data, you can configure your system for active operation. 8. Operation The payment system is now ready for you and your customers. 3.5 Support contact Please ask the licensee for the support contact. 3.6 Choosing the appropriate interface For distribution via catalogue and call centre or if you want to record only few payments and the required credit card or bank data are already available you can record payment data manually with your web browser. This is explained in the Sparkassen-Internetkasse user manual. If data of payment transactions are already present in an application you can import them into Sparkassen-Internetkasse as a file. This requires a special contractual agreement. Importing files is explained in the Sparkassen-Internetkasse user manual. Two interfaces are available for recording payments automatically: shop interface and form service. Version Date of issue: 26/11/

13 3.7 SEPA Direct Debits Shop interface The shop interface permits the highest degree of control and the largest extent of freedom for designing the course of the payment procedure. The shop or application is responsible for recording all payment-relevant data for your customers. In order to be able to transfer credit card data, bank data, and other sensitive customer data securely online, you require an SSL certificate that enables you to carry out SSL encryption with a 128 bit key length. Note that if you record credit card data, you are required to comply with the "Payment Card Industry (PCI) Data Security Standards" of Visa and MasterCard. The shop interface is the suitable connection alternative, if your customers' payment data are already stored in your application. Your application does not have to be a classical web shop. The shop interface offers you a higher functional range than the form service. Reversing and returning payments, for example, is not possible with the form service. The additional functions soring, credit assessment and address verification are also only available with the shop interface. Form service If you do not have an SSL certificate already and do not want to purchase one, you can connect to Sparkassen-Internetkasse using the form service. The HTML forms shown to your customers to enter credit card or bank data are displayed by the Sparkassen-Internetkasse server. The transfer of payment data thus takes place 128-bit SSL encrypted, without you requiring an SSL certificate. You can influence the appearance of these HTML forms to harmonise with the design of your shop. The recording of address data and other customer data required for the online purchase is carried out by your shop even when using the form service. With the form service, credit card data will not be saved in your shop and you save effort and time for participating in the "Payment Card Industry Data Security Standard" (PCI) program of Visa und MasterCard since participation in the PCI program takes place centrally through the Sparkassen-Internetkasse-Service. Furthermore the form service enables secure credit card payments according to the 3D-Secure protocol, better known as "Verified by Visa" and "MasterCard SecureCode" as well as Maestro payments according to the 3D-Secure protocol. 3.7 SEPA Direct Debits By default SEPA direct debits are cleared through Sparkassen-Internetkasse according to the SDD COR1 standard. The SDD COR1 direct debits are submitted with a due date three TARGET2 business days (not on weekends or the so called TARGET2 or TARGET holidays) after the date on which the capture or reservation/capture is generated in Sparkassen-Internetkasse. For SDD COR1 direct debits Sparkassen-Internetkasse currently accepts German and Austrian bank accounts. Alternatively you can carry out SEPA SDD Core direct debits by submitting the parameter debitmode=sepacore when you record the payment. With SEPA Core Version Date of issue: 26/11/

14 3.7 SEPA Direct Debits direct debits you can optionally carry out international direct debits within the SEPA countries. You can activate international direct debits in the front office on the Master Data view of the shop. Note In the case of SEPA Core direct debits you have to enter a due date. Regarding the pre-notification of customers and the issuing of mandates by customers the requirements of the SEPA regulations apply and have to be observed by the shop owner. In addition, the processing of SEPA direct debits requires additional information regarding your standing data (creditor ID, IBAN, BIC, etc.) which you can configure in the front office. If a customer signed a SEPA mandate for recurring payments there may be changes to the original mandate you have to take into account during the next payment to prevent it from being rejected due to invalid mandate information. Proceed as follows in these cases: If your creditor ID changes you enter the new creditor ID in the front office. For all affected mandates, submit the previous creditor ID with the next recurring payment after the change in the field creditorid_obsolete. If the mandate reference changes you submit the current value in the field mandateid and additionally the previous value in the field mandateid_obsolete. If the customer's IBAN changes, at the shop interface you submit the current value in the field iban and additionally the previous value in the field iban_obsolete. In the form service you also enter the previous IBAN in the field iban_obsolete and let the customer enter the new IBAN in the form. In the case of a return debit note you can assign it to the corresponding Sparkassen-Internetkasse transaction by using the SEPA End To End ID. The End To End ID consists of the final six characters of the retrefnr followed by a dot and the orderid. In the process, underscores which are not allowed in the End To End ID are removed from the orderid. Version Date of issue: 26/11/

15 4.1 Prerequisites 4 Shop interface 4.1 Prerequisites The shop or your application is responsible for recording all payment-relevant data for your customers. In order to be able to enter credit card data, bank data, and other sensitive customer data securely online, you require a SSL certificate that enables you to carry out SSL encryption with a 128 bit key length. 1 If you record the customer data required for payment by other means, e.g. by written subscription or in a call center this prerequisite does not apply. Note that if you record credit card data, you are required to comply with the "Payment Card Industry Data Security Standards (PCI DSS)" of Visa and Master- Card. Your application must be able to send SSL-client encrypted (128 bit key length) HTTP requests (GET or POST) and to receive and process the response. An example for communication with the Sparkassen-Internetkasse server can be found in Section s, p. 65. On the basis of the parameters of the response message, your application must evaluate whether the payment was successful (parameter rc has the value 000 and parameter posherr has the value 0 ) or not (parameter posherr has a value other than 0). Your application displays a message to the customer in the browser depending on the result, and updates the status of the order in the shop. 4.2 Function description The following diagram shows an example of a payment transaction in the form of a flow chart. 1 You can get an SSL certificate e.g. from VeriSign ( or Thawte ( Version Date of issue: 26/11/

16 4.2 Function description Figure 4-1: Diagram showing shop interface The transaction proceeds as follows: 1. The customer makes a purchase in the shop and enters the required payment data. 2. The shop receives this data and checks that the format is correct. If an error occurs, an error message is issued (step 11). 3. The shop generates a request message and sends this to the Sparkassen- Internetkasse server via HTTPS request. 4. The Sparkassen-Internetkasse server checks the transferred data. If an error occurs, processing is terminated and an error code is set in field posherr (step 9). 5. The Sparkassen-Internetkasse server sends the payment data to the payment gateway. 6. The payment gateway processes this data. 7. The payment gateway transfers the result message to the Sparkassen-Internetkasse server. 8. The Sparkassen-Internetkasse server processes the result message and stores the result of the transaction in the database. (This result is now displayed in the front office.) 9. The Sparkassen-Internetkasse server sends a response message to the shop. Version Date of issue: 26/11/

17 4.3 Verifying the issuing country of credit cards 10. The shop evaluates the response message and stores the result. 11. The shop shows the customer the result of the transaction. Using and forwarding a shopping basket number is the best reference between the payment procedure in the shop, the credit note on the trader account and the debit of the customer account. For more information, see Section Parameters with special significance, p Verifying the issuing country of credit cards Sparkassen-Internetkasse enables you to check the issuing country of credit cards. To use this optional feature you can specify for every credit card payment which issuing countries you want to accept or reject. In addition you can submit the country of delivery to the shop interface. Sparkassen-Internetkasse will then check if the country of delivery matches the issuing country of the credit card. If not, Sparkassen-Internetkasse rejects the credit card or informs your shop - depending which policy you chose for this transaction. At present, verifying the issuing country is available for Visa and MasterCard credit cards. 4.4 Card number aliases Card number aliases provide a possibility to carry out recurring payments with a credit card without saving the credit card details in your system. Thus, if you use the form service to carry out the first payment with a credit card or to register an alias for the credit card (see Section Card number aliases, p. 74) you do not have to participate in the "Payment Card Industry Data Security Standard" (PCI DSS) programme by Visa and MasterCard. Your account has to be configured accordingly to use card number aliases. If your account is configured to use card number aliases, you only have to submit the credit card number and expiry date for the first payment with a particular credit card. In the response you will receive a card number alias that has been generated by Sparkassen-Internetkasse. Alternatively you can submit your own card number alias in the ppan field. For all subsequent payments with this credit card you submit the card number alias in the ppan field instead of the credit card number and the expiry date. You can create card number aliases for bank accounts as well if your account is configured accordingly. In this case you only submit bank code and account number or IBAN for the first payment and submit the card number alias instead for all subsequent payments with this bank account. You can also create card number aliases independently from any payment. Sparkassen-Internetkasse provides the following functionality to manage card number aliases: create a card number alias for a credit card or bank account get infomation about a card number alias and the credit card or bank account it is assigned to Version Date of issue: 26/11/

18 4.5 Access data find out if a card number alias exists remove a card number alias Sparkassen-Internetkasse guarantees an unambiguos assignment of a card number alias to a credit card or bank account. An existing card number alias cannot be assigned to another credit card or bank account. Conversely, you cannot assign more than one card number alias to a particular credit card or bank account. Details about using card nubmer aliases are described in Section Transaction details, p. 22. Card number aliases for credit cards are automatically deleted twelve months after the card expires. 4.5 Access data Submit your queries to the following URL: Test access: Live access: HTTP basic authentication is used to protect access for the identification of the trader account and authentication of the payment request. This means that you must enter your login and password to access the URL. You receive your login and password when your access is activated for use. You may need additional components/libraries in order to execute HTTPS requests with HTTP basic authentication in your shop as HTTP(S) client. Components/libraries are available for the common programming and script languages. Note that SSL encryption requires a 128 bit key length. Shorter key lengths cannot be regarded as secure. Implementation of login and password transfer depends on the components/libraries used for this. Usually, a transfer in the URL is also possible, for example prot/request.po Do not send your login and password together with the payment data as a CGI parameter! During implementation, make sure that URL, login and password are configurable and can be updated easily during the switch from test to live access and in case of subsequent changes. Version Date of issue: 26/11/

19 4.6 Interface version 4.6 Interface version This document relates to version of the shop interface. In every shop interface response message, the current version number is specified in the parameter posh_version. 4.7 Transaction types The following sections contain the possible transaction types for credit card and direct debit payments. The associated parameters of the request and response message can be found in Section Parameter overview, p Reserve Carry out a reservation if the order is fulfilled at a later point in time, but the order value for the card submitted by the customer is to be approved or the specified bank details are to be checked when the order is placed. The reservation period is approx. seven days for credit cards and 30 days for direct debits. The reservation period for credit card payments is regulated by your acceptance contract. In case of uncertainties concerning the reservation period for credit card payments please contact your acquirer. Once this reservation period has expired, it is no longer possible to capture this transaction. Sparkassen-Internetkasse also allows you to determine for each reservation if and when it is to be automatically captured by the Sparkassen-Internetkasse system. Direct debit The system checks whether the specified bank code exists and whether the specified account number is valid for the check digit procedure of this bank. If an IBAN is submitted it is checked accordingly. The parameters of the request and response message can be found in Table 4-1, p. 25. Credit card The system checks whether a submitted card exists, is blocked, and can be charged with a particular amount. This request can be rejected, or approved by granting of an approval number. If it is approved, the requested amount is reserved from the credit limit of the submitted card. The parameters of the request and response message can be found in Table 4-2, p Reserve/capture Reservation and capture are carried out together at the same time. A separate capture message is not required to initiate the capture. Version Date of issue: 26/11/

20 4.7 Transaction types Use the Reserve/Capture transaction type if the business transaction has been concluded, in other words, if a shopping basket has been offered, ordered, and delivered to the customer, for example. The parameters of the request and response message can be found in Table 4-3, p. 29 (direct debit) and Table 4-4, p. 31 (credit card) Refund Refunds are transactions that return the payments to the customer. The refunded amount can be part of the paid amount or the full paid amount. You can carry out a refund as an initial transaction or with reference to an existing capture or reservation/capture. Note It depends on the configuration of your account whether you are allowed to carry out a refund as an initial transaction. The process for the submission and the clearing of refunds on your customers' current accounts may need to be coordinated with your account-holding institution. The parameters of the request and response message can be found in Table 4-5, p. 32, Table 4-6, p. 34, Table 4-9, p. 37, Table 4-10, p. 39. If the refund refers to a transaction that has already been carried out, you need the orderid and trefnum of this transaction as parameters of the request message. You will find trefnum in the response message of every transaction Reversal Reservations, reserved/captured transactions, refunds and credit notes can all be reversed. A reservation can be reversed as long as the capture message has not been sent or until the reservation period expires. In the case of direct debit transactions, reserved/captured transactions, refunds and credit notes can be reversed on the same day. In the case of credit card transactions the period in which a reversal is possible depends on your acquirer. The parameters of the request and response message can be found in Table 4-11, p. 40 (direct debit), and Table 4-12, p. 41 (credit card). You need the orderid and trefnum of the transaction to be reversed as parameters of the request message. You will find trefnum in the response message of every transaction Capture A capture transaction must be preceded by a "Reservation" transaction. The amount to be captured must be less than or equal to the reserved amount. This means that partial amounts can also be captured, for example. During the capture, an amount is debited from the customer account and credited to the trader account. This model assumes that the underlying business transaction is Version Date of issue: 26/11/

21 4.7 Transaction types closed, for example a shopping basket was offered, ordered, and delivered to the customer. Important Captures cannot be reversed. A refund must be made. The parameters of the request and response message can be found in Table 4-7, p. 35 (direct debit) and Table 4-8, p. 36 (credit card). You need the orderid and trefnum of the transaction to be captured as parameters of the request message. You will find trefnum in the response message of every transaction Means of payment verification The credit card or bank details are checked (see Section Reserve, p. 19. No payment is carried out. You can also use this transaction type to register a card number alias Diagnosis A diagnosis request is used to receive the response of a transaction that is already concluded one more time. This is helpful if you do not know the status of a transaction, for example because you did not receive an answer to your request due to a problem with the internet connection or an error occured while processing the response of the Sparkassen-Internetkasse service and the data are no longer available. With a diagnosis you can search for the last partial transaction. If, for example, you carried out a reservation and later captured this reservation the diagnosis relates to the capture. The parameters of the request and response message can be found in Table 4-17, p. 49. You need orderid and trefnum of the transaction you are looking for as parameters for the request message. For the first partial transaction of a payment process trefnum corresponds to the process number with _01 attached. For subsequent partial transactions the attached number is incremented: _02, _03, etc. s: You are looking for a reservation with transaction number Set parameter trefnum to 1234_01. You have carried out a reservation/capture and a refund with the process number In order to look for the refund you set trefnum to 1234_02. If a transaction with the given values for orderid and trefnum cannot be found, you will receive a response message with error code posherr=106 or posherr=100 and rc=875 and the corresponding error message in parameter rmsg. Version Date of issue: 26/11/

22 4.8 Transaction details Transactions with blacklist check In the case of direct debits with transaction types reserve und reserve/capture it is possible to check a blacklist in addition to the existing validation of the bank account. This additional validation is controlled by the payment_options parameter. Transactions with blacklist check are only possible if they have been activated for your account. To comply with German data privacy regulations it is necessary that the customer consents to the disclosure of their data to InterCard. For this purpose, please display the following text to your customers: Zur Begrenzung des Zahlungsausfallrisikos bin ich einverstanden mit der Übermittlung von BLZ und Kontonummer an die InterCard AG, Mehlbeerenstraße 4, Taufkirchen und einer Sperrdatei-Abfrage, ob bei Inter- Card offene Forderungen zur genannten Bankverbindung vorliegen. Zur Verhinderung von Missbrauch ( 4safe-Check ) werden weiterhin BLZ, Kontonummer, Datum, Uhrzeit und Betrag der Zahlung an InterCard übermittelt, dort händlerspezifisch ausgewertet und eine Empfehlung zur Akzeptanz der Zahlung zurückgegeben. The text sould be placed directly below the selection of the payment method or, in the case of a separate page for the input of bank code and bank account number, above or below the input fields - but in any case before the submit button of the form. The parameters of the request and response message can be found in Table 4-15, p. 46 and Table 4-16, p Transaction details For each transaction, the following tables show which values have to be included in the request message and which values you receive with the response. The parameters command and payment_options are used to control the transaction type. They must be assigned the values listed in the tables. In some cases, parameters may not be included in the response message. The conditions that cause this are stated in a cross-column table row. Obsolete parameters are indicted by an asterisk (*). These parameters are irrelevant for the functionality of the shop interface Card number aliases If your account is configured to use card number aliases for credit cards or bank accounts the transaction details for the credit card or direct debit transaction types reserve, reserve/capture and refund (initial transaction) differ as follows from the description in the subsequent tables: Version Date of issue: 26/11/

23 4.8 Transaction details First transaction with a credit card or bank account Set the payment_options parameter to creditcard;generate_ppan (instead of creditcard) or elv;generate_ppan (instead of elv) ly, you can submit the desired card number alias in the additional parameter ppan. If you do not submit this parameter Sparkassen-Internetkasse will generate a card number alias. If successful, the response contains the addtional parameter ppan. If you submitted a card number alias ppan contains the value you submitted, otherwise the value generated by Sparkassen-Internetkasse. Use this card number alias for all subsequent transactions with this credit card or bank account. Subsequent transaction with a credit card or bank account Parameter payment_options=creditcard or payment_options=elv, respectively Omit the creditc and expdat or bankcode and account or iban parameters in the request. Instead, submit the ppan parameter containing the card number alias. The card number alias in th ppan parameter may consist of up to 50 alphanumerical and special characters and spaces. A card number alias can be assigned only once. You can assign only one card number alias to a credit card (characterised by card number and expiry date) or bank account (characterised by bank code and account number or IBAN respectively). The shop interface offers you the possibility to find out if a given card number alias has already been assigned (see Section Checking if a Card Number Alias Exists, p. 50) or if any card number alias and, if so, which card number alias has been assigned to a credit card or bank account (see Section Getting Information about a Card Number Alias, p. 51) Reserve, direct debit If your account is configured to use card number aliases for bank accounts the request parameters change as specified in Section Card number aliases, p. 22. Parameter Request Response command payment_options, preauthorization, elv orderid basketnr clientip amount currency, EUR account Submit either account and bankcode or iban. Version Date of issue: 26/11/

24 4.8 Transaction details Parameter Request Response bankcode iban bic Submit either account and bankcode or iban. Submit either account and bankcode or iban. Only for SEPA direct debits with bank accounts from outside of Germany. accountholder mandateid mandatesigned mandatename sequencetype creditorid_obsolete iban_obsolete bic_obsolete mandateid_obsolete debitmode autocapture, if the SEPA mandate is modified, if the SEPA mandate is modified, if the SEPA mandate is modified, if the SEPA mandate is modified posh_version posherr rmsg rc txn_date txn_time merch_name * merch_street * merch_town * merch_tid *, can be blank., can be blank., can be blank., can be blank., can be blank. included in the response if parameter rc contains a value. pcode * posem * poscc * aid trefnum Version Date of issue: 26/11/

25 4.8 Transaction details Parameter Request Response retrefnr txntype timestamp Included in the response, value not set cai * txn_card txn_expdat Table 4-1: Reserve, direct debit The '*' character indicates obsolete parameters. These parameters are irrelevant for the functionality of the shop interface Reserve, credit card The optional parameters acceptcountries, deliverycountry, deliverycountryaction and rejectcountries permit to check the issuing country of a credit card. At present, this verification can be performed for Visa and MasterCard cards. If a customer pays with a card from another brand, the issuing country will not be checked and the payment will not be rejected because of the issuing country of the credit card. Submitting the card verification code is mandatory with the following exception: in the case of recurring payments (seriesflag=recurring) the card verification code has to be submitted only with the first transaction with this particular credit card. This rule applies also if card number aliases are used. If your account is configured to use card number aliases the request parameters change as specified in Section Card number aliases, p. 22. The optional parameters customer_addr_... are used to validate the customer's address (verification of postal code and numerical parts of the address like street and appartment number). This service is at present only available for payments with American Express credit cards. The address verification does not influence the result of the payment. Instead, the result of the address verification is returned in the field rc_avsamex and additionally as a traffic light value in the parameter rc_score. Parameter Request Response command payment_options, preauthorization, creditcard orderid basketnr clientip Version Date of issue: 26/11/

26 4.8 Transaction details Parameter Request Response amount currency creditc expdat cvcode, can be blank. cardholder merchantref autocapture acceptcountries rejectcountries deliverycountry, if deliverycountry is set and deliverycountryaction=notify in the request. deliverycountryaction hotline seriesflag additionalnote, recurring For American Express credit cards only customer_addr_street customer_addr_number customer_addr_zip customer_addr_city posh_version posherr rmsg rc txn_date txn_time merch_name * merch_street * merch_town * merch_tid *, can be blank., can be blank., can be blank., can be blank., can be blank. included in the response if parameter rc contains a value. pcode * posem * Version Date of issue: 26/11/

27 4.8 Transaction details Parameter Request Response poscc * aid trefnum retrefnr txntype timestamp cai * txn_card txn_expdat rc_score rc_avsamex After American Express address verification After American Express address verification Table 4-2: Reserve, credit card The '*' character indicates obsolete parameters. These parameters are irrelevant for the functionality of the shop interface Reserve/capture, direct debit If your account is configured to use card number aliases for bank accounts the request parameters change as specified in Section Card number aliases, p. 22. Parameter Request Response command payment_options, authorization, elv orderid basketnr clientip amount currency, EUR account bankcode iban Submit either account and bankcode or iban. Submit either account and bankcode or iban. Submit either account and bankcode or iban. Version Date of issue: 26/11/

28 4.8 Transaction details Parameter Request Response bic Only for SEPA direct debits with bank accounts from outside of Germany. accountholder mandateid mandatesigned mandatename sequencetype creditorid_obsolete iban_obsolete bic_obsolete mandateid_obsolete debitmode duedate, if the SEPA mandate is modified, if the SEPA mandate is modified, if the SEPA mandate is modified, if the SEPA mandate is modified in case of a SEPA Core direct debit posh_version posherr rmsg rc txn_date txn_time merch_name * merch_street * merch_town * merch_tid *, can be blank., can be blank., can be blank., can be blank., can be blank. included in the response if parameter rc contains a value. pcode * posem * poscc * aid trefnum retrefnr txntype timestamp Version Date of issue: 26/11/

29 4.8 Transaction details Parameter Request Response Included in the response, value not set cai * txn_card txn_expdat Table 4-3: Reserve/capture, direct debit The '*' character indicates obsolete parameters. These parameters are irrelevant for the functionality of the shop interface Reserve/capture, credit card The optional parameters acceptcountries, deliverycountry, deliverycountryaction and rejectcountries permit to check the issuing country of a credit card. At present, this verification can be performed for Visa and MasterCard cards. If a customer pays with a card from another brand, the issuing country will not be checked and the payment will not be rejected because of the issuing country of the credit card. Submitting the card verification code is mandatory with the following exception: in the case of recurring payments (seriesflag=recurring) the card verification code has to be submitted only with the first transaction with this particular credit card. This rule applies also if card number aliases are used. If your account is configured to use card number aliases the request parameters change as specified in Section Card number aliases, p. 22. The optional parameters customer_addr_... are used to validate the customer's address (verification of postal code and numerical parts of the address like street and appartment number). This service is at present only available for payments with American Express credit cards. The address verification does not influence the result of the payment. Instead, the result of the address verification is returned in the field rc_avsamex and additionally as a traffic light value in the parameter rc_score. You can also use this transaction to carry out a voice authorisation. To do so, you submit the authorisation code you obtained from the voice authorisation service in the aid field - in addition to the other payment data. Parameter Request Response command payment_options, authorization, creditcard orderid basketnr clientip amount Version Date of issue: 26/11/

30 4.8 Transaction details Parameter Request Response currency creditc expdat cvcode, can be blank. cardholder merchantref acceptcountries rejectcountries deliverycountry, if deliverycountry is set and deliverycountryaction=notify in the request. deliverycountryaction hotline seriesflag additionalnote, recurring For American Express credit cards only customer_addr_street customer_addr_number customer_addr_zip customer_addr_city posh_version posherr rmsg rc txn_date txn_time merch_name * merch_street * merch_town * merch_tid *, can be blank., can be blank., can be blank., can be blank., can be blank. included in the response if parameter rc contains a value. pcode * posem * poscc * aid for voice authorisation only Version Date of issue: 26/11/

31 4.8 Transaction details Parameter Request Response trefnum retrefnr txntype timestamp cai * txn_card txn_expdat rc_score rc_avsamex After American Express address verification After American Express address verification Table 4-4: Reserve/capture, credit card The '*' character indicates obsolete parameters. These parameters are irrelevant for the functionality of the shop interface Refund, direct debit, initial transaction This transaction may be deactivated by the configuration of your account. If your account is configured to use card number aliases for bank accounts the request parameters change as specified in Section Card number aliases, p. 22. Parameter Request Response command payment_options, refund, elv orderid basketnr clientip amount currency, EUR account bankcode iban bic Submit either account and bankcode or iban. Submit either account and bankcode or iban. Submit either account and bankcode or iban. Only for SEPA direct debits with bank accounts from outside of Germany. Version Date of issue: 26/11/

32 4.8 Transaction details Parameter Request Response accountholder posh_version posherr rmsg rc txn_date txn_time merch_name * merch_street * merch_town * merch_tid *, can be blank., can be blank., can be blank., can be blank., can be blank. included in the response if parameter rc contains a value. pcode * posem * poscc * aid trefnum retrefnr txntype timestamp Included in the response, value not set cai * txn_card txn_expdat Table 4-5: Refund, direct debit, initial transaction The '*' character indicates obsolete parameters. These parameters are irrelevant for the functionality of the shop interface Refund, credit card, initial transaction This transaction may be deactivated by the configuration of your account. Submitting the card verification code is mandatory with the following exception: in the case of recurring payments (seriesflag=recurring) the card verification code has to be submitted only with the first transaction with this particular credit card. This rule applies also if card number aliases are used. Version Date of issue: 26/11/

33 4.8 Transaction details If your account is configured to use card number aliases the request parameters change as specified in Section Card number aliases, p. 22. Parameter Request Response command payment_options, refund, creditcard orderid basketnr clientip amount currency creditc expdat cvcode, can be blank. cardholder merchantref additionalnote posh_version posherr rmsg rc txn_date txn_time merch_name * merch_street * merch_town * merch_tid *, can be blank., can be blank., can be blank., can be blank., can be blank. included in the response if parameter rc contains a value. pcode * posem * poscc * aid trefnum retrefnr txntype timestamp Version Date of issue: 26/11/

34 4.8 Transaction details Parameter Request Response cai * txn_card txn_expdat Table 4-6: Refund, credit card, initial transaction The '*' character indicates obsolete parameters. These parameters are irrelevant for the functionality of the shop interface Capture, direct debit Parameter Request Response command payment_options, capture, elv orderid basketnr clientip amount currency trefnum, included in the response if parameter rc contains a value. duedate in case of a SEPA Core direct debit posh_version posherr rmsg rc txn_date txn_time merch_name * merch_street * merch_town * merch_tid *, can be blank., can be blank., can be blank., can be blank., can be blank. included in the response if parameter rc contains a value. pcode * posem * poscc * Version Date of issue: 26/11/

35 4.8 Transaction details Parameter Request Response aid retrefnr txntype timestamp account bankcode iban bic accountholder Included in the response, value not set cai * txn_card txn_expdat Table 4-7: Capture, direct debit The '*' character indicates obsolete parameters. These parameters are irrelevant for the functionality of the shop interface Capture, credit card Parameter Request Response command payment_options, capture, creditcard orderid basketnr clientip amount currency trefnum, included in the response if parameter rc contains a value. merchantref additionalnote posh_version posherr rmsg Version Date of issue: 26/11/

36 4.8 Transaction details Parameter Request Response rc txn_date txn_time merch_name * merch_street * merch_town * merch_tid * cvcode, can be blank., can be blank., can be blank., can be blank., can be blank., Included in the response, value not set included in the response if parameter rc contains a value. pcode * posem * poscc * aid retrefnr txntype timestamp creditc expdat cai * txn_card txn_expdat Table 4-8: Capture, credit card The '*' character indicates obsolete parameters. These parameters are irrelevant for the functionality of the shop interface Refund, direct debit, follow-up transaction This transaction is a follow-up transaction, i.e. a transaction that relates to a preceding capture or reservation/capture. Parameter Request Response command payment_options, refund, elv orderid basketnr Version Date of issue: 26/11/

37 4.8 Transaction details Parameter Request Response clientip amount currency trefnum, included in the response if parameter rc contains a value. posh_version posherr rmsg rc txn_date txn_time merch_name * merch_street * merch_town * merch_tid *, can be blank., can be blank., can be blank., can be blank., can be blank. included in the response if parameter rc contains a value. pcode * posem * poscc * aid retrefnr txntype timestamp account bankcode iban bic accountholder Included in the response, value not set cai * txn_card txn_expdat Table 4-9: Refund, direct debit, follow-up transaction Version Date of issue: 26/11/

38 4.8 Transaction details The '*' character indicates obsolete parameters. These parameters are irrelevant for the functionality of the shop interface Refund, credit card, follow-up transaction This transaction is a follow-up transaction, i.e. a transaction that relates to a preceding capture or reservation/capture. Parameter Request Response command payment_options, refund, creditcard orderid basketnr clientip amount currency trefnum, included in the response if parameter rc contains a value. merchantref additionalnote posh_version posherr rmsg rc txn_date txn_time merch_name * merch_street * merch_town * merch_tid *, can be blank., can be blank., can be blank., can be blank., can be blank. Included in the response, value not set cvcode included in the response if parameter rc contains a value. pcode * posem * poscc * aid retrefnr Version Date of issue: 26/11/

39 4.8 Transaction details Parameter Request Response txntype timestamp creditc expdat cai * txn_card txn_expdat Table 4-10: Refund, credit card, follow-up transaction The '*' character indicates obsolete parameters. These parameters are irrelevant for the functionality of the shop interface Reversal, direct debit Parameter Request Response command payment_options, reversal, elv trefnum, included in the response if parameter rc contains a value. orderid basketnr clientip posh_version posherr rmsg rc txn_date txn_time merch_name * merch_street * merch_town * merch_tid *, can be blank., can be blank., can be blank., can be blank., can be blank. included in the response if parameter rc contains a value. pcode * posem * Version Date of issue: 26/11/

40 4.8 Transaction details Parameter Request Response poscc * aid retrefnr txntype timestamp account bankcode iban bic accountholder amount currency Included in the response, value not set cai * txn_card txn_expdat Table 4-11: Reversal, direct debit The '*' character indicates obsolete parameters. These parameters are irrelevant for the functionality of the shop interface Reversal, credit card Parameter Request Response command payment_options, reversal, creditcard trefnum, included in the response if parameter rc contains a value. orderid basketnr clientip posh_version posherr rmsg rc, can be blank. Version Date of issue: 26/11/

41 4.8 Transaction details Parameter Request Response txn_date txn_time merch_name * merch_street * merch_town * merch_tid * cvcode, can be blank., can be blank., can be blank., can be blank., Included in the response, value not set included in the response if parameter rc contains a value. pcode * posem * poscc * aid retrefnr txntype timestamp creditc expdat cai * txn_card txn_expdat amount currency Table 4-12: Reversal, credit card The '*' character indicates obsolete parameters. These parameters are irrelevant for the functionality of the shop interface Means of payment verification, direct debit If your account is configured to use card number aliases for bank accounts the request parameters change as specified in Section Card number aliases, p. 22. Parameter Request Response command payment_options, verifymop, elv orderid Version Date of issue: 26/11/

42 4.8 Transaction details Parameter Request Response basketnr clientip currency, EUR account bankcode iban bic Submit either account and bankcode or iban. Submit either account and bankcode or iban. Submit either account and bankcode or iban. Only for SEPA direct debits with bank accounts from outside of Germany. accountholder posh_version posherr rmsg rc txn_date txn_time merch_name * merch_street * merch_town * merch_tid *, can be blank., can be blank., can be blank., can be blank., can be blank. included in the response if parameter rc contains a value. pcode * posem * poscc * aid trefnum retrefnr txntype timestamp Included in the response, value not set cai * txn_card txn_expdat Table 4-13: Means of payment verification, direct debit Version Date of issue: 26/11/

43 4.8 Transaction details The '*' character indicates obsolete parameters. These parameters are irrelevant for the functionality of the shop interface Means of payment verification, credit card The optional parameters acceptcountries, deliverycountry, deliverycountryaction and rejectcountries permit to check the issuing country of a credit card. At present, this verification can be performed for Visa and MasterCard cards. If a customer pays with a card from another brand, the issuing country will not be checked and the payment will not be rejected because of the issuing country of the credit card. Submitting the card verification code is mandatory with the following exception: in the case of recurring payments (seriesflag=recurring) the card verification code has to be submitted only with the first transaction with this particular credit card. This rule applies also if card number aliases are used. If your account is configured to use card number aliases the request parameters change as specified in Section Card number aliases, p. 22. The optional parameters customer_addr_... are used to validate the customer's address (verification of postal code and numerical parts of the address like street and appartment number). This service is at present only available for payments with American Express credit cards. The address verification does not influence the result of the payment. Instead, the result of the address verification is returned in the field rc_avsamex and additionally as a traffic light value in the parameter rc_score. Parameter Request Response command payment_options, verifymop, creditcard orderid basketnr clientip currency creditc expdat cvcode, can be blank. cardholder merchantref acceptcountries rejectcountries deliverycountry, if deliverycountry is set and deliverycountryaction=notify in the request. Version Date of issue: 26/11/

44 4.8 Transaction details Parameter Request Response deliverycountryaction hotline For American Express credit cards only customer_addr_street customer_addr_number customer_addr_zip customer_addr_city posh_version posherr rmsg rc txn_date txn_time merch_name * merch_street * merch_town * merch_tid *, can be blank., can be blank., can be blank., can be blank., can be blank. included in the response if parameter rc contains a value. pcode * posem * poscc * aid trefnum retrefnr txntype timestamp cai * txn_card txn_expdat rc_score rc_avsamex After American Express address verification After American Express address verification Table 4-14: Means of payment verification, credit card Version Date of issue: 26/11/

45 4.8 Transaction details The '*' character indicates obsolete parameters. These parameters are irrelevant for the functionality of the shop interface Reserve, direct debit with blacklist check This type of transaction is only available if it has been activated for your account. If your account is configured to use card number aliases for bank accounts the request parameters change as specified in Section Card number aliases, p. 22. Parameter Request Response command payment_options, preauthorization, elv;checklist orderid basketnr clientip amount currency, EUR account bankcode iban bic Submit either account and bankcode or iban. Submit either account and bankcode or iban. Submit either account and bankcode or iban. Only for SEPA direct debits with bank accounts from outside of Germany. accountholder mandateid mandatesigned mandatename sequencetype creditorid_obsolete iban_obsolete bic_obsolete mandateid_obsolete debitmode, if the SEPA mandate is modified, if the SEPA mandate is modified, if the SEPA mandate is modified, if the SEPA mandate is modified posh_version Version Date of issue: 26/11/

46 4.8 Transaction details Parameter Request Response posherr rmsg rc txn_date txn_time merch_name * merch_street * merch_town * merch_tid *, can be blank., can be blank., can be blank., can be blank., can be blank. included in the response if parameter rc contains a value. pcode * posem * poscc * aid trefnum retrefnr txntype timestamp Included in the response, value not set cai * txn_card txn_expdat Table 4-15: Reserve, direct debit with blacklist check The '*' character indicates obsolete parameters. These parameters are irrelevant for the functionality of the shop interface Reserve/capture, direct debit with blacklist check This type of transaction is only available if it has been activated for your account. If your account is configured to use card number aliases for bank accounts the request parameters change as specified in Section Card number aliases, p. 22. Version Date of issue: 26/11/

47 4.8 Transaction details Parameter Request Response command payment_options, authorization, elv;checklist orderid basketnr clientip amount currency, EUR account bankcode iban bic Submit either account and bankcode or iban. Submit either account and bankcode or iban. Submit either account and bankcode or iban. Only for SEPA direct debits with bank accounts from outside of Germany. accountholder mandateid mandatesigned mandatename sequencetype creditorid_obsolete iban_obsolete bic_obsolete mandateid_obsolete debitmode duedate, if the SEPA mandate is modified, if the SEPA mandate is modified, if the SEPA mandate is modified, if the SEPA mandate is modified in case of a SEPA Core direct debit posh_version posherr rmsg rc txn_date txn_time merch_name * merch_street *, can be blank., can be blank., can be blank. Version Date of issue: 26/11/

48 4.8 Transaction details Parameter Request Response merch_town * merch_tid *, can be blank., can be blank. included in the response if parameter rc contains a value. pcode * posem * poscc * aid trefnum retrefnr txntype timestamp Included in the response, value not set cai * txn_card txn_expdat Table 4-16: Reserve/capture, direct debit with blacklist check The '*' character indicates obsolete parameters. These parameters are irrelevant for the functionality of the shop interface Diagnosis Parameter Request Response command payment_options, diagnose, atos orderid basketnr clientip trefnum, included in the response if parameter rc contains a value. posh_version posherr rmsg rc txn_date, can be blank. Version Date of issue: 26/11/

49 4.8 Transaction details Parameter Request Response txn_time merch_name * merch_street * merch_town * merch_tid *, can be blank., can be blank., can be blank., can be blank. included in the response if parameter rc contains a value. pcode * posem * poscc * aid retrefnr txntype timestamp Included in the response, value not set cai * txn_card txn_expdat Table 4-17: Diagnosis The '*' character indicates obsolete parameters. These parameters are irrelevant for the functionality of the shop interface Creating a Card Number Alias for a Credit Card Parameter Request Response command creditc expdat cardholder, ppan_create ppan If posherr=0 posh_version posherr rmsg Table 4-18: Creating a Card Number Alias for a Credit Card Version Date of issue: 26/11/

50 4.8 Transaction details Creating a Card Number Alias for a Bank Account Parameter Request Response command account bankcode iban accountholder, ppan_create Submit either account and bankcode or iban. Submit either account and bankcode or iban. Submit either account and bankcode or iban. ppan If posherr=0 posh_version posherr rmsg Table 4-19: Creating a Card Number Alias for a Bank Account Removing a Card Number Alias Parameter Request Response command ppan, ppan_remove posh_version posherr rmsg Table 4-20: Removing a Card Number Alias Checking if a Card Number Alias Exists Parameter Request Response command ppan, ppan_exists posh_version posherr rmsg Table 4-21: Checking if a Card Number Alias Exists Version Date of issue: 26/11/

51 4.9 Parameter overview Getting Information about a Card Number Alias Parameter Request Response command creditc expdat cardholder account bankcode iban accountholder ppan posh_version posherr rmsg, ppan_info Submit either ppan or creditc and expdat or account and bankcode or iban. Submit either ppan or creditc and expdat or account and bankcode or iban. Submit either ppan or creditc and expdat or account and bankcode or iban. Submit either ppan or creditc and expdat or account and bankcode or iban. Submit either ppan or creditc and expdat or account and bankcode or iban. Submit either ppan or creditc and expdat or account and bankcode or iban. If ppan was submitted in the request and the card number alias was created for a credit card. If ppan was submitted in the request and the card number alias was created for a credit card. If ppan was submitted in the request and the card holder was submitted when the card number alias was created. if ppan was submitted in the request and the card number alias was created for a bank account. if ppan was submitted in the request and the card number alias was created for a bank account. if ppan was submitted in the request and the card number alias was created for a bank account. If ppan was submitted in the request and the account holder was submitted when the card number alias was created. If creditc and expdat or account and bankcode were submitted in the request. Table 4-22: Getting Information about a Card Number Alias 4.9 Parameter overview The following chapters contain a detailed overview of the parameters used in the transaction details. The format of the parameter description is described in Section Parameter format description, p Obsolete parameters are indicated by an asterisk (*). These parameters are not relevant for the functionality of the shop interface. Version Date of issue: 26/11/

52 4.9 Parameter overview Parameters with special significance Shopping basket number You can transfer the shopping basket number to the Sparkassen-Internetkasse service in your requests as the optional parameter basketnr. Forwarding the shopping basket number is the best reference between the payment procedure in the shop, the credit note on the trader account and the debit of the customer account. It makes it easier for you to assign return debits and process customer queries about their postings. The shopping basket number is, unless otherwise agreed, forwarded and included on your customers' account statements and your credit card statement. In the case of direct debits, the shopping basket is displayed on your account statement, if the transfer of individual credit notes was agreed. If you want individual credit notes to be displayed on your account statement please arrange for it with the responsible licensee. The following formats apply for the basketnr parameter for forwarding the shopping basket number in credit card transactions: Credit card processor Format American Express ANL B+S Card Service AN-30 my123ref Elavon AN-30 my123ref ConCardis AN-30 my123ref Lufthansa AirPlus AN-30 my123ref P.O.S. Transact AN-30 my123ref Table 4-23: Format for the parameter basketnr for forwarding the shopping basket number - credit card For direct debits, up to 50 characters of the SEPA character set, i.e. letters (no umlauts and no ß), digits as well as ', :,?,,,., (, +,., ) and / are possible Parameter details acceptcountries A[,]-255 AT,DE,CH List of accepted issuing countries. Two letter country codes according to the current ISO 3166 standard (see ma/02iso-3166-code-lists/list-en1.html). Without this parameter all issuing countries are accepted. Table 4-24: Parameter acceptcountries Version Date of issue: 26/11/

53 4.9 Parameter overview account N The account number of the customer's bank account. Table 4-25: Parameter account accountholder ANL[+?/-:().,']-70 John Smith The account holder of the customer's bank account. Table 4-26: Parameter accountholder additionalnote ANLS-25 Overwrites the merchant identification on the customer's credit card statement. Can be used, for example, if a merchant offers products under several shop names to enable customers to attribute the payment to a purchase. Applicable only if your account is configured accordingly. Table 4-27: Parameter additionalnote aid ANL-32 a34232 Approval number of authorising party. Table 4-28: Parameter aid amount N The amount in the smallest unit of a currency. The value 5025 for the currency euro therefore corresponds to 50 euro and 25 cents. Exception: in the response of a follow-up transaction (capture, refund, reversal) where no amount was submitted in the request the amount is returned with a decimal comma, e.g. 50,25. Table 4-29: Parameter amount Version Date of issue: 26/11/

54 4.9 Parameter overview autocapture N-3 72 Period - in hours - between reservation und automatic capture. If the parameter is not sent, no automatic capture will be executed. Values may range from 0 to 168 hours, i.e. up to one week, for credit card payments and from 0 to 720 hours, i.e up to 30 days, for direct debit payments. Table 4-30: Parameter autocapture Caution In those rare cases where the "autocapture" is not successful (e.g. because the acquirer is unreachable) the automatic capture is not attempted a second time. In this case Sparkassen-Internetkasse sends an to the technical address configured in the front office to enable you to repeat failed captures manually if necessary. In the case that no technical address is configured for your shop we recommend to check the affected reservations at regular intervals. bankcode N Bank code of the customer's bank account. Table 4-31: Parameter bankcode basketnr ANLS , Flower Shop Shopping basket number. Field that can be freely defined by the trader and used to transfer additional information. This field can also be used to include information (e.g. the shop name) on the buyer's and trader's account and credit card statement (see Section Shopping basket number, p. 52). Table 4-32: Parameter basketnr bic AN11 VZVDDED1XXX BIC of a bank. Table 4-33: Parameter bic Version Date of issue: 26/11/

55 4.9 Parameter overview bic_obsolete AN11 BDFEFR2TXXX Previous BIC of the customer if the SEPA mandate is modified. Only in the case of recurring payments (sequencetype=recurring or sequencetype=final) with the first payment after the mandate changed. Is determined by Sparkassen-Internetkasse in the case of a German previous IBAN. in case of a previous IBAN (field iban_obsolete) from another country. Table 4-34: Parameter bic_obsolete cai * AN-15 se34322 Contract partner number assigned to the trader by the authorising party.this parameter is irrelevant for the functionality of the shop interface. Table 4-35: Parameter cai * cardholder ANLS-70 John Smith Credit card owner. Table 4-36: Parameter cardholder clientip N[.] Customer's IP address. Will be logged, does not have any other function. Table 4-37: Parameter clientip command FIX authorization Together with the parameter payment_options, describes the transaction type. Table 4-38: Parameter command Version Date of issue: 26/11/

56 4.9 Parameter overview creditc N Credit card number. The number has to be transferred without blanks. Table 4-39: Parameter creditc creditorid_obsolete AN18 DE98ZZZ Previous creditor ID if the SEPA mandate is modified. Only in the case of recurring payments (sequencetype=recurring or sequencetype=final) with the first payment after the mandate changed. Table 4-40: Parameter creditorid_obsolete currency A3 EUR The currency code as defined by ISO Always use EUR for direct debits. Table 4-41: Parameter currency customer_addr_city ANLS-30 Sheffield The town/city of a customer's address. Table 4-42: Parameter customer_addr_city customer_addr_number ANLS-8 8 The street number of a customer's address. Table 4-43: Parameter customer_addr_number Version Date of issue: 26/11/

57 4.9 Parameter overview customer_addr_street ANLS-30 High Street The street of a customer's address. Table 4-44: Parameter customer_addr_street customer_addr_zip N The postal code of a customer's address. Table 4-45: Parameter customer_addr_zip cvcode N Credit card verification number (CVC2-Code). Table 4-46: Parameter cvcode debitmode FIX sepacore Kind of direct debit. "sepacore" für SEPA Core direct debits. Without this parameter an SDD COR1 direct debit is carried out. Table 4-47: Parameter debitmode deliverycountry A2 / N1 DE Request: country of delivery. Two letter country code according to the current ISO 3166 standard (see Response: 0: match, 1: no match between country of delivery and issuing country of the credit card, 2: the check could not be performed. (The issuing country can only be determined for Visa and MasterCard.) Table 4-48: Parameter deliverycountry Version Date of issue: 26/11/

58 4.9 Parameter overview deliverycountryaction FIX notify Determines how to proceed if the country provided in deliverycountry does not match the issuing country of the credit card. 'notify': the shop will be informed in the shop notification. 'reject': payment with this credit card is rejected. If the parameter is not provided 'reject' is assumed. Table 4-49: Parameter deliverycountryaction duedate N Due date of a SEPA Core direct debit formatted YYYYMMDD. The due date has to be at least seven (four for the sequence types "Recurring payment" - sequencetype=recurring - or "Last payment" - sequencetype=final) TARGET2 business days (not on weekends or the so called TARGET2 or TARGET holidays) after the current date. Table 4-50: Parameter duedate expdat N The expiration date of the credit card in the format YYMM. The first two characters refer to the year of expiry for the card. The last two characters refer to the month of expiry. Table 4-51: Parameter expdat hotline ANLS Phone number of the merchant for enquiries concerning the payment. Applicable only if your account is configured accordingly and only together with the parameter seriesflag=recurring. Table 4-52: Parameter hotline iban AN22 DE IBAN of a bank account. Table 4-53: Parameter iban Version Date of issue: 26/11/

59 4.9 Parameter overview iban_obsolete AN22 DE Previous IBAN of the customer if the SEPA mandate is modified. Only in the case of recurring payments (sequencetype=recurring or sequencetype=final) with the first payment after the mandate changed. Table 4-54: Parameter iban_obsolete mandateid AN[+?/-:().,']-35 M /1-AB Mandate reference number. Unique identification of a SEPA direct debit mandate. A forward slash '/' is not allowed as the first or last character of the mandate reference number. Inside the mandate reference number two consecutive forward slashes are not allowed. Table 4-55: Parameter mandateid mandateid_obsolete AN[+?/-:().,']-35 M /1-AB Previous mandate reference number if the SEPA mandate is modified. Only in the case of recurring payments sequencetype=recurring or sequencetype=final) with the first payment after the mandate changed. A forward slash '/' is not allowed as the first or last character of the mandate reference number. Inside the mandate reference number two consecutive forward slashes are not allowed. Table 4-56: Parameter mandateid_obsolete mandatename ANL[+?/-:().,']-70 Smith and Jones Name of the payment recipient as specified in the SEPA mandate. If not submitted the name configured in the standing data of your shop is used. Table 4-57: Parameter mandatename mandatesigned N Date, when the SEPA mandate was issued, formatted YYYYMMDD. Table 4-58: Parameter mandatesigned Version Date of issue: 26/11/

60 4.9 Parameter overview merch_name * ANLS-50 Wine Shop Trader name stored in the system.this parameter is irrelevant for the functionality of the shop interface. Table 4-59: Parameter merch_name * merch_street * ANLS-50 7, High Street Trader's street and house number stored in the system. This parameter is irrelevant for the functionality of the shop interface. Table 4-60: Parameter merch_street * merch_tid * AN Trader's terminal identification number.this parameter is irrelevant for the functionality of the shop interface. Table 4-61: Parameter merch_tid * merch_town * ANLS Siebendorf Trader's postcode and city stored in the system.this parameter is irrelevant for the functionality of the shop interface. Table 4-62: Parameter merch_town * merchantref AN-30 RH_6712 Transaction reference. Will be shown on the merchant's credit card statement. (If not submitted the shopping basket number will be shown there.) Table 4-63: Parameter merchantref Version Date of issue: 26/11/

61 4.9 Parameter overview orderid AN[-_/]-17 ans_ Unique transaction number that identifies the payment transaction for a shop. Table 4-64: Parameter orderid payment_options FIX creditcard Together with the parameter command, describes the transaction type. Table 4-65: Parameter payment_options pcode * N-2 00 Additional operation code of the VÖB-ZVD payment gateway. This parameter is irrelevant for the functionality of the shop interface. Table 4-66: Parameter pcode * poscc * N-2 07 Transaction code of the VÖB-ZVD payment gateway. This parameter is irrelevant for the functionality of the shop interface. Table 4-67: Parameter poscc * posem * AN Operation code for the current gateway. This parameter is irrelevant for the functionality of the shop interface. Table 4-68: Parameter posem * Version Date of issue: 26/11/

62 4.9 Parameter overview posh_version ANLS Version of the shop interface. Table 4-69: Parameter posh_version posherr N Primary return code of the system (messages of the Sparkassen-Internetkasse service). Table 4-70: Parameter posherr ppan ANLS-50 5b6fd81b60f88b52c99ca71df555c831 Card number alias for a credit card. Table 4-71: Parameter ppan rc N Secondary return code of the particular payment or scoring system. The actual contents are explained in the appendix. Table 4-72: Parameter rc rc_avsamex FIX 5F American Express response code of the address verification. "5F": numerical parts of the address and postcode are correct. "5N": neither address nor postcode are correct. "5A": numerical address parts are correct but not the postcode. "5Z": postcode is correct but not the address. "5U": unknown, address and postcode could not be checked. Table 4-73: Parameter rc_avsamex Version Date of issue: 26/11/

63 4.9 Parameter overview rc_score FIX Y Traffic light return code of an American Express address verification. Possible values are G - green, Y - yellow, R - red, U - unknown. G means numerical parts of the address and postcode are correct and corresponds to rc_avsamex=5f. Y means either numerical address parts or postcode are correct and corresponds to rc_avsamex=5a or rc_avsamex=5z. R means neither numerical address parts nor postcode are correct and corresponds to rc_avsamex=5n. U means the address could not be checked and corresponds to rc_avsamex=5u. Table 4-74: Parameter rc_score rejectcountries A[,]-255 AT,DE,CH List of card issuing countries that will be rejected. Two letter country codes according to the current ISO 3166 standard (see If not provided, all issuing countries will be accepted. Table 4-75: Parameter rejectcountries retrefnr ANLS Transaction number of authorising party. Table 4-76: Parameter retrefnr rmsg ANLS-200 Transaction approved. Result as text. Table 4-77: Parameter rmsg sequencetype FIX first Sequence type of a SEPA direct debit. If not submitted a single payment is assumed. "oneoff": single payment, "first": first payment of a sequence, "recurring": follow-up payment, "final": last payment of a sequence. Table 4-78: Parameter sequencetype Version Date of issue: 26/11/

64 4.9 Parameter overview seriesflag FIX recurring Send the parameter seriesflag=recurring if this is a follow-up transaction of a recurring payment. Recurring payments are, for example, subscriptions or rental fees which are widely used in various business areas. As a merchant who offers recurring payments you have to inform the card holder explicitly that a recurring payment will be carried out and that you will initiate follow-up transactions. This requires you to obtain the explicit consent of the card holder - comparable to the acceptance of your general terms and conditions by activating a field in your shop. Note: If you are not sure whether you may generate recurring payments, please ask your contractual partner for credit card acceptance. An additional agreement may be required. Table 4-79: Parameter seriesflag timestamp N Timestamp of the transaction in the format YYYYMMDDHHMMSS (CET). Table 4-80: Parameter timestamp trefnum AN[-_/]-20 ans_834732_01 Sparkassen-Internetkasse transaction reference number. This number is used as a reference for transactions that are a follow-up of previous transactions (for example, a capture following a reservation). Table 4-81: Parameter trefnum txn_card ANLS-40 VISA Credit card brand name. Table 4-82: Parameter txn_card txn_date NS10 27/09/2006 Date part of the timestamp in the format dd/mm/yyyy. Table 4-83: Parameter txn_date Version Date of issue: 26/11/

65 4.10 s txn_expdat AS7 12/2009 Credit card expiration date in the format MM/YYYY. Table 4-84: Parameter txn_expdat txn_time NS5 23:50 Time part of the timestamp in the format HH:MM. Table 4-85: Parameter txn_time txntype ANLS-50 Reservierung/Pre-Authorization The transaction type as a word. Table 4-86: Parameter txntype 4.10 s transaction The following table contains an example transaction. It shows the message sent to Sparkassen-Internetkasse and the response returned. 1 Parameter Request Response command preauthorization X payment_options creditcard X orderid Zy_ Zy_ basketnr AB04198 AB04198 amount currency EUR EUR creditc expdat Fields that are not contained in the request or the response, are identified with the character 'X'. Version Date of issue: 26/11/

66 4.10 s Parameter Request Response cvcode posh_version X posherr X 0 rmsg X Genehmigt oder erfolgreich beendet. rc X 000 txn_date X 26/06/2003 txn_time X 16:52 merch_name X Testname merch_street X Test Street 9 merch_town X Testtown merch_tid X 06F pcode X 00 posem X 110 poscc X 12 aid X trefnum X Zy_ _01 retrefnr X txntype X Reservierung/Pre-Authorization timestamp X cai X txn_card X VISA txn_expdat X 05/2006 Table 4-87: Reserve, credit card Sample code The following sample code in Java and PHP show how your shop connection via the shop interface works. Do not use this sample code into your software unchanged. They merely serve to illustrate the connection principle. Java Listing 4-1 import java.text.simpledateformat; import java.util.date; import java.util.stringtokenizer; import java.net.urldecoder; import org.apache.commons.httpclient.httpclient; import org.apache.commons.httpclient.httpexception; Version Date of issue: 26/11/

67 4.10 s import org.apache.commons.httpclient.namevaluepair; import org.apache.commons.httpclient.usernamepasswordcredentials; import org.apache.commons.httpclient.methods.postmethod; /** * SendRequest.java - NOT FOR PRODUCTION USE! * uses Jakarta Commons Http Client, version * (see * Jakarta Commons Logging required at runtime * (see * JSSE required for Java older than 1.4 for HTTPS support * (see */ public class SendRequest { private static final String USERID = "tobechanged"; private static final String PASSWD = "tobechanged"; private static final String SERVER = "testsystem.sparkasseninternetkasse.de"; private static final String URL = " + SERVER + "/request/request/prot/request.po"; private static final int connectiontimeout = 10000; // milliseconds private static final int sockettimeout = 60000; // milliseconds public static void main(string[] args) { SendRequest req = new SendRequest(); req.start(); private void start() { try { NameValuePair[] data = { new NameValuePair("command", "preauthorization"), new NameValuePair("payment_options", "creditcard"), new NameValuePair("currency", "EUR"), new NameValuePair("amount", "1000"), new NameValuePair("creditc", " "), new NameValuePair("expdat", "0812"), new NameValuePair("orderid", getorderid()) ; PostMethod req = new PostMethod(URL); req.setrequestbody(data); HttpClient client = new HttpClient(); client.setconnectiontimeout(connectiontimeout); client.settimeout(sockettimeout); // prepare http basic authentication client.getstate().setcredentials(null, SERVER, new UsernamePasswordCredentials(USERID, PASSWD)); client.getstate().setauthenticationpreemptive(true); int statuscode = client.executemethod(req); System.out.println("HTTP STATUS CODE: " + statuscode); String res = req.getresponsebodyasstring(); System.out.println("PLAIN RESPONSE: " + res); StringTokenizer tokenizer = new StringTokenizer(res, "&"); String decoded; while (tokenizer.hasmoretokens()) { decoded = URLDecoder.decode(tokenizer.nextToken(), Version Date of issue: 26/11/

68 4.10 s "UTF-8"); System.out.println(decoded); catch (Exception e) { e.printstacktrace(); PHP // create a unique orderid private String getorderid() { // created a pseudo-id SimpleDateFormat formatter = new SimpleDateFormat("yyMMddHHmmssS"); return formatter.format(new Date()); Listing 4-2 <?php // see for details on CURL // execute on command line $userid="tobechanged"; $passwd="tobechanged"; // dummy orderid $timestamp=date("ymdhis"); $orderid=$timestamp; $request="orderid=$orderid&command=preauthorization". "&amount=2000&account= &bankcode= ". "&accountholder=peter+smith&currency=eur&". "payment_options=elv"; $url=" "/request/request/prot/request.po"; $ch=curl_init(); curl_setopt ($ch, CURLOPT_URL, $url); // no header in output curl_setopt ($ch, CURLOPT_HEADER, 0); // return reponse as result curl_setopt ($ch, CURLOPT_RETURNTRANSFER, 1); // do a POST-Request curl_setopt ($ch, CURLOPT_POST, 1); curl_setopt ($ch, CURLOPT_TIMEOUT, 60); curl_setopt ($ch, CURLOPT_USERPWD, "$userid:$passwd"); curl_setopt ($ch, CURLOPT_POSTFIELDS, $request); $result = curl_exec ($ch); curl_close ($ch); echo "Plain request: ". $request echo "Plain result : ". $result. "\n";. "\n"; $keys = explode('&', $result); Version Date of issue: 26/11/

69 4.11 Frequently asked questions (FAQ) sort ($keys); $i=0; while ($i < count($keys)) { $pair = split('=', $keys[$i]); echo htmlspecialchars(urldecode($pair[0])), '=[', htmlspecialchars(urldecode($pair[1])), "]\n"; $i++;?> 4.11 Frequently asked questions (FAQ) Q: What timeout should be set on the HTTP(S) client? A: Generally, you receive a response to your HTTPS request to the Sparkassen- Internetkasse service within a few seconds. However, with some credit card transactions, there may be problems connecting to the credit card processors' systems. The payment gateway of the Sparkassen-Internetkasse service returns a response within 55 seconds at the latest, even if a response has not been received from the credit card processor by then. Taking account of the processing time in the Sparkassen-Internetkasse service and the runtime of request and response, we recommend that you set the timeout on your HTTP(S) client to 60 seconds. Q: What does the error message "Transaction number message already assigned" mean? A: You application must generate unique transaction numbers. If it does not, you receive this error message in the response (parameter posherr has the value "108"). This also applies for the tests in the test system during the connection phase. You can use sequential transaction numbers or the date and time, for example, to generate unique transaction numbers. The test system and the live system have different sets of transaction numbers. When you change from the test system to the live system, you can reuse the transaction numbers from the test system. Q: Which currencies are configured as standard? A: The euro, US dollar, British pound, Swiss frank, Danish, Swedish and Norwegian crown, Canadian dollar and South African rand are the default currencies for credit card transactions, and the euro only for direct debits. Enter the currency in the parameter currency (e.g. EUR or USD). Q: Why do I get response codes that are amount dependent in the test system? A: In the test system, the cents of the specified amount are included as a response code for credit card transactions. The advantage of this is that it enables you to generate and test all response codes easily. Version Date of issue: 26/11/

70 4.11 Frequently asked questions (FAQ) An amount of 1,23 EUR (parameter amount has the value "123") leads to a response code (parameter rc) of "023". Therefore, for credit card transactions in the test system, only use whole euro or US dollar amounts (parameter amount is a multiple of 100) if you want to complete a successful credit card payment. Q: Why do I get an HTTP response with the status code 401 (unauthorised)? A: There are three possible reasons: You are not carrying out HTTP basic authentication, or HTTP basic authentication contains errors. In your application, check whether the login and password were transferred correctly. Your login and/or password are incorrect. In the trader interface, check your login for the shop interface. Try to change your password for the shop interface. (You can enter your current password as the new password.) If you enter your current password incorrectly, an error message is displayed. If you have forgotten your password for the shop interface, contact the support team. The support team will provide you with a new password. Your access to the Sparkassen-Internetkasse service is locked for security reasons if you enter an incorrect password for your login three times. This applies for attempted logins to the trader interface and for authentication of the shop interface. Contact the support team to unlock your access. Q: Which parameters must I store for post-processing transactions? A: You need the parameter trefnum in order to post-process payments (reversal, refund, etc.) in the application. This is contained in the Sparkassen-Internetkasse service response message. The other required parameters, namely transaction number and possibly also amount and currency, were generated in your application and should be stored in any case for processing your business processes. Q: Which response code do I have to evaluate, posherr or rc? A: The parameter posherr contains the primary response code of the Sparkassen- Internetkasse service. posherr is "0" for successful transactions. All other values for posherrmean that the transaction failed. Thus an evaluation of the parameter posherr is sufficient to determine whether the transaction was successful. The parameter rc contains the secondary response code of the payment gateway. The Sparkassen-Internetkasse server recognises many errors. posherr then contains the response code for the particular error. In this case, rc is empty because the transaction is not routed to the payment gateway. If the check in the Sparkassen-Internetkasse server does not result in any errors, the transaction is sent on to the payment gateway. If an error occurs now, posherr contains the value "100" and rc contains the response code of the payment gateway. Version Date of issue: 26/11/

71 4.11 Frequently asked questions (FAQ) If you evaluate both posherr and rc, you can display specific error messages for your customers. For example, if the bank code is missing, you could ask your customer to enter all the required data and try again. If a credit card is locked, you could display a different error message, because a second attempt would not be successful. Version Date of issue: 26/11/

72 5.1 Introduction 5 Form service / 3D-Secure 5.1 Introduction With the form service, Sparkassen-Internetkasse allows your shop to provide customers with encrypted transmission of payment data without its own SSL certificate. Payments are processed completely in the Sparkassen-Internetkasse service, from payment data entry through to the display of the payment result. Customer and online shop are informed of the result of a payment. You can choose between forms for standard web browsers and forms designed for the Apple iphone and other smartphones with a WebKit based browser. Figure 5-1: Form service on the Apple iphone Shop customer requirements The bank must have registered and released credit card holders for Verified by Visa or MasterCard SecureCode for 3D-Secure payments. The customer's browser must have activated JavaScript support. JavaScript is required to transfer the customer between shop, CCS and Access Control Server (ACS). Payments without 3D-Secure simply require a valid credit card or bank account. Version Date of issue: 26/11/

73 5.2 Function description 5.2 Function description Payments with 3D-Secure The following is an example of how the data transfer of a successful transaction works: 7 5 Customer Browser Shop Access Control Server (ACS) 6 VISA Directory 4 Credit Card Security Cartridge (CCS) Payment Backend 8 Figure 5-2: Sample payment transaction 1. Having filled his/her shopping basket, the online shop customer proceeds to the checkout and selects the payment type "Verified by Visa" or "Master- Card SecureCode". 2. The shop redirects the browser of the shop customer to the CCS, which displays the form for entering credit card data. 3. The shop customer enters the credit card data in the form and sends it off. If the customer clicks the "Cancel" button payment is aborted and the CCS notifies the shop with an error message. 4. The CCS establishes the Access Control Server (ACS) valid for the credit card number. 5. The CCS routes the browser of the shop customer to the relevant ACS. 6. The shop customer authorises payment at the ACS in a pop-up window (by entering a password, PIN or TAN). 7. The ACS initials payment authorisation and the CCS stores the initialled payment authorisation. 8. The CCS reroutes the payment request to the payment backend of the Sparkassen-Internetkasse service and notifies the shop of the transaction result Payments without 3D-Secure A simplified transaction procedure applies to direct debits and credit card payments without 3D-Secure. It consists of steps 1 to 3 and step 8 of the 3D- Secure payment procedure described above. Version Date of issue: 26/11/

74 5.3 Card number aliases Maestro payments You can also carry out Maestro payments with the form service. Maestro payments are always carried out according to the 3D-Secure protocol. Note Maestro payments require a separate contract with B+S Card Service. 5.3 Card number aliases If your account is configured to use card number aliases for credit cards or bank accounts you can tell Sparkassen-Internetkasse that you want to create a card number alias for the customer's credit card or bank account by submitting the payment_options=generate_ppan parameter. In the response you will receive a card number alias that has been generated by Sparkassen-Internetkasse. Alternatively, you can submit your own card number alias in the ppan field. With the card number alias you can carry out more transactions with this credit card or bank account in the form service, the front office or via the shop interface. As an alternative you can use the form service to register card number aliases without a payment. To do that you can either proceed as described in Section Request message - registering a card number alias, p. 90. In this case the card number alias is merely registered. No online verification of the credit card or bank account is carried out and the course of transaction corresponds to that of payments without 3D-Secure. Instead of this, you can carry out a reservation (transactiontype=preauthorization) without amount or with amount=0 to register the card number alias (see Section Request message - payments, p. 75). By submitting the parameter payment_options=generate_ppan_verify_online you can tell Sparkassen-Internetkasse that you are carrying out a registration causing Sparkassen-Internetkasse to show the form for entering the credit card or bank account data with text suitable for a registration transaction. 5.4 Access data Your contractual partner will provide the access data for live access. The test system can be accessed at the following URL: Test access: Productive access: Send requests to the Sparkassen-Internetkasse service using the CGI parameters described in the following section only. Version Date of issue: 26/11/

75 5.5 Transaction details 5.5 Transaction details The following sections contain details on payment initialisation and how the Sparkassen-Internetkasse service notifies the shop Request message - payments The parameters listed in the following tables are sent to the Sparkassen-Internetkasse server via the customer's browser by means of a redirect. The shop thus reacts to a browser action with a response that routes the customer to the Sparkassen-Internetkasse server. This can be done by means of an HTTP redirect header, an HTML page with a meta tag, or a JavaScript form. An example for implementation using a meta tag can be found in Section, p. 90. You will find explanations of the range of values information used in the following tables in Section Parameter format description, p The appendix in Section MAC - Message Authentication Code, p. 130 contains more details on the mac parameter. Please read Section Shopping basket number, p. 52 to learn more about the shopping basket number (parameter basketid). The optional parameters acceptcountries, deliverycountry and rejectcountries require to check the issuing country of a credit card. This check can currently be performed for Visa and MasterCard. If a customer pays with a card from a different brand, the issuing country is not checked and the payment will not be rejected because of the issuing country of the credit card. If a credit card is rejected because of its issuing country the form for entering the credit card data will be shown again to the customer with an error message. You can provide the text for this message in the request message (see Section Parameter overview Request Message, p. 76) or have the CCS display the standard message for this error. In the case of a direct debit payment the optional parameters customer_... are used to generate a PDF file with a SEPA direct debit mandate if payment_options includes the value sepa_pdf_mandate. The submitted values are used to preset the input fields and can be changed by the customer on the form service pages. If these fields are not submitted the input fields are empty and have to be filled in by the customer. In the case of credit card payments the optional parameters customer_addr_... are used to validate the customer's address if payment is made with an American Express credit card. For other kinds of payment, the values of these parameters are not used. The address verification does not influence the result of the payment. Instead, the result of the address verification is returned in the field rc_avsamex and additionally as a traffic light value in the parameter rc_score. Occasionally the CCS might not receive an answer from the Directory Server because of connection problems. Due to the different regulations of Visa and MasterCard the CCS will proceed as follows in this case: For MasterCard the transaction is continued. Version Date of issue: 26/11/

76 5.5 Transaction details For a Visa card the transaction is stopped unless the payment_options parameter is set to "sslifnotenrolled" in the request message. In this case payment is continued as an SSL transaction without liability shifting. The transaction is also stopped - for Visa as well as for MasterCard - if the Directory Server answers the CCS that it could not determine if a credit card is enrolled for 3D Secure. Also in this case, if you submitted payment_options=sslifnotenrolled in the request message payment is continued as an SSL transaction without liability shifting Parameter overview Request Message The following tables show an overview of mandatory and optional parameters of the request message. For every parameter the tables show the allowed range of values, an example and an explanation. The explanation always contains information if it is a mandatory or an optional parameter. Note If you do not submit the optional parameter transactiontype (see below), a reservation is carried out.please note that you have to capture the reservation in a second step to receive the payment which leads to additional costs for this second transaction. acceptcountries A[,]-255 AT,DE,CH, for credit card payment; list of accepted issuing countries. Two letter country codes according to the current ISO 3166 standard (see Without this parameter all issuing countries are accepted. Table 5-1: Parameter acceptcountries additionalnote ANLS-25 Overwrites the merchant identification on the customer's credit card statement. Can be used, for example, if a merchant offers products under several shop names to enable customers to attribute the payment to a purchase. Applicable only if your account is configured accordingly. Table 5-2: Parameter additionalnote Version Date of issue: 26/11/

77 5.5 Transaction details amount N[,]-10 22,60, unless payment_options=generate_ppan_verify_online. Amount. Cent amounts are separated with a decimal comma. Even amounts can be submitted without decimal comma and cent amounts, e.g. 22 instead of 22,00 EUR. Amounts in currencies like JPY that do not have a smaller currency unit have to be submitted without decimal comma and without fractional digits. Table 5-3: Parameter amount autocapture N-3 72, for reservation only: period - in hours - between reservation and automatic capture. If omitted, no automatic capture will be executed. Value may range from 0 to 168 hours for credit card payments and from 0 to 720 hours for direct debit payments. Table 5-4: Parameter autocapture Caution In those rare cases where the "autocapture" is not successful (e.g. because the acquirer is unreachable) the automatic capture is not attempted a second time. In this case Sparkassen-Internetkasse sends an to the technical address configured in the front office to enable you to repeat failed captures manually if necessary. In the case that no technical address is configured for your shop we recommend to check the affected reservations at regular intervals. backendretrycount N-2 3. Specifies how often the customer can retry the payment if the payment fails and - possibly by using another credit card or bank account - a successful processing of the payment seems possible. Without this parameter no retry is allowed in this case. Errors that are discovered already during a basic validation of the input data, e.g. a missing card verification code or an expiry date in the past, are not affected by this rule. In these cases a retry is always possible. As long as a retry is allowed the form to enter the means of payment details is displayed again with an error message and the shop notification is not sent yet. Table 5-5: Parameter backendretrycount Version Date of issue: 26/11/

78 5.5 Transaction details basketid ANLS-50 ba_ ; identification of ordered shopping basket or article, can be shown on buyer's and merchant's account or credit card statement, see Section Shopping basket number, p. 52 Table 5-6: Parameter basketid bic_obsolete AN-11 BDFEFR2TXXX Previous BIC des Kunden in case of a change of the SEPA mandate. Only in the case of recurring payments (sequencetype=recurring or sequencetype=final) with the first payment after the change. Is determined by Sparkassen-Internetkasse in the case of a German previous IBAN. if a previous IBAN (field iban_obsolete) from another country is submitted. Table 5-7: Parameter bic_obsolete clientip N[.] ; IP address of the customer. Is used to check the IP address in case this check is carried out (see ipcheckaction). If clientip is not submitted Sparkassen-Internetkasse determines the IP address when the customer submits the form with the payment data. Table 5-8: Parameter clientip command FIX sslform field; request definition Table 5-9: Parameter command countryrejectmessage ANL-255 Please choose another credit card, only in combiantion with acceptcountries or rejectcountries. Error message if a credit card is rejected because of its issuing coutnry. If not provided, the standard message for this error will be used. Table 5-10: Parameter countryrejectmessage Version Date of issue: 26/11/

79 5.5 Transaction details creditorid_obsolete AN18 DE98ZZZ Previous creditor ID if the creditor ID of your shop has changed. Only in the case of recurring payments (sequencetype=recurring or sequencetype=final) with the first payment after the creditor ID changed. Table 5-11: Parameter creditorid_obsolete cssurl ANS URL of the cascading style sheet (CSS), the form will be displayed with. If the parameter is not submitted the URL that is configured in the front office will be used. Table 5-12: Parameter cssurl currency A3 EUR field; currency code as defined by ISO Always use EUR for direct debits. Table 5-13: Parameter currency customer_addr_city ANLS-80 Leeds ; town/city of a customer's address. For address verification of payments with American Express credit cards and to create a PDF file with a SEPA mandate. Table 5-14: Parameter customer_addr_city customer_addr_country [A-Z]2 DE ; country code of a customer's address according to ISO To create a PDF file with a SEPA mandate. Table 5-15: Parameter customer_addr_country Version Date of issue: 26/11/

80 5.5 Transaction details customer_addr_number ANLS-32 98A ; street number of a customer's address. For address verification of payments with American Express credit cards and to create a PDF file with a SEPA mandate. Table 5-16: Parameter customer_addr_number customer_addr_street ANLS-80 High Street ; street of a customer's address. For address verification of payments with American Express credit cards and to create a PDF file with a SEPA mandate. Table 5-17: Parameter customer_addr_street customer_addr_zip ANL ; postal code of a customer's address. For address verification of payments with American Express credit cards and to create a PDF file with a SEPA mandate. Table 5-18: Parameter customer_addr_zip customer_firstname ANL-24 John ; the customer's first name. To create a PDF file with a SEPA mandate. Table 5-19: Parameter customer_firstname customer_lastname ANL-30 Smith ; the customer's surname. To create a PDF file with a SEPA mandate. Table 5-20: Parameter customer_lastname Version Date of issue: 26/11/

81 5.5 Transaction details date N[_:] _12:23:45, current date and time in YYYYMMDD_HH:mm:ss format Table 5-21: Parameter date debitmode FIX sepacore. Kind of direct debit. "sepacore" für SEPA Core direct debits. Without this parameter an SDD COR1 direct debit is carried out. Table 5-22: Parameter debitmode deliverycountry A2 DE. Country of delivery. Two letter country code according to ISO If this country does not match the issuing country of the credit card the payment will be rejected or the shop will be informed about the mismatch (see deliverycountryaction). Table 5-23: Parameter deliverycountry deliverycountryaction FIX notify. Determines how to proceed if the country provided in deliverycountry does not match the issuing country of the credit card. Possible values: "notify": the shop will be informed in the shop notification "reject": payment with this credit card is rejected If the parameter is not provided "reject" is assumed. Table 5-24: Parameter deliverycountryaction deliverycountryrejectmessage ANL-255 Please choose another credit card. Error message if the credit card is rejected because the issuing country of the credit card does not match the country submitted in deliverycountry. If not provided the standard message for this error will be used. Table 5-25: Parameter deliverycountryrejectmessage Version Date of issue: 26/11/

82 5.5 Transaction details duedate N Due date of a SEPA Core direct debit formatted YYYYMMDD. The due date has to be at least seven (four for the sequence types "Recurring payment" - sequenc etype=recurring - or "Last payment" - sequencetype=final) TARGET2 business days (not on weekends or the so called TARGET2 or TARGET holidays) after the current date. Table 5-26: Parameter duedate form_label_cancel AL-30 Back. Text of the cancel button. If not submitted, the standard text will be displayed. Make sure the submitted text is appropriate for the language of the form (see locale parameter). Table 5-27: Parameter form_label_cancel form_label_submit AL-30 Pay. Text of the submit button. If not submitted, the standard text will be displayed. Make sure the submitted text is appropriate for the language of the form (see locale parameter). Table 5-28: Parameter form_label_submit form_merchantname ANL-32 Smith and Jones. Merchant name to be displayed in the form. If empty, no merchant name will be displayed. If this parameter is omitted the merchant name configured in Sparkassen-Internetkasse is displayed. Table 5-29: Parameter form_merchantname iban_obsolete AN-34 DE Previous IBAN of the customer in case of a change of the SEPA mandate. Only in the case of recurring payments (sequencetype=recurring or sequencetype=final) with the first payment after the change. Table 5-30: Parameter iban_obsolete Version Date of issue: 26/11/

83 5.5 Transaction details ipcheckacceptcountries A[,]-255 AT,DE,CH ; List of accepted countries for the customer's IP address. Two letter country codes according to the current ISO 3166 standard ISO 3166 (see An empty list means no restriction of the country of the IP address. The IP address is only checked if the ipcheckaction parameter was also submitted. Table 5-31: Parameter ipcheckacceptcountries ipcheckaction FIX notify. Determines how to proceed if the country of the customer's IP address is rejected because of the values in ipcheckacceptcountries and ipcheckrejectcountries. Possible values: "notify": the shop will be informed in the shop notification "reject": payment is rejected If this parameter is not submitted the IP address will not be checked. Table 5-32: Parameter ipcheckaction ipcheckmode FIX sloppy. Sometimes only a region, e.g. "EU" or "Asia/Pacific" can be determined from the IP address. In "sloppy" mode the values in ipcheckacceptcountries or ipcheckrejectcountries match if one of the countries lies within this region. In "strict" mode there would be no match in this case. Possible values: strict sloppy If the parameter is not provided "strict" is assumed. Table 5-33: Parameter ipcheckmode ipcheckrejectcountries A[,]-255 AT,DE,CH ; List of ountries that are not accepted for the customer's IP address. Two letter country codes according to the current ISO 3166 standard ISO 3166 (see An empty list means no restriction of the country of the IP address. The IP address is only checked if the ipcheckaction parameter was also submitted. Table 5-34: Parameter ipcheckrejectcountries Version Date of issue: 26/11/

84 5.5 Transaction details ipcheckrejectmessage ANL-255 payment rejected., only together with ipcheckaction and ipcheckacceptcountries or ipcheckrejectcountries. Error message if payment is rejected because of the customer's IP address. If not provided the standard message for this error will be used. Table 5-35: Parameter ipcheckrejectmessage locale FIX en. Language of the form to be displayed. "de" - German, "en" - English, "es" - Spanish, "fr" - French, "it" - Italian, "pt" - Portuguese, "nl" - Dutch, "cs" - Czech, "sv" - Swedish, "da" - Danish. If not submitted, the German form will be displayed. Additional "locales" with modified text exist for donations: "spde" (donation, German) and "spen" (donation, English). Table 5-36: Parameter locale mac N[abcdef]40 0fab98c2d51992adff4732e2c5ab8599f15723e3 field; Message Authentication Code; used to safeguard against payment data manipulation, see Section MAC - Message Authentication Code, p. 130 Table 5-37: Parameter mac mandateid AN[+?/-:().,']-35 M /1-AB for SEPA direct debits. Mandate reference number. Unique identification of a SEPA direct debit mandate. A forward slash '/' is not allowed as the first or last character of the mandate reference number. Inside the mandate reference number two consecutive forward slashes are not allowed. Table 5-38: Parameter mandateid Version Date of issue: 26/11/

85 5.5 Transaction details mandateid_obsolete AN[+?/-:().,']-35 M /1-AB Previous mandate reference number if the SEPA mandate changes. Only in the case of recurring payments (sequencetype=recurring or sequencetype=final) with the first payment after the change. A forward slash '/' is not allowed as the first or last character of the mandate reference number. Inside the mandate reference number two consecutive forward slashes are not allowed. Table 5-39: Parameter mandateid_obsolete mandatename ANL[+?/-:().,']-70 Smith and Jones for SEPA direct debits. Name of the payment recipient as specified in the SEPA mandate. If not submitted the name configured in the standing data of your shop is used. Table 5-40: Parameter mandatename mandatesigned N for SEPA direct debits. Date, when the SEPA mandate was issued, formatted YYYYMMDD. Table 5-41: Parameter mandatesigned merchantref ANS-30 RH_6712, only for credit card payments. Transaction reference that will be shown on the merchant's credit card statement in place of the shopping basket number. Table 5-42: Parameter merchantref notificationfailedurl ANS If the shop cannot be informed about the outcome of the payment, a result page with a link to this URL is displayed to the customer. Table 5-43: Parameter notificationfailedurl Version Date of issue: 26/11/

86 5.5 Transaction details notifyurl ANS URL where the shop notification will be sent to. If the parameter is not submitted the URL that is configured in the front office will be used. Table 5-44: Parameter notifyurl orderid AN[-_/]-17 order_ field; transaction number Table 5-45: Parameter orderid Version Date of issue: 26/11/

87 5.5 Transaction details payment_options FIX sslifnotenrolled. If your account is configured to use card number aliases: "generate_ppan": specifies that a card number alias shall be created for the customer's credit card or bank account. "generate_ppan_verify_online": specifies that the transaction is a registration of a card number alias and not a payment. The text in the form is displayed as is appropriate for a registration, the amount is not displayed. Can be used only together with transactiontype=preauthorizationor without the transactiontype parameter and only with an amount of not more than 1 EUR or 1 of another currency respectively. For credit card transactions: "cardholder" states that the form that is shown to the customer contains a mandatory field for entering the credit card owner. "optionalcardholder" means that the form includes a field for the card owner but the customer is not required to enter anything Without this parameter the form will not include an input field for the credit card owner. "sslifnotenrolled" specifies that an SSL transaction without liability shifting is carried out in case of a Visa card if Sparkassen-Internetkasse does not receive an answer from the Visa Directory or if the Visa or MasterCard Directory could not determine if the credit card is enrolled for 3D Secure. If not submitted, the transaction will be aborted under these circumstances. "amexavs": if the customer pays with an American Express card he is asked for his address and an American Express address verification is carried out. The result of the address verification is returned in the shop notification in the fields rc_avsamex and rc_score. For direct debits: "accountholder" states that the direct debit form that is shown to the customer contains a mandatory field for entering the account holder. "optionalaccountholder" means that the direct debit form contains a field for the account holder but the customer is not required to enter anything Without this parameter the direct debit form merely contains input fields for account number and bank code. "checklist": before the direct debit a blacklist is checked. Only available if this option has been activated for your account. If the form is displayed in German, a sentence is displayed that the customer consents that payment data is submitted to InterCard. "sepa_pdf_mandate" specifies that a PDF file with a SEPA direct debit mandate should be created in the form service. This requires additional information which the customer has to enter in the course of the form service dialogue. If you want to submit more than one payment option, use a semicolon to separate the individual values, e.g. "amexavs;cardholder" Table 5-46: Parameter payment_options Version Date of issue: 26/11/

88 5.5 Transaction details paymentmethod FIX creditcard field, payment type, "creditcard", "maestro" or "directdebit". Credit card transactions are carried out as 3D-Secure payments if your account is configured accordingly. Otherwise the transaction is performed without 3D-Secure. Table 5-47: Parameter paymentmethod ppan ANLS-50 5b6fd81b60f88b52c99ca71df555c831. Card number alias for a credit card or bank account. In combination with payment_options=generate_ppan or payment_options=generate_ppan_verify_online this value will be used for the new card number alias that is being created. If not submitted, Sparkassen-Internetkasse will generate a card number alias in this case and send it to you in the shop notification. Otherwise Sparkassen-Internetkasse will find the details of the credit card or bank account corresponding to this card number alias and display these in the payment form. In this case, the only remaining input field the customer has to fill in is the card number verification code in the case of a credit card payment. Table 5-48: Parameter ppan rejectcountries A[,]-255 AT,DE,CH, for credit card payment; list of card issuing countries that will be rejected. Two letter country codes according to ISO If not provided, all issuing countries will be accepted. Table 5-49: Parameter rejectcountries sequencetype FIX first. Sequence type of a SEPA direct debit. If not submitted a single payment is assumed. "oneoff": single payment, "first": first payment of a sequence, "recurring": follow-up payment, "final": last payment of a sequence. Table 5-50: Parameter sequencetype Version Date of issue: 26/11/

89 5.5 Transaction details seriesflag FIX recurring. Send the parameter seriesflag=recurring if this is a follow-up transaction of a recurring payment. Recurring payments are, for example, subscriptions or rental fees which are widely used in various business areas. As a merchant who offers recurring payments you have to inform the card holder explicitly that a recurring payment will be carried out and that you will initiate follow-up transactions. This requires you to obtain the explicit consent of the card holder - comparable to the acceptance of your general terms and conditions by activating a field in your shop. Note: If you are not sure whether you may generate recurring payments, please ask your contractual partner for credit card acceptance. An additional agreement may be required. Table 5-51: Parameter seriesflag sessionid ANSL-255 Nhdz747458sNX ; identification of current session in online shop, used for notifying the shop Table 5-52: Parameter sessionid sslmerchant AN[-_.]-16 mycompanyssl field; trader identification Table 5-53: Parameter sslmerchant transactiontype FIX authorization, if not set: "preauthorization"; transaction type. Reserve ("preauthorization") or reserve/capture ("authorization"), see Section Reserve, p. 19 and Section Reserve/capture, p. 19 Table 5-54: Parameter transactiontype Version Date of issue: 26/11/

90 5.5 Transaction details version FIX 1.8 Form service version. "1.8" for standard web browsers, "1.8m" to display forms designed for smartphones and similar mobile devices. Table 5-55: Parameter version This example shows how your shop can redirect the customer to the Sparkassen-Internetkasse server. The request message is contained in the meta tag. Listing 5-1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> <html> <head> <meta http-equiv="refresh" content="0; URL= amount=1,00&basketid=b &command=sslform&currency=eur&date= _15:40:39&orderid=o &paymentmethod=creditcard&sessioni d=s &sslmerchant=tobechanged&transactiontype=authorization&vers ion=1.8&mac=0fab98c2d51992adff4732e2c5ab8599f15723e3"> </head> <body></body> </html> Note Don't copy the URL contained in this example to the adress bar of your browser to call Sparkassen-Internetkasse. You would merely receive an error message Reaction of the Sparkassen-Internetkasse server As a response to this request transmitted by redirect, Sparkassen-Internetkasse displays a form in which the customer must enter the data for payment. After the data is submitted, the payment is processed (steps 4 to 8 in Section Payments with 3D-Secure, p. 73). If the customer clicks the "Cancel" button in this form payment is aborted and Sparkassen-Internetkasse informs the shop with an error message Request message - registering a card number alias Registering a card number alias follows the same course of transaction as a payment without 3D-Secure. However fewer parameters are required in the request message: Version Date of issue: 26/11/

91 5.5 Transaction details command FIX sslform field; request definition Table 5-56: Parameter command cssurl ANS URL of the cascading style sheet (CSS), the form will be displayed with. If the parameter is not submitted the URL that is configured in the front office will be used. Table 5-57: Parameter cssurl form_label_cancel AL-30 Back. Text of the cancel button. If not submitted, the standard text will be displayed. Make sure the submitted text is appropriate for the language of the form (see locale parameter). Table 5-58: Parameter form_label_cancel form_label_submit AL-30 Pay. Text of the submit button. If not submitted, the standard text will be displayed. Make sure the submitted text is appropriate for the language of the form (see locale parameter). Table 5-59: Parameter form_label_submit form_merchantname ANL-32 Smith and Jones. Merchant name to be displayed in the form. If empty, no merchant name will be displayed. If this parameter is omitted the merchant name configured in Sparkassen-Internetkasse is displayed. Table 5-60: Parameter form_merchantname Version Date of issue: 26/11/

92 5.5 Transaction details locale FIX en. Language of the form to be displayed. "de" - German, "en" - English or "sv" - Swedish. If not submitted, the German form will be displayed. Table 5-61: Parameter locale mac N[abcdef]40 0fab98c2d51992adff4732e2c5ab8599f15723e3 field; Message Authentication Code; used to safeguard against data manipulation, see Section MAC - Message Authentication Code, p. 130 Table 5-62: Parameter mac notificationfailedurl ANS If the shop cannot be informed about the outcome of the payment, a result page with a link to this URL is displayed to the customer. Table 5-63: Parameter notificationfailedurl notifyurl ANS URL where the shop notification will be sent to. If the parameter is not submitted the URL that is configured in the front office will be used. Table 5-64: Parameter notifyurl Version Date of issue: 26/11/

93 5.5 Transaction details payment_options FIX cardholder. "cardholder" states that the form that is shown to the customer contains a mandatory field for entering the credit card owner. "optionalcardholder" means that the form includes a field for the card owner but the customer is not required to enter anything Without this parameter the form will not include an input field for the credit card owner. "accountholder" states that the form that is shown to the customer contains a mandatory field for entering the owner of the bank account. "optionalaccountholder" means that the form includes a field for the owner of the bank account but the customer is not required to enter anything Without this parameter the form will not include an input field for the owner of the bank account. Table 5-65: Parameter payment_options paymentmethod FIX registerpan field. The value is "registerpan" to register a card number alias for a credit card or "registeraccount" to register a card number alias for a bank account. Table 5-66: Parameter paymentmethod ppan ANLS-50 5b6fd81b60f88b52c99ca71df555c831. Card number alias. If not submitted, Sparkassen-Internetkasse will generate a card number alias and send it to you in the shop notification. Table 5-67: Parameter ppan sessionid ANSL-255 Nhdz747458sNX ; identification of current session in online shop, used for notifying the shop Table 5-68: Parameter sessionid Version Date of issue: 26/11/

94 5.5 Transaction details sslmerchant ANS-16 mycompanyssl field; trader identification Table 5-69: Parameter sslmerchant version FIX 1.8 Form service version. "1.8" for standard web browsers, "1.8m" to display forms designed for smartphones and similar mobile devices. Table 5-70: Parameter version Shop notification After a payment has been processed, the shop is informed of the result (step 8 in Section Payments with 3D-Secure, p. 73). The parameters listed in the following table are transferred to the URL submitted in the notifyurl parameter in the initial request. Without this parameter the notification is sent to the URL configured in the front office. Important For security reasons it is mandatory to evaluate the shop notification. In particular, you can only determine from the shop notification if the customer's payment was succesful or not. Note For an SSL encrypted shop notification you need an SSL certificate issued by an accepted certificate authority for the server you specified in the URL for shop notification. Certificates you generated yourself are not accepted. You will not receive a shop notification if your SSL certificate is not accepted by the Sparkassen-Internetkasse server. You will also not receive a shop notification if the server name in the URL for shop notification does not match the server for which the SSL certificate was issued. This also applies if, for example, you enter the IP address instead of the server name in the URL for shop notification. Important If your shop notification is transferred SSL encrypted, please test if the shop notification still works when you exchange your SSL certificate. Please note that future versions of Sparkassen-Internetkasse can contain additional response parameters. Version Date of issue: 26/11/

95 5.5 Transaction details Parameter overview shop notification - payments The following tables show an overview of the shop notification parameters. Please note that not every response message contains all of these parameters and some parameters possibly contain no value. For example the aid parameter is empty if the transaction was not completed successfully and the basketid and sessionid parameters only contain values if you submitted these parameters in the request message. account N[*] **** Masked bank account number if the customer entered the account number during a direct debit payment. Table 5-71: Parameter account aid ANL-32 a34232 Approval number of authorising party Table 5-72: Parameter aid amount ANS-10 22,60 Amount. Cent amounts are separated with a decimal comma. Table 5-73: Parameter amount bankcode N Bank code. If the customer entered it during a direct debit payment. Table 5-74: Parameter bankcode basketid ANLS-50 ba_ Identification of ordered shopping basket or article Table 5-75: Parameter basketid Version Date of issue: 26/11/

96 5.5 Transaction details bic AN8-11 VZVDDED1XXX BIC of the customer's bank account in the case of a SEPA direct debit payment. Table 5-76: Parameter bic creditc N[*] ******1111 Masked credit card number. In the case of a credit card payment. Table 5-77: Parameter creditc currency A3 EUR The currency code as defined by ISO Table 5-78: Parameter currency deliverycountry FIX 0 If deliverycountry was provided and deliveryaction=notify in the request message. Possible values: "0" match "1" no match between country of delivery and issuing country of the credit card "2" the check could not be performed. (The issuing country can only be determined for Visa and MasterCard.) Table 5-79: Parameter deliverycountry directposerrorcode N-3 0 This parameter includes the primary return code of the system; for details, see Table 6-7, p. 126 Table 5-80: Parameter directposerrorcode Version Date of issue: 26/11/

97 5.5 Transaction details directposerrormessage ANSL-255 Genehmigung verweigert. Error message, if applicable Table 5-81: Parameter directposerrormessage expdat N The expiration date of the credit card in the format YYMM. The first two characters refer to the year of expiry for the card. The last two characters refer to the month of expiry. In the case of a credit card payment. Table 5-82: Parameter expdat iban AN-34 DE IBAN. In the case of a SEPA direct debit payment. Table 5-83: Parameter iban ipcheckresult FIX accepted If ipcheckaction=notify was submitted in the request message. Possible values: "accepted" "rejected" the country of the customer's IP address is not accepted "unknown" the IP address could not be checked Table 5-84: Parameter ipcheckresult mac N[abcdef]40 0fab98c2d51992adff4732e2c5ab8599f15723e3 Message Authentication Code, used to safeguard against shop notification manipulation (see Appendix, Section MAC - Message Authentication Code, p. 130) Table 5-85: Parameter mac Version Date of issue: 26/11/

98 5.5 Transaction details orderid AN[-_/]-17 order_ Transaction number Table 5-86: Parameter orderid ppan ANLS-50 5b6fd81b60f88b52c99ca71df555c831 Card number alias, if payment_options=generate_ppan or paymentmethod=generate_ppan_verify_online was submitted in the request. Table 5-87: Parameter ppan rc N This parameter includes the secondary return code of the payment system. Table 5-88: Parameter rc rc_avsamex FIX 5F Response code of an American Express address verification. "5F": both address and postcode are correct. "5N": neither address nor postcode are correct. "5A": address is correct but not the postcode. "5Z": postcode is correct but not the address. "5U": unknown, address and postcode were not checked. Table 5-89: Parameter rc_avsamex rc_score FIX Y Traffic light value of an American Express address verification. The following values are possible: G - green, Y - yellow, R - red, U - unknown. G means numerical parts of the address and postcode are correct and corresponds to rc_avsamex=5f. Y means either numerical address parts or postcode are correct and corresponds to rc_avsamex=5a or rc_avsamex=5z. R means neither numerical address parts nor postcode are correct and corresponds to rc_avsamex=5n. U means the address could not be checked and corresponds to rc_avsamex=5u. Table 5-90: Parameter rc_score Version Date of issue: 26/11/

99 5.5 Transaction details retrefnum AN Reference number of payment Table 5-91: Parameter retrefnum sessionid ANSL-255 Nhdz747458sNX Identification of current session in online shop, used for the link back to the shop Table 5-92: Parameter sessionid trefnum AN[-_/]-20 order_ _01 Transaction number Sparkassen-Internetkasse service Table 5-93: Parameter trefnum txn_card ANSL-255 VISA Brand name of the credit card. In the case of a credit card payment. Table 5-94: Parameter txn_card version FIX 1.1 Version of the shop notification message. This document describes version 1.1 of the shop notification. Table 5-95: Parameter version Parameter overview shop notification - registering a card number alias When you register a card number alias without a payment the response also includes the parameters listed in the previous section. However, some of the response parameters will be empty. In this case the following parameters are Version Date of issue: 26/11/

100 5.5 Transaction details relevant: directposerrorcode, directposerrormessage, mac, ppan and sessionid if submitted in the request. In addition to the parameters mentioned in the previous section, after registering a card number alias the shop notification includes the following fields: account N[*] **** Masked bank account number. If the card number alias was registered for a bank account. Table 5-96: Parameter account accountholder ANLS-255 John Smith Account holder's name if submitted in the registration form. Table 5-97: Parameter accountholder bankcode N Bank code. If the card number alias was registered for a bank account. Table 5-98: Parameter bankcode bic AN8-11 VZVDDED1XXX BIC if the card number alias was registered for a bank account. Table 5-99: Parameter bic cardholder ANLS-255 John Smith Card holder's name if submitted in the registration form. Table 5-100: Parameter cardholder Version Date of issue: 26/11/

101 5.5 Transaction details creditc N[*] ******1111 Masked credit card number. If the card number alias was registered for a credit card. Table 5-101: Parameter creditc expdat N The expiration date of the credit card in the format YYMM. The first two characters refer to the year of expiry for the card. The last two characters refer to the month of expiry. If the card number alias was registered for a credit card. Table 5-102: Parameter expdat iban AN-34 DE IBAN. If the card number alias was registered for a bank account. Table 5-103: Parameter iban txn_card ANSL-255 VISA Brand name of the credit card. If the card number alias was registered for a credit card. Table 5-104: Parameter txn_card version FIX 1.1 Version of the shop notification message. This document describes version 1.1 of the shop notification. Table 5-105: Parameter version Version Date of issue: 26/11/

102 5.5 Transaction details Parameter overview response message The Sparkassen-Internetkasse server expects confirmation of this message from the online. Otherwise the customer will receive an error message. The response to a notification is a URL-coded document which only contains one text line (no HTML tags, etc.) in the format parameter=value. Use the rurls parameter to show the customer the success page, or rurlf if you wish to display the error page. Assign the parameter a URL as a value. The customer sees this as a link on the success or error page. Instead of having Sparkassen-Internetkasse show its success or error page, you can make Sparkassen-Internetkasse send the customer an HTTP redirect to your own success or error page. For this purpose send the redirecturls parameter instead of rurls for the success page and redirecturlf instead of rurlf for the error page. Please note that even a successfully processed payment could contain an error. For example, it is possible that the transmitted mac parameter does not match the calculated parameter. In this case, the confirmation should report an error. The payment will not be automatically reversed afterwards. In this case, you have to reverse the payment manually in the trader interface. Whether the customer sees a success or error message depends on the parameter that the URL contains. The response to a notification should be given within 30 seconds. Parameter overview response message redirecturlf ANS Parameter that indicates that a payment contained errors. Contains a URL. Sparkassen-Internetkasse sends a redirect to this URL to the customer's browser. Table 5-106: Parameter redirecturlf redirecturls ANS Parameter which identifies a payment as successful and contains a URL. Sparkassen-Internetkasse sends a redirect to this URL to the customer's browser. Table 5-107: Parameter redirecturls Version Date of issue: 26/11/

103 5.6 Modification of the forms rurlf ANS Parameter that indicates that a payment contained errors. The Sparkassen-Internetkasse error page is shown to the customer. Table 5-108: Parameter rurlf rurls ANS Parameter which identifies a payment as successful and contains a URL. The Sparkassen-Internetkasse success page is shown. Table 5-109: Parameter rurls A response message could look like this: Listing 5-2 rurls= 5.6 Modification of the forms You can influence the appearance of the forms using Cascading Style Sheets (CSS). In the front office you can configure the URL of the style sheet that is applied to the forms. Fill in the field CSS-URL on the page for the configuration of the SSL forms. As an alternative or to override the URL in the configuration you can submit the URL in the cssurl parameter. If the URL is not configured or submitted a default style sheet is used. Please note that the style sheet will be used for the forms for entering payment data (credit card or direct debit) as well as for the success and error pages. On the test and productive system complete CSS files with the following URLs are available. Test system, form with "S-Internetkasse" writing: Productive system, form with "S-Internetkasse" writing: Test system, form without "S-Internetkasse" writing: Version Date of issue: 26/11/

104 5.6 Modification of the forms Productive system, form without "S-Internetkasse" writing: The CSS file with "S-Internetkasse" writing also exists in a variant for the forms designed for the Apple iphone and other smartphones with a WebKit based browser. Replace the version "1.8/standard" in the URL with "1.8/mobile" to access the "mobile" CSS. The Forms are structured by nested div elements with either an id or a class attribute assigned to it: Version Date of issue: 26/11/

105 5.6 Modification of the forms Figure 5-3: Layout of the forms The image above shows identifiers for ids and class attributes used in the HTML Code for the pages. The forms for the Apple iphone and other smartphones with a WebKit based browser have the same principal structure but require a different stylesheet. Use the following stylesheets as the basis for your modifications. Do not modify the identifiers of the styles. Version Date of issue: 26/11/

106 5.6 Modification of the forms Standard (version 1.8) Listing 5-3 /* comment in for debugging */ /*div { border : 1px solid red!important; padding : 2px!important; margin : !important; */ body, img, form, input.submit, input.heading { padding : 0px; margin : 0px; border : 0px; body, img, input, select, option { font-family : helvetica, "Liberation Sans", Arial; font-size : 12px; line-height : 16px; color : #17294c; body { background : url("sprite-repeat-x.png") #6f81a6 repeat-x; a, a:link, a:visited, a:hover, a:active, a:focus { color : #0055ff; /* settings for cvc help popup */ body.popup { background : #ffffff; margin : 12px; body.popup div.pageheading { font-size : 17px; line-height : 36px; font-weight : bold; body.popup div.section div.heading { margin-top : 12px; line-height : 24px; font-weight : bold; /* settings for regular form service window */ #bound { width : 560px; min-height : 560px; margin : auto; * html * #bound { /* IE6 only match */ height : 560px; Version Date of issue: 26/11/

107 5.6 Modification of the forms #topleft, #middleleft, #bottomleft { clear : left; #topleft, #topcenter, #topright, #bottomleft, #bottomcenter, #bottomright, #heading, #messagebox, div.panel, input.submit, input.heading { background : url("sprite-no-repeat.png") #f0f0f0 no-repeat; #middleleft, #middlecenter, #middleright { background : url("sprite-repeat-y.png") #f0f0f0 repeat-y; #topleft, #topcenter, #topright { height : 128px; #content { min-height : 192px; * html * #content { /* IE6 only match */ height : 192px; #bottomleft, #bottomcenter, #bottomright { height : 64px; #topcenter, #middlecenter, #bottomcenter { margin-right : 32px; /* width of right column */ #topright, #middleright, #bottomright { margin-left : 48px; /* width of left column */ #topleft { background-position : left 0px; #topcenter { background-position : -48px 0px; #topright { background-position : right 0px; #middleleft { background-position : left 0px; #middlecenter { background-position : -48px 0px; #middleright { Version Date of issue: 26/11/

108 5.6 Modification of the forms background-position : right 0px; #bottomleft { background-position : left bottom; #bottomcenter { background-position : -48px bottom; #bottomright { background-position : right bottom; #header { height : 80px; #header img { float : left; margin-right : 17px; #heading, input.submit { font-weight : bold; color : #f0f0f0; background-color : #465165; #heading { background-position : -48px -208px; #heading div, div.panel div { display : inline; /* fix IE6 double margin bug */ float : left; margin-left : 16px; padding-top :7px; #heading, div.panel { width : 464px; #heading, div.panel { height : 32px; #messagebox { height : 80px; background-position : -48px -320px; #messagebox div { padding-top : 16px; margin-right : 32px; Version Date of issue: 26/11/

109 5.6 Modification of the forms margin-left : 80px; #messagebox.error { color : #f0f0f0; background-color : #e65c5c; background-position : -48px -240px; div.panel { overflow : hidden; background-color : #a1a7b2; background-position : -48px -400px; div.panel.error { color : #f0f0f0; background-color : #e65c5c; background-position : -48px -464px; div.error div.message { margin-left : 36px; div.panel div.caption { width : 192px; div.panel div.value { width : 224px; div.panel div.caption, div.panel div.value { overflow : hidden; div.panel div.heading, input.heading { font-weight : bold; input.heading { background-position : -48px -432px; width:100%; height : 32px; text-align : left; padding-left : 16px; form, #buttons { margin-top : 16px; #buttons.btnright { float: right; #buttons.btnrightmrg { margin-right : 16px; Version Date of issue: 26/11/

110 5.6 Modification of the forms div.panel div.value input { width : 144px; height : 14px; line-height : 14px; background : #f0f0f0; position : relative; top : -2px; input.submit { vertical-align : top; width : 144px; height : 32px; background-position : -48px -496px; #footer { margin-top : 16px; height : 48px; #footer img, #footer a { margin-right : 16px; #footer a img { margin-right : 0px;.disclaimer { margin-right : 16px; margin-left : 2px; margin-top : 10px; margin-bottom : 10px; font-size : 11px; line-height : 16px; color : #808080;.mandateTxtPanel { width: 462px; max-height: 400px; overflow: auto; border: 1px solid rgb(176, 182, 195);.mandateTxtMsg { margin-right : 16px; margin-left : 2px; margin-top : 10px; margin-bottom : 10px; font-size : 11px; line-height : 16px; color : #808080; select.selectcountry { width: 148px; Version Date of issue: 26/11/

111 5.6 Modification of the forms Smartphones (version 1.8m) Listing 5-4 ody, img, form, input.submit, input.heading { padding : 0px; margin : 0px; border : 0px; body, img, input, select, option { font-family : "Helvetica Neue", "Helvetica", "Liberation Sans", "Arial"; font-size : 17px; color : #010066; body { background : url("background.png") #f8f8f8; div { overflow : hidden; a, a:link, a:visited, a:hover, a:active, a:focus { color : #0055ff; #messagebox.error div a, #messagebox.error div a:link, #messagebox.error div a:visited, #messagebox.error div a:hover, #messagebox.error div a:active, #messagebox.error div a:focus { color : #ffffff; /* settings for cvc help popup */ body.cvc2 { font-size : 17px; background : #ffffff; margin-top : 0px; margin-bottom : 11px; margin-left : 10px; margin-right : 10px; color : #000000; body.cvc2 div.contenttitle { line-height : 22px; padding-top : 11px; padding-bottom : 11px; font-weight : bold; color : #010066; border-bottom : 2px solid #000166; body.cvc2 div.cvc2-outerbox div.cvc2-title { margin-top : 22px; line-height : 22px; font-weight : bold; color : #405080; Version Date of issue: 26/11/

112 5.6 Modification of the forms /* settings for regular form service window */ #bound { width : 100%; #topleft, #middleleft, #bottomleft { clear : left; #topcenter, input.submit, input.heading { background : url("sprite-no-repeat.png") no-repeat; #topright, div.panel-left, div.panel-right, div.panel-center, #footer { background : url("sprite-repeat.png"); div.panel-left, div.panel-right { background-repeat : no-repeat; #topleft, #topcenter, #topright { height : 44px; #heading { font-weight : bold; color : #5a5a9c; #content { margin-left : 3.125%; margin-right : 3.125%; #header, #bottomleft, #bottomcenter, #bottomright { height : 0px; visibility : hidden; #topleft { background-color : #ffffff; #topcenter { margin-left : 3.125%; background-position : -10px 0px; input.submit { font-weight : bold; color : #f0f0f0; Version Date of issue: 26/11/

113 5.6 Modification of the forms #heading { background-position : -48px -208px; #heading div { margin-left : 3.125%; #heading div, div.panel-center div, div.panel div { line-height : 44px; float : left; #heading, div.panel, div.panel-center { min-height : 44px; #messagebox { width : 100%; background-color : #ffffff; background: -webkitgradient(linear, left top, left bottom, from(#e8e8e8), to(#ffffff)); margin-bottom : 11px; #messagebox div { padding-top : 11px; padding-bottom : 11px; margin-left : 3.125%; margin-right : 3.125%; line-height : 22px; height : 88px; div.panel-left.error div.panel-right div.panel-center, #messagebox.error { background-color : #c80751; div.panel-left.error, #messagebox.error { color : #ffffff; #messagebox.error { background: -webkitgradient(linear, left top, left bottom, from(#de6a96), to(#c80751)); div.panel-center { background-color : #ffffff; margin-right : 3.333%; div.panel-right { margin-left : 3.333%; Version Date of issue: 26/11/

114 5.6 Modification of the forms /* first panels */ div.panel-left.first { background-position : left -264px; div.panel-left.first div.panel-right { background-position : right -264px; div.panel-left.first div.panel-right div.panel-center { background-position : 0px -308px; /* first panels for error messages */ div.panel-left.error.first { background-position : left -44px; div.panel-left.error.first div.panel-right { background-position : right -44px; div.panel-left.error.first div.panel-right div.panel-center { background-position : 0px -88px; /* standard panels */ div.panel-left { background-position : left -352px; div.panel-right { background-position : right -352px; div.panel-center { background-position : 0px -308px; /* standard panels for error messages */ div.panel-left.error { background-position : left -176px; div.panel-left.error div.panel-right { background-position : right -176px; div.panel-left.error div.panel-right div.panel-center { background-position : 0px -88px; /* last panels */ div.panel-left.last { background-position : left -440px; div.panel-left.last div.panel-right { background-position : right -440px; Version Date of issue: 26/11/

115 5.6 Modification of the forms div.panel-left.last div.panel-right div.panel-center{ background-position : 0px -396px; /* some special handling for message boxes */ div.panel-left.error div.panel-right div.panel-center div.message { overflow : visible; white-space : normal; margin-top : 11px; line-height : 22px; margin-bottom : 11px; div.caption { font-weight : bold; width : 0; overflow : visible; div.panel-center div.value { float : right; div.caption, div.value { white-space : nowrap; div.heading { font-weight : bold; input.heading { background-position : right -88px; height : 44px; width : 100%; font-weight : bold; text-align : left; border : 0px solid transparent; input.submit { margin-top : 11px; display : block; clear:both; width : 300px; height : 44px; line-height : 44px; background-position : -11px -44px; border : 0px solid transparent; #footer { background-color : #ffffff; background-position : 0px -484px; margin-top : 11px; padding-top : 11px; padding-bottom : 11px; padding-left : 3.125%; padding-right : 3.125%; height : 44px; Version Date of issue: 26/11/

116 5.7 Configuration of Your Account #footer img { margin-right : 3.125%; #footer a img { margin-top : 7px; margin-right : 0px;.disclaimer { line-height : 15px; color: #404040; margin-bottom : 22px; margin-right : 12px; text-shadow: 0px 1px 0px #ffffff; font-size : small; input[name="bankcode"], input[name="accountnumber"] { width : 98px; input[name="cc_no"] { width : 154px; 5.7 Configuration of Your Account Credit Card Verification Number The credit card verification number is an input field in the form for entering credit card data. The card verification number is a security feature that increases the likelihood that the customer actually possesses the card. The credit card verification number is in the signature field on the back of the card (Master- Card, Visa, Diners, some American Express cards; the last three numbers) or on the front of the card (some American Express cards; the four numbers above the card number). In the standard configuration of your account entering the credit card verification number is mandatory. If a customer does not enter the number the payment will not be accepted. If you want to make the credit card verification number an optional input, please contact the customer support. Note Please observe the arrangements in your card acceptance contract with your acquirer. Usually you are obliged to submit the card verification number. Version Date of issue: 26/11/

117 5.8 FAQ 5.8 FAQ Q: Why doesn't Sparkassen-Internetkasse inform my shop about the payment outcome? A: If your shop system does not receive a message from Sparkassen-Internetkasse, ensure that the URL for shop notification has been correctly configured. It is also important that this URL can be accessed by a computer from the Internet and is not protected by a firewall system. If you configured a URL starting with "https" possibly your SSL certificate is not accepted by the Sparkassen-Internetkasse server (e.g. a certificate you generated yourself). Or perhaps the certificate was issued for another server than the one specified in the URL. This also happens for HTTPS connections if you entered the IP address instead of the server name in the URL for shop notification. Q: What do I need to keep in mind when switching from the test to the live system? A: The URL for shop notification must be configured on the live Sparkassen-Internetkasse system. On the shop side, the Sparkassen-Internetkasse URL must be adapted, and in some cases, so must the trader ID (field sslmerchant). Q: Can I embed the notification response in HTML code? A: No. The response must begin with the text rurls= or rurlf=. Q: What happens if a customer tries to pay with a Visa or MasterCard that hasn't been registered for Verified by Visa or MasterCard SecureCode? A: Normally a liability shift occurs (see below). Q: What does "liability shift" mean? A: Liability shift means a shift of liability: If a transaction is disputed, the liability shift guarantees that the liability shifts in favour of the trader. The risk of a return debit is passed to the customer bank. The trader acquires entitlement to this liability shift by using software certified by Visa, such as the CCS, no matter how the customer has authorised his payment. Depending on your credit card acquirer liability shift can be restricted. Please ask your acquirer for details. Version Date of issue: 26/11/

118 6.1 Test data 6 Appendix 6.1 Test data Test data for payment transactions Test data are available for testing the functionality during integration of Sparkassen-Internetkasse. Use these test data only on the test system. Payments will only be simulated there. In general, only payments with valid currencies will be accepted. Please use whole amounts not exceeding 100 euro for test payments. Credit Card Payments Important Credit card payments will be rejected in the test system if amounts in cent are submitted. The return value in the rc field will be set to the submitted cent amount. Note Please do not use real credit card data for your tests! The card numbers in the table below can be used to test credit card payments. For successful payments, use a validity date in the future. The credit card verification number will not be checked in the test system. You can use any number. Visa MasterCard American Express Table 6-1: Test data for credit card payments At this point, Visa and MasterCard do not plan any test payments for Verified by Visa or MasterCard SecureCode. American Express Address Verification You can use the card number and any expiry date in the future together with the following addresses and card verification codes to test the American Express address verification. Every test data set includes a card verification code (parameter cvcode), post code (customer_addr_zip), town (customer_addr_city), street (customer_addr_street) and street number (customer_addr_number). Version Date of issue: 26/11/

119 6.1 Test data Card Verification Code Post Code Town Street Street Number Testort an der Lahn Teststaedter Hauptstrasse Testhausen Musterallee 121 a Karben-Rendel Aussenbezirk 4455 A-1049 Wiener Neustadt Musterstaedter Gasse 19 b 0099 W14 4WW London Downing Street 11 Table 6-2: Test data for American Express address verification If you carry out a simulated American Express address verification on the test system the result will be rc_avsamex=5f and rc_score=g for any of these test data sets. Changing the street number leads to rc_avsamex=5z and rc_score=y, changing the post code yields rc_avsamex=5a and rc_score=y. If you modify the post code and the street number you will receive rc_avsamex=5n and rc_score=r. If you submit a wrong card verification code payment will be rejected and you will receive rc_avsamex=5u and rc_score=r - regardless of the address data you submitted. Check of the Issuing Country of a Credit Card To test how the issuing country of a credit card is checked you can use the following values for the acceptcountries and rejectcountries parameters. Country code v+ Visa cards only v- no Visa cards Table 6-3: Country codes for test purposes Direct Debit Payments The bank details in the table below can be used to test direct debit payments. The check of cent amounts available for credit card payments is not available for direct debit payments. The first set of bank details has an incorrect bank code. For test payments, you get the return value rc=884. Account number Bank code Table 6-4: Test data for direct debit payments - invalid bank code For payments with the bank code in the table below, the account number is not checked; the payments are accepted. Version Date of issue: 26/11/

120 6.2 Response messages Account number Bank code Table 6-5: Test data for direct debit payments - every account number valid For payments with the bank code in the table below, the account number is checked; a payment with the account number specified below is refused. You get the return value rc=883. A valid account number for this bank code is Account number Bank code Table 6-6: Test data for direct debit payments - incorrect account number for valid bank code You can use the following IBANs for successful test payments: DE , DE The following IBANs are invalid and result in the response code rc=005: DE , DE Response messages Sparkassen-Internetkasse messages The following table explains the return values of the posherr (shop interface) or directposerrorcode (form service) field. The return value is in the first column. The second column shows the meaning of this value. The third column shows how the trading system should react to this return value. When processing these messages in the shop system, please note that they are not meant to be passed directly to the ordering customer. Simplified messages such as Approved, Approval rejected, or Processing not possible at this time should be forwarded to the customer where necessary. Use the receipt function of the Sparkassen-Internetkasse service to issue a proper receipt. Incorrect could also mean that the corresponding value is blank or not available. Version Date of issue: 26/11/

121 6.2 Response messages Results value Meaning Reaction 0 Transaction successfully concluded 100 Transaction with the payment gateway not concluded successfully Enter result in database or shop system. The analysis of the error code (field rc) received by the gateway is decisive for processing the request further. 102 Timeout The shop may not perform any further transactions with this transaction number to avoid double postings. The underlying business transaction should consider payment not made. The state of this transaction at the gateway is unknown. In this case, the trader should ask Support personnel for clarification. If the transaction has been successfully concluded at the gateway, Support personnel will reverse the payment. 103 Transaction with escore not concluded successfully 104 POA-Transaction not concluded successfully 106 No transaction under this trefnum. 107 No transaction under this transaction number. 108 Transaction number already assigned. 118 Invalid amount for refund or capture The analysis of the error code (field rc) received by the gateway is decisive for processing the request further. The analysis of the error code (field rc) received by the gateway is decisive for processing the request further. Investigate whether the specified transaction reference number really corresponds to a preceding transaction. Contact Support personnel for clarification if this is the case. Investigate whether the specified procedure number really corresponds to a preceding transaction. Contact Support personnel for clarification if this is the case. Select a unique transaction number for each transaction. Check the transferred amount and compare it with the amount of the previous transaction. 133 Card expired If possible, the shop should prompt the customer to correct the credit card data entered and to resubmit the transaction. 141 Trader does not accept this card type. Display the possible credit card types. If the error was not caused by customer entry, contact your Support personnel for clarification. 151 Invalid response message Do not perform any further transactions with this transaction number to avoid double postings. The underlying business transaction should consider payment not made. The state of this transaction at the Gateway is unknown. Ask customer support for clarification. If the transaction has been successfully concluded at the gateway, Support personnel will reverse the payment. 156 orderid parameter incorrect. Check the content of the orderid parameter and compare its format with the documentation. Version Date of issue: 26/11/

122 6.2 Response messages Results value Meaning Reaction 157 creditc parameter incorrect. Check the content of the creditc parameter and compare its format with the documentation. If necessary, inform your customer about the incorrect entry and offer to correct the value. 158 expdat parameter incorrect. Check the content of the expdat parameter and compare its format with the documentation. If necessary, inform your customer about the incorrect entry and offer to correct the value. Provide the customer with selection fields in order to avoid incorrect entries. 159 currency parameter incorrect. Check the content of the currency parameter and compare its format with the documentation. The currency for direct debits has to be EUR. If necessary, inform your customer about the incorrect entry and offer to correct the value. Allow the customer to choose from possible currencies in order to avoid incorrect entries. 160 amount parameter incorrect. Check the content of the amount parameter and compare its format with the documentation. 162 trefnum parameter incorrect. Check the content of the trefnum parameter and compare its format with the documentation. 165 Unpermitted parameter Check the parameter transmitted in the request message and compare it with the mandatory parameters described in the documentation. 166 command parameter incorrect. Check the content of the command parameter and compare its format with the documentation. 172 Access denied. Please report to your Support personnel for clarification if this response appears more than once. 186 Transaction already captured, reversed or concluded. Check if you tried to carry out the transaction twice by mistake. 197 Invalid request Implement the interface according to the documentation If you are unable to solve the problem, contact your Support personnel. 198 System is temporarily out of order. Please report to your Support personnel for clarification if this response appears more than once. 199 System error The state of this transaction at the Gateway is unknown. Ask Support personnel for clarification. 300 No connection to gateway Please report to your Support personnel for clarification if this response appears more than once. 303 cvcode parameter incorrect. Check the content of the cvcode parameter and compare its format with the documentation. If necessary, inform your customer about the incorrect entry and offer to correct the value. 304 bankcode parameter incorrect. Check the content of the bankcode parameter and compare its format with the documentation. If necessary, inform your customer about the incorrect entry and offer to correct the value. Version Date of issue: 26/11/

123 6.2 Response messages Results value Meaning Reaction 305 account parameter incorrect. Check the content of the account parameter and compare its format with the documentation. If necessary, inform your customer about the incorrect entry and offer to correct the value. 307 Direct debit not allowed. Please report to your Support personnel for clarification if this response appears more than once. 308 Configuration for this payment or precheck was not created. 309 Configuration for this payment or precheck was blocked. 310 payment_options parameter incorrect. Please report to your Support personnel for clarification if this response appears more than once. Please report to your Support personnel for clarification if this response appears more than once. Check the content of the payment_options parameter and compare its format with the documentation. 311 customer_id parameter incorrect. Check the content of the customer_id parameter and compare its format with the documentation. 312 customer_title parameter incorrect. 313 customer_firstname parameter incorrect. 314 customer_lastname parameter incorrect. 315 customer_date_of_birth parameter incorrect. 316 customer_addr_street parameter incorrect. 317 customer_addr_number parameter incorrect. 318 customer_addr_zip parameter incorrect. Check the content of the customer_title parameter and compare its format with the documentation. If necessary, inform your customer about the incorrect entry and offer to correct the value. Check the content of the customer_firstname parameter and compare its format with the documentation. If necessary, inform your customer about the incorrect entry and offer to correct the value. Check the content of the customer_lastname parameter and compare its format with the documentation. If necessary, inform your customer about the incorrect entry and offer to correct the value. Check the content of the customer_date_of_birth parameter and compare its format with the documentation. If necessary, inform your customer about the incorrect entry and offer to correct the value. Check the content of the customer_addr_street parameter and compare its format with the documentation. If necessary, inform your customer about the incorrect entry and offer to correct the value. Check the content of the customer_addr_number parameter and compare its format with the documentation. If necessary, inform your customer about the incorrect entry and offer to correct the value. Check the content of the customer_addr_zip parameter and compare its format with the documentation. If necessary, inform your customer about the incorrect entry and offer to correct the value. Version Date of issue: 26/11/

124 6.2 Response messages Results value Meaning Reaction 319 customer_addr_city parameter incorrect. 320 customer_addr_country parameter incorrect. 321 customer_since_mm parameter incorrect. 322 customer_since_yy parameter incorrect. 323 This transaction type is not allowed for the configured gateway. 324 Error in request during entry check Check the content of the customer_addr_city parameter and compare its format with the documentation. If necessary, inform your customer about the incorrect entry and offer to correct the value. Check the content of the customer_addr_country parameter and compare its format with the documentation. If necessary, inform your customer about the incorrect entry and offer to correct the value. Check the content of the customer_since_mm parameter and compare its format with the documentation. Check the content of the customer_since_yy parameter and compare its format with the documentation. Check the content of the command and payment_options parameters and compare their format with the documentation. Please report to your Support personnel for clarification if this response appears more than once. 332 providerid parameter incorrect. Check the content of the providerid parameter and compare its format with the documentation. If necessary, inform your customer about the incorrect entry and offer to correct the value. 333 msisdn parameter incorrect. Check the content of the msisdn parameter and compare its format with the documentation. If necessary, inform your customer about the incorrect entry and offer to correct the value. 334 paymentmethod parameter incorrect. Check the content of the paymentmethod parameter and compare its format with the documentation. 335 tracenumber parameter incorrect. Check the content of the tracenumber parameter and compare its format with the documentation. 336 terminalid parameter incorrect. Check the content of the terminalid parameter and compare its format with the documentation. 337 terminalid and tracenumber have to be submitted together. Check the content of the terminalid and tracenumber parameters. Do not submit only one of these parameters D-Secure authorisation failed. Inform your customer about the incorrect entry. The transaction may be repeated. 339 autocapture parameter incorrect. Check the content of the autocapture parameter and compare its format with the documentation. 341 The mobile phone provider is not accepted by the merchant. 342 basketnr or basketid parameter incorrect. Check the content of the providerid parameter and compare its format with the documentation. Check the content of the basketnr or basketid parameter and compare its format with the documentation. Version Date of issue: 26/11/

125 6.2 Response messages Results value Meaning Reaction 343 Credit card not issued in an accepted country. 344 Credit card not issued in the specified country. 345 This merchant may only refund amounts of transactions that have already been carried out. Ask the customer to choose another means of payment. Ask the customer to choose another means of payment. Check if the refund is related to a transaction that has already been carried out. 346 timestamp parameter incorrect. Check the content of the timestamp parameter and compare its format with the documentation. 347 Aborted by user. Let the customer choose another payment method. 349 Limit exceeded. Show an error message to the customer. If necessary, check the limit configuration in the front office. 350 This means of payment is on the blacklist. 351 giropay payments are currently not possible with this institute. Show an error message to the customer. If necessary, check the blacklist configuration in the front office. Show an error message to the customer. 352 The bank code is unknown. Show an error message to the customer. Offer the customer to try again. It is possibly a typing error. 353 The card number alias already exists. 354 The merchant is not allowed to use card number aliases. 355 The merchant is only allowed to use card number aliases. 356 The submitted card number alias is unknown. Send the request again with a new, unique card number alias or send the request without a card number alias. In this case, Sparkassen-Internetkasse will generate a card number alias and return it to you in the response. If you agreed on using card number aliases probably your account has not been configured properly. In this case, please contact customer support. Otherwise check if your input parameters are in accordance with the documentation. If you did not agree on using card number aliases probably your account has not been configured properly. In this case, please contact customer support. Otherwise check if your input parameters are in accordance with the documentation. Check the value of the card number alias. Perhaps a previous attempt to create this card number alias failed and you therefore assume that it exists. 357 ppan parameter incorrect. Check the content of the ppan parameter and compare its format with the documentation. 358 The submitted card number alias is unknown. 359 A transaction with this transaction number is currently in work. If you don't know which card number alias is assigned to this credit card, the shop interface provides the possibility to find the card number alias. Please read the documentation. Probably you submitted the same transaction twice at the same time. Please avoid this in the future. Version Date of issue: 26/11/

126 6.2 Response messages Results value Meaning Reaction 360 The merchant is not allowed to submit credit card data at this interface. 361 additionalnote parameter incorrect. 362 Bank does not participate in giropay. 370 The card number alias was created for a different payment method. Use credit card aliases with this interface. If you are PCI certified you can have your account re-configured to allow you to submit credit card data at this interface. Check the content of the additionalnote parameter and compare its format with the documentation. Offer the customer to enter another bank account or to choose another payment method. Correct the payment method or use the appropriate alias. 372 Session timeout Repeat the payment. 373 iban parameter incorrect. Check the content of the iban parameter and compare its format with the documentation. 374 bic parameter incorrect. Check the content of the bic parameter and compare its format with the documentation. 375 The means of payment of a follow-up transaction has to be the same as with the initial transaction. 376 This means of payment is on the blacklist. 377 Mandate modifications only in recurring payments Omit all means of payment details that are not documented for this type of transaction. The means of payment of the predecessor transaction will be used then. Show an error message to the customer. Remove the mandate modification data or mark the transaction as a recurring payment. 378 Reference not found Select the correct reference. 500 Card type not accepted for currency. Display the possible credit card types for this currnecy. If the error was not caused by customer entry, contact your Support personnel for clarification. Table 6-7: Sparkassen-Internetkasse messages VÖB-ZVD payment gateway messages The following values are possible in the rc field: Results value Meaning 000 Approved, or completed successfully 002 Call approval service 003 Invalid trader identification 004 Confiscate card 005 Approval denied Version Date of issue: 26/11/

127 6.2 Response messages Results value Meaning 012 Invalid transaction 013 Credit limit exceeded 014 Invalid card 021 No processing 030 Format error authorising party 031 Routing not defined 033 Invalid expiry date 034 Suspicion of manipulation 040 Function/card type not supported 043 Stolen card, please confiscate 055 Wrong PIN 056 Card not in the database of the authorising party 057 Card not identical to the card of the underlying transaction 058 Terminal identification unknown 061 Card blocked 062 Restricted-use card 064 Amount higher than the underlying transaction 074 PIN must be renewed 075 Too many incorrect PIN entries 077 PIN entry 080 Transaction volume no longer available 081 Error in message flow 085 Rejection by authorising party 086 The merchant is unknown 091 Authorising party currently not available 092 The authorising party does not process this type of card. 096 Processing not possible at present 098 Time stamp implausible or sequencing problem 101 AID file for the rerouted/capture request was not found (reservation possibly expired). 102 AID file for the rerouted/capture request could not be read. 103 AID file for the rerouted/capture request could not be written. 200 Cannot read receipt number for the virtual POS. 201 Cannot read trace number for the virtual POS 203 No free terminal for this trader Version Date of issue: 26/11/

128 6.2 Response messages Results value Meaning 207 Authorisation interrupted due to timeout. 209 No connection to authorisation system 210 Error connecting to the routing system 212 The trace number in the response differs from the one in the request. 213 The terminal ID in the response differs from the original. 214 Incoming message cannot be transferred to the ZVT protocol. 215 Outgoing message cannot be transferred to the ZVT protocol. 216 The message number from the response does not match the requested function. 217 This message number is not supported by the IPS. 218 Invalid amount for reversal or capture 231 Invalid currency code 705 POS terminal table was not previously created. 706 Impossible attachment to a semaphore for the POS administration. 707 Impossible detachment of a semaphore for the POS administration 719 The displayed POS terminal for this trader could not be found. 841 SET authentication not activated 842 3D-Secure authentication not activated 843 UCAF authentication not activated 844 EMV transaction type not activated 845 ecommerce transaction type not activated 846 POS transaction type not activated 847 MailOrder transaction type not activated 850 The PGW interface could not return the authorisation system's complete response. 851 The response from the virtual POS terminal contains no data or invalid data. 852 Terminal not responding 860 The data length received by the PGW interface does not match the expected length. 861 The PGW interface could not provide the required memory for the incoming data. 862 Terminal not responding 863 The msgnr field contains an invalid size. 864 The msgnr field in the incoming message is missing. 865 The nrofgoods field in the incoming message is missing. 866 One or several of the mandatory fields in the incoming message are missing. 867 The PGW interface could not provide enough memory for the incoming message. 868 The trader data file could not be found or read. Version Date of issue: 26/11/

129 6.3 Parameter format description Results value Meaning 869 The trader system data file could not be found or read. 870 The trader is unknown in the IP system. 871 The trader system ID could not be read, or the instruction of the trader system ID does not match the trader. 872 The trader is not authorised to use the PGW interface. 873 The trader password is incorrect. 874 The trader system password is incorrect. 875 The transaction could not be found in the IP system (this is a response to a diagnostics query). 876 The incoming message could not be sent to the virtual POS terminal for authorisation. 877 The validity check for the card number has failed. 878 Incorrect card number length 879 The byte size for reading is not defined. 880 The specified byte size for reading is zero. 881 One or several mandatory fields in the incoming message contain no value. 882 Routing system is temporarily out of order. 883 Invalid account number for this bank code 884 Invalid bank code 885 Format error in the input data 890 Unknown error. Please report to your Support personnel for clarification. 891 SET authentication is not activated for this trader DSecure authentication is not activated for this trader. 893 Spa-Ucaf authentication is not activated for this trader. 894 EMV transactions are not activated for this trader. 895 The ecommerce transaction type is not activated for this trader. 896 The POS transaction type is not activated for this trader. 897 The MailOrder transaction type is not activated for this trader. 898 The Subscription transaction type is not activated for this trader. 899 Transaction number already assigned in the back-end system Table 6-8: Messages of the VÖB-ZVD payment gateway and card processors 6.3 Parameter format description All characters that define the format of a parameter are listed and explained in the following table. Version Date of issue: 26/11/

130 6.4 MAC - Message Authentication Code Character A N S L Xn X-n Meaning Letter Numbers Special characters Blanks exactly n characters maximum n characters FIX fixed string [] A number of permitted characters are listed between square brackets. a s N5 ANS-10 AN[_]-10 Number with exactly 5 characters String with up to 10 characters This string may contain letters, numbers and special characters, but no blanks. String with up to 10 characters This string may contain letters, numbers and the character '_', but no blanks. a If the square bracket itself is also allowed, then it appears twice, e.g. [[]. Table 6-9: Format description 6.4 MAC - Message Authentication Code Without a security procedure, payment data are not protected against manipulation. When payment is initialised, the payment data are routed via the customer's browser and can be manipulated there. The Message Authentication Code (MAC) is used to safeguard payment data from manipulation. MAC enables the Sparkassen-Internetkasse service to recognise manipulation and to respond with an error message. Shop notification is also usually carried out via an unencrypted HTTP request and is therefore not protected against manipulation either. The MAC calculated by the Sparkassen- Internetkasse service enables your application to recognise possible manipulation by checking the MAC. To do this, your application must calculate the MAC from the parameters of the response message. If the MAC calculated in this way matches the MAC in the response message, you can assume that the response message has not been manipulated HMAC - Keyed-Hashing for Message Authentication The standardised procedure HMAC (RFC 2104) is used to calculate the MAC. HMAC describes how the input message (the payment data to be secured) is lin- Version Date of issue: 26/11/

131 6.4 MAC - Message Authentication Code ked to a key and how the MAC is then calculated. The cryptographic hash function SHA-1 is used to calculate the MAC. The SSL password is used as a key that you receive when your access is activated. The key is decisive for the security of the HMAC procedure. Make sure that unauthorised parties are unable to access your SSL password. To increase security, we recommend using a "random" password with the maximum permitted length of 20 characters. Change your SSL password from time to time. The message that the HMAC procedure is applied to consists of the values of the parameters of the request or response message. These are strung together alphabetically by parameter name, without separators or spaces. If optional parameters are not specified, the next parameter is added. The HMAC procedure is described briefly below. You will find a detailed description in RFC 2104, HMAC: Keyed-Hashing for Message Authentication ( see The common programming and script languages already contain implementations for hash algorithm SHA-1, which you can use. In some cases, you can also find complete implementations of the HMAC procedure. The MAC is represented in hexadecimal format. Each byte is represented by two characters (numbers, lowercase letters a to f). HMAC procedure with SHA-1 The HMAC procedure consists of the following steps: 1. Append as many zero bytes (0x00) to the key needed to produce a 64 byte key. 2. XOR (bitwise exclusive-or logic operation) the above key with a byte string consisting of 64 bytes 0x Append the values of the input parameters, sorted alphabetically by the parameter names, without blanks or separators to the string resulting from step 2. The parameters that are relevant for the calculation of the MAC are listed here in the correct order: Initialisation of payment acceptcountries (optional, accepted issuing countries) additionalnote (optional) amount autocapture (optional, hours until automatic capture is carried out) backendretrycount (optional) basketid (optional, shopping basket number) bic_obsolete (optional) clientip (optional, IP address) command (request definition ) countryrejectmessage (optional) creditorid_obsolete (optional) Version Date of issue: 26/11/

132 6.4 MAC - Message Authentication Code cssurl (optional) currency customer_addr_city (optional, town) customer_addr_country (optional, country code) customer_addr_number (optional, street number) customer_addr_street (optional, street) customer_addr_zip (optional, postal code) customer_firstname (optional) customer_lastname (optional) date (optional, date and time) debitmode (optional) deliverycountry (optional) deliverycountryaction (optional) deliverycountryrejectmessage (optional) duedate (optional, date) form_label_cancel (optional) form_label_submit (optional) form_merchantname (optional) iban_obsolete (optional) ipcheckacceptcountries (optional, accepted countries of the IP address) ipcheckaction (optional, action in case IP address is not accepted) ipcheckmode (optional, mode of the IP address check) ipcheckrejectcountries (optional, countries to reject when the IP address is checked) ipcheckrejectmessage (optional, error message if IP address is rejected) locale (optional) mandateid (optional, SEPA mandate reference) mandateid_obsolete (optional) mandatename (optional, SEPA mandate name) mandatesigned (optional, date when the SEPA mandate was issued) merchantref (optional) notificationfailedurl (optional) notifyurl (optional) orderid (transaction number) payment_options (optional) Version Date of issue: 26/11/

133 6.4 MAC - Message Authentication Code paymentmethod ppan (optional, card number alias) rejectcountries (optional, issuing countries to be rejected) sequencetype (optional, SEPA sequence type) seriesflag (optional) sessionid (optional) sslmerchant (trader identification) transactiontype version Request message - registering a card number alias command (request definition ) cssurl (optional) form_label_cancel (optional) form_label_submit (optional) form_merchantname (optional) locale (optional) notificationfailedurl (optional) notifyurl (optional) payment_options (optional) paymentmethod ppan (optional, card number alias) sessionid (optional) sslmerchant (trader identification) version Shop notification - payments account (optional, bank account number) aid (approval number) amount bankcode (optional) basketid (shopping basket number, if specified in payment initialisation) bic (optional, BIC) creditc (optional, credit card number) currency deliverycountry (optional) Version Date of issue: 26/11/

134 6.4 MAC - Message Authentication Code directposerrorcode ( Sparkassen-Internetkasse response code) directposerrormessage (success/error message) expdat (optional, credit card date of expiration) iban (optional, IBAN) ipcheckresult (optional) orderid (transaction number) ppan (optional, card number alias) rc (secondary return code) rc_avsamex (only after an American Express address verification) rc_score (only after an American Express address verification) retrefnum (reference number of payment gateway) sessionid (if specified in payment initialisation) trefnum (Sparkassen-Internetkasse transaction number) txn_card (optional, credit card brand) version Shop notification - registering a card number alias account (optional, bank account number) accountholder (optional) bankcode (optional) bic (optional, BIC) cardholder (optional) creditc (optional, credit card number) directposerrorcode (Sparkassen-Internetkasse response code) directposerrormessage (success/error message) expdat (optional, credit card date of expiration) iban (optional, IBAN) ppan (card number alias) sessionid (if submitted in the request) txn_card (optional, credit card brand) version 4. Apply the SHA-1 hash function to the result of step XOR (bitwise exclusive-or logic operation) the 64-byte key resulting from Step 1 with a byte string consisting of 64 bytes 0x5c. 6. Append the result of step 4 without blanks or separators to the 64-byte key resulting from step 5. Version Date of issue: 26/11/

135 6.4 MAC - Message Authentication Code 7. Apply the SHA-1 hash function to the result of step 6 and output the result in hexadecimal code. The results of step 2 and step 5 only need to be calculated once initially and when the SSL password is changed. You can therefore store the results of step 2 and step 5, so that you do not have to calculate the XOR operation of the key for every message s Here are two sample MAC calculations. You will find additional test cases for your HMAC implementation in RFC 2202 (see Parameter Value amount 10,00 basketid command currency date ba_ sslform EUR _12:23:45 orderid paymentmethod sessionid sslmerchant transactiontype creditcard Nhdz747458sNX mycompany preauthorization version 1.8 SSL password mac 8A!v#6qPc3?+G1on 42b32a9b1dfcc6308bb29f6d02decc74782cf6b9 Table 6-10: MAC calculation - initialisation of payment In this case, the compiled message to which the HMAC procedure will be applied is: "10,00ba_100202sslformEUR _12:23: creditcardNhdz sNXmycompanypreauthorization1.8". Together with the SSL password "8A!v#6qPc3?+G1on" as the key, the resulting MAC calculated is: "42b32a9b1dfcc6308bb29f6d02decc74782cf6b9". Parameter aid Value a34232 amount 10,00 basketid currency ba_ EUR Version Date of issue: 26/11/

136 6.4 MAC - Message Authentication Code Parameter Value directposerrorcode 0 directposerrormessage orderid rc 000 retrefnum sessionid Nhdz747458sNX trefnum _01 SSL-Passwort mac 8A!v#6qPc3?+G1on efaada83d2b62d44bb685abb23897a4e591952db Table 6-11: MAC calculation - shop notification In this case, the compiled message to which the HMAC procedure will be applied is: "a ,00ba_100202eur nhdz747458snx _01". Together with the SSL password "8A!v#6qPc3?+G1on" as the key, the resulting MAC calculated is: "efaada83d2b62d44bb685abb23897a4e591952db" Sample code Java Listing 6-1 import java.io.unsupportedencodingexception; import java.security.invalidkeyexception; import java.security.nosuchalgorithmexception; import javax.crypto.mac; import javax.crypto.spec.secretkeyspec; public class HmacSha1 { private static final String HEXDIGITCHARS = " abcdef"; private static final String ENCODING = "ISO "; /** * Convert a byte array to a hex string of the format * "1f30b7". */ public static final String bytearraytohex(byte[] bytearray) { int hn, ln, cx; StringBuffer buf = new StringBuffer(byteArray.length * 2); for(cx = 0; cx < bytearray.length; cx++) { hn = ((int)(bytearray[cx]) & 0x00ff) / 16; ln = ((int)(bytearray[cx]) & 0x000f); buf.append(hexdigitchars.charat(hn)); buf.append(hexdigitchars.charat(ln)); return buf.tostring(); /** Version Date of issue: 26/11/

137 6.4 MAC - Message Authentication Code * RFC 2104 HMAC implementation * Creates an SHA-1 HMAC */ public static String hmac(string key, String data) throws InvalidKeyException, NoSuchAlgorithmException, UnsupportedEncodingException { String algorithm = "HMACSHA1"; // Get the HMAC algorithm Mac mac = Mac.getInstance(algorithm); // Initialize the algorithm with the key byte[] keybytes = key.getbytes(encoding); mac.init(new SecretKeySpec(keyBytes, 0, keybytes.length, algorithm)); // calculate and output MAC mac.update(data.getbytes(encoding)); return bytearraytohex(mac.dofinal()); public static void main(string args[]) throws NoSuchAlgorithmException, InvalidKeyException, UnsupportedEncodingException { System.out.println(hmac("8A!v#6qPc3?+G1on", "10,00ba_100202sslformEUR" + " _12:23: creditcardNhdz747458sNXmycompany" + "preauthorization1.5")); The program outputs "3508adf0a9e2b00cfb0c401fd37f3bed1c358580". As of version 1.4, the classes of the Java Cryptography Extension (JCE) used are part of the standard scope of Java SE SDK. PHP (as of version 4.3.0) Listing 6-2 <?php function hmac ($key, $data) { // RFC 2104 HMAC implementation for php. // Creates an SHA-1 HMAC. $b = 64; // byte length for SHA-1 // if the key has more than 64 bytes, hash it //if (strlen($key) > $b) { // $key = pack("h*",sha1($key)); // $key = str_pad($key, $b, chr(0x00)); $ipad = str_pad('', $b, chr(0x36)); $opad = str_pad('', $b, chr(0x5c)); $k_ipad = $key ^ $ipad ; $k_opad = $key ^ $opad; return sha1($k_opad. pack("h*",sha1($k_ipad. $data))); echo hmac("8a!v#6qpc3?+g1on", "10,00ba_100202sslformEUR _12:23: creditcardNhdz747458sNXmycomp anypreauthorization1.5");?> The script outputs "3508adf0a9e2b00cfb0c401fd37f3bed1c358580". As of version 4.3.0, the SHA-1 hash function is part of the standard scope PHP. Version Date of issue: 26/11/

138 7 Glossary 7 Glossary Account Acquirer API Authentication BIC CCS CGI Client CSS Gateway Hash HMAC HTTP HTTP basic authentication HTTPS IBAN Java User access to a data system or online offer An acquirer is a company who concludes agreements with traders on behalf of the credit card companies about accepting credit cards as a means of payment. Acquirers in Germany include B+S Card Service or ConCardis for example. Application Programming Interface: Programming and application interface. A security measure when using certain systems. Access is granted, for example, when a user name and correct password are entered. Business Identifier Code. Unique identification code for both financial and nonfinancial institutions participating in international money transfers. Credit Card Security Cartridge. Component of the Sparkassen-Internetkasse service that has been certified by Visa and enables credit card payments according to the 3D-Secure protocol. Common Gateway Interface: Standard for executing programs that run externally on a web server Computer in a network (e.g. Internet, intranet) that uses the services of a central computer (the server), such as data, disk space, and resources. Cascading Style Sheets - language for formatting HTML elements. A gateway is an interface between different networks and services. In terms of the Sparkassen-Internetkasse system, Payment Gateway refers to the transfer point between trader or payment hosting service provider and the credit card acquirer (e.g. B+S CardService). Unique checksum, see SHA-1 Keyed-Hashing Message Authentication Code: see MAC Hypertext Transfer Protocol: Transfer protocol for data exchange in computer networks Access protection of an online offer through password and login. In the event of a request without authorisation, the server sends a response with the status code 401 (unauthorised). In the request, the client must send a HTTP header for authentication containing the login and password in a Base64 coded form. Hypertext Transfer Protocol Secure: Hypertext Transfer Protocol Secure: Especially secure transfer protocol for data exchange in computer networks; uses SSL International Bank Account Number. Internationally agreed means of identifying bank accounts. Object-oriented programming language Version Date of issue: 26/11/

139 JavaScript MAC Meta tag PGW PHP PIN Redirect RFC SEPA Server Session ID SHA-1 SSL Stylesheet Tag URL VÖB-ZVD 7 Glossary Script language for HTML files. (Scripts are not processed directly but instead must be converted to machine code step by step.) Message authentication code: Cryptographic check value; ensures the integrity and authenticity of messages A tag placed in the header of an HTML file. See also: Tag Abbreviation of payment gateway PHP Hypertext Preprocessor, a server-side script language Personal Identification Number Automatic rerouting. Requests For Comments: Documentation of standards and technologies on the Internet Single Euro Payments Area. Aims at improving the efficiency of cross border payments. Central computer in a network (e.g. Internet, intranet). The server provides other computers (clients) with services such as data, disk space and resources. Unique identification number of a process Secure hash algorithm: An algorithm for generating unique checksums; used to sign electronic files ("digital fingerprint") Secure Socket Layer: a protocol for the encrypted transfer of sensitive data (e.g. credit card numbers) over the Internet Defined layout instructions and format specifications Marker or control character in page mark-up languages. In the source text, tags are marked by angle brackets. Uniform Resource Locator: the address where a document is located in the World Wide Web VÖB-ZVD is an institution of the Bundesverband Öffentlicher Banken Deutschlands e.v. (VÖB) Version Date of issue: 26/11/