Grillparzerstraße 18 81675 Munich Germany P +49 (89) 45 230 - 291 F +49 (89) 45 230 – 099 [email protected]

PAY.ON Platform Documentation PayPipe Integration

Release 1.5.5

PayPipe Documentation – XML Integrator 1

Grillparzerstraße 18 81675 Munich Germany P +49 (89) 45 230 - 291 F +49 (89) 45 230 – 099 [email protected]

Release History

Release Description Date Changes 0.9.0 Alpha Version 0.9.1 Beta Version 0.9.2 Minor Release 0.9.3 Minor Release 2009-01-27 Return codes, brands, changes in request and response messages 0.9.4 Minor Release 2009-02-05 Recurring Payment, Connection to PayPipe, Certification process 0.9.5 Minor Release 2009-04-04 Recurring Payment changes, XML samples changes 1.0.0 Major Release 2009-05-01 Changes to Certification Process 1.0.1 Minor Release 2009-05-23 Changes to Customer Required Field Definiitions 1.0.2 Minor Release 2009-06-22 Extensions to AVS Support 1.0.3 Minor Release 2009-07-13 Added new certification tests for swiss francs (CHF) 1.1.0 Major Release 2009-08-01 New Return Codes 1.1.1 Minor Release 2009-09-30 New TransactionCategories: MAIL_ORDER and TELEPHONE_ORDER as required by several acquirers 1.1.2 Minor Release 2009-10-20 New Brand MILESANDMORE 1.1.3 Minor Release 2009-10-29 Better description of common used terms 1.1.4 Minor Release 2009-11-08 More information on payment types 1.2.0 Major Release 2009-11-12 Added new certification tests for currencies, recurring and 3DSecure 1.2.1 Minor Release 2010-01-25 Added PayPipe HTTP Access error codes Appendix A.4 1.2.2 Minor Release 2010-04-21 Changes to tag in group “ReferencedTransaction” 1.3.0 Major Release 2010-05-10 Added workflow description, updates on certification for asynchronous workflows 1.3.1 Minor Release 2010-06-08 Added XML request and response samples for certification (Appendix C) New XML request and response tags added 1.3.2 Minor Release 2010-07-28 Minor changes for clarifications 1.4.0 Major Release 2012-02-21 Include SHA-1 SecurityHash as digital signature 1.5.0 Major Release 2012-03-28 Adding MarketData to enable Airline-processing 1.5.1 Minor Release 2012-04-18 Minor changes for clarifications 1.5.2 Minor Release 2012-07-06 Minor changes for clarifications 1.5.3 Minor Release 2012-07-27 Added return codes 1.5.4 Minor Release 2012-09-19 Brands updated – previousAmount added 1.5.5 Minor Release 2013-07-15 Clarification about account details in reference Transactions

PayPipe Documentation – XML Integrator 2

Grillparzerstraße 18 81675 Munich Germany P +49 (89) 45 230 - 291 F +49 (89) 45 230 – 099 [email protected]

PayPipe Documentation – XML Integrator 3

Grillparzerstraße 18 81675 Munich Germany P +49 (89) 45 230 - 291 F +49 (89) 45 230 – 099 [email protected]

Preface

PAY.ON Platform Documentation - PayPipe Integration

Copyright © 2012 PAY.ON AG. All rights reserved. Printed in Germany / European Union

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 PAY.ON AG and delete the material from any computer.

Contact Information

For questions relating to this document please contact:

PAY.ON AG Grillparzerstraße 18 81675 Munich Germany phone: +49 89 45230 291 e-mail: [email protected]

PayPipe Documentation – XML Integrator 4

Grillparzerstraße 18 81675 Munich Germany P +49 (89) 45 230 - 291 F +49 (89) 45 230 – 099 [email protected]

Content

1 Introduction ...... 7 1.1 Target Audience ...... 7 1.2 Conventions ...... 7 2 Technical Information ...... 9 2.1 PayPipe Routing Mechanism ...... 9 2.2 Character Set and Encoding ...... 9 2.3 Security ...... 9 3 PayPipe XML Sample Request and Responses...... 10 3.1 PayPipe XML Request Sample ...... 10 3.2 PayPipe XML Response Sample ...... 11 3.3 PayPipe XML Asynchronous Response Sample ...... 12 4 Workflows ...... 14 5 Payment Types ...... 17 5.1 Preauthorization (PA) ...... 18 5.2 Preauthorization Supplement (PA) ...... 19 5.3 Capture (CP) ...... 20 5.4 Debit (DB) ...... 21 5.5 Credit (CD) ...... 22 5.6 Refund (RF) ...... 23 5.7 Reversal (RV) ...... 24 6 Details for implementation ...... 25 6.1 Mode ...... 25 6.2 Identification Tag Group ...... 25 6.3 Merchant Accounts ...... 26 6.4 Country Codes ...... 26 6.5 Payment ...... 26 6.6 Account Tag Groups ...... 27 6.6.1 CreditCardAccount ...... 27 6.6.2 BankAccount ...... 27 6.6.3 VirtualAccount ...... 27 6.7 Authentication ...... 28 6.8 AVS (Address Verification Servie) ...... 28 6.9 CVV Validation ...... 29 6.10 ConnectorTxIds ...... 30 6.11 Recurring Transactions ...... 30 6.12 Merchant Category ...... 30 6.13 Airline Data ...... 31 7 XML Tag Glossary ...... 33 7.1 Request and Response Tag ...... 33 7.2 Transaction Tags for XML Request ...... 33

PayPipe Documentation – XML Integrator 5

7.3 Transaction Tags for XML Response ...... 39 7.4 Response Validation – HASH Digital Signature ...... 42 8 Integration Process ...... 43 8.1 Apply for test and live accounts ...... 43 8.2 Connectivity and Security ...... 43 8.3 Error Simulation ...... 44 8.4 Certification ...... 44 8.4.1 General Information ...... 44 8.4.2 Integration Testing Process ...... 45 8.4.3 Test Cases for certification ...... 47 Appendix A – Return Codes ...... 51 Appendix B – Brands ...... 56 Appendix C – Certification Help ...... 57

PayPipe Documentation – XML Integrator 6

1 Introduction

1.1 Target Audience

This document is tailored to software developers who intend to integrate the XML API of PayPipe into their payment system.

1.2 Conventions

Font Styles

The monospace font is used for any XML or source code, file names, HTML tags, etc. The italic font style is used to represent terms that are explained in the glossary of common used terms (see end of this chapter).

Mandatory All tables explaining XML elements and attributes have a column called “Mandatory”. There are only two possible values for this column which are either “Yes” or “No”. “Yes” indicates that the element or attribute is mandatory for each possible request. “No” means that it is not mandatory for all requests, but conditionally mandatory depending on the type of request or depending on the used clearing institute.

Tags and Attributes Tag names starting as lower case mean that those tags are attributes of a parent tag. Tags starting with Upper case are used for XML parameters.

Data Types

Notation Description an alphabetic and numeric characters a alphabetic A-Z, a-z n numeric digits 0-9 TS Timestamp in the Format “yyyy-MM-dd HH:mm:ss”, e.g. “2008-04-01 13:44:12”

PayPipe Documentation – XML Integrator 7

IP nnn.nnn.nnn.nnn e.g. 144.123.012.010 URL e.g. http://www.myserver.com/response/answer.php CDATA Unparsed XML Data, CDATA section starts with "” B64 Base64 encoded list List of elements 32 Fixed length of 32 Bytes 0…15 Variable length up to 15 Bytes

Common used terms ClearingInstitute Synonym for any Acquirer, , third party processor and the like PayPipe is connected to. Therefore a ClearingInstitute supports PayPipe XML API Provider The entity that is connected to PayPipe and uses the PayPipe services to route transactions to Clearing Institutes PSP Synonym for “Provider” Preauthorization Preauthorization of a shopper account is technically a "hold" on a credit line from a purchase placed there by a merchant who has initiated a debit, but not completed it yet. Reversal Nullification of an authorized transaction (debit or preauthorization) that has not been settled. If supported by the card issuer, a reversal will immediately "undo" an authorization and return it to the open-to-buy balance on a cardholder's account. Some card issuers do not support reversals. Often referred to as “Void” or “Cancel” Debit Debit is often referred to as “Sale” or “Charge” and deducts the shopper’s account immediately. Capture Completes an open Preauthorization Credit Credits the shopper account without a reference to a former debit. Also referred to as “Payout”. Refund Credits the shopper account referencing a previous debit or capture transaction. Maximum amount of a refund typically is the amount of the previous debit or capture amount.

PayPipe Documentation – XML Integrator 8

2 Technical Information

2.1 PayPipe Routing Mechanism

PayPipe is a routing gateway only, meaning it does route your transactions to the clearing institute as specified within an XML request.

Please note these important points before reading this document:

 PayPipe is stateless, that means: o PayPipe does not store any transactions o PayPipe does not create a Unique ID or something similar for a transaction o PayPipe has no merchant-, channel- , entity- or business-case-concept o ….

 There is no need to configure any MIDs within PayPipe.  All configuration issues are handled on the platform of the payment provider that uses the PayPipe services.  Each transaction must contain all information necessary to route a transaction to the specified clearing institute, bank or payment provider.

2.2 Character Set and Encoding

PayPipe uses the default character set of the XML specification, UTF-8. ASCII 0 – 127 characters are also valid UTF-8 characters.

Every XML message sent to PayPipe must be UTF-8 encoded. Any other encoding may result in system errors or misbehavior under certain circumstances.

2.3 Security

All requests are sent over the Internet using HTTPS (HTTP over SSL) at a standard 128-bit encryption.

PayPipe Documentation – XML Integrator 9

3 PayPipe XML Sample Request and Responses

3.1 PayPipe XML Request Sample

Sent to the PayPipe API within the POST parameter “requestXML” 2894.9340.3418 ff8080811df256eb011df25705b3001f 56500 56500 TestXAPTER DE 37.00 EUR 2894.9340.3418 TPX_order# PSP_A/MER_A/DEFAULT jean le coq 123 VISA 4200000000000000 kosel bobby 101.202.011.022 [email protected] 0049 89 6542123 0049 177 6542123

DE Frankfurt DE7 Hauptstrasse 61821
05 AAACAgSRBklmQCFgMpEGAAAAAAA= CAACCVVUlwCXUyhQNlSXAAAAAAA=

PayPipe Documentation – XML Integrator 10

3.2 PayPipe XML Response Sample

2894.9340.3418 ff8080811df256eb011df25705b3001f Transaction succeeded C888541127745606146897 2d0ec783cb7c2d5b117499e6211caef4 https://c3-test.wirecard.com:443/secure/ssl-gateway Successful system entry 2894.9340.3418 2894.9340.3418 ff8080811df256eb011df25705b3001f C888541127745606146897 720316 THIS IS A DEMO TRANSACTION USING CREDIT CARD NUMBER 420000****0000. NO REAL MONEY WILL BE TRANSFERED. INFO ACK 2010-06-25 10:54:20 ]]>

PayPipe Documentation – XML Integrator 11

3.3 PayPipe XML Asynchronous Response Sample

Sent back to PSP () within the POST parameter “responseXML”

7020.3674.0770 8a8294492921fa9d0129267cc2f02db4 Transaction succeeded 0080000003241737 2d0ec783cb7c2d5b117499e6211caef4 2010-06-11T10:22:00.993Z 008033152 0 SHA1_RSA 8CB0E25928FDB8D223EE2D496723CA0A1185F4 fA9g4xLi3Oil23336UavgWBQnRmhlSGA3LQytRfi/iUJcgUKCIrWcvxjbcAP1aa8WRDcZ0BQ3R rkgbQax5VVLiCjzl7qc4VnP/Hgimevx7+d5rm444675JNQ50pK0D/MMcKqpg00ezB4XidM8 b9rE0GTMWRzTE54xH+w= 008110034241737 ]]> Successful 2010-03-11T10:22:01.237Z 0080 0081303241737 Success Hr J A T Velmer 011220444 DEN HAAG

VPa4123W30h/5xb8YFa/1AzBQnqM8gHhcQoEJsdjKi7kYuQUi+mXNzN/t82ew3bS9TZCudVyJDmi8vsW/ARn DZV32qZtBJHR2dCic/4Oo8MgUG1/PG0viW3y3h234h3UYa+tA79dtSuwGC+4hMH5lxVLS8/XoahA= 2652D431E922C3B23B492344CD7BFBD62 ]]>

PayPipe Documentation – XML Integrator 12

Hr J A T Cwlmwe NL 012341582 FORTIS_TEST

PayPipe Documentation – XML Integrator 13

4 Workflows

PayPipe covers several workflows of acquirers, or payment method providers. Depending on the payment method or business setup the payment transaction can be handled in a synchronous way (request and immediate final response) or asynchronous way where the shopper needs to be redirected to a 3rd party page.

4.1 Synchronous Workflow

Figure 1 Synchronous Workflows

Step Description 1 PSP sends XML request to ClearingInstitute using the PayPipe XML API 2 ClearingInstitute responds with XML response in the PayPipe format

PayPipe Documentation – XML Integrator 14

Examples for ClearingInstitutes where a synchronous workflow is supported are credit card acquirers like Postbank, Concardis, Barclaycard, Elavon UK, Elavon USA, Privatbank RU, ...

4.2 Asynchronous Workflow

Figure 2 Asynchronous Workflow

Step Description 1 PSP sends XML request to ClearingInstitute using the PayPipe XML API. 2 ClearingInstitute responds with XML response in the PayPipe format containing a redirect URL. PSP needs to make sure that the shopper is redirected to this URL. 3 Shopper interacts with a ClearingInstitute (e.g. with page in case of iDeal or issuer page in case of 3dSecure authentication) page 4 ClearingInstitute sends the updated transaction status to PSP as a PayPipe XML message. The XML message is sent as a HTTP POST request within the parameter “responseXML” to the URL specified within “ResponseURL”. 5 PSP responds to the XML message of step 4 with the URL where the shopper should be redirected to. PSP has to send the URL plain within the response body.

PayPipe Documentation – XML Integrator 15

6 PayPipe makes sure the shopper is redirected back to the URL PSP specified in step 5 7 In case of status changes on the ClearingInstitute side after the shopper has finished the transaction, some ClearingInstitutes send updated status messages to PSP as PayPipe XML messages. The XML message is sent as a HTTP POST request within the parameter “responseXML” to the URL specified within “ResponseURL”. In case the server at ResponseURL is down or not reachable the XML is resent every ten minutes for one hour until the PSP server responds with “OK”.

Examples for ClearingInstitutes where an asynchronous workflow is supported are wallet providers like PayPal or ClickandBuy, acquirers that use their own 3DSecure MPI workflow and online bank transfer method providers like iDeal, Giropay or (CA).

PayPipe Documentation – XML Integrator 16

5 Payment Types

PayPipe unifies the various payment types of all connected banks and acquirers to the following payment types:

For requests sent from PSP to ClearingInstitute:  Preauthorization and Preauthorization Supplement (PA)  Full and partial Capture of a Preauthorization (CP)  Debit (DB)  Credit (CD)  Reversal of a Capture, Preauthorization or Debit (RV)  Refund of a Capture or Debit (RF)

In general it is very important to understand that the XML tags that need to be sent in for each of the types very much depend on the connected acquirer, bank or payment provider (Merchant Account type) being used. The examples provided in this document are only samples that might be rejected due to missing fields.

PayPipe Documentation – XML Integrator 17

5.1 Preauthorization (PA)

Example for a Preauthorization request:

1315.5153.6922 ff8080811df258ed011df258fd88001f ActRH5QGxUBoIRcUwyJwvIVa-CoxAAR54Yqzk15g5kjtrr0lcA1cNjBk nomad._1184000533_biz_api1.gmail.com PDFQ5Q54Y75TXMHV DE 14.99 EUR 1315.5153.6922 TPX_order# *** PSP_A/MER_A/DEFAULT [email protected] PAYPAL kosel bobby 101.202.011.022 [email protected]

US San Jose CA Eureka St 7 95131

PayPipe Documentation – XML Integrator 18

5.2 Preauthorization Supplement (PA)

Example for a Preauthorization Supplement request:

5019.4183.5421 ff8080811df2a13c011df2a20120002c ActRH5QGxUBoIRcUwyJwvIVa-CoxAAR54Yqzk15g5kjtrr0lcA1cNjBk nomad._1184000533_biz_api1.gmail.com PDFQ5Q54Y75TXMHV DE 22.99 EUR 5019.4183.5421 TPX_order# [email protected] PAYPAL bobby kosel kosel bobby 101.202.011.022 [email protected]

US San Jose CA Eureka St 7 95131
9XG441235L096390U

PayPipe Documentation – XML Integrator 19

5.3 Capture (CP)

Example for a Capture request:

8925.8029.6392 ff8080811df2a741011df2a758500028 56500 56500 TestXAPTER DE 37.00 EUR 8925.8029.6392 C866595122813673228174

PayPipe Documentation – XML Integrator 20

5.4 Debit (DB)

Example for a Debit request:

1315.5153.6922 ff8080811df258ed011df258fd88001f xxx PDFQ5Q54Y75TXMHV DE 14.99 EUR 1315.5153.6922 TPX_order# *** PSP_A/MER_A/DEFAULT Joe Doe 313 VISA 4200000000000000 kosel bobby 101.202.011.022 [email protected]>

US San Jose CA Eureka St 7 95131

PayPipe Documentation – XML Integrator 21

5.5 Credit (CD)

Example for a Credit request:

h987i654j321k098l765m432n210o987 123456789123456789 aaaaaaaaaaabbbbbbbbbccccc 15.99 USD 123 VISA 4012301230123010 127.0.0.1 [email protected]

DE Leipzig goete1 2345

PayPipe Documentation – XML Integrator 22

5.6 Refund (RF)

Example for a Refund request:

h987i654j321k098l765m432n210o987 123456789123456789 aaaaaaaaaaabbbbbbbbbccccc 15.99 USD 123 VISA 4012301230123010 127.0.0.1 [email protected]

DE Leipzig goete1 2345
15.99 62488dd849e137098b6a74bb42f9efda T2632H

PayPipe Documentation – XML Integrator 23

5.7 Reversal (RV)

Example for a Reversal request:

8925.8029.6392 ff8080811df2a741011df2a758500028 56500 56500 TestXAPTER DE 37.00 EUR 8925.8029.6392 C866595332813673228174

PayPipe Documentation – XML Integrator 24

6 Details for implementation

6.1 Mode Transactions can either be sent in TEST, LIVE or INTEGRATION mode

 TEST means that the transaction is sent to the test system of the clearing institute.  LIVE means that the transaction is sent to the live (production) system of the clearing institute.  INTEGRATION mode means that the transaction stays inside the PayPipe system and is handled by a clearing institute simulator (e.g. necessary for general PayPipe tests or initial certification)

6.2 Identification Tag Group

Both IDs in this tag group identify a single transaction and are generated by the Provider.

 UUID This ID is a global unique ID, typically 32 characters long. Where possible this id is sent to the Clearing Institute and used for matching of chargebacks or the like.

 ShortID This ID is a short representation of a UUID used for Clearing Institutes where a 32 character UUID is not supported or where an ID must be presented to the account or card holder (e.g. on the bank account statement). Typically this id could be 8 to 15 characters long. Some Clearing Institutes use this ID for later matching of Chargebacks.

 OrderID This is an ID that is typically used to identify a particular order in the PSP or the merchant system.

 ShopperID This ID is typically used to mark a transaction with information of a certain shopper. If the clearing institute supports this functionality, multiple transaction could be grouped with this ID.

PayPipe Documentation – XML Integrator 25

6.3 Merchant Accounts

 type This attribute specifies the type of Clearing Institute where the transaction should be routed to. Examples are DUMMY, PAYPAL, PAGO, BANK, ELAVON, … Please check our PayPipe online documentation for the correct name of the attribute for the required Clearing Institute.

 All other fields are set depending on the Clearing Institute (Acquirer) used. Please ask your account manager for details

6.4 Country Codes

See ISO 3166-1 for a complete list of all supported country codes.

6.5 Payment

 type (chapter 5) Supported Payment Types are PA, CP, DB, RF, RV, CD

 previousAmount In case you use PayPipe for partial Captures or partial Refunds, this field indicates how much you have already refunded or captured before.In case you use PayPipe for multiple partial Captures or multiple partial Refunds, this field indicates the sum of the amount already refunded or captured before. If a previous capture or refund has been revered it will no longer be added in the calculation.

Complex Sample Calculation to illustrate the logic:

Type of Payment Amount previousAmount 1) PA 100 EUR 0 EUR 2) CP 50 EUR 0 EUR 3) RF 20 EUR 0 EUR 4) CP 25 EUR 50 EUR (out of 2) 5) CP 25 EUR 75 EUR (2 + 4) 6) RV of 5) 25 EUR N/A 7) RF 12 EUR 20 EUR (out of 3) 8) CP 25 EUR 75 EUR (again 2 + 4 since 5 reversed)

Note: Technically PayPipe supports such complex workflows. If such workflows can be applied very much depends on the acquirer/clearing institute and the particular account

PayPipe Documentation – XML Integrator 26

setup.

 Amount The amount is sent in the format ##.00, meaning it must contain a dot and must contain the two minor digits. Even currencies like JPY, KRW, LBP which do not have decimals, must be sent in the format ##.00

Examples: EUR12.44 is sent in as 12.44, EUR12 is sent in as 12.00, EUR9.9 is sent in as 9.90 JPY12300 is sent in as 12300.00

 Currency Codes See ISO 4217 currency code list for a complete list of currency codes. PayPipe supports all currencies. Nevertheless, depending on the Clearing Institute or the Merchant Account only selected currencies can be used.

6.6 Account Tag Groups

The account tag depends very much on the used payment method.

6.6.1 CreditCardAccount

The tag group must be specified for all types of non-referencing card payments like VISA, AMEX, MasterCard, any . For some Clearing Institutes account details need to be provided also for referencing transactions (e.g. card number).

Depending on the settings of the Merchant Account at the Clearing Institute some attributes are mandatory or not (see chapter 7 for details).

6.6.2 BankAccount

The tag is mandatory for all types of non-referencing bank account payments like Direct Debit in Germany, Austria, Spain, Netherlands a.s.o. It is also mandatory for some Online Transfer methods like iDeal or Sofortueberweisung (Directpay), Interac, EPS and the like.

6.6.3 VirtualAccount

The tag is mandatory for virtual account payments like PayPal, Moneybookers,

PayPipe Documentation – XML Integrator 27

ClickandBuy but also for payments with Loyalty Programs like MilesAndMore.

6.7 Authentication

This tag group is used for transmitting 3DSecure data for Mastercard SecureCode, VISA Verified by Visa or JCB JSecure. PayPipe does not support its own MPI, so you need to use your own MPI or the MPI of a third party processor (e.g. PAY.ON PaySourcing)

 ECI-Codes

00 internal code and is not submitted to acquirer. "00" transactions are either submitted as 07 or as standard transactions without 3D data depending on the acquirer. 01 Mastercard Securecode ATTEMPT 02 Mastercard Securecode SUCCESS 05 Verified By VISA SUCCESS 06 Verified By VISA ATTEMPT 07 DEFAULT Ecommerce Transaction

 Verification Code CAVV for VISA, UCAF for Mastercard. Is up to 32 Bytes long and Base64 encoded

 Xid Must be 28 Bytes long and Base64 encoded

6.8 AVS (Address Verification Service)

AVS instructions are

IGNORE AVS is processed, but the result is ignored and the transaction is not rejected SKIP AVS is not processed CHECK AVS is processed and transaction is rejected based on RejectPolicy

Possible AVS Result codes: A Address does match, zip code does not match Z Address does not match, zip code matches N Address and Zip do not match U Technical or Logical Error. AVS cannot be applied on card or address (not UK or US issuer), issuer is not available, etc. F Address and Zip match

PayPipe Documentation – XML Integrator 28

Rejection Policy:

This attribute allows you to define which AVS return values lead to a rejection. All Values that are not part of the RejectPolicy are considered as a successful authorization. Examples: NAZ Transaction is rejected if zip code does not match, address does not match or address and zip do not match UNAZ Transaction is rejected if zip code does not match, address does not match, address and zip do not match and a technical or logical error occurred. N Transaction is rejected if zip AND address do not match and no technical/logical error occurred

6.9 CVV Validation

Some Acquirers allow the explicit control of the CVV validation.

Valid CVV instructions are: IGNORE CVV validation is processed, but the result is ignored and the transaction is not rejected SKIP CVV validation is not processed CHECK CVV validation is processed and transactions is rejected based on RejectPolicy

Possible CVV Validation result codes: M CVV2/CVC2/Discover CID/AMEX CID Match N CVV2/CVC2/Discover CID/AMEX CID No match P Not Processed S merchant has indicated that the CVV2/CVC2/Discover CID/AMEX CID data is not present on the card, but Issuer indicated it should be present U Unsupported by issuer/Issuer unable to process request

Rejection Policy:

This attribute allows you to define which CVV validation return values lead to a rejection. All Values that are not part of the RejectPolicy are considered as a successful authorization. Note: Only a few acquirers/issuers allow you explicit control over that process Examples: N This is the default setting. Transaction is rejected if CVV2/CVC2/Discover CID/AMEX CID does not match.

PayPipe Documentation – XML Integrator 29

SN Transaction is rejected if CVV2/CVC2/Discover CID/AMEX CID does not match or should have been present

6.10 ConnectorTxIds

The XML response XML contains three ConnectorTxIDs (ConnectorTxID1, ConnectorTxID2, ConnectorTxID3) Those IDs are IDs returned by the Clearing Institute and are needed for the referencing of transactions. This means all three IDs must be stored and resent with each referencing transaction (Capture, Refund, Reversal) Examples for Aqcuirer Postbank (Postransact Germany): 947083 System Trace Audit Number 107431 ... Authorization Id 26K00001 ... TerminalId used for transaction

Note: For you as the integrator it is not necessary to know the meaning of this fields, but you have to resend the three IDs for each referencing transaction.

6.11 Recurring Transactions

Recurring transactions are flagged with the tag.

For initial transaction (containing CVV code) send the following XML tag:

All recurring transactions (without a CVV code) are sent with this tag:

Please check with your account manager if the used acquirer is supporting recurring transactions!

6.12 Merchant Category

The tag is an abstraction of VISA’s merchant category codes and states which kind of business the merchant is in.

Possible Values of the tag are: RETAIL

PayPipe Documentation – XML Integrator 30

SERVICES AIRLINE Required for merchants who cater to the airline industry HOTEL TRAVEL GAMING GAMBLING DIGITAL CONTENT AUCTION ADULT UTILITIES E_TICKETING ONLINE_FINANCIAL

6.13 Airline Data

Merchants who want to process transactions containing flight ticket information can do this by using the Tag MarketData in settlement requests, i.e. in requests with transaction type DB or CP. The data that is actually mandatory to fill in for a valid request depends on the receiver connector, so please refer to the corresponding receiver connector sheet for more specific information.

As described in chapter 7.2, most of the fields have to be filled with standardized IATA-codes. PAY.ON will only do a plausibility-check on these fields, so please remember to check the receiver’s settlement responses, which might be file-based in some cases.

To define Airline Data, the MerchantCategory (AIRLINE) must be set in the MerchantAccount.

AIRLINE

The type-attribute of the tag MarketData must be the same as in MerchantCategory. So for Airline Data set the attribute to type=”Airline”:

Sample Airline Data: … Ettone Bewarzer BEG JAT

PayPipe Documentation – XML Integrator 31

JT STR JU347 F 2012-12-12

PayPipe Documentation – XML Integrator 32

7 XML Tag Glossary

7.1 Request and Response Tag

The Request and Response tags identify if the XML message is a request or response and they contain the Transaction tag group .

Tag Names starting as lower case mean that those tags are attributes of a parent tag.

7.2 Transaction Tags for XML Request

Tag Data Length Mand. Comment Type Request responseURL URL 0…255 No Used for Clearing Institutes where an asynchronous response is expected at the end of the payment workflow, e.g. PAYPAL, iDEAL, DirectPay, etc. Transaction requestTimestamp TS 19 No Optional timestamp when XML was sent to PayPipe. Can be used for monitoring or time measurement mode a 4 Yes Either “LIVE”, “TEST” or “INTEGRATION”, see chapter 6 for details about modes Identification Yes Used to send in your own IDs. It is highly recommended to use your own IDs. PayPipe will not generate any IDs for the transaction! ShortID an 4…16 No Short ID identifying the transaction UUID an 8…32 Yes Unique ID identifying the transaction OrderID An 64 No (Unique) Identification of the order in the PSP system. If acquirer/bank provides similar fields, PayPipe will pass on information to acquirer/bank. If the corresponding acquirer field is shorther than the one sent by the PSP orderID will not be sent if optional or cut off to the acquirer length.

PayPipe Documentation – XML Integrator 33

ShopperID An 64 No Identification of the shopper in the merchant/PSP system. If acquirer/bank provides similar fields, PayPipe will pass on information to acquirer/bank. If the corresponding acquirer field is shorter than the one sent by the PSP shopperID will not be sent if optional or cut off to the acquirer length.

MerchantAccount Yes See chapter 6.3 type a 0…32 Yes Type or name of Merchant Account. Examples are PAYPAL, MONEYBOOKERS, IDEAL, … MerchantID an 0…127 No Depending on type this field has a meaning in context with the used connector MerchantName an 0…127 No Depending on type this field has a meaning in context with the used connector Key an 0…255 No Depending on type this field has a meaning in context with the used connector Username an 0…127 No Depending on type this field has a meaning in context with the used connector Password an 0…127 No Depending on type this field has a meaning in context with the used connector TerminalID an 0…128 No Depending on type this field has a meaning in context with the used connector IBAN an 0…32 No IBAN of the Merchant Account InternationalBankID an 0…32 No BIC of the Merchant Account NationalBankID an 0…32 No e.g. bank ID, “bankleitzahl”, „branch ID“ UploadUser an 0…127 No Depending on type of connector this tag is used for uploading batch offline files. Typically it is a FTP user account name UploadPassword an 0…127 No Depending on type of connector this tag is used for uploading batch offline files. Typically it is a FTP user account password Country a 2 No Country of the Merchant Account, 2 capitals according to ISO 3166-1 TransactionCategory a 0…10 No Describes what type of Transaction Category is applied on the Mercahnt Account. Can be one of ANY, ECOMMERCE, MOTO, MAIL_ORDER, TELEPHONE_ORDER, EWALLET. Default is ANY

PayPipe Documentation – XML Integrator 34

RecurringCode A 0…10 No Describes what recurring code is configured on the Merchant Account. Can be one of NONE, RECURRING, INSTALLMENT. Default is NONE. Note: this code is Merchant Account specific and has nothing to do with the tag . MerchantCategory A 0..255 No See chapter 6.12 for details about possible values. AVS No AVS instructions. By default AVS is not processed instruction a 50 No See chapter 6.8 for details about possible AVS instructions rejectionPolicy a 50 No See chapter 6.8 for details about possible AVS Rejection policies CVVValidation No CVV Validation instructions. By default CVV Validation is not processed instruction a 50 No See chapter 6.9 for details about possible CVV validation instructions rejectionPolicy a 50 No See chapter 6.9 for details about possible CVV rejection policies Secret an 0…255 No Used for secure callback, See chapter - 7.4 ReferencedTransaction No type A 2 Yes Type of the original transaction. See chapter 5 for a list of all payment types Amount n 10.2 No/Yes Amount of the referenced transaction (depending on Aquirer!) requestTimestamp TS 19 No Timestamp of the referenced transaction, example 2008-05-02 14:02:54 ConnectorTxID1 an 0…255 No ID of the original response of the referenced transaction within the tag ConnectorTxID2 an 0…255 No ID of the original response of the referenced transaction within the tag ConnectorTxID3 an 0…255 No ID of the original response of the referenced transaction within the tag Authentication No Authentication information for 3DSecure of the reference transaction. Some acquirers require this information to be submitted again for referencing transactions like Refunds or Reversals.

PayPipe Documentation – XML Integrator 35

Eci n 2 Yes List of possible values see chapter 6.6 Verification B64 32 No CAVV for VISA, UCAF for Mastercard if available Xid B64 28 No Xid of authenticated transaction if available

Payment Yes type a 2 Yes Type of the transaction. See chapter 5 for a list of all payment types previousAmount n 10.2 No Full Amount that was previously captured as required by some acquirers, see chapter 6.4 for details Amount n 10.2 Yes Amount of the transaction, format is ##.00 Currency a 3 Yes Currency code list according to ISO 4217 Descriptor an 0…255 No Descriptor of the transaction as it appears on the merchant or shopper statement (acquirer specific behavior)

CreditCardAccount No For Card Transactions like Credit or Debit Cards Holder a 0…255 No Holder (name) as it appears on the card Brand a 0…12 Yes Brand of the Card. See Appendix A for a list of all supported brands Number an 0…32 Yes Number as stated on the card Verification n 4 No Card Verification Code (CVV, CVD, …) Expiry Yes Expiry Date of the card month n 2 Yes Two digits with a leading zero, e.g. “03” for March year n 4 Yes Four digit year, eg. 2012 Start No Start Date of the card (e.g. MAESTRO cards) month n 2 Yes Two digits with a leading zero, e.g. “03” for March year n 4 Yes Four digit year, e.g. 2008 CardIssueNumber n 4 No Cond. Mandatory for MAESTRO cards

BankAccount No For Bank Transactions like Direct Debit, Credit Transfers to bank accounts, Online Transfers Holder a 255 Yes Holder of the bank account Country a 2 Yes Country of the bank account, 2

PayPipe Documentation – XML Integrator 36

capitals according to ISO 3166-1 Number an 24 No Local Number of the bank account IBAN an 28 No International bank account number Bank an 12 No Local Bank ID (BLZ, bank code, …) BIC an 11 No International Bank Identifier BankName an 255 No Name of the Bank, mandatory for certain online transfer methods like iDeal

VirtualAccount No For all payment methods within the category of Virtual Accounts (Wallets) Brand a 0…50 Yes Brand of the Virtual Account (e.g. PAYPAL, PRZELEWY, MONEYBOOKERS, …) ID an 100 No ID of the user account (e.g. PAYPAL ID of the shopper)

Customer No Detailed information about the shopper. Depending on the acquirer or payment method this section is mandatory or optional Name No Either family and given OR the company name must be specified Family a 50 No Family name of the shopper Given a 50 No Given name of the shopper Company an 60 No Company name of the shopper if available Contact No IP Ip 15 No IP address of the shopper Email an 128 No Email address of the shopper Mobile an 25 No Mobile phone number of the shopper Phone an 25 No Landline phone number of the shopper Address No Country a 2 No 2 capitals according to ISO 3166-1 City a 50 No City of the shopper State an 50 No State of the shopper Street an 100 No Street of the shopper Zip an 20 No Zip code of the shopper

MarketData No See Chapter 6.13 for information on MarketData type a 0…255 Con Type of the MarketData, see 6.13 PassengerData Con Contains a list of Passengers Passenger Con Contains data for one Passenger restrictedTicket a 0…5 Con One of: “true”, “false”

PayPipe Documentation – XML Integrator 37

PassengerName a 0…255 Yes Name of the Passenger OriginatingAirport a 3 Yes IATA Code of the originating Airport TicketNumber an 0…32 Con The Ticketnumber AirlineCode an 0…15 Con IATA Airline code AirlineName a 0…255 Con Name of the Airline CheckDigit n 2 Con Airline ticket check digit. Only for Diners AgentCode n 8 Con IATA Agent code AgentName an 0…255 Con Agent name Itinerary Contains a list of legs FlightLeg Con Contains data for one flight leg number n 0…2 Yes Counting the number of legs. Must be in the correct order starting from 1…n legs if there is more than one leg. stopOverAllowed a 0…5 Con One of: “true”, “false” CarrierCode a 0…4 Yes IATA-Code that identifies a carrier on arrival/departure signs, baggage tags, Global Distribution System (GDS), tickets, etc Destination a 3 Yes IATA Code of the Destination Airport FlightNumber an 0…7 Con Normally 3-5 digits + 2 digits airline code. ClassOfService n 0…3 Con (e.g F for First Class, B for Business,...)

LegDepartureDate TS 10 Con Departure date must be in the Format: YYYY-MM-DD FareBasis an 0…6 Con Code for Airline charges

Authentication No Authentication information for 3D Secure transactions Eci n 2 Yes List of possible values see chapter 6.6 Verification B64 32 No CAVV for VISA, UCAF for Mastercard if available Xid B64 28 No Xid of authenticated transaction if available

Recurrence No Defines if the transaction is sent to a Merchant Account that is configured for recurring transactions. mode a 10 Yes One of “INITIAL” or “REPEATED”

Parameters No Used for 1 to n Parameters to be sent in. Mandatory for certain Clearing Institutes Parameter An 255 Yes e.g.

PayPipe Documentation – XML Integrator 38

name=”salutation”>Mr Name an 32 Yes

7.3 Transaction Tags for XML Response

Tag Data Length Mand. Comment Type Request Transaction mode a 4 Yes Either “LIVE” or “TEST”. Same as was sent in the Request XML Response A 5 Yes SYNC or ASYNC. In case of ASYNC this response contains redirect information where the shopper should be redirected to (e.g. PayPal redirect). Also transaction update messages are marked as ASYNC. Identification No Same as in the initial request. Your IDs are returned within this section ShortID an 0…15 No Short ID identifying the transaction UUID an 0…32 No Unique ID identifying the transaction OrderID An 64 No (Unique) Identification of the order in the PSP system. If acquirer/bank provides similar fields, PayPipe will pass on information to acquirer/bank. If the corresponding acquirer field is shorther than the one sent by the PSP orderID will not be sent if optional or cut off to the acquirer length. ShopperID An 64 No Identification of the shopper in the PSP system. If acquirer/bank provides similar fields, PayPipe will pass on information to acquirer/bank. If the corresponding acquirer field is shorter than the one sent by the PSP shopperID will not be sent if optional or cut off to the acquirer length.

Processing Yes This tag group contains information about the processing of the transaction requestTimestamp TS 19 Yes Timestamp when the transaction was

PayPipe Documentation – XML Integrator 39

received from the client responseTimestamp TS 19 Yes Timestamp when the transaction was sent back to the client PayPipeProcessingTime n 1…6 Yes Time consumed within PayPipe server in milliseconds connectorTime n 1…6 Yes Time for communication with Clearing Institute in milliseconds ConnectorTxID1 an 0…50 No ID returned by the Clearing Institute identifying the transaction, see 6.10 for details description an 0…50 No The description attribute contains the acquirer naming of the ConnectorTxID1. There are reserved names for descriptions that are common with all acquirers and can be used to interpret results without knowing the actual connector. ConnectorTxID2 an 0…50 No ID returned by the Clearing Institute identifying the transaction, see 6.10 for details description an 0…50 No The description attribute contains the acquirer naming of the ConnectorTxID2. There are reserved names for descriptions that are common with all acquirers and can be used to interpret results without knowing the actual connector. ConnectorTxID3 an 0…50 No ID returned by the Clearing Institute identifying the transaction, see 6.10 for details description an 0…50 No The description attribute contains the acquirer naming of the ConnectorTxID3. There are reserved names for descriptions that are common with all acquirers and can be used to interpret results without knowing the actual connector. Return an 0…255 Yes Text message of return code code an 0…11 Yes Return code, see full list in Appendix A AVSResult a 1 No Mapped value of the AVS acquirer code to PayPipe AVS codes - see chapter 6.8 for more on PayPipe AVS codes. There is no need to return the mapped value in subsequent transactions CVVResult a 1 No Mapped value of the CVV/CVV2/CID/CVC acquirer code to

PayPipe Documentation – XML Integrator 40

PayPipe CVV/CVV2/CID/CVC codes - see chapter 6.9 for more on PayPipe CVV codes. There is no need to return the mapped value in subsequent transactions.

Redirect No Containing 0 to n Parameters for the redirect url URL 0…255 No URL where the shopper needs to be redirected to Parameter List, an 0…255 Yes List of parameter values that need to be posted to the URL name an 0…50 Yes Name of each of the parameters

ConnectorDetails No ConnectorDetails are used to return additional details from an acquirer without mapping. The ConnectorDetails have to be returned in subsequent transaction since the values can be used e.g. for settlements in batch processing. ConnectorDetails contain a variable number of Result subelements depending on the acquirer at hand. For a PayPipe client its recommended to store those as key/value pairs. With that the Paypipe client can also do analysis based on Acquirer criteria. Result an 0…255 No Acquirer value of the result. Field is not mapped. name an 0…50 Yes Name of the field on acquirer side

SecurityHash an 0…255 No See next chapter - 7.4

ConnectorSent url URL 0…255 Yes URL of the acquirer to which the request was sent to ConnectorReceived This tag group contains information about the response received from the acquirer/bank. Please use this information for support issues with the acquirer. timestamp TS 19 Yes Time when the response of the acquirer was received Returned an 0…255 Yes Text message returned by the acquirer, e.g. “Transaction successful”. This message differs for each acquirer. code an 0…20 Yes Original return code received in the response of the acquirer, e.g.

PayPipe Documentation – XML Integrator 41

“00” or “ACK”. This code differs for each acquirer. Body CDATA 0…1024 Yes Response message received by the Clearing Institute (Acquirer). Please store this information for debugging and support purposes!

7.4 Response Validation – HASH Digital Signature

To guarantee the integrity of the response message and parameters a digital signature generated with SHA-1 algorithm verifies not only the origin as the Merchant Secret key is a parameter merged in the signature but also the system hashes the message relevant parameters. The receiver then knowing the secret and the message parameters calculates the hash using the same SHA-1 algorithm and verifies it with the received. In case both are the same the origin and the message content is verified. In case the hashes differ the message is compromise and shall not be treated as valid. The secret is an optional tag and put in the marchant account in the request.

myOwnSecret

If the secret is set on the merchant account the callback response will include a SecurityHash, otherwise the SecurityHash tag won’t exist. N.B.: These secret/SecurityHash tags are only used in async connectors with callback.

The HASH tag is:  labeled  generated by SHA-1 encryption algorithm  contains following parameters o Return code (Value of attribute “code” in tag ) o Returned code (Value of attribute “code” in tag ) o UUID (Value of tag ) o SECRET

The string to generate the hash is built like this: ReturnCode + "|" + ReturnedCode + "|" + UUID + "|" + SECRET Note: If one of the parameters above is not part of the response message, the parameter is set to an empty string like the returned code in following example, “100.100.100||asdf123sadf123123asdf32|myOwnSecret”.

PayPipe Documentation – XML Integrator 42

8 Integration Process

8.1 Apply for test and live accounts

To apply for a PayPipe account please complete the “PayPipe Application Form” and send it to [email protected]. Within this document we require information about your test and live system(s) and the certification test cases you want to process during certification phase. See chapter 8.4.3 for details about all certification test sets.

Once we grant your account, you will get in return  an account (accountId/password) to the test system (also needed for Certification)  confirmation of a certification date

8.2 Connectivity and Security

The PayPipe test system (for general testing and certification) is available at: https://test.ppipe.net/connectors/gateway The PayPipe LIVE system is available at: https://ppipe.net/connectors/gateway

The XML request has to be sent in a parameter called "requestXML". The whole request needs to be sent as HTTP POST. The payment system is working with the UTF-8 character set. All incoming request must be fully UTF-8 encoded. The content-type of your message must be set to: application/x-www-form-urlencoded;charset=UTF-8

Asynchronous update requests sent from PayPipe to responseURL are sent within the Parameter "responseXML” as an HTTP POST request. The content-type of the response message ist set to: application/x-www-form-urlencoded;charset=UTF-8

Besides the source IP identification the interface is protected with HTTP Basic Authentication (http://en.wikipedia.org/wiki/Basic_access_authentication). For authentication please use the username and password you received for your PayPipe account.

Basic Authentication samples for Java can be found here: http://hc.apache.org/httpclient-3.x/authentication.html

PayPipe Documentation – XML Integrator 43

8.3 Error Simulation

Error simulation (only with mode=INTEGRATION) can be performed by sending the following special amounts respectively triggering an error code for test purposes:

Amount Return code 2.51 EUR 800.100.152, transaction declined by authorization system 2.52 EUR 800.100.151, transaction declined (invalid card) 2.53 EUR 900.100.400, timeout at connectors/acquirer side 2.54 EUR 900.100.300, no response from connector/acquirer [uncertain result]

8.4 Certification

8.4.1 General Information

Please use our test system for your integration purposes. Once the integration is complete you are ready to run the verification tests, which consist of the following steps:

 Apply for a certification date at [email protected] and attach the completed certification sheet (see document “PayPipe certification application”). See chapter 8.4.3 for details about all certification test sets.  On the confirmed day of certification, send in all required certification tests one after the other.  Upon completion of the tests, submit your own application log files to [email protected] containing the PayPipe XML messages you sent and received as well as your internal processing of the response messages. Your logs must contain timestamp information as well.

Our certification department will then verify all tests in the PayPipe internal logs and will inform you of the certification result. In case of missing tests or errors you will need to resubmit all test cases again until certification is granted.

Once certification is granted we will also enable you for the LIVE system and you can start processing there. Depending on the desired connectors additional certification test cases in conjunction with acquiring system may be needed. It may also be necessary to do certifications if additional connectors are requested despite already processing LIVE transaction via other connectors. That basically depends on the similarity of workflows. If so, you will be notified separately.

PayPipe Documentation – XML Integrator 44

8.4.2 Integration Testing Process

Send a transaction to the test system (test.ppipe.net) with mode=INTEGRATION. When using mode INTEGRATION you are not testing against a particular connector implementation but a simulated connector instead. This simulation supports all payment types and also allows you to provoke certain errors. The Integration connector also allows workflows like preauthorization/capture/refund to be tested. It will check the referencing of the transactions and decline invalid transaction referencing.

Sample – Debit: 2894.9340.3418 c6f94eda19b3ab31bcb69c8de458af2c 1234567890 15.00 EUR 2894.9340.3418 TPX_order# PSP_A/MER_A/DEFAULT Joe Doe 313 VISA 4200000000000000 Doe Joe [email protected] 127.0.0.1 +62215551102

Stuttgart DE Baden-Württemberg Am Walde 4 13530
05 AAACAgSRBklmQCFgMpEGAAAAAAA= CAACCVVUlwCXUyhQNlSXAAAAAAA=

PayPipe Documentation – XML Integrator 45

Sample Response: 2894.9340.3418 c6f94eda19b3ab31bcb69c8de458af2c Transaction succeeded c6f94eda19b3ab31bcb69c8de458af2c c6f94eda b3ab31bcb69c8de458af2c Successfully processed Successfully processed]]>

Sample Referencing Transaction: 2894.9340.3418 c6f94eda19b3ab31bcb69c8de458af2c 1234567890 15.00 EUR 2894.9340.3418 TPX_order# PSP_A/MER_A/DEFAULT Joe Doe VISA 4200000000000000 12339349519140046633229

PayPipe Documentation – XML Integrator 46

8.4.3 Test Cases for certification

The standard certification test suite includes the following tests for testing of standard workflows for successful and rejected transactions. The tests have to be made in INTEGRATION mode. See Appendix C for test account information and sample XML request and respons messages.

Test Case Set A: Standard Credit Card Tests Test Number Test Case Expected Return code A.1 10 EUR Creditcard DB followed by RV 000.000.000 A.2 19.90 EUR PA, 14.90 EUR CP, 000.000.000 4.90 EUR RF A.3 17.90 EUR RF on 24.90 EUR PA 800.100.170 A.4 29.90 EUR CP on 19.90 EUR PA 700.100.300 A.5 2.51 USD DB 800.100.152 A.6 2.52 GBP DB 800.100.151 A.7 2.53 CHF DB 900.100.400 A.8 2.54 EUR DB 900.100.300 Test 1 and 2 are successful test cases, tests 3 to 8 are error test cases.

Test Case Set B: Currency Credit Card Tests Test Number Test Case Expected Return code B.1 10.01 xxx* Creditcard DB followed by RV 000.000.000 * xxx needs to be replaced by a valid ISO currency code

Please repeat B.1 with all currencies you want to certify with PayPipe.

Test Case Set C: Recurring Credit Card Tests Test Number Test Case Expected Return code C.1 20 EUR Creditcard DB () with CVV C.2 21 EUR Creditcard DB () without CVV

Test Case Set D: Merchant MPI 3Dsecure Tests Test Number Test Case Expected Return code

PayPipe Documentation – XML Integrator 47

D.1 25 EUR Creditcard VISA PA 000.000.000 Successful 3D Authentication ECI 05 D.2 26.01 USD Creditcard MASTER PA 000.000.000 User not enrolled ECI 01 D.3 26.02 USD Creditcard MASTER PA 000.000.000 Successful 3D Authentication ECI 02 D.4 26.03 EUR Creditcard VISA PA 000.000.000 Attempt processing ECI 06

Test Case Set E: Acquirer MPI 3Dsecure Tests Test Number Test Case Expected Return code (asynchronous) E.1 35 EUR Creditcard VISA 000.200.000 PENDING and (4711100000000000) PA then asynchronously 000.000.000 to the specified responseURL E.2 36.01 USD Creditcard MASTER PA 000.200.000 PENDING and then asynchronously 000.000.000 to the specified responseURL E.3 36.02 EUR Creditcard VISA 000.200.000 PENDING and (4012001037461114) PA then asynchronously 100.380.401 to the specified responseURL Test 1 and 2 are successful test cases, test 3 is an error test case.

Test Case Set F: Acquirer Credit Card Payment Page Tests Test Number Test Case Expected Return code F.1 10 EUR PA 000.200.000 PENDING and then asynchronously 000.000.000 to the specified responseURL F.2 10.10 USD DB 000.200.000 PENDING and then asynchronously 000.000.000 to the specified responseURL

PayPipe Documentation – XML Integrator 48

F.3 11 EUR DB 000.200.000 PENDING and then asynchronously 800.100.152 to the specified responseURL Test 1 and 2 are successful test cases, test 3 is an error test case.

Test Case Set G: Online Bank Transfer Tests Test Number Test Case Expected Return code G.1 1.10 EUR PA 000.200.000 PENDING and then asynchronously 000.000.000 to the specified responseURL G.2 2.11 EUR 000.200.000 PENDING and User has cancelled then asynchronously 100.396.101 to the specified responseURL G.3 3.20 EUR 000.200.000 PENDING and Session expired (user has not continued, closed then asynchronously browser window, …) 100.395.502 to the specified responseURL G.4 4.21 EUR 000.200.000 PENDING and Status is open (Bank does not have final state then asynchronously yet) first 900.100.300 to the specified responseURL, changes to 000.000.000 after one minute G.5 5 EUR 000.200.000 PENDING and Failure with transaction at bank side then asynchronously 800.100.152 to the specified responseURL Test 1 is a successful test case, test 2, 3, 5 are error test cases. Test 4 tests status changes that may happen depending on the payment method you use.

Test Case Set H: Wallet Tests Test Number Test Case Expected Return code G.1 1.10 EUR PA 000.000.000

G.2 2.11 EUR 000.200.000 PENDING and User has cancelled then asynchronously 100.396.101 to the specified responseURL

PayPipe Documentation – XML Integrator 49

G.3 3.20 EUR 000.200.000 PENDING and Session expired (user has not continued, closed then asynchronously browser window, …) 100.395.502 to the specified responseURL G.4 5 EUR 000.200.000 PENDING and Failure with transaction at wallet provider then asynchronously 800.100.152 to the specified responseURL Test 1 is a successful test case, test 2, 3, 4 are error test cases.

PayPipe Documentation – XML Integrator 50

Appendix A – Return Codes

A.1 Return Codes of bank, clearing institute, bank, payment provider, etc.

NOTE: All these return codes are returned by the third party processor and are beyond PayPipe’s control. In case of any questions regarding those codes, please check the connector response and send a support request to the used clearing institute with the log output of the connector response. As PayPipe processes the requests, but does not run the systems on either end of the transaction, the PayPipe team is not able to assist in these cases and therefore refers you to the respective clearing institute.

Transaction Successful Return Code Description 000.000.000 Transaction succeeded

000.200.000 Transaction pending

Declined Return Code Description 100.396.101 Transaction canceled by user 100.395.101 Bank not supported for Giropay 100.395.102 100.396.201 Transaction canceled by merchant 100.397.102 Transaction declined by authorization system (updated) 100.397.101 Transaction cancelled by user (updated) 100.150.201 Registration is not confirmed yet 100.396.106 Not confirmed by user 100.100.100 Request contains no creditcard, bank account number or bank name 100.100.101 Invalid creditcard, bank account number or bank name 100.100.400 Request contains no cc/bank account holder 800.100.198 Transaction declined (invalid holder) 800.100.197 Transaction declined (registration canceled externally) 800.100.176 Transaction declined (account temporarily not available. Please try again later) 700.400.101 not supported by authorization system 100.550.401 Currency field is invalid 100.700.801 Identity contains no or invalid identification value 100.800.501 Invalid country

PayPipe Documentation – XML Integrator 51

100.900.500 Invalid reccurence mode 800.100.174 Amount field should not be empty 100.550.303 Amount format invalid (only two decimals allowed) 100.550.301 Amount is too large 700.100.200 Non matching reference amount 700.100.300 Invalid amount (probably too large) 800.100.155 Amount exceeds credit 700.300.300 Referenced tx can not be refunded, captured or reversed (already refunded, captured or reversed) 700.300.700 Referenced tx can not be reversed (reversal not possible anymore) 800.100.167 Referencing transaction does not match 800.100.170 Transaction not permitted 800.100.191 Transaction in wrong state on aquirer side 800.110.100 Duplicate transaction 800.100.151 Invalid card 800.100.159 Stolen card 800.100.160 Card blocked 800.100.165 Card lost 800.100.168 Restricted card 800.100.171 Pick up card 800.100.169 Card type is not processed by the authorization center 800.100.157 Wrong expiry date 800.100.153 Invalid CVV 800.100.166 Incorrect personal identification number 800.100.162 Limit exceeded 800.100.100 For unknown reason 800.100.156 Format error 800.100.150 Refund on gambling tx not allowed 800.100.152 Transaction declined by authorization system 800.100.154 Transaction marked as invalid 800.100.158 Suspecting manipulation 800.100.161 Too many invalid tries 800.100.163 Maximum transaction frequency exceeded 800.100.164 Merchants limit exceeded

PayPipe Documentation – XML Integrator 52

800.100.172 Account blocked 800.100.173 Invalid currency, not processed by authorization center 800.100.190 Invalid configuration data 800.100.192 Invalid CVV, amount is reserved on card for a few days 800.100.195 UserAccount Number/ID unknown 800.100.196 Registration error 800.200.101 Creditcard / bank account declined by clearing house 800.400.100 AVS Check Failed 800.400.110 AVS Check Failed. Amount is reserved on card for a few days! 100.395.502 Acquirer/Bank reported timeout on online transfer transaction

800.700.101 Family name too long 800.700.500 Company name too long 800.800.102 Invalid street 800.800.202 Invalid zip 800.100.402 cc/bank account holder not valid 800.400.200 Invalid Payer Authentication in 3DSecure transaction 800.400.500 Waiting for confirmation of non-instant payment. Denied for now. 800.800.302 Invalid city 800.900.101 Invalid email address (probably invalid syntax) 800.900.200 invalid phone number (has to start with a digit or a '+', at least 7 and max 25 chars long) 800.900.401 Invalid IP number 800.900.450 Invalid birthdate 800.700.201 Given name too long

A.2 Communication errors

These types of erorrs occur in cases where technical errors on the third party processor or between PayPipe and the third party processor occur.

Return Code Description 600.200.400 Unsupported Payment Type 600.200.100 Invalid Payment Method 900.100.100 Unexpected communication error with connector/acquirer 900.100.200 Error response from connector/acquirer 900.100.201 Serious error on gateway

PayPipe Documentation – XML Integrator 53

900.100.202 Invalid transaction flow, the requested function is not applicable for the referenced transaction. 900.100.300 No response from connector/acquirer [uncertain result] 900.100.400 Timeout at connectors/acquirer side 900.100.500 Timeout at connectors/acquirer side (try later) 100.380.401 User Authentication Failed 100.390.102 PARes Validation failed 100.390.103 PARes Validation failed - problem with signature 100.390.110 Cardholder Not Found - card number provided is not found in the ranges of the issuer 100.390.111 Communication Error to VISA/Mastercard Directory Server 100.390.112 Technical Error in 3D system 100.390.113 Unsupported User Device - Authentication not possible 000.400.101 Card not participating/authentication unavailable 000.400.102 User not enrolled 200.200.103 invalid format for processing by gateway (no reference id) 100.390.108 Transaction rejected because merchant not participating in 3DSecure program 900.100.600 Connector/acquirer currently down 900.300.600 User session timeout 900.200.100 Message Sequence Number of Connector out of sync

A.3 PayPipe internal validation errors

100.200.103 Bank account has invalid bankcode/name account number combination 100.500.201 Payment type invalid 100.100.501 Invalid credit card brand 200.200.106 duplicate transaction. Please verify that the UUID is unique

200.100.103 Invalid Request Message. The request contains structural errors

200.100.101 Invalid Request Message. No valid XML. XML must be url-encoded! maybe it contains a not encoded ampersand or something similar.

A.4 PayPipe HTTPS Access errors

PayPipe Documentation – XML Integrator 54

800.800.800 PayPipe gateway is currently not available. Please contact [email protected] in case this error persists. 800.800.810 You are connecting from an unknown Server IP address. Please contact [email protected] 800.800.820 Invalid HTTP authentication parameters (username or password wrong). Please contact [email protected]

PayPipe Documentation – XML Integrator 55

Appendix B – Brands

This is a list of the most common brands supported by PayPipe. Ask your account manager in case a brand you need to process is missing.

Name of Brand in XML requests VISA MASTER AMEX DINERS DISCOVER 4B CHINAUNIONPAY CARTEBANCAIRE CARTEBLANCHE CARTEBLEUE CASHTICKET DANKORT DELTA ENROUTE EURO6000 ELO GALERIA JCB LASER MAESTRO MILESANDMORE PAYPAL PAYPAL_CONTINUE PAYSAFECARD POSTEPAY PRZELEWY SERVIRED SOLO VISAELECTRON VISADEBIT VPAY

PayPipe Documentation – XML Integrator 56

Appendix C – Certification Help

Please use the following test card numbers or test accounts for your certirfication:

Test Case Test Card / Account Numbers Comments A, B, C, D, F VISA 4012888888881881, Expiry 01/15, CVV Use Code 456 MASTER 5105105105105100, Expiry 01/16, CVV 789 E VISA 4711100000000000 (enrolled), Expiry Use 02/15, CVV Code 456 , VISA 4012001037461114 (failed authorization), specify valid Expiry 03/15, CVV Code 456 responseURL within MASTER 5453010000059543, Expiry 02/16, CVV tag and 789 redirect to URL G Bank 10000000 Use , Number 4444 specify valid Country DE responseURL within tag and redirect to URL H Brand “CERTIFICATION_WALLET”, Use , Id [email protected] specify valid responseURL within tag and redirect to URL

PayPipe Documentation – XML Integrator 57

Sample Request Test Case A Debit (DB):

1a6bbf12a38c408a9298f113e3d747ad c05df0f5d03d4dcbadce508ec1a709f91 Joe Doe QmfCBiBDGrM55v01 0 DE ANY NONE 10.00 EUR Joe Doe 4012888888881881 VISA 456 Joe Doe

Am Walde 4 13530 Stuttgart DE
+64215551102 [email protected] 111.15.117.190

PayPipe Documentation – XML Integrator 58

Sample Response Test Case A Debit (DB): 1a6bbf12a38c408a9298f113e3d747ad 1a6bbf12a38c408a9298f113e3d747ad 3a6bbf12 8c408a9298f113e3d747ad Transaction succeeded Successfully processed Successfully processed]]>

PayPipe Documentation – XML Integrator 59

Sample Request Test Case A Reversal (RV):

c3bb3470abd649ac8c6e6e92f3e21d81 d012a93ecf7f4853ae05e70a5c43ac8e Joe Doe QmfCBiBDGrM55v0 0 ANY NONE 10.00 EUR Joe Doe 4200000000000000 VISA 313 1a6bbf12a38c408a9298f113e3d747ad 3a6bbf12 8c408a9298f113e3d747ad

Sample Response Test Case A Reversal (RV): c3bb3470abd649ac8c6e6e92f3e21d81 c3bb3470abd649ac8c6e6e92f3e21d8e c3bb3470 d649ac8c6e6e92f3e21d8e Transaction succeeded Successfully processed Successfully processed]]>

PayPipe Documentation – XML Integrator 60

Sample Request Test Case D Debit (DB):

162d0be67b9548318fbb88e019669833 5d33a678c2c84172b3a726ee6c3c9f Joe Doe QmfCBiBDGrM55v0 0 UK ANY NONE 11.00 GBP Joe Doe 4012888888881881 MASTER 313 Joe Doe

Am Walde 4 13530 Stuttgart UK
+613424102 [email protected] 128.21.111.190 02 AAABAhGEcSWFUSWFVIRwAAAAAAA= MDAwMDAwMDAwMDAwNjUwOTk4ODE=

PayPipe Documentation – XML Integrator 61

Sample Response Test Case D Debit (DB): 162d0be67b9548318fbb88e019669833 162d0be67b9548318fbb88e019669833 162d0be6 9548318fbb88e019669851 Transaction succeeded Successfully processed Successfully processed]]>

PayPipe Documentation – XML Integrator 62

Sample Request Test Case E and F Preauth (PA): 5863.3555.4210 40288b16293c069701293fa94b07285d 31241234 1234 1324 ECOMMERCE NONE 35.00 EUR 5863.3555.4210 DEFAULT Order Number 981 Caspar Caspar 456 VISA 4711100000000000 Niderlands Nina 82.135.34.186 [email protected] 1234567890

NL Amsterdam NETHERLAND Kanalstr. 12345

PayPipe Documentation – XML Integrator 63

Sample Response Test Case E and F: 5863.3555.4210 40288b16293c069701293fa94b07285d Transaction pending x4Lv9m1r94jpY0l+lkTX/jGbFYE= 02 15 Transaction pending

Sample asynchronous transaction state update Test Case E and F: 5863.3555.4210 40288b16293c069701293fa94b07285d Transaction succeeded 23163 Successful

PayPipe Documentation – XML Integrator 64

Sample Request Test Case G Preauth (PA):

5519.7581.5842 40288b16293c069701293fb6bef528e4 1234567890 34534 1324 DE ECOMMERCE NONE 1.10 EUR 5519.7581.5842 DEFAULT Order Number 986 Doris Deutschmann 4444 10000000 DE

Sample Response Test Case G: 5519.7581.5842 40288b16293c069701293fb6bef528e4 Transaction succeeded edc8fd5cf2b65cf04a3292acdd230792 edc8fd5cf2b65cf04a3292acdd230792 There were no errors during the execution of the operation.

PayPipe Documentation – XML Integrator 65

Sample asynchronous transaction state update Test Case G: 5519.7581.5842 40288b16293c069701293fb6bef528e4 Transaction succeeded edc8fd5cf2b65cf04a3292acdd230792 9ea9a2742f11bf71cac44605bfe9a9fd There were no errors during the execution of the operation.

Sample Request Test Case H Preauth (PA):

7409.5437.6866 40288b16293c069701293fbcf93a2945 123 TESTDEPAY GMBH ads 2612 1.10 EUR 7409.5437.6866 DEFAULT Order Number 988 [email protected] CERTIFICATION_WALLET

PayPipe Documentation – XML Integrator 66

Sample Response Test Case H: 7409.5437.6866 40288b16293c069701293fbcf93a2945 Transaction succeeded edc8fd5cf2b65cf04a3292acdd230792 edc8fd5cf2b65cf04a3292acdd230792 There were no errors during the execution of the operation.

Sample asynchronous transaction state update Test Case H: 7409.5437.6866 40288b16293c069701293fbcf93a2945 Transaction succeeded edcwercf04a3292acdd230792 9eawerac44605bfe9a9fd There were no errors during the execution of the operation.

PayPipe Documentation – XML Integrator 67