Card Processing. Merchant Specification. Version 3.5.0

(1)

Card Processing

Merchant Specification

(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.

Printed in Germany / European Union Version 3.5.0

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-85630 Grasbrunn Germany phone: +49 89 4424 0640 e-mail: [email protected]

(3)

1 Introduction ...5

1.1 Audience ... 5

1.2 Document Conventions ...5

1.3 Software Requirements...5

1.4 References ...5

1.5 Revision History ...6

2 Overview ...7

2.1What is XML ... 7

2.2 XML Messages ...7

2.3 Secure Data Transfer ...8

3 XML Messaging ...9

3.1 Request Format ... 9

3.2 Response Format... 10

4 Test Gateway ...12

4.1 Test Access ...12

4.2 Error Messages ...12

4.3 Test Cards ...13

5 Transaction Modes and Methods ... 14

5.1 Demo ...14

5.2 Live ...16

5.3 Single Transaction ...17

5.4 Recurring Transaction ...17

5.5 Installment Transaction ... 21

5.6 Implementation ...22

(4)

6 Transaction Types ... 23

6.1 Preauthorization ... 24

6.2 Capture Preauthorization ... 32

6.3 Preauthorization Supplement ... 36

6.4 Capture Preauthorization Supplement ... 39

6.5 Authorization ... 44

6.6 Authorization Check ... 52

6.7 Capture Authorization ... 54

6.8 Purchase ... 59

6.9 Notification ... 70

6.10 Bookback ... 73

6.11 Reversal ... 77

6.12 Original Credits ... 81

6.13 Query ... 86

6.14 Refund ... 91

6.15 Standard Response Message ... 96

7 Address Verification Service ... 98

7.1 AVS Response Message ... 98

7.2 Wirecard AVS Response Codes... 99

7.3 Wirecard Response Code Mapping... 99

8 Glossary ... 101

Appendix A: Error Codes ... 105

Appendix B: AVS Codes ... 120

Appendix C: Airline Market Segment ... 121

Appendix D: Car Rental Market Segment ... 124

Appendix E: Fleet Card Market Segment ... 128

Appendix F: Hotel Market Segment ... 130

Appendix G: Travel Market Segment ... 134

Appendix H: XML Extensions ... 136

Appendix I: Purchasing Process ... 138

(5)

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)

(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

2007-07-19 2.0.0 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.

2007-09-04 2.1.0 Airline Market and Travel Market segments (Appendices C and F) updated with different tax (VAT) type fields and identifiers. Query request updated.

2007-10-09 2.2.0 Authorization Code removed from Capture, Refund, Bookback, etc Only required in Notification Requests. Some minor changes. 2007-10-31 2.3.0 Elements in Airline Market and Travel Market segments (Appendices

C and F) updated. New code added in Error Messages (Appendix A). 2007-11-05 2.3.1 Minor changes.

2007-11-29 2.4.0 Transaction Type Capture removed from notice. Data Type for Address fields changed to ANS (alphanumeric and special characters).

2008-03-04 2.5.0 Single/Initial Request examples updated. Card Start Date & Card Issue Number for Switch/Solo/Maestro changed to optional. 2008-04-07 3.0.0 Chapter 7 on AVS incorporated. Query date format updated. 2008-05-14 3.0.1 VAT field settings changed form mandatory to conditional - with

comment "relevant for AirPlus Acceptance UATP transactions only". FareBasis data type changed from a6 to an6.

2008-07-22 3.0.2 Note added to Refund examples.

2008-09-01 3.1.0 DTD Reference (xsi:noNamespaceSchemaLocation="wirecard.xsd") removed from XML examples and Appendix D (Car Rental market segment) incorporated.

2008-09-22 3.1.1 minor updates.

2008-10-15 3.2.0 Section 6.12 (Original Credits) added. Sections 6.10 (Bookback) and 6.14 (Refund) updated. Some minor updates.

2008-11-05 3.2.1 Section 6.12 (Original Credits) updated.

2009-02-10 3.3.0 Phone number format updated. Cross references incorporated. 2009-06-30 3.4.0 <FunctionResult>ACK</FunctionResult> in XML samples changed

to <FunctionResult>PENDING</FunctionResult>. IP address format description changed. Error code 20001 included. CountryCode in OCT request table included. Section 4.3 (Test Cards) incorporated. Section 5 updated. Description of parameter <State> rewritten. 2009-08-14 3.5.0 Error Codes (Appendix A) updated. Example of Reversal

(7)

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

2.2.1 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.

(8)

2.2.2 Notations

The following notations define the data type formats of message elements.

2.2.3 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 10646. 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.

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.

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, 00-99 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

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.

(9)

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="http://www.w3.org/1999/XMLSchema-instance"> <W_REQUEST> <W_JOB> <JobID>Job 1</JobID> <BusinessCaseSignature>0123456789ABCDEF</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>0123456789ABCDEF</ BusinessCaseSignature > <FNC_CC_ABC> … </FNC_CC_ ABC> <FNC_CC_DEF> … </FNC_CC_ DEF> <FNC_CC_GHI> … </FNC_CC_ GHI> </W_JOB>

(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="http://www.w3.org/1999/XMLSchema-instance"> <W_RESPONSE>

<W_JOB>

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="http://www.w3.org/1999/XMLSchema-instance"> <W_REQUEST> <W_JOB> <JobID>user-assigned job-ID</JobID> <BusinessCaseSignature>0123456789ABCDEF</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>4200000000000000</CreditCardNumber> <CVC2>1234</CVC2> <ExpirationYear>2009</ExpirationYear> <ExpirationMonth>01</ExpirationMonth> <CardHolderName>John Doe</CardHolderName> </CREDIT_CARD_DATA> <CONTACT_DATA> <IPAddress>192.168.1.1</IPAddress> </CONTACT_DATA> </CC_TRANSACTION> </FNC_CC_TRANSACTION> </W_JOB> </W_REQUEST> </WIRECARD_BXML>

(11)

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="http://www.w3.org/1999/XMLSchema-instance"> <W_RESPONSE> <W_JOB> <JobID>Job1</JobID> <FNC_CC_ TRANSACTION>

<FunctionID> Transaction 1</FunctionID> <CC_TRANSACTION mode="demo"> <TransactionID>457892347623478</TransactionID> <PROCESSING_STATUS> <GuWID>C0098854100980113920</GuWID> <AuthorizationCode>975023</AuthorizationCode> <StatusType>INFO</StatusType> <FunctionResult>ACK</FunctionResult> <TimeStamp>2001-01-31 20: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

(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 4200000000000000 and flag the transaction with the mode type ‘demo’.

1. Amounts below EUR 1000.00 or any other currency will generate an acknowledgement (ACK) with the response status error code 9500.

2. Amounts between EUR 1000.02 and EUR 1000.98 are reserved for response codes in the ACM error code range.

Amount: 100002 - 02 Call Voice Authorization Number. Amount: 100003 - 03 Invalid Merchant Number. Amount: 100004 - 04 Retain Card.

Amount: 100005 - 05 Authorization Declined. Amount: 100006 - 06 Error in Sequence Number. Amount: 100009 - 09 Wait Command.

...

Amount: 100098 - 98 Date and Time Not Plausible.

Example:

The amount of EUR 1000.02( <Amount>100002<Amount> ) will produce response code 02: <Type>REJECTED</Type>

<Message>Call voice authorization number.</Message>

Any failure not specified by the Wirecard system will produce error code 250: <Type>REJECTED</Type>

<Message>System Error.</Message>

(13)

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): 401200

2 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 1 4012000100000007 01/19 007 00 Approved or completed successfully

2 4012000200020004 01/19 004 02 Call Voice-authorization number; Initialization Data

3 4012000300030002 01/19 002 03 Invalid merchant number 4 4012000400040000 01/19 999 04 Retain card 5 4012000500050008 01/19 008 05 Authorization declined 6 4012000600120008 01/19 008 12 Invalid transaction 7 4012000700130006 01/19 006 13 Invalid amount 8 4012000800140004 01/19 004 14 Invalid card 9 4012000900210004 01/19 004 21 No action taken 10 4012001000300000 01/19 999 30 Format Error 11 4012001100330006 01/19 006 33 Card expired 12 4012001200340004 01/19 004 34 Suspicion of Manipulation (CVC2) 13 4012001300400005 01/19 005 40 Requested function not supported 14 4012001300430002 01/19 002 43 Stolen Card, pick up

15 4012001500560004 01/19 004 56 Card not in authorizer's database 16 4012001600580001 01/19 001 58 Terminal ID unknown

17 4012001700620004 01/19 004 62 Restricted Card

18 4012001800910008 01/19 008 91 Card issuer temporarily not reachable

19 4012001900920006 01/19 006 92 The card type is not processed by the authorization center

20 4012002000960009 01/19 009 96 Processing temporarily not possible

(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 <?xml version="1.0" encoding="UTF-8"?> <WIRECARD_BXML xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance"> <W_REQUEST> <W_JOB>

<JobID>example ID Purchase J1</JobID>

<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>5500000000000000</CreditCardNumber> <ExpirationYear>2010</ExpirationYear> <ExpirationMonth>12</ExpirationMonth> <CVC2>471</CVC2> </CREDIT_CARD_DATA>

attribute mode defines if transaction is sent as simulated transaction or live transaction

(15)

<CORPTRUSTCENTER_DATA> <ADDRESS>

<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)8323933406</Phone> <Email>[email protected]</Email> </ADDRESS> <PERSONINFO> <BirthDate>1982-04-17</BirthDate> </PERSONINFO> </CORPTRUSTCENTER_DATA> <CONTACT_DATA> <IPAddress>127.0.0.1</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="http://www.w3.org/1999/XMLSchema-instance"> <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>

<Info>THIS IS A DEMO TRANSACTION USING CREDIT CARD NUMBER 550000****0000. NO REAL MONEY WILL BE TRANSFERED.</Info> <StatusType>INFO</StatusType> <FunctionResult>ACK</FunctionResult> <TimeStamp>2009-06-02 16:21:31</TimeStamp> </PROCESSING_STATUS> </CC_TRANSACTION> </FNC_CC_PREAUTHORIZATION> </W_JOB> </W_RESPONSE> </WIRECARD_BXML>

(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="http://www.w3.org/1999/XMLSchema-instance" 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>C895978124540997772104</GuWID> <AuthorizationCode></AuthorizationCode>

<Info>THIS IS A DEMO TRANSACTION USING CREDIT CARD NUMBER 420000****0000. NO REAL MONEY WILL BE TRANSFERED.</Info> <StatusType>INFO</StatusType>

<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>2009-06-19 13:12:57</TimeStamp> </PROCESSING_STATUS> </CC_TRANSACTION> </FNC_CC_TRANSACTION> </W_JOB> </W_RESPONSE> </WIRECARD_BXML>

(17)

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.

<CC_TRANSACTION mode="demo">

<Usage>OrderNo-FT345S71 Thank you</Usage> <RECURRING_TRANSACTION>

<Type>Initial</Type> </RECURRING_TRANSACTION> <CREDIT_CARD_DATA> <CreditCardNumber>4200000000000000</CreditCardNumber> <CVC2>001</CVC2> <ExpirationYear>2009</ExpirationYear> <ExpirationMonth>01</ExpirationMonth> <CardHolderName>John Doe</CardHolderName> </CREDIT_CARD_DATA> <CONTACT_DATA> <IPAddress>192.168.1.1</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)555-1234</Phone> <Email>[email protected]</Email> </ADDRESS> </CORPTRUSTCENTER_DATA> </CC_TRANSACTION> shows method (defined in attribute type)

(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>9457892347623478</TransactionID> <GuWID>C328668112556109425394</GuWID> <RECURRING_TRANSACTION> <Type>Repeated</Type> </RECURRING_TRANSACTION> </CC_TRANSACTION> </FNC_CC_AUTHORIZATION> …

5.4.1 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.

5.4.2 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>9457892347623478</TransactionID> <GuWID>C328668112556109425394</GuWID> <Amount>10000</Amount> <Currency>USD</Currency> …

NOTE: If the payment card data of a customer has changed, all data must be

re-submitted 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.

(19)

5.4.3 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:

Fig. 1: Recurring transaction flow for subscriptions

SHOPPER MERCHANT WIRECARD

shopper sends a subscription

test message with payment details merchant sends Authorization request message*

Wirecard returns Authorization response message with GuWID 1 subscription

with monthly payments

merchant sends new Authorization, or Purchase or Capture request

message with GuWID 1 Wirecard returns response

message with GuWID 2

*merchant stores shopper‘s personal data and sends card details to Wirecard

Wirecard returns response message with GuWID 3 first month

payment

second month payment

xxx month

payment _{Wirecard returns response} message with GuWID xxx merchant sends new Authorization,

or Purchase or Capture request message with GuWID 1

shopper sends a subscription

payment

xxx month

or Purchase or Capture request message with GuWID 1 shopper sends a subscription

payment

xxx month

or Purchase or Capture request message with GuWID 1

(20)

Starting with an initial Authorization request, a typical recurring transaction flow using different transaction types may look like this:

Fig. 2: Recurring transaction flow for new product and transaction type shopper submits first online order

with payment details

merchant sends Authorization request message *

Wirecard returns Authorization response message with GuWID 1

Order 2 € 450 Order 3 € 175 Order 1 € 350

shopper submits second online order with payment details

merchant sends new Authorization request message with GuWID 1 Wirecard returns Authorization response message with GuWID 2 shopper submits third online order

with payment details merchant sends new Authorization_{request message with GuWID 1}

Order 4

new product shopper submits fourth online

order with payment details

end of week settlement

merchant sends Capture Authorization with GuWID 1

Wirecard returns Capture Authorization response

merchant sends a Purchase request message

Wirecard returns Purchase response message with GuWID 4

Wirecard returns Capture Authorization response merchant sends Capture Authorization with GuWID 3

Wirecard returns Capture Authorization response shopper submits first online order

with payment details

merchant sends Authorization request message *

Order 2 € 450 Order 3 € 175 Order 1 € 350

shopper submits second online order with payment details

merchant sends new Authorization request message with GuWID 1 Wirecard returns Authorization response message with GuWID 2 shopper submits third online order

with payment details merchant sends new Authorization_{request message with GuWID 1}

Order 4

new product shopper submits fourth online

order with payment details

end of week settlement

merchant sends a Purchase request message

Wirecard returns Purchase response message with GuWID 4

Wirecard returns Capture Authorization response merchant sends Capture Authorization with GuWID 3

(21)

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.

5.5.1 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="<http://www.w3.org/1999/XMLSchema-instance>"> <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>192.168.1.1</IPAddress> </CONTACT_DATA> </CC_TRANSACTION> </FNC_CC_PURCHASE> </W_JOB> </W_REQUEST>

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.

(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="http://www.w3.org/1999/XMLSchema-instance"> <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>192.168.1.1</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 [email protected] 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.

(23)

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.

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.

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 6.53 - Authorization Error Response for an example.

(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.

6.1.1 Preauthorization Request Message

The preauthorization request may contain the following elements:

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.

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.

(25)

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 4217. 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 4217. 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. Element (Cont.) Sett. Data Type Description

(26)

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 3166-1 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 follow-up 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.

(27)

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 dot-decimal 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 3166-1 country code

associated with the cardholder. Element (Cont.) Sett. Data Type Description

(28)

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)555-5555-739” indicating PBX extension 739 at phone number 555-5555 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()52-5454-742.

Email con. an..256 This is the cardholder’s email 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 3166-1 country code where

the license was issued.

BirthDate opt.

YYYY-MM-DD

This field shows the debtor’s birth date. TaxIdentificationNumber opt. an..32 This is the debtor’s TIN.

(29)

Example: Single / Initial Preauthorization Request <?xml version="1.0" encoding="UTF-8"?> <WIRECARD_BXML xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance"> <W_REQUEST> <W_JOB> <JobID>Job 1</JobID> <BusinessCaseSignature>0123456789ABCDEF</BusinessCaseSignature> <FNC_CC_PREAUTHORIZATION> <FunctionID>Preauthorization 1</FunctionID> <CC_TRANSACTION mode="demo"> <TransactionID>9457892347623478</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>4200000000000000</CreditCardNumber> <CVC2>001</CVC2> <ExpirationYear>2009</ExpirationYear> <ExpirationMonth>01</ExpirationMonth> <CardHolderName>John Doe</CardHolderName> </CREDIT_CARD_DATA> <CONTACT_DATA> <IPAddress>192.168.1.1</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)555-1234</Phone> <Email>[email protected]</Email> </ADDRESS> <PERSONINFO> <DRIVERS_LICENSE> <LicenseNumber>IL213839304</LicenseNumber> <State>IL</State> <Country>US</Country> </DRIVERS_LICENSE> <BirthDate>1967-12-01</BirthDate> <TaxIdentificationNumber>1112223333</TaxIdentificationNumber> </PERSONINFO> </CORPTRUSTCENTER_DATA> </CC_TRANSACTION> </FNC_CC_PREAUTHORIZATION> </W_JOB> </W_REQUEST> </WIRECARD_BXML>

(30)

Example: Repeated Preauthorization Request <?xml version="1.0" encoding="UTF-8"?> <WIRECARD_BXML xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance"> <W_REQUEST> <W_JOB> <JobID>Job 1</JobID> <BusinessCaseSignature>0123456789ABCDEF</BusinessCaseSignature> <FNC_CC_PREAUTHORIZATION> <FunctionID>Preauthorization 1</FunctionID> <CC_TRANSACTION mode="demo"> <TransactionID>9457892347623478</TransactionID> <GuWID>C325436112551595096071</GuWID> <RECURRING_TRANSACTION> <Type>Repeated</Type> </RECURRING_TRANSACTION> </CC_TRANSACTION> </FNC_CC_PREAUTHORIZATION> </W_JOB> </W_REQUEST> </WIRECARD_BXML>

(31)

6.1.2 Preauthorization Successful Response

Please refer to Section 6.14 - Standard Response Message for the field definitions of the preauthorization successful response.

Example: <?xml version="1.0" encoding="UTF-8"?> <WIRECARD_BXML xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance"> <W_RESPONSE> <W_JOB> <JobID>job 1</JobID> <FNC_CC_PREAUTHORIZATION> <FunctionID>function 1</FunctionID> <CC_TRANSACTION mode="demo"> <TransactionID>9457892347623478</TransactionID> <PROCESSING_STATUS> <GuWID>C242720181323966504820</GuWID> <AuthorizationCode>153620</AuthorizationCode> <FunctionResult>ACK</FunctionResult> <TimeStamp>2001-01-31 20:39:24</TimeStamp> </PROCESSING_STATUS> </CC_TRANSACTION> </FNC_CC_PREAUTHORIZATION> </W_JOB> </W_RESPONSE> </WIRECARD_BXML>

6.1.3 Preauthorization Error Response

Please refer to Section 6.14 - Standard Response Message for the field definitions of the preauthorization error response.

Example: <?xml version="1.0" encoding="UTF-8"?> <WIRECARD_BXML xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance"> <W_RESPONSE> <W_JOB> <JobID>job 1</JobID> <FNC_CC_PREAUTHORIZATION> <FunctionID>function 1</FunctionID> <CC_TRANSACTION mode="demo"> <TransactionID>9457892347623478</TransactionID> <PROCESSING_STATUS> <GuWID>C242720181323966504827</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>2001-01-31 20:39:24</TimeStamp> </PROCESSING_STATUS> </CC_TRANSACTION> </FNC_CC_PREAUTHORIZATION> </W_JOB> </W_RESPONSE> </WIRECARD_BXML>

(32)

6.2 Capture Preauthorization

A Capture Preauthorization is similar to the Capture Authorization. For a Capture

Preauthorization request, a valid GuWID from a former Preauthorization request is required. The amount settled may be less than the amount authorized. The amount remaining on the authorization is available for further captures as long as the authorization period does not expire. Please note that in some cases a pre-authorization can only be captured once. This is dependent of the acquirer policies.

An amount higher than the authorized may also be captured but there is no guarantee. It depends on the acquirer whether a greater amount may be captured and how much greater this can be. The recommended value is up to 5% of the original amount.

A capture of an authorization transaction (e.g. ‘authorization’, ‘preauthorization’,

‘preauthorization supplement’) can be made up to 7 days following the original request. In exceptional cases this period may be longer (depending on the acquirer and issuing bank). Please contact Wirecard technical support for further information on the expiration period.

6.2.1 Capture Preauthorization Request Message

The capture preauthorization request may contain the following elements: Element Sett. Data Type Description

W_REQUEST man. c This is a collection of Card Capture Pre-authorization 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 still be provided in the XML request. Omitting the element will result in a response error. See Appendix J for permissible

characters. BusinessCaseSignatu

re

man. an..16 This is the unique merchant identifier against which the request is made.

FNC_CC_CAPTURE_ PREAUTHORIZATION

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 still be provided in the XML request. Omitting the element will result in a response error. See Appendix J for permissible characters.

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

(33)

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.

SalesDate opt.

YYYY-MM-DD

This is the calendar date of the purchase. It is optional and can be included if the sales date is different from the date the transaction is posted for processing. It can be backdated up to 30 days.

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. GuWID man. an..22 This is the Wirecard transaction ID of the

previous Preauthorization request. 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 tranactions, 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 4217. 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 4217. This is the default setting.

CountryCode con. a 2 This is the ISO 3166-1 code of the country where the transaction takes place. It is conditional meaning that it must be added if this parameter is included in the corresponding Authorization /Preauthorization. Also, the country must be identical with the country mentioned in the corresponding Authorization /Preauthorization.

NOTE: For some acquirers this is a mandatory

request field. Element (Cont.) Sett. Data Type Description

(34)

Example: <?xml version="1.0" encoding="UTF-8"?> <WIRECARD_BXML xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance"> <W_REQUEST> <W_JOB> <JobID>job 1</JobID> <BusinessCaseSignature>0123456789ABCDEF</BusinessCaseSignature> <FNC_CC_CAPTURE_PREAUTHORIZATION> <FunctionID>capturing 1</FunctionID> <CC_TRANSACTION mode=“demo“> <TransactionID>9457892347623478</TransactionID> <SalesDate>2007-04-30</SalesDate> <GuWID>C242720181323966504820</GuWID> <Amount minorunits="2">600</Amount> <Usage>OrderNo-FT345S71 Thank you</Usage> <COST_CENTER_DATA> <CostAccountNumber>78500</CostAccountNumber> <ServiceDate>2006-12-17</ServiceDate> </COST_CENTER_DATA> </CC_TRANSACTION> </FNC_CC_CAPTURE_PREAUTHORIZATION> </W_JOB> </W_REQUEST> </WIRECARD_BXML>

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. The usage field for the capture overrides the field value provided with the authorization. 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.

COST_CENTER_DAT A

opt. c This is a collection of the cost center data of an organization.

EmployeeID opt. an..17 This request element helps identify the employee.

DepartmentCode opt. an..17 This code describes the organization’s department.

CostAccountNumber opt. an..17 This field is reserved for the number defining the cost account.

AccountingUnit opt. an..17 This element is reserved for accounting units. AccountNumber opt. an..17 This field shows the account number.

ServiceDate opt. YYYY-MM-DD

This field shows the date the service is provided (departure date), e.g. 2006-10-14.

ProjectNumber opt. an..17 This is the number of the project. OrderNumber opt. an..17 This is the order number.

ActionNumber opt. an..32 This is the action number.

Destination opt. an..17 This element defines the travel destination. Element (Cont.) Sett. Data Type Description

(35)

6.2.2 Capture Preauthorization Successful Response

Please refer to Section 6.14 - Standard Response Message for the field definitions of the capture preauthorization successful response.

Example: <?xml version="1.0" encoding="UTF-8"?> <WIRECARD_BXML xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance"> <W_RESPONSE> <W_JOB> <JobID>job 1</JobID> <FNC_CC_CAPTURE_PREAUTHORIZATION> <FunctionID>function 1</FunctionID> <CC_TRANSACTION mode="demo"> <TransactionID>9457892347623478</TransactionID> <PROCESSING_STATUS> <GuWID>C242720181323966504820</GuWID> <FunctionResult>PENDING</FunctionResult> <TimeStamp>2001-01-31 20:39:24</TimeStamp> </PROCESSING_STATUS> </CC_TRANSACTION> </FNC_CC_CAPTURE_PREAUTHORIZATION> </W_JOB> </W_RESPONSE> </WIRECARD_BXML>

6.2.3 Capture Preauthorization Error Response

Please refer to Section 6.14 - Standard Response Message for the field definitions of the capture preauthorization error response.

Example: <?xml version="1.0" encoding="UTF-8"?> <WIRECARD_BXML xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance"> <W_RESPONSE> <W_JOB> <JobID>job 1</JobID> <FNC_CC_CAPTURE_PREAUTHORIZATION> <FunctionID>function 1</FunctionID> <CC_TRANSACTION mode="demo"> <TransactionID>9457892347623478</TransactionID> <PROCESSING_STATUS> <GuWID>C242720181323966504827</GuWID> <StatusType>INFO</StatusType> <FunctionResult>NOK</FunctionResult> <ERROR> <Type>REJECTED</Type> <Number>21</Number>

<Message>No action taken.</Message> </ERROR> <TimeStamp>2001-01-31 20:39:24</TimeStamp> </PROCESSING_STATUS> </CC_TRANSACTION> </FNC_CC_CAPTURE_PREAUTHORIZATION> </W_JOB> </W_RESPONSE> </WIRECARD_BXML>

Card Processing. Merchant Specification. Version 3.5.0

Card Processing

Merchant Specification

COPYRIGHT

TRADEMARKS

CONTACT INFORMATION

Contents

1

Introduction ...5

1.1

Audience ... 5

1.2

Document Conventions ...5

1.3

Software Requirements...5

1.4

References ...5

1.5

Revision History ...6

2

Overview ...7

2.1What is XML ... 7

2.2

XML Messages ...7

2.3

Secure Data Transfer ...8

3

XML Messaging ...9

3.1

Request Format ... 9

3.2

Response Format... 10

4

Test Gateway ...12

4.1

Test Access ...12

4.2

Error Messages ...12

4.3

Test Cards ...13

5

Transaction Modes and Methods ... 14

5.1

Demo ...14

5.2

Live ...16

5.3

Single Transaction ...17

5.4

Recurring Transaction ...17

5.5

Installment Transaction ... 21

5.6

Implementation ...22

6

Transaction Types ... 23

6.1

Preauthorization ... 24

6.2

Capture Preauthorization ... 32

6.3

Preauthorization Supplement ... 36

6.4

Capture Preauthorization Supplement ... 39

6.5

Authorization ... 44

6.6

Authorization Check ... 52

6.7

Capture Authorization ... 54

6.8

Purchase ... 59

6.9

Notification ... 70

6.10 Bookback ... 73

6.11 Reversal ... 77

6.12 Original Credits ... 81

6.13 Query ... 86

6.14 Refund ... 91

6.15 Standard Response Message ... 96