Card Processing. Merchant Specification. Version 3.5.0

Transcription

1 Version 3.5.0

2 This document has been created by the Wirecard AG. Its contents may be changed without prior notice. External web links are provided for information only. Wirecard does not claim liability for access to and correctness of the referenced content. COPYRIGHT The information contained in this document is intended only for the person or entity to which it is addressed and contains confidential and/or privileged material. Any review, retransmission, dissemination or other use of, or taking of any action in reliance upon, this information by persons or entities other than the intended recipient is prohibited. If you received this in error, please contact Wirecard AG and delete the material from any computer. Copyright 2008 Wirecard AG All rights reserved. Printed in Germany / European Union Version Last Updated: July 2009 TRADEMARKS The Wirecard logo is a registered trademark of Wirecard AG. Other trademarks and service marks in this document are the sole property of the Wirecard AG or their respective owners. CONTACT INFORMATION For questions relating to this document please contact: Wirecard Technologies AG Bretonischer Ring 4 D Grasbrunn Germany phone: support@wirecard.com 2 Version 3.5.0

3 Card Processing Contents 1 Introduction Audience Document Conventions Software Requirements References Revision History Overview What is XML XML Messages Secure Data Transfer XML Messaging Request Format Response Format Test Gateway Test Access Error Messages Test Cards Transaction Modes and Methods Demo Live Single Transaction Recurring Transaction Installment Transaction Implementation Revoking Recurring and Installment Transactions...22 Version

4 6 Transaction Types Preauthorization Capture Preauthorization Preauthorization Supplement Capture Preauthorization Supplement Authorization Authorization Check Capture Authorization Purchase Notification Bookback Reversal Original Credits Query Refund Standard Response Message Address Verification Service AVS Response Message Wirecard AVS Response Codes Wirecard Response Code Mapping Glossary Appendix A: Error Codes Appendix B: AVS Codes Appendix C: Airline Market Segment Appendix D: Car Rental Market Segment Appendix E: Fleet Card Market Segment Appendix F: Hotel Market Segment Appendix G: Travel Market Segment Appendix H: XML Extensions Appendix I: Purchasing Process Appendix J: ASCII Characters Version 3.5.0

5 Card Processing 1 Introduction 1.1 Audience This specification is intended to be read by the technical staff in the merchant s organization responsible for implementing and administering the XML-based card processing interface. It is assumed that the reader has a working knowledge of the programming languages discussed in this specification. 1.2 Document Conventions This document uses the following conventions: The monospace font is used for example code and code listings, file names, commands, path names, directory names, Hypertext Markup Language (HTML) tags, and any text that must be typed on the screen. The italic font is used in code to represent placeholder parameters (variables) that should be replaced with an actual value, or items that require emphasis. Brackets ([]) are used to enclose optional parameters. A slash (/) is used to separate directories in a path and to indicate a blank or closing XML parameter. 1.3 Software Requirements To implement the XML interface for standard card processing, the following requirements must be met: Internet connection supporting SFTP Working knowledge of XML SSL server supporting 128-bit (or stronger) encryption 1.4 References 3-D Secure Card Processing - Specification (Wirecard documentation) HTTPS Gateway - Specification (Wirecard documentation) Introducing 3-D Secure - White Paper (Wirecard documentation) Uniform Resource Identifier (URI): Generic Syntax (RFC 2396) UTF-8, a transformation format of ISO (RFC 2279) Version

6 1.5 Revision History This specification is periodically updated to reflect the modifications made to the card processing interface. With each revision a new entry is added to the table below, including the date of and the reason for the version change. Additionally, vertical revision bars are placed in the margins to indicate the changes in the text. Date Version Comments New transaction type (Authorization Check) added and CREDIT_CARD_DATA fields CardStartYear, CardStartMonth, CardIssueNumber added to Preauthorization Request. Some minor editorial changes. New transaction mode (Installment Transaction) and related error codes added Airline Market and Travel Market segments (Appendices C and F) updated with different tax (VAT) type fields and identifiers. Query request updated Authorization Code removed from Capture, Refund, Bookback, etc Only required in Notification Requests. Some minor changes Elements in Airline Market and Travel Market segments (Appendices C and F) updated. New code added in Error Messages (Appendix A) Minor changes Transaction Type Capture removed from notice. Data Type for Address fields changed to ANS (alphanumeric and special characters) Single/Initial Request examples updated. Card Start Date & Card Issue Number for Switch/Solo/Maestro changed to optional Chapter 7 on AVS incorporated. Query date format updated VAT field settings changed form mandatory to conditional - with comment "relevant for AirPlus Acceptance UATP transactions only". FareBasis data type changed from a6 to an Note added to Refund examples DTD Reference (xsi:nonamespaceschemalocation="wirecard.xsd") removed from XML examples and Appendix D (Car Rental market segment) incorporated minor updates Section 6.12 (Original Credits) added. Sections 6.10 (Bookback) and 6.14 (Refund) updated. Some minor updates Section 6.12 (Original Credits) updated Phone number format updated. Cross references incorporated <FunctionResult>ACK</FunctionResult> in XML samples changed to <FunctionResult>PENDING</FunctionResult>. IP address format description changed. Error code included. CountryCode in OCT request table included. Section 4.3 (Test Cards) incorporated. Section 5 updated. Description of parameter <State> rewritten Error Codes (Appendix A) updated. Example of Reversal Succcessful response (Section ) corrected. 6 Version 3.5.0

7 Card Processing 2 Overview 2.1 What is XML XML, the extensible Markup Language, is designed to carry data in predefined tags. It does not replace HTML, the HyperText Markup Language, but complements it. XML picks up where HTML leaves off. It allows specific markup to be created for specific data. HTML doesn t clearly distinguish markups. Markup for look and links gets mixed in with data. If you change the look of HTML markups, links may be lost. If you change link markups, the look may be lost. This is not the case with XML. Unlike HTML, the extensible Markup Language is not only flexible but also easy to customize and maintain. 2.2 XML Messages This section describes the structure, format, and definition of XML messages. These are defined as a set of fields containing the following parameters: name of the XML message element setting of the XML message element (see also description below) data type defining the structure of the element Required Settings The exchange of XML messages is based on certain requirements. If these are not met, the XML request/response communication will fail. It is therefore imperative that the message elements are defined as required (see the request message elements described in Chapter 6. The request elements are defined as mandatory, optional, or conditional. Mandatory A mandatory (man.) message is necessary to ensure the proper routine and posting of an XML message. Any mandatory message element not included as requested will cause the process request type to be rejected. Optional The inclusion or omission of an optional (opt.) message field is at the discretion of the merchant. A transaction request is also processed if an optional field is missing. Conditional A conditional (con.) message field must be included in some instances. Its omission may cause the process request type to be rejected. Version

8 2.2.2 Notations The following notations define the data type formats of message elements. Notation Description a alphabetic A-Z, a-z n numeric digits, 0-9 an alphanumeric characters as alphabetic and special characters ans alphanumeric and special characters DD Day, 01 through 31 MM Month, 01 to 12 YY Year, where 00=2000, 01=2001, etc. hh hour, 00 to 23 mm minute, 00 to 59 ss second, 00 to 59 3 Fixed length of 3 bytes..17 Variable length up to a maximum of 17 bytes. c collection of elements UTF-8 Character Encoding As credit cards are accepted from customers around the world, the XML text messages of credit card transactions may contain data in different languages. To cater to these cross-border card transactions, merchants are advised to configure their system to send XML text messages in the 8-bit Unicode Transformation Format (UTF-8), a variable-length character encoding described in ISO/IEC UTF-8 is designed for multilingual environments, allowing letters, symbols, numbers, and ideograms from around the world to be converted and consistently represented by computers. While the bit patterns of the ASCII characters are sufficient to exchange transaction data in English, most other languages based on the Latin alphabet use additional symbols (umlauts) which are not covered by standard ASCII, such as ü, ä ö or ß (German), ñ (Spanish) and å (Swedish and other Nordic languages). For example, the text message of a credit card transaction from the German cardholder "Günter Groß" will read "G?nter Gro?" and instead of receiving a clear description like "Gebühren für Gäste" in the usage field the system will receive "Geb?hren f?r G?ste". To avoid such garbled text messages, it is imperative that merchants use UTF-8 encoding. NOTE: All field length values in this specification are byte values! The actual number of characters allowed in a field may be less than the given byte value as certain UTF-8 characters are represented using more than one byte. 2.3 Secure Data Transfer To guard confidentiality, cardholder and transaction data is sent over the Internet using HTTP over SSL (HTTPS) at a standard 128-bit encryption. For more information, see the Wirecard system specification HTTPS Gateway, describing how to set up a secure connection to the Wirecard processing environment. 8 Version 3.5.0

9 Card Processing 3 XML Messaging At the highest level, the Wirecard XML structure represents payment or risk management requests and responses. These are submitted, one at a time, as Wirecard Business XML [WIRECARD_BXML] documents. 3.1 Request Format The high-level structure of a Wirecard Business XML document looks like this: <?xml version="1.0" encoding="utf-8"?> <WIRECARD_BXML xmlns:xsi=" <W_REQUEST> <W_JOB> <JobID>Job 1</JobID> <BusinessCaseSignature> ABCDEF</BusinessCaseSignature> <FNC_CC_XYZ> </FNC_CC_ XYZ> </W_JOB> </W_REQUEST> </WIRECARD_BXML> The tag <BusinessCaseSignature> identifies the merchant of record for the transaction within the Wirecard system. Note that the merchant of record may be different than the submitting party in a delegated processing model. The tag <FNC_CC_XYZ> represents a function call resulting in the processing of certain submitted information encapsulated by the <FNC_CC_XYZ></FNC_CC_XYZ> tag-pair. A <W_JOB></W_JOB> tag-pair may include up to 10 different function calls performing a variety of operations as shown below: <W_JOB> <JobID>Job 1</JobID> <BusinessCaseSignature> ABCDEF</ BusinessCaseSignature > <FNC_CC_ABC> </FNC_CC_ ABC> <FNC_CC_DEF> </FNC_CC_ DEF> <FNC_CC_GHI> </FNC_CC_ GHI> </W_JOB> A <FNC_CC_XYZ></FNC_CC_XYZ> tag pair may include up to 5 transactions of the same type. Version

10 3.2 Response Format Each request [<W_REQUEST></W_REQUEST>] submission produces a corresponding XML response document containing results for each submitted transaction request. The high-level structure of a response looks like this: <?xml version="1.0" encoding="utf-8"?> <WIRECARD_BXML xmlns:xsi=" <W_RESPONSE> <W_JOB> <JobID> Job 1</JobID> <FNC_CC_ XYZ> </FNC_CC_ XYZ> </W_JOB> </W_RESPONSE> </WIRECARD_BXML> For tracking purposes three unique identification levels are defined and allow the user to correlate request and response data. From these three levels, only the second and third are tracked by Wirecard. The first level is for the merchant only. <?xml version="1.0" encoding="utf-8"?> <WIRECARD_BXML xmlns:xsi=" <W_REQUEST> <W_JOB> <JobID>user-assigned job-id</jobid> <BusinessCaseSignature> ABCDEF</BusinessCaseSignature> <FNC_CC_TRANSACTION> <FunctionID>user-assigned function-id</functionid> <CC_TRANSACTION mode="demo"> <TransactionID>unique user-assigned transaction-id</transactionid> <CountryCode>DE</CountryCode> <CommerceType></CommerceType> <Amount minorunits="2">50000</amount> <Currency>EUR</Currency> <Usage>DE</Usage> <CREDIT_CARD_DATA> <CreditCardNumber> </CreditCardNumber> <CVC2>1234</CVC2> <ExpirationYear>2009</ExpirationYear> <ExpirationMonth>01</ExpirationMonth> <CardHolderName>John Doe</CardHolderName> </CREDIT_CARD_DATA> <CONTACT_DATA> <IPAddress> </IPAddress> </CONTACT_DATA> </CC_TRANSACTION> </FNC_CC_TRANSACTION> </W_JOB> </W_REQUEST> </WIRECARD_BXML> 10 Version 3.5.0

11 Card Processing The assigned IDs are not necessarily unique in the Wirecard system and serve only for tracking purposes on the user-side. The unique Wirecard system-wide transaction key is the GuWID (Globally unique Wirecard ID) which is returned as a processing results of a transaction: <?xml version="1.0" encoding="utf-8"?> <WIRECARD_BXML xmlns:xsi=" <W_RESPONSE> <W_JOB> <JobID>Job1</JobID> <FNC_CC_ TRANSACTION> <FunctionID> Transaction 1</FunctionID> <CC_TRANSACTION mode="demo"> <TransactionID> </TransactionID> <PROCESSING_STATUS> <GuWID>C </GuWID> <AuthorizationCode>975023</AuthorizationCode> <StatusType>INFO</StatusType> <FunctionResult>ACK</FunctionResult> <TimeStamp> :39:24</TimeStamp> </PROCESSING_STATUS> </CC_TRANSACTION> </FNC_CC_TRANSACTION> </W_JOB> </W_RESPONSE> </WIRECARD_BXML> NOTE: Please store the GuWID returned by the Wirecard system to enable easy and fast processing of transaction related customer service requests! Version

12 4 Test Gateway Merchants planning to integrate the Wirecard platform can test the integration on a dedicated test gateway. It is basically identical to the live HTTPS gateway with the exception that none of the submitted payment requests actually trigger a movement of moneys. As part of the Wirecard quality assurance, merchants are requested to perform several tests on the test gateway in cooperation with the Wirecard support organization prior to connecting to the live HTTPS Gateway. This is to ensure a smooth and flawless communication and transaction data flow between the integrating company and Wirecard. You can send test transactions to our system with varying amounts and in any currency using any of the transaction types described in this specification. 4.1 Test Access To set up your test access please refer to the system specification HTTPS Gateway. 4.2 Error Messages When sending test transactions to our system you can create specific error messages. To do so, please use card number and flag the transaction with the mode type demo. 1. Amounts below EUR or any other currency will generate an acknowledgement (ACK) with the response status error code Amounts between EUR and EUR are reserved for response codes in the ACM error code range. Amount: Call Voice Authorization Number. Amount: Invalid Merchant Number. Amount: Retain Card. Amount: Authorization Declined. Amount: Error in Sequence Number. Amount: Wait Command.... Amount: Date and Time Not Plausible. Example: The amount of EUR ( <Amount>100002<Amount> ) will produce response code 02: <Type>REJECTED</Type> <Number>02</Number> <Message>Call voice authorization number.</message> Any failure not specified by the Wirecard system will produce error code 250: <Type>REJECTED</Type> <Number>250</Number> <Message>System Error.</Message> For a complete list of ACM error codes, see Appendix A. 12 Version 3.5.0

13 Card Processing 4.3 Test Cards Several Visa test cards are available for demo purposes to simulate real transactions. By using any of the test card numbers from the table below, merchants can generate defined transactions with the response codes and messages shown. The card numbers are provided courtesy of VISA for Product Integration Testing (PIT) only. They have no issuer assigned and are generated as follows: First 6 digits are the Bank Identification Number (BIN): digits test number 4 digits Response Code (only the last two are used) 4 digits (Luhn check fulfillment) Please use the following parameters in your demo XML request: Test No. Card No. Exp. Date CVV2 Code Resp. Code Resp. Message / Approved or completed successfully / Call Voice-authorization number; Initialization Data / Invalid merchant number / Retain card / Authorization declined / Invalid transaction / Invalid amount / Invalid card / No action taken / Format Error / Card expired / Suspicion of Manipulation (CVC2) / Requested function not supported / Stolen Card, pick up / Card not in authorizer's database / Terminal ID unknown / Restricted Card / Card issuer temporarily not reachable / The card type is not processed by the authorization center / Processing temporarily not possible Version

14 5 Transaction Modes and Methods Merchants can post payment transactions to the Wirecard processing platform using different modes and methods. The use of two distinct transaction mode helps merchants distinguish between demo transaction and live transaction. In addition to defining a particular mode, merchants can select a transaction method (single transaction, recurring transaction or installment transaction) to signal to the system that the transaction request is to be treated as a one-off payment transaction or that the card data is to be processed and stored with reference for future (related) payment request. The following Chapter discusses these modes and methods in detail. 5.1 Demo Merchants who process with Wirecard for the first time are connected to the payment processing platform in Demo mode. This is to ensure that while testing the card processing XML interface the posted transactions are not accidently routed to the Acquiring Bank for settlement. When a transaction is sent in demo mode using demo card data (see Section 4.3), the Wirecard system automatically verifies if the merchant is configured in demo mode. If the merchant s business case is not configured in demo mode, the system generates a response message with a message tag informing the merchant that the request could not be processes in demo mode as requested. In the parameter tag <CC_TRANSACTION> the merchant can add the attribute <mode= demo >. This attribute must be provided if the merchant wishes to test the card processing interface using a real credit card data instead of the demo data provided in Section 4.3. Request Example attribute mode defines if transaction is sent as simulated transaction or live transaction <?xml version="1.0" encoding="utf-8"?> <WIRECARD_BXML xmlns:xsi=" <W_REQUEST> <W_JOB> <JobID>example ID Purchase J1</JobID> <BusinessCaseSignature>123</BusinessCaseSignature> <FNC_CC_PREAUTHORIZATION> <FunctionID>example ID Purchase F1</FunctionID> <CC_TRANSACTION mode="demo"> <TransactionID>Authorization Initial 1</TransactionID> <Amount>1000</Amount> <Currency>EUR</Currency> <CountryCode>DE</CountryCode> <Usage>Y6162</Usage> <RECURRING_TRANSACTION> <Type>Initial</Type> </RECURRING_TRANSACTION> <CREDIT_CARD_DATA> <CardHolderName>John Doe</CardHolderName> <CreditCardNumber> </CreditCardNumber> <ExpirationYear>2010</ExpirationYear> <ExpirationMonth>12</ExpirationMonth> <CVC2>471</CVC2> </CREDIT_CARD_DATA> 14 Version 3.5.0

15 Card Processing <CORPTRUSTCENTER_DATA> <ADDRESS> <FirstName>John</FirstName> <LastName>Doe</LastName> <Address1>550 South Winchester blvd.</address1> <Address2>P.O. Box 850</Address2> <City>San Jose</City> <ZipCode>95128</ZipCode> <State>CA</State> <Country>US</Country> <Phone>+1(1) </Phone> </ADDRESS> <PERSONINFO> <BirthDate> </BirthDate> </PERSONINFO> </CORPTRUSTCENTER_DATA> <CONTACT_DATA> <IPAddress> </IPAddress> </CONTACT_DATA> </CC_TRANSACTION> </FNC_CC_PREAUTHORIZATION> </W_JOB> </W_REQUEST> </WIRECARD_BXML> Response Example <?xml version="1.0" encoding="utf-8"?> <WIRECARD_BXML xmlns:xsi=" <W_RESPONSE> <W_JOB> <JobID>example ID Purchase J1</JobID> <FNC_CC_PREAUTHORIZATION> <FunctionID>example ID Purchase J1 F1</FunctionID> <CC_TRANSACTION> <TransactionID>Authorization Initial 1</TransactionID> <PROCESSING_STATUS> <GuWID>C </GuWID> <AuthorizationCode>076427</AuthorizationCode> <Info>THIS IS A DEMO TRANSACTION USING CREDIT CARD NUMBER ****0000. NO REAL MONEY WILL BE TRANSFERED.</Info> <StatusType>INFO</StatusType> <FunctionResult>ACK</FunctionResult> <TimeStamp> :21:31</TimeStamp> </PROCESSING_STATUS> </CC_TRANSACTION> </FNC_CC_PREAUTHORIZATION> </W_JOB> </W_RESPONSE> </WIRECARD_BXML> Version

16 5.2 Live When a new merchant has successfully tested his XML interface with the processing platform, the merchant s business case is configured for live processing which means the payment transaction is no longer simulated in demo mode but the data is fully processed and settled by the acquiring bank. Any amount posted in live mode with parameter <Amount> to the Wirecard system will be treated as a real transaction with complete settlement. Response Example The following is a response to a request sent with demo card data on an XML interface configured for live processing: <?xml version="1.0" encoding="utf-8"?> <WIRECARD_BXML xmlns:xsi=" xsi:nonamespaceschemalocation="wirecard.xsd"> <W_RESPONSE> <W_JOB> <JobID>ACCEPTANCE-TEST</JobID> <FNC_CC_TRANSACTION> <FunctionID>GZS-PAGO</FunctionID> <CC_TRANSACTION> <TransactionID>1</TransactionID> <PROCESSING_STATUS> <GuWID>C </GuWID> <AuthorizationCode></AuthorizationCode> <Info>THIS IS A DEMO TRANSACTION USING CREDIT CARD NUMBER ****0000. NO REAL MONEY WILL BE TRANSFERED.</Info> <StatusType>INFO</StatusType> <FunctionResult>NOK</FunctionResult> <ERROR> <Type>DATA_ERROR</Type> <Number>24998</Number> <Message>Demo-card or demo-mode transactions are not allowed without demo terminal mode.</message> <Advice>Inspect your card number or remove attribute mode=''demo'' of tag 'CC_TRANSACTION'</Advice> </ERROR> <TimeStamp> :12:57</TimeStamp> </PROCESSING_STATUS> </CC_TRANSACTION> </FNC_CC_TRANSACTION> </W_JOB> </W_RESPONSE> </WIRECARD_BXML> 16 Version 3.5.0

17 Card Processing 5.3 Single Transaction A single transaction entails a one-off charge to a payment card account. It is typically used by Internet shoppers who place a single, one-time order with a merchant. 5.4 Recurring Transaction In contrast to the above, a recurring transaction describes a payment where the cardholder s account is periodically charged for a repeated delivery and use of a product or service (subscription, membership fee, etc.) over time. A recurring transaction consists of an initial request (which is identical in form and content to a single request) and one or several repeated transaction request messages. The initial request message (which in most cases is an Authorization) contains all relevant card and cardholder data, while the subsequent repeated message (which can be another Authorization, or a Capture or a Purchase) simply references an identifier (the Global Unique Wirecard ID) which is returned with the response message to the initial request. Example: INITIAL/SINGLE Request - Authorization The following is an example of a full-length initial request message containing all card and cardholder data in the CC_TRANSCATION collection element. shows method (defined in attribute type) <CC_TRANSACTION mode="demo"> <TransactionID> </TransactionID> <Amount minorunits="2">50000</amount> <Currency>EUR</Currency> <CountryCode>DE</CountryCode> <Usage>OrderNo-FT345S71 Thank you</usage> <RECURRING_TRANSACTION> <Type>Initial</Type> </RECURRING_TRANSACTION> <CREDIT_CARD_DATA> <CreditCardNumber> </CreditCardNumber> <CVC2>001</CVC2> <ExpirationYear>2009</ExpirationYear> <ExpirationMonth>01</ExpirationMonth> <CardHolderName>John Doe</CardHolderName> </CREDIT_CARD_DATA> <CONTACT_DATA> <IPAddress> </IPAddress> </CONTACT_DATA> <CORPTRUSTCENTER_DATA> <ADDRESS> <FirstName>John</FirstName> <LastName>Doe</LastName> <Address1>550 South Winchester blvd.</address1> <City>San Jose</City> <ZipCode>95128</ZipCode> <State>CA</State> <Country>US</Country> <Phone>+1(202) </Phone> < >John.Doe@ .com</ > </ADDRESS> </CORPTRUSTCENTER_DATA> </CC_TRANSACTION> Version

18 Example: REPEATED Request Authorization The following is an example of a shortened recurring request type Repeated which omits all card and cardholder data in the CC_TRANSCATION collection element and only references the Global Unique Wirecard ID (GuWID). <FNC_CC_AUTHORIZATION> <FunctionID>authorization 1</FunctionID> <CC_TRANSACTION mode="demo"> <TransactionID> </TransactionID> <GuWID>C </GuWID> <RECURRING_TRANSACTION> <Type>Repeated</Type> </RECURRING_TRANSACTION> </CC_TRANSACTION> </FNC_CC_AUTHORIZATION> NOTE: If the payment card data of a customer has changed, all data must be resubmitted in form of an initial transaction. The system will generate a new reference GuWID which must be used for all subsequent transactions by this cardholder Available Transaction Types It is possible to use the recurring functionality with the transaction types: Purchase Authorization Preauthorization Refund All other transactions like Capture, Bookback and Reversal are always processed as Single. Any recurring data that may be included in these XML request messages is simply ignored Permissible Changes It is also possible to send a repeated transaction containing the elements <Amount> and <Currency>, if the entered data differs from the input in the Initial transaction request message. This option is recommended for merchants who offer goods or services in different prices ranges. Example: <CC_TRANSACTION mode="demo"> <TransactionID> </TransactionID> <GuWID>C </GuWID> <Amount>10000</Amount> <Currency>USD</Currency> 18 Version 3.5.0

19 Card Processing Recurring Transaction Flow Merchants can decide themselves at any time which transaction type they wish to place in the recurring process (Authorization, Capture Authorization, Preauthorization, Capture Preauthorization or Purchase) meaning that an initial Authorization can also be followed by Purchase (as repeated transaction) instead of a Capture, referencing the GUWID of the initial request (in this case Authorization). A typical transaction flow using transaction type Purchase for a subscription may look like this: SHOPPER MERCHANT WIRECARD subscription with monthly payments shopper sends a subscription test message with payment details merchant sends Authorization request message* Wirecard returns Authorization response message with GuWID 1 first month payment merchant sends new Authorization, or Purchase or Capture request message with GuWID 1 Wirecard returns response message with GuWID 2 second month payment merchant sends new Authorization, or Purchase or Capture request message with GuWID 1 Wirecard returns response message with GuWID 3 xxx month payment merchant sends new Authorization, or Purchase or Capture request message with GuWID 1 Wirecard returns response message with GuWID xxx * merchant stores shopper s personal data and sends card details to Wirecard Fig. 1: Recurring transaction flow for subscriptions Version

20 Starting with an initial Authorization request, a typical recurring transaction flow using different transaction types may look like this: SHOPPER MERCHANT WIRECARD Order Order Order shopper submits first online order with payment details shopper submits second online order with payment details shopper submits third online order with payment details merchant sends Authorization request message * Wirecard returns Authorization response message with GuWID 1 merchant sends new Authorization request message with GuWID 1 Wirecard returns Authorization response message with GuWID 2 merchant sends new Authorization request message with GuWID 1 Wirecard returns Authorization response message with GuWID 3 Order 4 new product end of week settlement shopper submits fourth online order with payment details merchant sends Capture Authorization with GuWID 1 Wirecard returns Capture Authorization response merchant sends Capture Authorization with GuWID 2 Wirecard returns Capture Authorization response merchant sends Capture Authorization with GuWID 3 Wirecard returns Capture Authorization response merchant sends a Purchase request message Wirecard returns Purchase response message with GuWID 4 * merchant stores shopper s personal data and sends card details to Wirecard Fig. 2: Recurring transaction flow for new product and transaction type 20 Version 3.5.0

21 Card Processing 5.5 Installment Transaction Unlike recurring transactions, this mode allows customers to pay with their charge card for products and services in multiple installments, over a period of time agreed between the cardholder and the merchant. See also the Glossary for a definition of this transaction mode. For example, if a product is priced at 2000 Euros, the merchant can charge a down payment of 1000 Euros to the card at the time of the online purchase followed by one or several installments of a predefined amount. NOTE: Installment transactions are not supported by all acquirers. If a merchant posts a transaction using this payment mode and the acquirer does not support it, the request is flagged, processes and forwarded to the acquirer as a standard purchase transaction Initial and Repeated Installments can be posted as initial and repeated requests for the transaction types Preauthorization, Authorization and Purchase. While the initial request carries all product, contact, cardholder and card details, the repeated installment include only the amount and currency as well as reference identifier to the initial transaction, called GuWID (Global unique Wirecard ID). Example: Initial Purchase Request <?xml version= 1.0" encoding="utf-8"?> <WIRECARD_BXML xmlns:xsi="< <W_REQUEST> <W_JOB> <JobID>ACCEPTANCE-TEST</JobID> <BusinessCaseSignature>770</BusinessCaseSignature> <FNC_CC_PURCHASE> <FunctionID>FirstData-KAAI</FunctionID> <CC_TRANSACTION> <TransactionID>6.1.1</TransactionID> <CommerceType>eCommerce</CommerceType> <Amount>100</Amount> <Currency>EUR</Currency> <CountryCode>DE</CountryCode> <INSTALLMENT_PAYMENT> <Type>Initial</Type> </INSTALLMENT_PAYMENT> <CREDIT_CARD_DATA> <CreditCardNumber>414901****0147</CreditCardNumber> <CVC2>147</CVC2> <ExpirationYear>2009</ExpirationYear> <ExpirationMonth>12</ExpirationMonth> <CardHolderName>John Doe</CardHolderName> </CREDIT_CARD_DATA> <CONTACT_DATA> <IPAddress> </IPAddress> </CONTACT_DATA> </CC_TRANSACTION> </FNC_CC_PURCHASE> </W_JOB> </W_REQUEST> </WIRECARD_BXML> Version

22 Example: Repeated Purchase Request The following is an example of installment request type Repeated containing no card or carholder data. <?xml version="1.0" encoding="utf-8"?> <WIRECARD_BXML xmlns:xsi=" <W_REQUEST> <W_JOB> <JobID>ACCEPTANCE-TEST</JobID> <BusinessCaseSignature>770</BusinessCaseSignature> <FNC_CC_PURCHASE> <FunctionID>FirstData-KAAI</FunctionID> <CC_TRANSACTION> <TransactionID>6.1.1</TransactionID> <CommerceType>eCommerce</CommerceType> <Amount>100</Amount> <Currency>EUR</Currency> <CountryCode>DE</CountryCode> <INSTALLMENT_PAYMENT> <Type>Repeated</Type> </INSTALLMENT_PAYMENT> <CONTACT_DATA> <IPAddress> </IPAddress> </CONTACT_DATA> </CC_TRANSACTION> </FNC_CC_PURCHASE> </W_JOB> </W_REQUEST> </WIRECARD_BXML> 5.6 Implementation Merchants who wish to post recurring and installment transactions please contact the Wirecard Technical Support at for implementation requirements. 5.7 Revoking Recurring and Installment Transactions Cardholders can instruct their issuers to reject recurring and installment payments charged to their card. This they can do for goods and services purchased globally or for a particular merchant. In this case all transactions will be automatically flagged accordingly by the issuing bank and rejected by the Wirecard system. The transaction response message sent to the merchant will return error code 78 or 79. For more details see these codes defined in the Error Code List in Appendix A. 22 Version 3.5.0

23 Card Processing 6 Transaction Types The Wirecard platform processes the following transaction types: Preauthorization Capture Preauthorization Preauthorization Supplement Capture Preauthorization Supplement Authorization Authorization Check Capture Authorization Purchase Notification Bookback Reversal Original Credits Query Refund Request and Responses For every submitted transaction request, the Wirecard system returns a response message, regardless of the outcome of the transaction process (one for a failed process and one for a successful process). Included in every response message is a collection element field called Function name which, depending on the type of transaction processed and its outcome can have different values. Instead of listing the response message elements with each transaction type described in this Chapter, they are referenced by hypertext link from every response example. NOTE: It is important that merchants analyse all incoming XML response messages to verify if the transaction has been processed successfully. The outcome of a transaction is presented in the <PROCESSING_STATUS> element of the response message. See Section Authorization Error Response for an example. Supported Characters All text entered in the request element fields JobID, FunctionID, and TransactionID must conform to the ASCII character codes 32 to 126 (with the exception of code 39). The characters in this ASCII code range are known as printable characters, representing letters, digits, punctuation marks, and a few miscellaneous symbols. Code 32 denotes the space between words, as produced by the large space-bar of a keyboard. All other ASCII codes in the number range from 0 to 31 (known as control characters or non-printing character) are not supported. For more details see Appendix J. Version

24 6.1 Preauthorization A Preauthorization is no guarantee of payment. It only confirms that the card exists and that funds are available at the time of Preauthorization to cover a purchase amount. The funds are not credited at this time but the Preauthorization reduces the available credit limit for that card, so in a sense the funds are reserved for the purchase. If necessary, the initial reserved amount can be altered by using a preauthorization supplementary transaction. To settle the originally preauthorized amount, use the CAPTURE_PREAUTHORIZATION function. The amount settled may be less than the amount authorized. An amount higher than the authorized may also be captured but there is no guarantee. It depends on the acquirer whether a higher amount may be captured and how much higher it can be. Please bear in mind that a preauthorization can be captured multiple times depending on the acquiring process and the protocol used to settle the amount. NOTE: Merchants should verify the timeframe for which the acquirer guarantees the reservation of a preauthorized amount on a credit card. In most cases this timeframe is seven (7) days. For reasons of liability in the context of chargebacks, Wirecard, recommends to agree on a timeframe in the acquiring contract Preauthorization Request Message The preauthorization request may contain the following elements: Element Sett. Data Type Description W_REQUEST man. c This is a collection of Card Preauthorization message elements and their values. W_JOB man. c This is a collection of elements that defines a job within the request. The job may comprise of multiple transactions. JobID opt. an..32 This ID is reserved for merchant system data and can be used for tracking purposes. Although it is optional meaning that it does not have to contain data, the element itself (<JobID> </JobID>) must be provided in the request. Omitting this element will result in a response error. See Appendix J for permissible characters. BusinessCaseSignature man. an..16 This is the unique merchant identifier against which the request is made. FNC_CC_PREAUTHORI ZATION man. c This is a collection of transaction data elements and their values. FunctionID opt. an..32 This ID is reserved for merchant system data and can be used for tracking purposes. Although it is optional meaning that it does not have to contain data, the element itself ( <FunctionID> </FunctionID>) must be provided in the request. Omitting this element will result in a response error. See Appendix J for permissible characters. 24 Version 3.5.0

25 Card Processing Element (Cont.) Sett. Data Type Description CC_TRANSACTION man. c This is a collection of transaction data elements and their values. mode opt. an..32 This is the attribute defining the mode of the transaction. Possible values are: demo live TransactionID man. an..32 This is a unique ID associated with a single transaction, which is created by the merchant and submitted as part of the request. See Appendix J for permissible characters. CommerceType opt. an..23 Possible values: ecommerce MOTO CustomerPresent The default setting of this element is ecommerce. If you like to have your CommerceType set to MOTO or CustomerPresent, please contact Wirecard support to have these options activated. Amount con. n..16 This is the integer amount, defined in the smallest currency unit, for which the transaction is requested (e.g., $10.00 = 1000). The <Amount> element is mandatory for Single and Initial transaction types and if the amount of a Repeated (recurring) transaction differs from the amount of the related Initial transaction. For all other recurring transactions, this element is optional. minorunits opt. n..1 This is an attribute of the element <Amount>. It allows merchants to specify the number of decimal places for each transaction amount and currency. action opt. a..8 This is an attribute of the element <Amount>. It defines what action needs to be taken if the value of the attribute <minorunits> does not match the number of decimals defined in ISO standard The following actions are available: convert The amount is converted to the number of ISO-defined decimals validate The transaction is rejected if the value of <minorunits> does not match the number of decimals defined in ISO This is the default setting. PaymentGroupID opt. an..22 This optional identifier references transaction types of different payment methods (e.g. credit card and EFT) and represents them in a single group for easy monitoring via the ACM. Version

26 Element (Cont.) Sett. Data Type Description GuWID con. an..22 This is the GuWID of the associated initial transaction. It must be included if the transaction type is Repeated. Currency con. a 3 This is the ISO 4217 currency code used for the transaction. It is mandatory if the type of transaction is Single or Initial or if the currency of a Repeated transaction differs from the currency of the related Initial transaction. CountryCode con. a 2 This is the ISO code of the country where the transaction takes place. It is mandatory if the type of transaction is Single or Initial. Usage opt. an..256 This is the field, which is shown on the customer s card statement and can be used by the merchant for reference purposes. This feature is not supported by all the acquirers. The size of this field depends on the acquirer. Please contact Wirecard technical support for further clarification. RECURRING_TRANSA CTION opt. c This is a collection of recurrent information which simplifies the payment transaction message exchange between merchant and Wirecard. A Recurring Transaction is one that is authorized once by the cardholder for a repeated transaction by the merchant (e.g. monthly membership). This collection must be provided if the transaction is Initial or Repeated. Type man. an..8 Possible values: Single Initial Repeated To use the Recurring Transaction function it is necessary to send the first transaction as type initial (<Type>Initial</Type>) and the followup transaction as type repeated (<Type>Repeated</Type>). For type Single and Initial, CVC2 information (see CVC2 element) may be required. The type Single is used as default if the collection is not provided. CREDIT_CARD_DATA con. c This is a collection of credit card data. It is mandatory if the type of transaction is Single or Initial. CreditCardNumber man. n..20 This is a card number against which purchase is made. CVC2 con. n..4 The 3- or 4-digit security code (called CVC2, CVV2 or CID depending on the credit card brand) that appears on the back of a credit card following the card number. This code does not appear on imprints. 26 Version 3.5.0

27 Card Processing Element (Cont.) Sett. Data Type Description ExpirationYear man. YYYY The expiry year for the card against which the purchase will be made. ExpirationMonth man. MM The expiry month for the card against which the purchase will be made. CardHolderName man. a..256 Any person who opens a card account and makes purchases using a card. CardStartYear opt. YYYY This is the start year that is required for Switch/Solo/Maestro card only. CardStartMonth opt. MM This is the start month that is required for Switch/Solo/Maestro card only. CardIssueNumber opt. n..2 This is the card issue number as it appears on some Switch/Solo/Maestro cards. CONTACT_DATA opt. c This is the collection of the contact information. IPAddress opt. an..15 This is the IP address of the end user making the purchase. It must be provided in dotdecimal notation consisting of up to 15 characters in length. CORPTRUSTCENTER_ DATA con. c This is a collection of risk management related elements and values. This request level along with the related elements listed below are mandatory if the type of transaction is Single or Initial and additionally the card transaction process is to include a risk validation. ADDRESS man. c This is a collection of cardholder s billing address elements and values. It is highly recommended to provide these elements. This element is mandatory if the CORPTRUSTCENTER_DATA level is to be included in the XML request. FirstName man. an..128 This is the cardholder s first name. LastName man. an..128 This is the cardholder s last name. Address1 man. ans..256 This is the first address field of the cardholder. It is recommended to enter the street name in this field. Address2 opt. ans..256 This is the second address field of the cardholder. It is recommended to enter the street number in this field. City con. an..32 This field shows the city associated with the cardholder. ZipCode opt. an..12 This field shows the cardholder s zip code. State con. a 2 This is the state code is associated with the cardholder s credit card. It must be provided only by US and Canadian merchants accept payments from US or Canadian residents. Country opt. a 2 This is the ISO country code associated with the cardholder. Version

28 Element (Cont.) Sett. Data Type Description Phone opt. an..32 This is the cardholder s phone number. It can be provided in one of the following formats: +xxx(yyy)zzz-zzzz-ppp +xxx (yyy) zzz zzzz ppp +xxx(yyy)zzz/zzzz/ppp +xxx(yyy)zzzzzzzppp where: xxx = country code yyy = national direct dialing prefix zzzzzzz = area / city code and local number ppp = PBX extension Separators such as /, \ or - are permissible. For example, a typical international number would be +44(0) indicating PBX extension 739 at phone number with the national prefix 0 and country code 44. For countries which do not have a national prefix, the format must be configured with or without a space in brackets. Example: +420() con. an..256 This is the cardholder s address. PERSONINFO opt. c This is a collection of personal information. It is required by some countries for risk assessment of payment transactions. To avoid a transaction being rejected due to risk, it is recommended to provide this information (especially for the US market). DRIVERS_LICENSE opt. c This field shows a collection of driver license information. LicenseNumber opt. an..32 In this field the debtor s driver license number is entered. State con. a 2 This is the state code is associated with the cardholder s credit card. It must be provided only by US and Canadian merchants accept payments from US or Canadian residents. Country opt. a 2 This is the ISO country code where the license was issued. BirthDate opt. YYYY-MM- This field shows the debtor s birth date. DD TaxIdentificationNumber opt. an..32 This is the debtor s TIN. 28 Version 3.5.0

29 Card Processing Example: Single / Initial Preauthorization Request <?xml version="1.0" encoding="utf-8"?> <WIRECARD_BXML xmlns:xsi=" <W_REQUEST> <W_JOB> <JobID>Job 1</JobID> <BusinessCaseSignature> ABCDEF</BusinessCaseSignature> <FNC_CC_PREAUTHORIZATION> <FunctionID>Preauthorization 1</FunctionID> <CC_TRANSACTION mode="demo"> <TransactionID> </TransactionID> <CommerceType>eCommerce</CommerceType> <Amount minorunits="2">1200</amount> <Currency>EUR</Currency> <CountryCode>DE</CountryCode> <Usage>OrderNo-FT345S71 Thank you</usage> <RECURRING_TRANSACTION> <Type>Initial</Type> </RECURRING_TRANSACTION> <CREDIT_CARD_DATA> <CreditCardNumber> </CreditCardNumber> <CVC2>001</CVC2> <ExpirationYear>2009</ExpirationYear> <ExpirationMonth>01</ExpirationMonth> <CardHolderName>John Doe</CardHolderName> </CREDIT_CARD_DATA> <CONTACT_DATA> <IPAddress> </IPAddress> </CONTACT_DATA> <CORPTRUSTCENTER_DATA> <ADDRESS> <FirstName>John</FirstName> <LastName>Doe</LastName> <Address1>550 South Winchester blvd.</address1> <Address2>P.O. Box 850</Address2> <City>San Jose</City> <ZipCode>95128</ZipCode> <State>CA</State> <Country>US</Country> <Phone>+1(202) </Phone> < >John.Doe@ .com</ > </ADDRESS> <PERSONINFO> <DRIVERS_LICENSE> <LicenseNumber>IL </LicenseNumber> <State>IL</State> <Country>US</Country> </DRIVERS_LICENSE> <BirthDate> </BirthDate> <TaxIdentificationNumber> </TaxIdentificationNumber> </PERSONINFO> </CORPTRUSTCENTER_DATA> </CC_TRANSACTION> </FNC_CC_PREAUTHORIZATION> </W_JOB> </W_REQUEST> </WIRECARD_BXML> Version

30 Example: Repeated Preauthorization Request <?xml version="1.0" encoding="utf-8"?> <WIRECARD_BXML xmlns:xsi=" <W_REQUEST> <W_JOB> <JobID>Job 1</JobID> <BusinessCaseSignature> ABCDEF</BusinessCaseSignature> <FNC_CC_PREAUTHORIZATION> <FunctionID>Preauthorization 1</FunctionID> <CC_TRANSACTION mode="demo"> <TransactionID> </TransactionID> <GuWID>C </GuWID> <RECURRING_TRANSACTION> <Type>Repeated</Type> </RECURRING_TRANSACTION> </CC_TRANSACTION> </FNC_CC_PREAUTHORIZATION> </W_JOB> </W_REQUEST> </WIRECARD_BXML> 30 Version 3.5.0

31 Card Processing Preauthorization Successful Response Please refer to Section Standard Response Message for the field definitions of the preauthorization successful response. Example: <?xml version="1.0" encoding="utf-8"?> <WIRECARD_BXML xmlns:xsi=" <W_RESPONSE> <W_JOB> <JobID>job 1</JobID> <FNC_CC_PREAUTHORIZATION> <FunctionID>function 1</FunctionID> <CC_TRANSACTION mode="demo"> <TransactionID> </TransactionID> <PROCESSING_STATUS> <GuWID>C </GuWID> <AuthorizationCode>153620</AuthorizationCode> <FunctionResult>ACK</FunctionResult> <TimeStamp> :39:24</TimeStamp> </PROCESSING_STATUS> </CC_TRANSACTION> </FNC_CC_PREAUTHORIZATION> </W_JOB> </W_RESPONSE> </WIRECARD_BXML> Preauthorization Error Response Please refer to Section Standard Response Message for the field definitions of the preauthorization error response. Example: <?xml version="1.0" encoding="utf-8"?> <WIRECARD_BXML xmlns:xsi=" <W_RESPONSE> <W_JOB> <JobID>job 1</JobID> <FNC_CC_PREAUTHORIZATION> <FunctionID>function 1</FunctionID> <CC_TRANSACTION mode="demo"> <TransactionID> </TransactionID> <PROCESSING_STATUS> <GuWID>C </GuWID> <AuthorizationCode>799961</AuthorizationCode> <StatusType>INFO</StatusType> <FunctionResult>NOK</FunctionResult> <ERROR> <Type>REJECTED</Type> <Number>05</Number> <Message>Authorization Declined.</Message> <Advice>It is not possible to book the given amount from the credit account, e. g. limit is exceeded.</advice> </ERROR> <TimeStamp> :39:24</TimeStamp> </PROCESSING_STATUS> </CC_TRANSACTION> </FNC_CC_PREAUTHORIZATION> </W_JOB> </W_RESPONSE> </WIRECARD_BXML> Version