DataCash Merchant API Data Cash Developers Guide 2.57

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Developers Guide

Prepared for:

DataCash Merchants

Date:

May 2013

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Document Control

Reference

API001

Date

29/05/2013

Version

2.57

File Name

DataCash_Developers_Guide_2.57

REVISION HISTORY

Revision

Date

Comments / Reason

2.0

(Release)

26/11/2009

Developers Guide from DPG and APG combined

2.1

27/11/2009

Added Fuel Card Service

2.2

08/12/2009

Added PayPal Reference Transactions

Added Bankcard Query Transactions

2.3

11/01/2010

InstaDebit and ELV details added (FR)

2.4

28/01/2010

Standardisation of formatting and layout (JF)

2.5

09/02/2010

Updated HPS section with details for dynamic capture fields

and expired session handling (NB)

Updated PayPal Reference Transactions (NB)

2.6

19/02/2010

Updated HpsTxn response table and related XML (CTI)

Updated paReq example – textarea (JF)

2.7

03/03/2010

Grammar and format editing (JF)

Update to DataCash MPI And MPI Only (JF)

Update to Pre Registered Card Service card retention from 12

to 13 months (JF)

2.8

21/04/2010

Change HPS to HCC (JF)

Updated HCC Section with details for dynamic data

placeholders (RWM)

2.9

22/04/2010

Updates to ExperCash section (SJ)

Added ExperCash BackCharge information (SJ)

2.10

25/05/2010

New section added for Full HPS (RWM)

Updates to links to Appendices (AM)

Added GiroPay sample (AM)

2.11

07/06/2010

New section added for Payout transactions (RJB)

2.12

02/08/2010

Update to Direct Debit Notifications re Drawdown

Notifications (JF)

Update to <iframe /> mechanism example (JF)

2.13

16/09/2010

Updates to Single Card Payments and Card Holder Present

sections for authorize_referral_request transactions (SPD)

Update to details of required URLs for HPS HCC and 3DS (JF)

2.14

21/10/2010

Added information of the new eCheck integration into APG

(HA)

Added ClickandBuy and Envoy OneClick information for

Payout into APG (RB)

2.15

27/10/2010

Addition of new section (2.8.7) describing the Vtid

Configuration request and response (CI)

2.16

16/11/2010

Added information on the ExperCash IFrame. (RJB)

Added information on the Merchant Custom Fields. (RJB)

Added information on the Risk checking for Retail Merchants.

(RJB)

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.17

21/12/2010

Inclusion of additional Sales Channels (refer to section

2.4.7.1.2) (JF)

Max characters of prod_description field changed from 50 to

100 characters (refer to section 2.4.7.1.7) (JF)

Added additional supported fields for T3M (DEJ)

Added information on FraudOnlyTxn (DEJ)

Added information on OneClick responses –(RJB)

2.18

19/01/2011

Update to contacts for HPS (JF)

Update to FraudOnlyTxn (DEJ)

2.19

04/02/2011

Added SaleAmountDetails to the APG Purchase Method.

Section 3.3.1.1.3 (RJB)

Added RSG sections 2.4.10 & 2.4.11 (DEJ)

2.20

15/03/2011

Added American Express ISO8583 AdditionalData Section

(DEJ)

Added UseSaleCurrency element to section 3.3.3.1.7 (HA)

2.21

08/04/2011

Added information of the new Amazon integration into APG,

adding LineItem information under purchaseDetails (SJ)

Added version section (JW)

Added version 2 specific section to MPI Only section (JW)

Updated T3M documentation to include airline examples

(DEJ)

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.22

25/05/2011

Removed capitalisation on the vTID.configuration

documentation (SA)

PayPal:- re-ordering of elements in alphabetical order with

required field first and optional after. (SA)

PayPal: PayPalTxn.reference. Is required for G (use from

S)(SA)

PayPal.AirlineItineraryData is optional for D&C, PayPal.Items

optional for D (SA)

PayPal.ShippingAddress optional for D (SA)

PayPal: Updated "Values for paymentstatus" table in

"pending"line to explain that this only applies

PayPal.payment_type = "Any" (SA)

PayPal:update the "timestamp" fields in the XML response

examples to be more recent ones (SA)

PayPal:updated PayPal Auth Capture, PayPal.payment_action

must be "order" for S (SA)

PayPal: updated PayPal Auth Capture,

PayPal.payment_action may be "order" for D, or "sale" if

wishing to convert the existing txn (SA)

PayPal: Example URL for re-direct - added the URL for

the sandbox (www.sandbox.paypal) (SA)

PayPal: Added an xml for paypal elements (SA)

PayPal: AirlineItineraryData and FlightDetails. Updated the

PayPal Do Reference service. (SA)

PayPal: Amended the title on the second do_capture

transaction example. (SA)

PayPal: Updated the PayPal do reference for:

TxnDetails.amount; PayPalTxn.reference;

PayPalTxn.payment_action. (SA)

PayPal: Added Extra XML examples (SA)

PayPal: Updated the title for Example XML Requests for

update_billing_agreement (SA)

PayPal: Updated the title for Example XML Request for

do_reference_transaction and added an extra example (SA)

Removed reference to device_category=1 in the

request.Transaction.TxnDetails.ThreeDSecureBrowser (SA)

Added missing information to "Schema Elements for Query

Response" about the "HpsTxn" element (SA)

Added version 2 specific response changes (MPM)

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.23

03/06/2011

Removed DPG-Realtime Fraud Screening (MS)

Removed 3rdman references from text and replaced with

Datacash Fraud Service(DFS) (MS)

Updated the merchant_url description for 3Dsecure (SA)

2.24

08/06/2011

Updated the example XML under credit and debit card service

section (SA)

Updated the Secure element for 3d transaction to include

American Express (LL)

2.25

06/07/2011

Added section for PayPal Query Transactions (RWM)

2.26

13/07/2011

Added Tokenization elements (WB)

2.27

19/07/2011

Updated broken links

2.28

11/08/2011

Update to Tokenization XML and element name as well as the

reference to the appendices.

2.29

15/08/2011

Updated the Tokenization spelling to the US spelling:

tokenization

2.30

02/09/2011

Updated to include risk: https responses

2.31

22/09/2011

Updates to APG Section

Offline Bank Transfer, iDeal and WebMoney has been added

to Purchases (RJB)

Removed Not Applicable items from the Required Payment

Lists (RJB)

Added EntroPay and Ukash to the Payout section of APG.

(RJB)

Added extra nodes in the Offline Bank Transfer response

XML.

Updated to include Switch to Issuer (DMcC)

2.32

24/10/2011

Update to Merchant Narrative section to include txn_refund

(JMW)

2.33

08/11/2011

Added documentation for PreCall transaction (DEJ)

Added documentation for MiscCusomerInfo Block (DEJ)

Added 2 additional fields for Chase and version 2 transactions

and example xml (MPM)

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.34

21/11/2011

Update to include new Alternative Payments Section (EDI-

DPG). (DEJ)

Update to the HPS TXN Elements, Attributtes and Example

XML(OHB)

Added details of the Local Direct Debit functionality (NXB)

2.35

23/12/2011

Updated the values for Paypal: “localecode”

Updated the link to “website” in the Elements of Cv2Avs

2.36

09/01/2012

Removed type attribute from the examples where the Secure

element can be found.

Also removed the 'Attributes of service’ table for Secure

element. (PXR)

Added description of Custom Data element (RWM)

2.37

19/01/2012

Edited “Elements of HistoricTxn” authcode and reference

(SA)

Edited Example XML

threedsecure_authorize_referral_request, changed element

from "auth_code" to "authcode" (SA)

Updated hyperlinks (AS)

2.38

25/01/2012

Restructured HCC section, providing additional examples and

cross-referencing to other services (SA)

Restructured HPS section, providing additional examples and

cross-referencing to other services (SA)

Moved “Example XML Request for an additional fulfill when

configured for SplitShipment” to appropriate section

Added additional cross-references and FAQ link to Bankcard

Query Service (SA)

2.39

07/02/2012

Updated examples for VtidConfiguration (SA)

Updated Direct Debit Cont_Auth (SA)

Updated examples for 3DS using DataCash MPI (LL)

Updated HPS and HCC return_url and expiry_url definitions

(LL)

Updated Additional Data, correcting position of element

names within the schema (SA)

Updated PayPalTxn.reference for do_authorization (SA)

Reworked Card Tokenization to fit standard format. Added

Additional examples

2.40

24/02/2012

Updated RSG section to reflect that refunds can now be given

Risk block(JMW)

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.41

19/03/2012

Update to include POLi to the Alternative Payment Gateway

(APG). (RJB)

Added documentation for BIN Lookup Service (RJB)

Included Realtime Fraud Screening (SA)

Revised Batched Fraud Screening (SA)

2.42

02/04/2012

Include AliPay to the Alternative Payment Gateway (RJB)

2.42

17/05/2012

Added description of 'verify' transaction (RWM)

2.43

14.06.2012

IPN information updated. (APWD)

Removed generic element number 15 from valid request.

(AJH)

Specified the importance of the Home element.

Added that DCCCA works with card tokenisation.

2.44

18.06.2012

Removed some locale codes as they are not yet supported by

PayPalTxn. (RS)

2.45

20.07.2012

Amended device_category to read “0 – must be used for all

transactions.

2.46

23.08.2012

Added Paypal locale codes. RS

Added description of China Union Pay transactions. JMP

Incorrect ReD link removed

DPG password expiry info updated

Historic Cont Auth method of Recurring Payments changed to

ca_reference

2.47

4.08.2012

Giropay DPG/HPS added (OB).

2.48

11.09.2012

Added description of PayPass via HCC (GWAM)

Added PayPass Query Response XML (GWAM)

2.49

28.09.2012

Added Alipay to the DPG section. (AML)

Elavon US specific contauth Fire and Forget (AL)

2.50

12.10.2012

Recurring Transaction Enquiry Service (VAU/ABU) (DFM)

Removed DPG Giropay section, added iDeal and Sofort

txn_refund documentation to DPG section. (AML)

POLi removed

Added PayPass Full HPS and Direct details (GWAM)

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.51

22.11.2012

The section 2.12.9 (Giropay) has been reinstated (MJH)

2.52

06.12.2012

Added cardholdername to examples in sections 2.15.4.2.2

and 2.15.5.1. (CM)

2.53

10.01.2013

Adjusted DFS to DataCash Fraud Service (DCFS)

APM name validation clarified (DM)

PayPal information updated (AD)

URL adjusted (now fully qualified)

line_total field removed

Two Giropay instances reinstated

Example XML Element Risk for an RSG Transaction adjusted

MerchantCustomDetails corrected to CustomMerchantDetails

in section 3

2.54

07.02.2013

Addition of Currency Conversion Service and PayPass Online

Txn (SG)

2.55

07.03.2013

Addition of fulfil timestamp, cancel date, cancel timestamp

and transaction timestamp to RT Fraud Screening

QueryTxnResult. (CM)

Adjustment to RSG Service Overview for recurring payments.

2.56

18.04.2013

Updated the Line Items and Custom Merchant Fields. (KG)

Update ClickAndBuy Section. (KG)

Added 'VerificationDetails' section and 'execution order'

element in RSG Data Elements section. (CM)

Added VerificationResponse (for GB Group) for both RSG pre-

auth and post-auth responses. (CM)

2.57

24.05.2013

Added description for Boleto Bancario Transactions (EK)

Removed references to device_category as it is now

deprecated. (CM)

Changed TheThirdMan to The3rdMan throughout (SEC)

Adjusted PayPal batched info and added PayPal examples

(SEC)

Added Transaction Details to Single Card Payment TxnDetails

section (SEC)

Amended: display of table and checked for similar display

errors, incorrect references to appendix 24 and 25 and

spelling mistake. (SEC)

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

TABLE OF CONTENTS PAGE

Developers Guide ............................................................................ 1

Prepared for: .................................................................................. 1

DataCash Merchants ........................................................................ 1

Date: ............................................................................................. 1

1. Introduction to the DataCash Developers Guide .......................... 11

1.1 Audience ........................................................................ 11

1.2 Scope ............................................................................ 11

1.3 Support .......................................................................... 11

1.4 How to use this document ................................................ 11

1.4.1 Which Gateway? .............................................................. 11

1.4.2 The Layout Structure Used In This Document ...................... 12

2. DPG - DataCash Payment Gateway ............................................ 13

2.1 Introduction to DPG ......................................................... 13

2.1.1 XML Requests and Responses ........................................... 13

2.2 Single Card Payments ...................................................... 16

2.2.1 Credit and Debit Card Service ........................................... 16

2.2.2 Additional Data (American Express ISO8583) ...................... 30

2.2.3 Misc Customer Info .......................................................... 39

2.2.4 Line Item Detail .............................................................. 40

2.2.5 Airlines Transaction Records ............................................. 46

2.2.6 Merchant Narrative .......................................................... 61

2.2.7 Fuel Card Service ............................................................ 63

2.2.8 Hosted Card Capture ........................................................ 72

2.2.9 Hosted Payment Service ................................................... 91

2.2.10 Verify Transactions ........................................................ 103

2.3 Repeat Card Payments ................................................... 105

2.3.1 Payment Tokenization .................................................... 105

2.3.2 Capture Method Recurring Transactions ............................ 108

2.3.3 Historic Recurring Transactions ....................................... 114

2.3.4 Recurring Transaction Enquiry Service (VAU/ABU) ............. 122

2.3.5 Fire and Forget Recurring Transactions ............................. 126

2.4 Fraud Prevention ........................................................... 138

2.4.1 AVSCV2 ........................................................................ 138

2.4.2 URU® .......................................................................... 153

2.4.3 ReD Fraud Screening ..................................................... 185

2.4.4 3-D Secure, with DataCash MPI ....................................... 208

2.4.5 MPI Only ...................................................................... 222

2.4.6 3-D Secure, with 3rd party MPI ........................................ 232

2.4.7 Batched Fraud Screening ................................................ 238

2.4.8 Realtime Fraud Screening ............................................... 265

2.4.9 Fraud Only Transactions ................................................. 272

2.4.10 Risk Services Gateway (RSG) .......................................... 275

2.4.11 Pre & Post Authorisation Fraud Screening ......................... 279

2.4.12 HTTPS Responses .......................................................... 304

2.5 BACS Service ................................................................ 306

2.5.1 Direct Debit .................................................................. 306

2.5.2 Direct Debit Continuous Authority .................................... 323

2.5.3 Direct Credit – Direct Debit Refunds ................................. 334

2.5.4 Direct Credit – Standard ................................................. 337

2.5.5 Direct Credit – Card Collection Accounts ........................... 343

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.6 Batch Input .................................................................. 348

2.6.1 Available DPG Services ................................................... 349

2.6.2 Overview of Common Elements and Attributes .................. 350

2.6.3 Example Batch Requests ................................................ 364

2.7 Card Holder Present ....................................................... 381

2.7.1 Chip and Pin ................................................................. 381

2.7.2 Preallocated References.................................................. 393

2.8 Other DPG Services ....................................................... 397

2.8.1 PayPal .......................................................................... 397

2.8.2 Variable End of Day ....................................................... 466

2.8.3 RBS Gift Card ................................................................ 469

2.8.4 PrePay Technology (PPT) ................................................ 477

2.8.5 Currency Conversion Service ........................................... 488

2.8.6 Fexco Dynamic Currency Conversion ................................ 492

2.8.7 Bankcard Query Transactions .......................................... 494

2.8.8 vTID Configuration Transactions ...................................... 499

2.8.9 PreCall Transaction ........................................................ 501

2.9 Card Tokenization .......................................................... 508

2.9.1 Schema Elements for Request ......................................... 508

2.9.2 Example XML Requests .................................................. 512

2.9.3 Schema Elements for Response ....................................... 518

2.9.4 Example XML Responses ................................................ 519

2.10 Switch to Issuer Transactions .......................................... 525

2.10.1 Versioning .................................................................... 525

2.10.2 Standard transaction - response elements ........................ 525

2.10.3 Query transaction – response elements ............................ 526

2.10.4 Transactions including CSC data ...................................... 526

2.10.5 Transactions including AVS data ...................................... 528

2.11 Local Direct Debit .......................................................... 530

2.11.1 Service Overview ........................................................... 530

2.11.2 LocalDDTxn .................................................................. 530

2.11.3 TxnDetails .................................................................... 532

2.11.4 HistoricTxn ................................................................... 533

2.12 Alternative Payment Methods .......................................... 536

2.12.1 Common Request Elements ............................................ 536

2.12.2 iDeal Transactions ......................................................... 537

2.12.3 Sofort Transactions ........................................................ 541

2.12.4 WebMoney Transactions ................................................. 545

2.12.5 MisterCash Transactions ................................................. 547

2.12.6 La Caixa Transactions .................................................... 550

2.12.7 Nordea Transactions ...................................................... 552

2.12.8 Alipay Transactions ........................................................ 553

2.12.9 Giropay Transactions ..................................................... 555

2.12.10 Common Response Elements .................................... 560

2.12.11 Offline Bank Transfer (OBT) Response Elements ......... 561

2.12.12 Redirect Response Elements ..................................... 561

2.12.13 Compatibility With HPS ............................................ 563

2.13 BIN Lookup Service ....................................................... 566

2.13.1 Service Overview ........................................................... 566

2.13.2 XML Schema for Request ................................................ 566

2.13.3 XML Schema for response ............................................... 567

2.14 China Union Pay ............................................................ 569

2.14.1 Summary of Service ...................................................... 569

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.14.2 Schema Elements for Request ......................................... 569

2.14.3 Authorisation transactions .............................................. 570

2.14.4 Authorisation commencement transactions ....................... 572

2.14.5 Txn Refund and Cancel transactions ................................. 574

2.14.6 Unsuccessful, Invalid or Failed Transactions ...................... 575

2.14.7 Query Transactions ........................................................ 576

2.15 PayPass OnLine ............................................................. 580

2.15.1 Summary of Service ...................................................... 580

2.15.2 Shipping Address Suppression ......................................... 580

2.15.3 HCC ............................................................................. 580

2.15.4 Full HPS ....................................................................... 584

2.15.5 Direct ........................................................................... 588

2.15.6 Query Transactions ........................................................ 593

2.15.7 Authorisation Transactions .............................................. 595

2.16 Boleto Bancario ............................................................. 597

2.16.1 Summary of Service ...................................................... 597

2.16.2 Full HPS ....................................................................... 597

2.16.3 Direct ........................................................................... 603

2.16.4 Query Boleto Bancario Transactions ................................. 608

2.16.5 Query HPS Boleto Bancario Transactions .......................... 611

3. APG – Alternative Payment Gateway ........................................ 614

3.1 Introduction To APG ....................................................... 614

3.1.1 Glossary ....................................................................... 614

3.2 APG Overview ............................................................... 614

3.2.1 APG SOAP Web Service .................................................. 614

3.2.2 APG Redirect Solution .................................................... 615

3.2.3 Security ....................................................................... 615

3.2.4 Transaction Flow ........................................................... 616

3.3 APG SOAP Web Service .................................................. 622

3.3.1 Shared XML Request and Response elements .................... 622

3.3.2 Purchase ...................................................................... 628

3.3.3 Payout ......................................................................... 752

3.3.4 Transaction Querying ..................................................... 783

3.3.5 RetrieveSettlementValue ................................................ 788

3.3.6 GetInformation ............................................................. 793

3.3.7 Modification .................................................................. 811

3.4 APG Event Notifications .................................................. 817

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

1. INTRODUCTION TO THE DATACASH DEVELOPERS GUIDE

1.1 AUDIENCE

This document is intended to be used by developers, technical personnel and business

analysts to facilitate a successful integration by a merchant to the gateways provided

by DataCash.

This is reflected in the layout of the document, which covers the submission of data in

XML form to DataCash.

1.2 SCOPE

This document describes the interfaces, messages, data formats, and responses used

for integration into DataCash. This is a technical API document and as such does not

cover the business reasons or business process for integration.

This document is supplemented with an Appendices document.

Both the Developers Guide and the Appendices are available for download from the

DataCash Developers Area: https://testserver.datacash.com/software/download.cgi.

This document describes some of the services that DataCash currently provides at a

high level. The other services’ descriptions can be found on the DataCash website, and

a link to the relevant webpage will be provided in this document.

1.3 SUPPORT

For any assistance or information pertaining to existing or new DataCash services,

please contact Support via the DataCash website.

1.4 HOW TO USE THIS DOCUMENT

1.4.1 Which Gateway?

This document is split into two main parts, each catering for specific processing needs.

 The first part deals with integrating into the DPG (DataCash Payment Gateway)

system. If you would like to process credit card transactions via DataCash, then this

section applies to you. Please see Section 2 DPG - DataCash Payment Gateway.

o Note that this system also includes functionality to process PayPal and UK

Direct Debit (BACs) transactions.

 The second part deals with integrating into the APG (Alternative Payment Gateway)

system. If you would like to process non-card purchase or payout method

transactions via DataCash (electronic wallets, prepaid products, and bank

transfers), then this section applies to you. Please see Section 3 APG – Alternative

Payment Gateway

Both of these systems provide Risk Screening Services.

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

1.4.2 The Layout Structure Used In This Document

Despite the length of this document, there is a simple structure in place to make it

easy to use.

Firstly, as described above, the document is split into two sections: one for card

processing and the other for non-card payment method processing.

Secondly, within each of the two main sections the Services that are provided by each

gateway are listed.

Thirdly, for each Service there are four sub sections:

1. Request XML complex structures

2. Request examples

3. Response XML complex structures

4. Response examples

Fourthly, for each XML complex structure, information is provided about:

 Description and position

 Elements

 Attributes

 Examples

And lastly, full examples of the Request and Response complex structures are

provided, showing a number of variations depending on the scenario.

Cross-references are used throughout this document, for XML complex structures that

are shared between various Services.

(To navigate forward, click on the link)

Back to Contents

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2. DPG - DATACASH PAYMENT GATEWAY

2.1 INTRODUCTION TO DPG

This section of the document is the DataCash Developer’s Guide for the DPG. It is

aimed at developers and technical personnel who will be integrating applications for

card, PayPal and UK Direct Debit processing.

As each DPG Service requires particular information to be submitted and this

information tends to be grouped within similar areas (parent elements) of the XML

schema, the names of the parent elements will first be introduced.

Each parent will then be placed into its context in the schema and its child elements

discussed. This includes any restrictions on the format, length and transaction type of

each element.

If the DPG Service contains additional aspects (for example notifications for Standard

Direct Debit and Standard Recurring Transactions), this will also be covered.

2.1.1 XML Requests and Responses

There are certain features of the Request and Response that are applicable to all DPG

Services; these elements are covered in this section. Others are only used for a

particular Service or group of Services; these elements will be covered within the

documentation for that Service.

2.1.1.1 Request

The Request has an optional attribute “version” which can be sent to the DPG.

The version of the request when supplied indicates version specific functionality which

may vary depending on the type of request.

The attribute corresponds to an unsigned integer.

It is important to note that when a version attribute is specified with a value greater

value than 1, the Response Element will be returned with a version attribute that

directly corresponds to the value passed in with the Request.

The vast majority of requests will not have separate versions. When the version

attribute is not supplied this value will default to “1”. Please note that where version is

not explicitly mentioned when describing specific types of requests in this document, it

can be assumed that version 1 is the only supported version of the request. It can also

be assumed that supplying a greater version number will not adversely affect current

functionality for these services.

Where version is explicitly documented when describing specific types of request,

special attention should be given to the effects of changing the version attribute of the

Request.

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example Request Using Optional Version Attribute

...

</Request>

In the Request, only the Authentication element is used for all DPG Services.

2.1.1.2 Authentication

Element Name:

Authentication

Position:

Request

Element

Name

Description

Values /

Limitations

client

Specifies the account the transaction will be

processed on (vTID)

As advised by

DataCash

password

The password for the account.

As advised by

DataCash1

When your account is setup, DataCash will advise you of the password. This password

currently has a maximum lifetime of 12 months, however in an effort to streamline the

password expiry process, as of the 18th of September 2012, your DPG password will

no longer have an expiry date. The changes remain compliant with PCI DSS

regulations. If your DPG password is due to expire prior to this time, please follow the

guidelines available below to make the necessary changes for this last compulsory

time. Should you still wish to change your DPG password at any given time after the 18

September 2012, the facility to do so is still available?

Further information about generating a new password is available in the Support

Centre: http://datacash.custhelp.com/cgi-

bin/datacash.cfg/php/enduser/std_adp.php?p_faqid=567

(keyword search “DPG password”)

Example XML for Authentication complex elements

<password>mypasswd</password>

</Authentication>

2.1.1.3 Response

There are several elements to the Response that are returned regardless of the Service

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

used. These are:

Element Name

Description

Status

Numeric return code indicating the result of the transaction

Reason

A text field expanding on the status of the transaction

datacash_reference

The DataCash reference of the transaction.

Time

The Unix Timestamp at which the transaction reached the

DataCash server

Mode

Indicates the current status of your account – one of: live,

test or accreditation

There are also the following additional elements that may be returned depending upon

the result of the transaction:

Element Name

Description

Information

If an error is generated, additional information is often

returned to allow the source of the error to be identified

merchant_reference

Your reference number

Back to Contents

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.2 SINGLE CARD PAYMENTS

2.2.1 Credit and Debit Card Service

A technical introduction to this Service is available on the website:

http://www.datacash.com/gettingproducts.php?id=Bank-Card-Processing-

2.2.1.1 Schema Elements for Request

In this section the required fields for each transaction type will be presented, along

with example XML for those fields. The XML is presented in italics for those fields that

are not required for all transaction types. If the transaction type is specified in the

XML, this is highlighted in the cases where other transaction types can be used in its

place.

As not all transaction types use the same fields, each field will be labelled with the

following key:

 O - Optional

 R - Required, field must be presented

 X - Excluded, presenting this field will cause the transaction to fail

 M - Mandatory if Available, if the information is available, it should be presented

Please refer to the website for definitions of the transaction types and examples of

when you may wish to implement them.

The following keys will be used for each transaction type:

 A - auth

 P - pre

 R - refund

 E – erp

 C – cancel

 F – fulfill

 TR – txn_refund

 ARR – authorize_referral_request

Initial Transactions with Card details

The auth, pre, refund and erp transaction types all require the same information

about the transaction to be provided. This data is passed in these distinct places in the

schema:

 Request

o Authentication – section 2.1.1.2

o Transaction

 CardTxn – the type and authorisation code, section 2.2.1.1.2

 Card - this contains all the information about the Card, section

2.2.1.1.1

 TxnDetails - contains details of the transaction, section 2.2.1.1.3

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Historic Transactions

The cancel, fulfill, txn_refund and authorize_referral_request transaction

types all require similar information about the transaction to be provided. This data is

passed in these distinct places in the schema:

 Request

o Authentication – section 2.1.1.2

o Transaction

 HistoricTxn – information relating to the original transaction section

2.2.1.1.4

 Card - this contains all the information about the Card, section

2.2.1.1.1

 TxnDetails - contains details of the transaction, section 2.2.1.1.3

2.2.1.1.1 Card

Element Name:

Card

Position:

Request.Transaction.CardTxn

Elements of Card

Element

Name

Description

Values / Limitations

A

P

R

E

pan

card number

must be a valid card number

between 13 and 19 digits in length

R

expirydate

expiry date for

the card

must be passed in mm/yy format

R

startdate

start date for

the card

must be passed in mm/yy format

M

issuenumber

issue number

of the card

must be one or two digits long

M

The CardInfo files can be used to determine whether a startdate or an issuenumber is

required for each card.

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example XML for Card complex elements

<Card>

</Card>

<Card>

</Card>

2.2.1.1.2 CardTxn

For transactions using card details only. In addition to the basic Card details, the

transaction type and authorisation code (if applicable) are sent in the CardTxn

element:

Element Name:

CardTxn

Position:

Request.Transaction

Elements of CardTxn

Element

Name

Description

Values / Limitations

A

P

R

E

Card

see section 2.2.1.1.1

authcode

authorisation code

received from the

bank

If presented, must be value received

from Banks Authorisation centre

O

method

the transaction

type

auth

pre

refund

erp

R

Example XML for CardTxn complex elements

</CardTxn>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.2.1.1.3 TxnDetails

For all transactions:

Element Name:

TxnDetails

Position:

Request.Transaction

Elements of TxnDetails

Element Name

Description

Values/

Limitations

A

P

R

E

C

F

TR

ARR

merchantrefer

ence

A unique

reference

number for each

transaction

Min 6, max 30

alphanumeric

characters. Must

be unique

R

-

*

-

amount

The value of the

transaction

R

-

O

-

custom_data

Custom data to

be stored against

the transaction,

for view/search

in Reporting

system

Max 30

alphanumeric

characters.

O

capture_metho

d

If vTID is set up for

more than one

capture method,this

specifies the

transaction’s

environment.

ecomm

cnp

cont_auth

ivrcapture

O

Attributes for Elements of TxnDetails

Attribute

Name

Attribute

of

Element

Values / Limitations

A

P

R

E

C

F

TR

ARR

currency

amount

Currency is passed in the 3

character ISO 4217

Alphabetic format (Default is

GBP)

e.g. GBP, USD, EUR

O

X

-

Note: For fulfill transactions, the merchantreference field is not required. However,

if the Merchant is subscribed to the SplitShipment Service and has already fulfilled part

of the transaction, the merchantreference field must be presented for any subsequent

fulfill transactions submitted on that transaction.

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example XML for TxnDetails complex elements:

Card Transaction

<merchantreference>myreference123459988</merchantreference>

<custom_data>1AZ23HHH</custom_data>

</TxnDetails>

Historic Transaction

</TxnDetails>

Additional fulfill when subscribed to SplitShipment

<merchantreference>myreference123459988_1</merchantreference>

</TxnDetails>

2.2.1.1.4 HistoricTxn

This element is the direct equivalent of the Card element (for transactions using card

details).

Element Name:

HistoricTxn

Position:

Request.Transaction

Elements of HistoricTxn

Element

Name

Description

Values /

Limitations

C

F

TR

ARR

reference

DataCash unique reference of

the original transaction

must be a valid

transaction

R

authcode

DataCash authorisation code of

the original transaction. For

fulfill and

authorize_referral_request,

if the original transaction was

referred, then provide the value

received from Banks

Authorisation centre

-

n/a

R

-

R

method

The transaction type

fulfill

txn_refund

cancel

authorize_referr

al_request

R

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example XML Request for HistoricTxn complex elements

<method>fulfill</method>

</HistoricTxn>

2.2.1.1.4.1 Acquirer Specific Notes

2.2.1.1.5 AdditionalInfo

For the Chase PaymentTech acquirer, an optional reversal=”true” attribute can be

supplied within the method element when a cancel is being performed. This has the

effect of attempting an online transaction reversal with the acquirer, in addition to

excluding the transaction from the settlement file.AdditionalInfo

Element Name

AdditionalInfo

Position

Request.Transaction.TxnDetails

Children

Yes

Attributes

No

Elements of AdditionalInfo

Element Name

Description

Values/Limitations

Required

addendumdata

O

risk_bypass

Y/N

O

CustomerInfo

See below

O

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.2.1.1.6 CustomerInfo

Element Name

CustomerInfo

Position

Request.Transaction.TxnDetails.AdditionalInfo

Children

Yes

Attributes

No

2.2.1.2 XML Examples Requests

2.2.1.2.1 Transactions with Card Details

Example XML Request for refund

</Authentication>

<Card>

</Card>

<method>refund</method>

</CardTxn>

<custom_data>1AZ23HHH</custom_data>

</TxnDetails>

</Transaction>

</Request>

If the method is changed, the same XML could also be used for auth, pre and erp

transactions.

Elements of CustomerInfo

Element Name

Description

Values/Limitations

Required

customer_ip_address

IP Address

Must be a valid IP Address

O

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example XML Request for pre with an authcode

</Authentication>

<Card>

</Card>

</CardTxn>

</TxnDetails>

</Transaction>

</Request>

2.2.1.2.2 Historic Transactions

Example XML Request for cancel

</Authentication>

<method>cancel</method>

</HistoricTxn>

</Transaction>

</Request>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example XML Request for fulfill

</Authentication>

</TxnDetails>

<method>fulfill</method>

</HistoricTxn>

</Transaction>

</Request>

Example XML Request for an additional fulfill when configured for

SplitShipment

<method>fulfill</method>

</HistoricTxn>

<merchantreference>fulfill_2</merchantreference>

</TxnDetails>

</Transaction>

</Request>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example XML Request for a txn_refund

</Authentication>

</TxnDetails>

<method>txn_refund</method>

</HistoricTxn>

</Transaction>

</Request>

Example XML Request for an authorize_referral_request

</Authentication>

<method>authorize_referral_request</method>

</HistoricTxn>

</Transaction>

</Request>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.2.1.3 Schema Elements for Response

In addition to the elements covered in this section, Responses for this Service will also

contain the general Response elements, as described in section 2.1.1.3.

2.2.1.3.1 CardTxn

Element Name:

CardTxn

Position:

Response

Element

Name

Description

Values / Limitations

issuer

The Card Issuing Bank, if known

card_scheme

The Card

Scheme, if

known. Current

values which

may be returned

are listed

 American

Express

 Arval Fuel Card

 ATM

 Debit

Mastercard

 Diners Club

 Discover

 Duet

 EnRoute

 GE Capital

 JCB

 Key Fuels Card

 Laser

 Maestro

 Mastercard

 Platima

 Solo

 PPT

 RBS Gift Card

 ReD Fuel Card

 Red Liquid Fuel

Card

 UK Fuel Card

 VISA

 VISA Debit

 VISA Electron

 Visa Purchasing

country

The Country of Issue, if known

authcode

Authorisation code for successful transactions. Additional information

from the bank if declined or referred

Example XML Response for CardTxn complex elements

<card_scheme>Visa</card_scheme>

<country>France</country>

<issuer>Credit Lyonnais</issuer>

</CardTxn>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.2.1.4 XML Example Responses

There are various results that can be returned for transactions. These can be clustered

into two groups:

 Bank Responses – the transaction is submitted to the bank

 Error codes – an error occurred which prevented the transaction from being sent

to the bank

If the transaction is submitted to the bank, the bank can either accept, decline or refer

the transaction. Please refer to the website for additional information on why

transactions can be declined or referred.

Status

Meaning

1

The bank has authorised the transaction

7

The bank has declined or referred the transaction

All others

All other responses are error codes

As there are many different return codes, this document only contains examples for

status 1 and 7. A complete list of Response Codes for this service is available on the

website. The Support Centre also contains extensive examples for most error codes,

with illustrations of how they would appear in both Reporting and an XML Response,

plus suggestions to prevent them occurring.

 Support Centre

 Website

2.2.1.4.1 Initial Transactions

Example XML Response for an authorised initial transaction

<card_scheme>Mastercard</card_scheme>

<country>United Kingdom</country>

</CardTxn>

<datacash_reference>3000000088888888</datacash_reference>

<reason>ACCEPTED</reason>

</Response>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example XML Response for a REFERRED transaction

<authcode>CALL AUTH CENTRE</authcode>

<card_scheme>Mastercard</card_scheme>

<country>United Kingdom</country>

<issuer>BARCLAYS BANK PLC</issuer>

</CardTxn>

<datacash_reference>3100000088888123</datacash_reference>

<reason>REFERRED</reason>

</Response>

Example XML Response for a DECLINED transaction

<authcode>DECLINED</authcode>

<card_scheme>Mastercard</card_scheme>

<country>United Kingdom</country>

</CardTxn>

<datacash_reference>4400200045583767</datacash_reference>

<reason>DECLINED</reason>

</Response>

2.2.1.4.2 Historic Transactions

Example XML Response for a successful cancel

<datacash_reference>4900200000000001</datacash_reference>

<reason>CANCELLED OK</reason>

</Response>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example XML Response for a successful fulfil

<datacash_reference>3900200000000001</datacash_reference>

<reason>FULFILLED OK</reason>

</Response>

Example XML for a successful txn_refund

<datacash_reference>4000000088889999</datacash_reference>

</HistoricTxn>

<reason>ACCEPTED</reason>

</Response>

Example XML Response for a successful authorize_referral_request

<datacash_reference>3900200000000001</datacash_reference>

<reason>ACCEPTED</reason>

</Response>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.2.1.4.2.1 Acquirer Specific Notes

As mentioned in the Acquirer Specific Notes (section 2.2.1.1.4.1) for the XML request,

the following is returned as a response to a Chase PaymentTech cancellation where the

method attribute reversal=”true” was supplied:

Example XML Response for a successfully reversed cancellation

<datacash_reference>4100900012345675</datacash_reference>

<reason reversal="success">CANCELLED OK</reason>

</Response>

This additional attribute indicates the results of the online reversal. This could be

‘success’, ‘failed’ or ‘not attempted’.

2.2.2 Additional Data (American Express ISO8583)

The following complex elements are specific to merchants subscribed to the American

Express ISO8583 service.

Element Name:

AdditionalData

Position:

Request.Transaction.TxnDetails

Element Name

Description

ITD

This element should be provided for Ecommerce transactions (See

section 2.2.2.1).

This block cannot be used in conjunction with the IAC element

(Ecommerce Airline Transactions). In the case where your

transaction involves the sale of airline tickets, just send the IAC

and not the ITD.

IAC

This element should be provided for Ecommerce Airline

transactions. It should be populated in addition to the standard

Request.Transaction.TxnDetails.AirlinesDetails elements. See

section 2.2.2.2

AAV

This element can be provided in addition to the standard Cv2Avs

element. It allows additional Cv2Avs data to be sent. See section

2.2.2.3

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.2.2.1 ITD

This block should only be sent for standard Ecommerce transactions that do not

involve the sale of Airline Tickets. If the transaction involves the sale of Airline tickets,

send the IAC block instead.

Element Name:

ITD

Position:

Request.Transaction.TxnDetails.AdditionalData

Element Name

Description

Values / Limitations

customer_email

The customer’s E-Mail

address. Example:

customer@example.com

Valid E-Mail format, Max 60 Bytes

customer_hostname

The customer’s hostname.

Valid FQDN format, Max 60 Bytes

http_browser_type

The customers browser type.

Max 60 Bytes

ship_to_country

The country code for the

shipping destination.

Max 3 Bytes

shipping_method

The shipping method used to

deliver the product or service

associated with the

transaction.

 01 - Same day

 02 - Overnight / next day

 03 - Priority 2-3 days

 04 - Ground, 4 or more days

 05 - Electronic delivery

 06 - ZZ - Reserved

MerchantProductSKU

See section 2.2.2.1.1

Up to 5 sub-elements can be

supplied in this block.

customer_ip

The customer’s IP address.

Valid IP Address Format, Max 15 Bytes

customer_ani

ANI (Automatic Number

Identification) specified phone

number that the customer

used to place the order.

Example: 6025551212

Numeric, Max 10 Bytes

customer_ii_digits

Telephone company-provided

ANI information identifier (II)

digits associated with

customer_ani field above. II

digits indicate the call type.

For example, cellular (61-63),

payphone (27), toll free (24,

25) etc.

Numeric, Max 2 Bytes

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.2.2.1.1 Merchant Product SKU

Element Name:

MerchantProductSku

Position:

Request.Transaction.TxnDetails.AdditionalData.ITD

Element Name

Description

Values / Limitations

sku

Unique SKU (Stock Keeping Unit)

inventory reference number of

product associated with this

authorization request. For multiple

items, you should provide the most

expensive item first. Up to 5

elements can be supplied.

Alphanumeric & Special

Characters, Max 15 Bytes.

Example XML for a MerchantProductSku

Element

...

<ITD>

...

</MerchantProductSku>

...

</ITD>

...

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.2.2.2 IAC

This block should be sent for Ecommerce Airline transactions where the sale of airline

tickets is involved. If there are no airline tickets involved, send the ITD block instead.

Element Name:

IAC

Position:

Request.Transaction.TxnDetails.AdditionalData

Element Name

Description

Values /

Limitations

departure_date

The flight departure date.

YYYYMMDD, Max 8

Bytes

PassengerName

This element contains the passengers name and other

details. See section 2.2.2.2.1

origin

The 3 character IATA airport code for

the departure airport.

Max 5 Bytes

dest

The 3 character IATA airport code for

the destination airport.

Max 5 Bytes

RoutingCities

Up to 10 city sub-elements can be supplied in this block.

See section 2.2.2.2.2

AirlineCarriers

Up to 9 airline sub-elements can be supplied in this block.

See section 2.2.2.2.3

farebasis

Primary & secondary discount codes

indicate class

of service and fare level associated

with ticket.

Truncate at 24 bytes, if necessary.

Max 24 Bytes

number_of_passengers

The number of passengers travelling.

Numeric, 3 Bytes

customer_ip

The customer’s IP address.

Valid IP Address Format,

Max 15 Bytes

customer_email

The customer’s E-Mail address.

Valid E-Mail format, Max

60 Bytes

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.2.2.2.1 Passenger Name

Element Name:

PassengerName

Position:

Request.Transaction.TxnDetails.AdditionalData.IAC

Element Name

Description

Values / Limitations

Surname

The customer’s

surname.

Max 40 Bytes

Firstname

The customer’s

firstname

Max 40 Bytes

middle_initial

The customer’s middle

initial(s)

Max 40 Bytes

title

The customers honorific.

Max 40 Bytes

Example XML for a PassengerName Element

...

<IAC>

...

<surname>Bloggs</surname>

<middle_initial>J</middle_initial>

</PassengerName>

...

</IAC>

...

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.2.2.2.2 Routing Cities

Element Name:

RoutingCities

Position:

Request.Transaction.TxnDetails.AdditionalData.IAC

Element Name

Description

Values / Limitations

city

Up to 10 city sub-

elements can be

supplied in this block.

The city elements should

contain the Routing

Airport or City Codes for

each leg on the ticket

(including the origin and

dest).

Max 5 Bytes per sub-element

Example XML for a RoutingCities Element

...

<IAC>

...

</RoutingCities>

...

</IAC>

...

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.2.2.2.3 Airline Carriers

Element Name:

AirlineCarriers

Position:

Request.Transaction.TxnDetails.AdditionalData.IAC

Element Name

Description

Values / Limitations

airline

Up to 9 airline sub-elements

can be supplied in this

block. The Airline Carrier

Code for each leg on the

ticket should be provided

(including origin and dest).

Note that each leg must

have an entry, even if

multiple or all legs are on

the same airline.

2 Character ICAO Airline

Designator, Max 5 Bytes

Example XML for a AirlineCarriers Element

...

<IAC>

...

</AirlineCarriers>

...

</IAC>

...

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.2.2.3 AAV

This should be provided in addition to the standard Cv2Avs block.

Element Name:

AAV

Position:

Request.Transaction.TxnDetails.AdditionalData

Element Name

Description

Values / Limitations

cm_billing_postal_code

The Card Member

billing postal code.

Max 9 Bytes

cm_billing_street_address

The Card Member

billing street address.

Max 20 Bytes

cm_first_name

The Card Member first

name.

Max 15 Bytes

cm_last_name

The Card Member

surname.

Max 30 Bytes

cm_phone_number

The Card Member

telephone number

Max 10 Bytes

ship_to_postal_code

The shipping postal

code.

Max 9 Bytes

ship_to_address

The shipping address.

Max 50 Bytes

ship_to_first_name

The shipping first

name.

Max 15 Bytes

ship_to_last_name

The shipping last

name.

Max 30 Bytes

ship_to_phone_number

The shipping phone

number.

Max 10 Bytes

ship_to_country_code

The shipping

destination country

code.

Max 3 Bytes

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.2.2.4 Example XML

Please note that the following snippet is an example. In reality the ITD and IAC

elements would never be submitted in the same request. The ITD block should be sent

for standard Ecommerce transactions, whereas the IAC block should be sent instead of

the ITD for Airline Ecommerce transactions.

Partial XML Request showing the AdditionalData Elements.

...

...

<ITD>

<customer_email>example@example.com</customer_email>

<customer_hostname>example.com</customer_hostname>

<http_browser_type>Mozilla /4,0</http_browser_type>

<ship_to_country>840</ship_to_country>

<shipping_method />

</MerchantProductSku>

<customer_ip>127.0.0.1</customer_ip>

<customer_ani>441315388400</customer_ani>

<customer_ii_digits>27</customer_ii_digits>

</ITD>

<IAC>

<departure_date>20110231</departure_date>

<surname>Bloggs</surname>

<middle_initial>J</middle_initial>

</PassengerName>

</RoutingCities>

</AirlineCarriers>

<number_of_passengers>2</number_of_passengers>

<customer_ip>192.168.1.1</customer_ip>

<customer_email>customer@example.com</customer_email>

</IAC>

<AAV>

<cm_billing_postal_code>EH6 7EZ</cm_billing_postal_code>

<cm_billing_street_address>14, Links

Place</cm_billing_street_address>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.2.3 Misc Customer Info

Misc Customer Info can be provided with the majority of transaction types. To use this

service it must be configured on your account by DataCash support.

The following complex element can be sent in the request XML and will be captured and

stored alongside the transaction by DataCash.

Element Name:

MiscCustomerInfo

Position:

Request.Transaction.TxnDetails

Element Name

Description

Values / Limitations

firstname

The customer’s first name.

Max 50 Characters.

lastname

The customer’s last name /

surname.

Max 50 Characters.

email

The customer’s E-Mail

address. Example:

customer@example.com

Valid E-Mail format. Max 255

Characters.

language

The country code for the

shipping destination.

Max 20 Characters.

Country

The customers country.

Max 50 Characters.

<cm_first_name>Joe</cm_first_name>

<cm_last_name>Bloggs</cm_last_name>

<cm_phone_number>441315388400</cm_phone_number>

<ship_to_postal_code>7446</ship_to_postal_code>

<ship_to_address>No 1 Waterview</ship_to_address>

<ship_to_first_name>Fred</ship_to_first_name>

<ship_to_last_name>Bloggs</ship_to_last_name>

<ship_to_phone_number>27215284500</ship_to_phone_number>

<ship_to_country_code>710</ship_to_country_code>

</AAV>

</AdditionalData>

...

</TxnDetails>

...

</Request>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.2.4 Line Item Detail

A technical introduction to this Service is available on the website:

http://www.datacash.com/gettingproducts.php?id=Corporate-Purchasing-

This service is utilised by sending a normal Credit and Debit Card Service Request with

additional information. This section of documentation assumes the Credit and Debit

Card Service has already been integrated and the reader is familiar with it. The Credit

and Debit Card Service is described in section 2.2.1.

Please bear in mind that the amount field must be reconciled with the line items. The

amount field should contain the gross amount, after tax and (where appropriate)

shipping and discounts. In order to compensate for rounding errors, a tolerance of one

minor currency unit per line item element is allowed.

When using the Line Item Detail Service, the transaction methods auth, pre, refund,

erp and txn_refund can all be submitted. However, if you are using the pre and erp

methods, the full amount must be fulfilled – partial fulfills cannot be used. The

txn_refund method can also be used, providing the full value of the original

transaction is refunded in one step. If a partial fulfill, or txn_refund is performed,

the amount would not reconcile with the line items.

2.2.4.1 Schema Elements for Request

In this section, the fields that can be presented with Line Item Detail transactions will

be presented along with example XML for those fields.

To process Visa or American Express Corporate Purchasing Cards, one can make use of

the LineItemDetail schema element:

 Request

o Authentication – section 2.1.1.2

o Transaction

 TxnDetails

 LineItemDetail - information relating to the whole order, section

2.2.4.1.5

o Shipping – details about the delivery, section 2.2.4.1.2

 AddressDetail – details about the delivery address, section

2.2.4.1.1

o Items – allows detail of each item to be passed, section 2.2.4.1.3

 Item – detailed information about a single item, section 2.2.4.1.4

As the fields which can be provided depend upon the Acquiring Bank you are using,

each field will be labelled with the following key:

 O - Optional

 R - Required, field must be presented

 X - Excluded, presenting this field will cause the transaction to fail

 M - Mandatory if available; if the information is available, it should be presented

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.2.4.1.1 AddressDetail

The fields within this element can only be presented for holders of American Express

cards when the cardholder is billed in a different country from the supplier (a cross

border transaction). If you are submitting such a transaction, it is recommended that

these fields are provided.

Submitting this information for a non-American Express transaction, or an American

Express non-cross border transaction will cause the transaction to be rejected.

Element Name

AddressDetail

Position

Request.Transaction.TxnDetails.LineItemDetail.Shipping

Children

Yes

Attributes

Yes

Elements of AddressDetail

Attribute

Name

Description

Values/Limitations

Amex

Amex,

cross

border

NWS

side

Designates whether the

source or destination

address

“source” or

“destination”

X

R

X

Elements of AddressDetail

Element

Name

Description

Values/Limitations

Amex

Amex,

cross

border

NWS

address

A single line of the

address. Between one

and four such lines may

be submitted,

distinguished by the line

attribute

Alphanumeric, up to

40 characters. line

attribute should be a

single digit between 1

and 4

X

R

X

postcode

The postal code for the

address

Alphanumeric, up to

10 characters

X

R

X

country

ISO numeric code for the

address

Numeric, 3-digit ISO

code. For example,

UK=826, France=250

etc.

X

R

X

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

XML Example element for AddressDetail

<address line="1">My Company</address>

<address line="2">My Street</address>

<address line="3">Mytown</address>

</AddressDetail>

<address line="1">Ma Maison</address>

</AddressDetail>

2.2.4.1.2 Shipping

Optional shipping information may be submitted for a CPC transaction. In the case of

American Express, whilst this information may be submitted, it is not used by their

systems at present (with the exception of the AddressDetail information discussed

above). In particular, shipping should not be used in invoice reconciliation for

American Express transactions.

Element Name

Shipping

Position

Request.Transaction.TxnDetails.LineItemDetail

Children

Yes

Attributes

No

Attributes of Shipping

Element Name

Description

Values / Limitations

Amex

NWS

AddressDetail

See section 2.2.4.1.1

destinationcountrycode

Country code of the

destination

ISO Alphabetic 3

characters

O

destinationpostalcode

Postcode to send to

Alphanumeric up to

10 characters

O

shipfrompostalcode

Postcode of the

source

Alphanumeric up to

10 characters

O

shippingamount

Net (pre-tax) cost

of shipping

Numeric

O

shippingVATrate

Percentage rate at

which shipping is

taxed

Numeric

O

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

XML Example elements for Shipping

</Shipping>

2.2.4.1.3 Items

Element Name

Items

Position

Request.Transaction.TxnDetails.LineItemDetail

Children

Yes

Attributes

No

Elements of Items

Element Name

Description

Values/Limitations

Item

An individual line item, as

described below

At least one item

element must be

submitted per

transaction

Example XML is shown in section 2.2.4.1.4.

2.2.4.1.4 Item

Details of the individual line items are submitted here.

Element Name

Item

Position

Request.Transaction.TxnDetails.LineItemDetail.Items

Children

Yes

Attributes

No

Attributes of Item

Element Name

Description

Required

Values/Limitations

commoditycode

The commodity code for

this purchase

N

Four-digit commodity

code.

See Appendix 1 for a

list.

description

Description of the item

Y

Alphanumeric up to

26 characters

(Barclays, Natwest),

or 40 characters

(Amex).

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

discountamount

The item-level discount

for this item

N

Numeric.

Not supported by

American Express

product_code

Merchant’s product code

N

Alphanumeric up to

12 characters

quantity

The number of units

Y

Numeric

totalamount

The total Net (pre-VAT)

cost of the items

Y

Numeric.

Must reconcile with

quantity, unitprice

and (where

appropriate)

discountamount

unitcost

The amount for a single

unit

Y

Numeric

unitmeasure

The units in which the

items are counted

Y

Alphanumeric up to

12 characters

vatrate

The item-level VAT rate

for this item

Y

Numeric

XML Example element for Items and Item

<Items>

<Item>

<description>Ring Binder</description>

</Item>

<Item>

<description>Photocopier paper</description>

</Item>

</Items>

2.2.4.1.5 LineItemDetail

This is where information relating to the order as a whole is submitted. Since each

acquiring bank has different requirements, this information is listed with the following

key:

Element Name

LineItemDetail

Position

Request.Transaction.TxnDetails

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Children

Y

Attributes

N

Elements of LineItemDetail

Element Name

Description

Values/Limitations

NWS

Amex

customercode

Customer-

supplied reference

field

Alphanumeric, up to

16 characters

R

O

customernumber

Customer-

supplied reference

field

Alphanumeric, up to

17 characters

N

O

customerref1

Customer-

supplied reference

field

Alphanumeric, up to

20 characters

N

O

customerref2

Customer-

supplied reference

field

Alphanumeric, up to

20 characters

N

O

customerVATnumber

The customer’s

VAT number

Alphanumeric, up to

13 characters

O

O1

discountamount

Transaction-level

discount amount

Numeric

O

O2

merchantVATnumber

The merchant’s

VAT number

Alphanumeric, up to

13 characters

O

R

originalinvoicenumber

The invoice

number of the

original

transaction (for

refunds)

Alphanumeric, up to

12 characters

O

originalorderdate

The date on which

the order was

placed

YYMMDD

O

supplierorderreference

The supplier’s

reference

Alphanumeric, up to

12 characters

O

N

transactionVAT

The total VAT

amount for the

transaction

Numeric. Must

reconcile with the

individual amounts

and VAT rates of the

items

R

transactionVATstatus

Should always be

‘1’

R

Notes:

1

For American Express transactions, the customer VAT number is required for cross

border transactions, and any transaction made by a Belgian merchant.

2

Whilst the discountamount field may be submitted to American Express, it is currently

ignored by their system. In particular, it must not be used in invoice reconciliation.

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.2.4.2 XML Example Request

2.2.5 Airlines Transaction Records

This service is utilised by sending additional information in an otherwise normal Credit

XML Example Transaction for an order with two items

</Authentication>

<Card>

</Card>

</CardTxn>

<customercode>CustCode123</customercode>

</Shipping>

<Items>

<Item>

<description>Ring Binder</description>

</Item>

<Item>

<description>Photocopier paper</description>

</Item>

</Items>

</LineItemDetail>

</TxnDetails>

</Transaction>

</Request>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

and Debit Card transaction. This section assumes that facility for processing Credit and

Debit Card transactions has already been integrated and the reader is familiar with it.

Details about the Credit and Debit Card Service are available in section 2.2.1

The DPG will also accept Airline data in a fulfill transaction when using the two-stage

transaction model. The location of the data in the request XML remains the same. At

present this only applies to Airline data.

This service is currently available for merchants using The Royal Bank of Scotland

Group (inc Natwest Streamline, Natwest IMS, Ulster Bank, Clydesdale Bank, Yorkshire

Bank) , Barclaycard Business and Omnipay.

2.2.5.1 Schema Elements for Request

In this section, the fields associated with Airlines transactions will be presented along

with example XML for those fields.

To submit flight itinerary information, one should use the AirlinesDetails container

element:

 Request

o Authentication – section 2.1.1.1.1

o Transaction

 TxnDetails

 AirlinesDetails – information relating to the whole order, section

2.2.5.1.1

o Passenger – details about an individual passenger, section 2.2.5.4

o FlightLeg – allows detail of each leg of the journey, section 2.2.6.4.1

In the following tables, each field will be labelled with the following key:

 O - Optional

 R - Required, field must be presented

2.2.5.1.1 AirlinesDetails

The AirlinesDetails elements contains information relating to the whole order.

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Element Name

AirlinesDetails

Position

Request.Transaction.TxnDetails

Children

Yes

Attributes

No

2.2.5.3 Elements of AirlinesDetails

Elements of AirlinesDetails

Element Name

Description

Values/Limitations

Required

agencyname

The POS agency

name

Alphanumeric, up to 26

characters (for submission

to DPG). For BMS

merchants: the first 25

characters will be used at

settlement

R

agencycode

The POS IATA

number

Numeric up to 8

characters

R

airlineplaninvoice

The airline plan

invoice

Alpha numeric, up to 6

characters

O

airlineplannumber

The airline plan

number

Alphanumeric, up to 2

characters

O

departurepoint

The departure

point

Three-character

origination code

R

Passenger

See Section 2.2.5.4

FlightLeg

See Section 2.2.6.4.1

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

XML Example elements for AirlinesDetails

<agencyname>MyAirlinesAgency</agencyname>

</AirlinesDetails>

<agencyname>MyAirlinesAgency</agencyname>

</AirlinesDetails>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.2.5.4 Passenger

There must be at least one passenger per transaction. Where there is more than one

person travelling, supplying multiple Passenger elements allows the entire transaction

to be authorised at once, whilst maintaining the individual invoice information for each

passenger. The sum of ticket prices for each passenger should match the amount field

that forms part of the normal Credit and Debit Card information. This element may

repeat as often as necessary.

Element Name

Passenger

Position

Request.Transaction.TxnDetails.AirlinesDetails

Children

Yes

Attributes

No

Elements of Passenger

Element Name

Description

Values/Limitations

Required

passengername

The passenger’s

name

Alphanumeric, up to 25

characters

R

passengerref

A unique reference

for the passenger

Alphanumeric, up to 17

characters for submission to

DPG. For BMS merchants: the

first 12 characters will be used

at settlement

R

ticketnumber

Ticket number for

the passenger.

This may optionally

be different for

each passenger

14 characters. This usually

consists of a 3-character prefix,

10 characters of ticket number

and a single check digit at the

end. The prefix characters and

check digit may optionally be

replaced by ‘0’

R

ticketprice

The ticket price for

the individual

passenger.

R

XML Example element for Passenger

<passengername>Joe Bloggs</passengername>

</Passenger>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.2.5.4.1 FlightLeg

Each transaction may contain details of up to four flight legs. These are each specified

in their own FlightLeg container element. For a multi-flight leg journey: the point of

departure for the first leg will be set to the value supplied in

AirlinesDetails.departurepoint; the point of departure for subsequent legs will be

taken to be the destination from the previous leg.

Element Name

FlightLeg

Position

Request.Transaction.TxnDetailsAirlinesDetails

Children

Yes

Attributes

Yes

Attributes of FlightLeg

Attribute

Name

Description

Values/Limitations

Required

number

The stage of the

journey

1, 2, 3 or 4

R

Elements of FlightLeg

Element Name

Description

Values/Limitations

Required

carriercode

Carrier code for this

leg

Two character carrier

code

R

class

Service class of this

leg

Single alphanumeric

character

R

departtax

Depature tax

Numeric, up to 12

digits including decimal

point

O

departuredate

Date of departure

for this leg

Date, as YYYYMMDD

R

destination

The destination for

this leg

Three-character

destination code

R

farebasiscode

The fare basis code

Alphanumeric, up to 6

charcters

O

flight_number

Flight number for

this leg

Alphanumeric, up to 4

characters

O

stopovercode

The stop-over code

Alphanumeric, 1

character

O

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

XML Example elements for FlightLeg

<flight_number>1234</flight_number>

</FlightLeg>

<flight_number>1234</flight_number>

</FlightLeg>

2.2.5.4.2 ISOAirline

The ISOAirline elements contains information relating to the whole order.

Element Name

ISOAirline

Position

Request.Transaction.TxnDetails

Children

Yes

Attributes

No

Elements of AirlinesDetails

Element Name

Description

Values/Limitations

Required

issuingcarrier

2- or 3-character

IATA assigned

airline designator.

Alphanumeric

R

customercode

Cardholder supplied

code

Alphanumeric, up to 27

characters

R

issuedate

Date of issue

YYMMDD

O

totalfees

Total fees

R

travelagencyname

Name of agency

Alphanumeric

R

ticketnumber

Ticket number

Alphanumeric, up to 15

characters

R

travelagencycode

IATA-assigned

Agency code (7

digits plus check

O

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

XML Example elements for ISOAirline

<travelagencyname>MyAgency</travelagencyname>

</ISOAirline>

2.2.5.4.3 ISOAirlinePassenger

Only details of one passenger may be provided in a transaction with ISO Airline data.

Element Name

ISOAirlinePassenger

Position

Request.Transaction.TxnDetails.ISOAirline

Children

Yes

Attributes

No

Elements of Passenger

digit).

totaltaxes

Total taxes

R

totalfare

Total fare

R

pnr

Alphanumeric, up to 6

characters

R

ISOAirlinePassenger

See Section 2.2.5.4.3

ISOAirlineLeg

See Section 2.2.6.4.4

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Element Name

Description

Values/Limitations

Required

passengername

The passenger’s

name

Alphanumeric, up to 25

characters

R

XML Example element for ISOAirlinePassenger

<passengername>Joe Bloggs</passengername>

</ISOAirlinePassenger>

2.2.5.4.4 ISOAirlineLeg

Each transaction may contain details of up to four flight legs. These are each specified

in their own ISOAirlineLeg container element. For a multi-flight leg journey, the point

of departure for the first leg will be set to the value supplied in

ISOAirline.departurepoint and the point of departure for subsequent legs will be

taken to be the destination from the previous leg.

Element Name

ISOAirlineLeg

Position

Request.Transaction.TxnDetails.ISOAirline

Children

Yes

Attributes

Yes

Attributes of FlightLeg

Attribute Name

Description

Values/Limitations

Required

number

The stage of the

journey

1, 2, 3 or 4

R

Elements of FlightLeg

Element Name

Description

Values/Limitations

Required

conjunctionticket

Alphanumeric, up to 15

characters

R

exchangeticket

Alphanumeric, up to 15

characters

R

couponnumber

Alphanumeric, single

characters

O

fare

R

taxes

R

fees

R

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

endorsement

Endorsement/Restri

ction

Alphanumeric, up to 20

characters

R

departuredate

YYMMDD

O

departuretime

HHMM

O

originairport

3-character IATA

location identifier.

R

arrivaldate

YYMMDD

O

arrivaltime

HHMM

O

destinationairpor

t

3-character IATA

location identifier.

R

carriercode

2- or 3-character

IATA assigned airline

designator.

R

stopovercode

Single alphanumeric

character

O

farebasiscode

Alphanumeric, up to 15

characters

R

flightnumber

Alphanumeric, up to 5

characters

R

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

XML Example elements for ISOAirlineLeg

</ISOAirlineLeg>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.2.5.5 XML Example Requests

XML Example Transaction for a ticket purchase for multi-leg, single-passenger

flight

</Authentication>

<Card>

</Card>

</CardTxn>

<travelagencyname>MyAgency</travelagencyname>

<passengername>Joe Bloggs</passengername>

</ISOAirlinePassenger>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

</ISOAirlineLeg>

</ISOAirlineLeg>

</ISOAirline>

</TxnDetails>

</Transaction>

</Request>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.2.5.6 XML Example Requests

XML Example Transaction for a ticket purchase for multi-leg, multi-passenger

flight

</Authentication>

<Card>

</Card>

</CardTxn>

<agencyname>MyAirlinesAgency</agencyname>

<passengername>Joe Bloggs</passengername>

</Passenger>

<passengername>Jane Bloggs</passengername>

</Passenger>

</FlightLeg>

</FlightLeg>

</AirlinesDetails>

</TxnDetails>

</Transaction>

</Request>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

XML Example Transaction supplying data in a “fulfill” transaction

</Authentication>

<method>fulfill</method>

</HistoricTxn>

<agencyname>MyAirlinesAgency</agencyname>

<passengername>Joe Bloggs</passengername>

</Passenger>

</FlightLeg>

</AirlinesDetails>

</TxnDetails>

</Transaction>

</Request>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.2.6 Merchant Narrative

The Merchant Narrative Service allows merchants to specify the narrative presented on

the cardholders statement on a per transaction basis, rather than basing the narrative

on static data held by the acquiring bank.

2.2.6.1 Schema Elements for Request

Element Name:

MerchantNarrative

Position:

Request.Transaction.CardTxn

Request.Transaction.HistoricTxn

Elements of MerchantNarrative

Element Name

Description

Values/Limitations

Required

narrative1

Merchant Narrative

element 1

Maximum 26

characters.

The following

characters are

permitted:

Alpha numerics,

!”%&’()*+,-./:;<=>?_

Spaces permitted

however leading and

trailing whitespace will

be trimmed

M

narrative2

Merchant Narrative

element 2

Maximum 26

characters.

The following

characters are

permitted:

Alpha numerics,

!”%&’()*+,-./:;<=>?_

Spaces permitted

however leading and

trailing whitespace will

be trimmed

M

Either narrative1, narrative2, or both can be present in the parent

MerchantNarrative element, however an empty MerchantNarrative element will not

be permitted.

The MerchantNarrative element can only be supplied for the following Bank Card

transaction methods:

 auth

 refund

 txn_refund

 pre

 erp

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

The Merchant Narrative service is not compatible with the Airlines Transaction Record

service.

2.2.6.2 XML Example Request

Example Merchant Narrative Request

<client>xxxxxxxx</client>

<password>xxxxxxxx</password>

</Authentication>

</TxnDetails>

<Card>

<pan>XXXXXXXXXXXXXXXX</pan>

</Card>

</MerchantNarrative>

</CardTxn>

</Transaction>

</Request>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.2.7 Fuel Card Service

The Fuel Card service allows merchants to trade with various fuel card acquirers.

Typically this will be via cardholder present terminals, and at the time of writing will

involve keyed and swiped transactions only (The majority of fuel cards don’t have chips

so parked transactions are not supported at the time of writing).

Refunds onto fuel cards are currently unsupported.

2.2.7.1 Schema Elements for Request

Legend

 FV = fuel_validate

 FOAS = fuel_offline_auth_settle

 FOA = fuel_online_auth

 FS = fuel_settle

2.2.7.1.1 FuelCardTxn

For transactions using card details only. In addition to the basic Card details, the

transaction type and authorisation code (if applicable) are sent in the FuelCardTxn

element:

Element Name:

FuelCardTxn

Position:

Request.Transaction

Elements of FuelCardTxn

Element Name

Description

Values/Limitations

FV

FOAS

FOA

FS

method

The

transaction

type

fuel_validate

fuel_offline_auth_settle

fuel_online_auth

fuel_settle

R

Card

Used for keyed transactions only.

See 2.7.1.1 in Card Holder Present section

M

-

card_details

Data read

from the

magnetic

stripe of the

card, or

equivalent

from the ICC

Must be Base64 encoded.

Only used for swiped

transactions

M

-

authcode

authorisation

code

received

from the

bank

If presented, must be value

received from Banks

Authorisation centre

-

M

O

R

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

receipt_no

The EFT

transaction

number

A one to six digit number.

The values taken in FOAS /

FS transactions will be used.

O

R

O

R

odometer_reading

Distance

travelled by

vehicle

The odometer reading from

the vehicle used in the fuel

transaction. Optional

O

-

registration_number

Registration

of vehicle

The registration from the

vehicle involved in the fuel

transaction. Optional.

O

-

FuelProducts

Complex XML element containing details

about the products ordered. See

FuelProducts section 2.2.8.1.2.

O

-

ICC

See 2.7.1.1.4 in Card Holder Present

section

M

-

Terminal

See 2.7.1.1.3 in Card Holder Present

section

M

-

2.2.7.1.2 FuelProducts

This complex element can contain one or more FuelProduct elements.

Element Name:

FuelProducts

Position:

Request.Transaction.FuelCardTxn

Elements of FuelProducts

Element

Name

Description

Values/Limitations

FV

FOAS

FOA

FS

FuelProduct

Complex XML element containing details about each

product ordered. See section 2.2.8.1.3.

O

-

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.2.7.1.3 FuelProduct

This complex element contains information about a specific fuel product in a

transaction.

Element Name:

FuelProduct

Position:

Request.Transaction.FuelCardTxn.FuelProducts

Elements of FuelProducts

Element Name

Description

Values/Limitations

FV

FOAS

FOA

FS

prod_code

Sale code of the

product ordered

2 alphanumeric characters

O

-

prod_quantity

Quantity of product

purchased. (e.g.

litres dispensed)

Decimal number

O

-

prod_value

Monetary value of

product purchased

Decimal number. Not

validated against overall

transaction amount.

O

-

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.2.7.2 XML Request Examples

Example XML for a fuel_validate transaction (keyed)

</Authentication>

<capturemethod>keyed</capturemethod>

</TxnDetails>

<method>fuel_validate</method>

<terminal_capabilities ic_reader="true"

magnetic_stripe_reader="true" manual_card_entry="true" />

<features_capabilities pin_pad_available="true" />

</Terminal>

<ICC>

<term_type>22</term_type>

</ICC>

<Card>

</Card>

<receipt_no>4383</receipt_no>

<odometer_reading>10000</odometer_reading>

<registration_number>H702MOF</registration_number>

<prod_code>01</prod_code>

<prod_quantity>50.22</prod_quantity>

<prod_value>99.99</prod_value>

</FuelProduct>

<prod_code>05</prod_code>

<prod_quantity>23.45</prod_quantity>

<prod_value>45.75</prod_value>

</FuelProduct>

</FuelProducts>

</FuelCardTxn>

</Transaction>

</Request>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example XML for a fuel_offline_auth_settle transaction (keyed)

</Authentication>

<capturemethod>keyed</capturemethod>

</TxnDetails>

<method>fuel_offline_auth_settle</method>

<terminal_capabilities ic_reader="true"

magnetic_stripe_reader="true" manual_card_entry="true" />

<features_capabilities pin_pad_available="true" />

</Terminal>

<ICC>

<term_type>22</term_type>

</ICC>

<Card>

</Card>

<receipt_no>7813</receipt_no>

<odometer_reading>29057</odometer_reading>

<registration_number>H702MOF</registration_number>

<prod_code>01</prod_code>

<prod_quantity>100.01</prod_quantity>

<prod_value>200.54</prod_value>

</FuelProduct>

</FuelProducts>

</FuelCardTxn>

</Transaction>

</Request>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example XML for a fuel_online_auth transaction (swiped)

</Authentication>

<capturemethod>swiped</capturemethod>

</TxnDetails>

<method>fuel_online_auth</method>

<terminal_capabilities ic_reader="true"

magnetic_stripe_reader="true" manual_card_entry="true" />

<features_capabilities pin_pad_available="true" />

</Terminal>

<ICC>

<term_type>22</term_type>

</ICC>

<card_details

type="track2_data">############</card_details>

<receipt_no>45671</receipt_no>

<odometer_reading>125781</odometer_reading>

<registration_number>H702MOF</registration_number>

</FuelCardTxn>

</Transaction>

</Request>

Example XML for a fuel_settle transaction

</Authentication>

<method>fuel_settle</method>

<receipt_no>123456</receipt_no>

</HistoricTxn>

</Transaction>

</Request>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.2.7.3 Schema Elements for Response

2.2.7.3.1 Response

Note: See main response section 2.1.1.3 for other elements of the response from

DataCash.

Element Name:

Response

Position:

Element Name

Description

acquirer_message

Textual message from the acquirer indicating the

transaction outcome

acquirer_response_code

Code returned by acquirer

referral_telephone_number

Base64 encoded referral telephone number.

Decode this to get the telephone number to call

in the case of an acquirer decline / referral.

2.2.7.3.2 FuelCardTxn

Element Name:

FuelCardTxn

Position:

Response

Element

Name

Description

issuer

The Card Issuing Bank, if known

card_scheme

The Card Scheme, if known. Current values which may be returned are

listed

country

The Country of Issue, if known

authcode

Authorisation code for successful transactions. Additional information

from the bank if declined or referred

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.2.7.4 XML Response Examples

2.2.7.4.1 Successful transactions

Example XML to a successful fuel_online_auth transaction

<?xml version="1.0" encoding="UTF-8" ?>

<card_scheme>Arval Fuel Card</card_scheme>

<issuer>Arval</issuer>

</FuelCardTxn>

<acquirer_message>AUTH CODE:100000</acquirer_message>

<acquirer_response_code>00</acquirer_response_code>

<datacash_reference>4900900012345676</datacash_reference>

<reason>ACCEPTED</reason>

</Response>

Example XML to a successful fuel_settle transaction

<?xml version="1.0" encoding="UTF-8" ?>

<datacash_reference>4900900012345676</datacash_reference>

<reason>SETTLED OK</reason>

</Response>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.2.7.4.2 Unsuccessful transactions

Example XML to an unsuccessful fuel_online_auth transaction

<?xml version="1.0" encoding="UTF-8" ?>

<authcode>DECLINED</authcode>

<card_scheme>Arval Fuel Card</card_scheme>

<issuer>Arval</issuer>

</FuelCardTxn>

<acquirer_message>DECLINED</acquirer_message>

<acquirer_response_code>05</acquirer_response_code>

<datacash_reference>4000900012345671</datacash_reference>

<reason>DECLINED</reason>

<referral_telephone_number>MTIzNA==</referral_telephone_number>

</Response>

2.2.7.4.3 Invalid transactions

Example XML to an invalid fuel_settle transaction

<?xml version="1.0" encoding="UTF-8" ?>

<datacash_reference>4400900012345674</datacash_reference>

<information>fuel_settle or fuel_offline_auth_settle must contain the

receipt_no element</information>

<reason>Fuels: Missing receipt_no element</reason>

</Response>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.2.8 Hosted Card Capture

The Hosted Card Capture (HCC) Service enables DataCash to capture sensitive

cardholder data on behalf of merchants and process transactions with the captured

data. As merchants do not capture and store the cardholder data directly, it is easier

for you to comply with the Payment Card Industry security standards.

This service may also be used in conjunction to with either the Card Tokenization

Service (section 2.9) or the Payment Tokenization Service (section 2.3.1) to enable the

Card Holder to enter only their CVV/CV2 details on the capture page, preventing the

need to re-enter their card details.

A technical introduction to this Service is available on the website:

http://www.datacash.com/gettingproducts.php?id=Hosted-Card-Capture

2.2.8.1 Schema Elements for Request

In this section, the required fields for each transaction type are presented along with

example XML for those fields.

The following keys will be used for each transaction type:

 S – setup

 Q – query

 P – a payment transaction, one of: pre, auth, refund, erp

Initial setup transaction

The setup transaction provides basic details to initiate the Hosted Card Capture

session. This data is passed in these distinct places in the schema:

 Request

o Authentication – section 2.1.1.2

o Transaction

 TxnDetails – contains payment information that will be displayed to the

customer, section 2.2.1.1.3.

 HpsTxn – contains all the details specific to the HCC session setup request,

section 2.2.8.1.3

 Card – this optional section contains the token for cvv only Card Tokens,

section 2.2.8.1.4

 DynamicData – this optional section contains dynamic data to display on the

capture page, section 2.2.8.1.5

Query transaction

After a customer has been returned to your website following the data capture process,

you may optionally send a query transaction. This will allow you to determine whether

the data capture was successful, without sending an authorisation. It will also allow you

to obtain information about the card details that were supplied.

This data is passed in these distinct places in the schema:

 Request

o Authentication – section 2.1.1.2

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

o Transaction

 HistoricTxn – details of the original setup transaction - section 2.2.1.1.4

Payment Using Captured Details

The auth, pre, refund and erp transaction types all require the same information

about the transaction to be provided. This data is passed in these distinct places in the

schema:

 Request

o Authentication – section 2.1.1.2

o Transaction

 TxnDetails – see section 2.2.1.1.3.

 CardTxn – see section 2.2.8.1.2.

 Card –contains the address information for AVS checking and policy,

section 2.2.8.1.4

o ExtendedPolicy – contains details of the AVSCV2 policy, section

2.4.1.1.2

 ThreeDSecure – optional section containing all the details required to

initiate the 3-D Secure check, section 2.4.4.1.1

2.2.8.1.1 TxnDetails

This element is presented for setup and payment transactions only.

Element Name:

TxnDetails

Position:

Request.Transaction

Elements of TxnDetails

Element Name

Description

Values / Limitations

S

Q

P

merchantreference

A unique

reference

number for

each

transaction

Minimum 6, maximum 30

alphanumeric characters. Must be

unique

R

-

O

amount

The value

of the

transaction.

R

-

R

Attributes for Elements of TxnDetails

Attribute

Name

Attribute of

Element

Values / Limitations

currency

amount

Currency is passed in the 3 character ISO 4217

Alphabetic format (Default is GBP)

e.g. GBP, USD, EUR

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Note: if the merchantreference field is not provided for a payment transaction, the DPG

will automatically use the same merchantreference as the setup.

Example XML for TxnDetail complex elements

<merchantreference>27fh450osdfhjk3hs</merchantreference>

</TxnDetail>

2.2.8.1.2 CardTxn

For payment transactions only. In addition to the referencing the HCC setup, the

transaction type and authorisation code (if applicable) are sent in the CardTxn

element:

Element Name:

CardTxn

Position:

Request.Transaction

Elements of CardTxn

Element

Name

Description

Values / Limitations

authcode

authorisation code

received from the

bank

Optional element. If presented, must be

value received from Banks Authorisation

centre

card_details

Specifies the

DataCash reference of

a successful HCC

session setup.

Required. Must be a 16-digit DataCash

reference.

method

the transaction type

auth

pre

refund

erp

Card

See section 2.2.8.1.4

Attributes for Elements of CardTxn

Attribute

Name

Attribute of

Element

Values / Limitations

type

card_details

Specifies the nature of the supplied DataCash reference.

For an HCC transaction, it must have the value

from_hps.

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example XML for CardTxn complex elements

<card_details type=”from_hps”>4100203022036495</card_details>

</CardTxn>

2.2.8.1.3 HpsTxn

This element must be present for all setup transactions. It should not be presented for

other transaction types.

Element Name:

HpsTxn

Position:

Request.Transaction

Elements of TxnDetails

Element

Name

Description

Values / Limitations

Required

method

The action that is being requested

Must have the value

“setup”

R

page_set_id

An ID number that signifies the “page

set” that should be used when

presenting the data capture screen to

the customer.

An integer value of a

page set that has

already been

configured.

R

return_url

A URL from the customer’s website. If

this value is supplied, then when the

data capture process has been

completed, the customer will be

redirected to this URL instead of the

default URL configured within HCC.

Max size 2083.

O

expiry_url

A URL from the customer’s website. If

this value is specified, the customer

will be redirected to this URL instead

of the default expiry URL configured

within HCC on attempting to visit an

expired session.

Max size 208.

O

cvv_only

If this element is given the value 1, it

signifies that this will be a CVV Only

card capture. This means that either a

pre-registered card or tokenized card

number are being used. The merchant

must be subscribed to the HCC CVV

Only service for this type of card

capture.

A value of 1 means

true. A value of 0

means false.

O

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Card

The Card element is only required if

using the AVSCV2 Service (section

2.4.1), or if a tokenized card number

is being presented (section 2.9) for a

CVV only transaction.

See section 2.2.8.1.4

card_details

In a CVV Only card capture, the

datacash_reference of the Payment

Token (section 2.3.1)

Referenced

transaction must

have taken place

within the previous

13 months, and have

a status=1.

Mutually exclusive

with Card.pan

element. cvv_only

must be 1.

O

Example HpsTxn element for a session setup to capture the cvv number,

where the card has previously been captured and tokenized using the

Payment Tokenization Service

<method>setup</method>

<page_set_id>1</page_set_id>

<cvv_only>1</cvv_only>

<card_details type="hps_prereg">2185999900000001</card_details>

<return_url>https://shop.example.com/process</return_url>

<expiry_url>https://shop.example.com/expired</expiry_url>

</HpsTxn>

Attributes of elements of HpsTxn

Attribute

Name

Attribute of

Element

Description

Values /

Limitations

Required

type

card_details

Specifies that a Payment Token

is being presented for use with

the cvv only transaction

hps_prereg

R

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example HpsTxn element for a session setup with Dynamic data

<method>setup</method>

<page_set_id>99</page_set_id>

<return_url>https://shop.example.com/process</return_url>

<expiry_url>https://shop.example.com/expired</expiry_url>

</HpsTxn>

2.2.8.1.4 Card

The Card element is only required for setup transactions if a tokenized card number is

being presented (section 2.9) for a CVV only transaction.

The Card element may also be presented for payment transactions if using the AVSCV2

Service (section 2.4.1).

Element Name:

Card

Position:

Request.Transaction.HpsTxn

Elements of CardTxn

Element

Name

Description

Values / Limitations

S

P

Cv2Avs

Contains the AVSCV2 policy and address details, if using the AVSCV2

Service – section 2.4.1

-

O

pan

A tokenized card number created

using the Card Tokenization service

(section 2.9).

Mutually exclusive with

card_details element. cvv_only

must be 1.

R

-

Attributes of elements of Card

Attribute

Name

Attribute of

Element

Description

Values /

Limitations

Required

type

pan

The Card Token as captured using

the Card Tokenization service

(section 2.9)

token

R

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example Card element for setup

<Card>

</Card>

Example Card element for a payment

<Card>

</Card>

2.2.8.1.5 DynamicData

This optional element contains values that can be used to replace placeholder values in

the card capture page.

Element Name:

DynamicData

Position:

Request.Transaction.HpsTxn

Elements of TxnDetails

Element

Name

Description

Values / Limitations

Required

dyn_data_1

The value intended to replace

the placeholder

__DYNAMIC_DATA_FIELD_1__

in the card capture page.

Max length: 2048 characters.

The value must be enclosed

in CDATA tags if it contains

HTML.

O

dyn_data_2

The value intended to replace

the placeholder

__DYNAMIC_DATA_FIELD_2__

in the card capture page.

Max length: 2048 characters.

The value must be enclosed

in CDATA tags if it contains

HTML.

O

dyn_data_3

The value intended to replace

the placeholder

__DYNAMIC_DATA_FIELD_3__

in the card capture page.

Max length: 2048 characters.

The value must be enclosed

in CDATA tags if it contains

HTML.

O

dyn_data_4

The value intended to replace

the placeholder

__DYNAMIC_DATA_FIELD_4__

in the card capture page.

Max length: 2048 characters.

The value must be enclosed

in CDATA tags if it contains

HTML.

O

dyn_data_5

The value intended to replace

the placeholder

__DYNAMIC_DATA_FIELD_5__

in the card capture page.

Max length: 2048 characters.

The value must be enclosed

in CDATA tags if it contains

HTML.

O

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

dyn_data_6

The value intended to replace

the placeholder

__DYNAMIC_DATA_FIELD_6__

in the card capture page.

Max length: 2048 characters.

The value must be enclosed

in CDATA tags if it contains

HTML.

O

dyn_data_7

The value intended to replace

the placeholder

__DYNAMIC_DATA_FIELD_7__

in the card capture page.

Max length: 2048 characters.

The value must be enclosed

in CDATA tags if it contains

HTML.

O

dyn_data_8

The value intended to replace

the placeholder

__DYNAMIC_DATA_FIELD_8__

in the card capture page.

Max length: 2048 characters.

The value must be enclosed

in CDATA tags if it contains

HTML.

O

dyn_data_9

The value intended to replace

the placeholder

__DYNAMIC_DATA_FIELD_9__

in the card capture page.

Max length: 2048 characters.

The value must be enclosed

in CDATA tags if it contains

HTML.

O

Up to nine values are permitted. If a placeholder value is empty or not present, then

the placeholder will be removed from the card capture page that the customer sees.

In order for HTML to be used in placeholder values, the content of the dyn_data

element must be enclosed in CDATA tags.

Example DynaminData element containing of HTML enclosed by CDATA tags

<dyn_data_1><![CDATA[some <b>dynamic</b> data]]></dyn_data_1>

<dyn_data_2><![CDATA[more dynamic data]]></dyn_data_2>

</DynamicData>

2.2.8.1.1 HistoricTxn

This element is used when performing query transactions

Element Name:

HistoricTxn

Position:

Request.Transaction

Elements of HistoricTxn

Element

Name

Description

Values /

Limitations

method

The transaction type

query

R

reference

The datacash_reference of the HCC

session setup request

R

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example XML Request Fragment for HistoricTxn complex elements

<method>query</method>

</HistoricTxn>

2.2.8.2 Example XML Requests

2.2.8.2.1 Session setup requests

Example XML request to set up a session, including optional XML elements

</Authentication>

</TxnDetails>

<method>setup</method>

<page_set_id>1</page_set_id>

<return_url>https://shop.example.com/process</return_url>

<expiry_url>https://shop.example.com/expired</expiry_url>

</HpsTxn>

</Transaction>

</Request>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example XML request to set up a session to only capture the cvv number,

where the card has previously been captured and tokenized using the

Payment Tokenization Service

</Authentication>

</TxnDetails>

<method>setup</method>

<page_set_id>1</page_set_id>

<cvv_only>1</cvv_only>

<card_details type="hps_prereg">2185999900000001</card_details>

<return_url>https://shop.example.com/process</return_url>

<expiry_url>https://shop.example.com/expired</expiry_url>

</HpsTxn>

</Transaction>

</Request>

Example XML request to set up a session to only capture the cvv number,

where the card has previously been captured and tokenized using the Card

Tokenization Service

</Authentication>

</TxnDetails>

<method>setup</method>

<page_set_id>1</page_set_id>

<cvv_only>1</cvv_only>

<Card>

8466A4B11D4F34227E50FF51A6B9CA946B4871FB</pan>

</Card>

<return_url>https://shop.example.com/process</return_url>

<expiry_url>https://shop.example.com/expired</expiry_url>

</HpsTxn>

</Transaction>

</Request>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example XML request to set up a session including DynamicData

</Authentication>

</TxnDetails>

<method>setup</method>

<page_set_id>1</page_set_id>

<return_url>https://shop.example.com/process</return_url>

<expiry_url>https://shop.example.com/expired</expiry_url>

<dyn_data_1>

<![CDATA[some <b>dynamic</b> data]]>

</dyn_data_1>

<dyn_data_2>

<![CDATA[more dynamic data]]>

</dyn_data_2>

</DynamicData>

</HpsTxn>

</Transaction>

</Request>

2.2.8.2.2 Query

Example XML Session Setup Query

</Authentication>

<method>query</method>

</HistoricTxn>

</Transaction>

</Request>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.2.8.2.3 Payments

Example XML Card Transaction Using Captured Data

</Authentication>

<capturemethod>ecomm</capturemethod>

</TxnDetails>

<card_details type="from_hps">4000900012345671</card_details>

</CardTxn>

</Transaction>

</Request>

Example XML Card Transaction Using Captured Data with Standard CV2AVS

policy

</Authentication>

<capturemethod>ecomm</capturemethod>

</TxnDetails>

<card_details type="from_hps">4000900012345671</card_details>

<Card>

<street_address1>Flat 7</street_address1>

<street_address2>89 Jumble Street</street_address2>

<street_address3>Mytown</street_address3>

</Cv2Avs>

</Card>

</CardTxn>

</Transaction>

</Request>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example XML Card Transaction Using Captured Data with 3-D Secure and

Standard AVSCV2 policy

</Authentication>

<capturemethod>ecomm</capturemethod>

<merchant_url>https://www.mywebsite.com/</merchant_url>

<purchase_desc>CDs and DVDs</purchase_desc>

<purchase_datetime>20120201 23:59:59</purchase_datetime>

<accept_headers>*/*</accept_headers>

<user_agent>IE/6.0</user_agent>

</Browser>

</ThreeDSecure>

</TxnDetails>

<card_details type="from_hps">4000900012345671</card_details>

<Card>

<street_address1>Flat 7</street_address1>

<street_address2>89 Jumble Street</street_address2>

<street_address3>Mytown</street_address3>

</Cv2Avs>

</Card>

</CardTxn>

</Transaction>

</Request>

2.2.8.3 Schema Elements for XML Response

The standard XML response elements are always returned as described within section

2.1.1.3 above.

Additional elements will also be present, depening upon the transaction type/method

and outcome.

A successful setup is indicated by a status code of 1 being returned. Any another code

indicates a rejected request or an error.

For query transactions, if the status returned has the value “1”, then this indicates

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

that the query has been successful. It does not indicate that the queried transaction

was successful. A full list of the possible values for the information element are

available in this FAQ:

https://datacash.custhelp.com/cgi-

bin/datacash.cfg/php/enduser/std_adp.php?p_faqid=1037/

2.2.8.3.1 HpsTxn

This element will only be present for setup and query responses.

Element Name:

HpsTxn

Position:

Response

Elements of HpsTxn

Element Name

Description

Values

Limitations

capture_status

The current status of the HCC

transaction at the time of

querying, e.g. “pending”,

“populated”

pending

populated

purged_used

purged_unused

Only present for

query

card_scheme

The Card Scheme, if known.

Possible values are

listed in section

2.2.1.3.1

Only present for

query if data is

populated and

scheme is known

country

The three-character ISO

country code, indicating the

card’s country of issue, if

known. E.g. “gbr”

Only present for

query if data is

populated and

country is known

cv2_captured

Determines if a CV2 value has

been captured during the

process of the HCC

transaction.

Yes

No

Only present for

query if data is

populated

expirydate

The expiry date of the date in

MMYY format

Only present for

query if data is

populated

hps_url

The HPS URL. This must be

added by the merchant.

Only present for

successful setup

issuer

The issuer of the card, if

known e.g. “Halifax Plc”

Only present for

query if data is

populated

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

pan

An obscured version of the

card number that shows only

the first six and last four

digits. The rest of the digits

are replaced with asterisks.

Only present for

query if data is

populated

session_id

A unique value that

corresponds to the session

that has been set up within

the HCC.

Only present for

successful setup

The hps_url and session_id should be used by the merchant to re-direct the cardholder

to the hosted page.

Example HpsTxn element for a successful session setup

<hps_url>https://dpg.example.com/hps/</hps_url>

<session_id>1172</session_id>

</HpsTxn>

Example HpsTxn elements for query responses

<card_scheme>VISA</card_scheme>

<issuer>Halifax Plc</issuer>

<capture_status>populated</capture_status>

<cv2_captured>No</cv2_captured>

</HpsTxn>

<capture_status>pending</capture_status>

</HpsTxn>

2.2.8.3.2 DynamicCapture

This element only applies for Merchants who have customised their capture page with

Dynamic Capture fields. Additional information about Dynamic Capture fields is

available in the FAQ:

https://datacash.custhelp.com/cgi-

bin/datacash.cfg/php/enduser/std_adp.php?p_faqid=1036/

Note also that this element may only be present within the query response and will

only be returned if data was captured.

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Element Name:

DynamicCapture

Position:

Response.HpsTxn

Elements of DynamicCapture

Element Name

Description

Values / Limitations

capf1

Dynamically captured field 1, if

entered.

32 chars

(max)

URL encoded

(except spaces)

capf2

Dynamically captured field 2, if

entered.

32 chars

(max)

URL encoded

(except spaces)

capf3

Dynamically captured field 3, if

entered.

32 chars

(max)

URL encoded

(except spaces)

capf4

Dynamically captured field 4, if

entered.

32 chars

(max)

URL encoded

(except spaces)

capf5

Dynamically captured field 5, if

entered.

32 chars

(max)

URL encoded

(except spaces)

capf6

Dynamically captured field 6, if

entered.

32 chars

(max)

URL encoded

(except spaces)

capf7

Dynamically captured field 7, if

entered.

32 chars

(max)

URL encoded

(except spaces)

capf8

Dynamically captured field 8, if

entered.

32 chars

(max)

URL encoded

(except spaces)

capf9

Dynamically captured field 9, if

entered.

32 chars

(max)

URL encoded

(except spaces)

Example DynamicCapture elements for query responses

</DynamicCapture>

2.2.8.4 Example XML Responses

2.2.8.4.1 Session Setup

The following example XML message would be returned in response to a successful

session setup request.

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example XML response to a successful session setup

<hps_url>https://dpg.example.com/hps/</hps_url>

<session_id>1172</session_id>

</HpsTxn>

<datacash_reference>4000900012345671</datacash_reference>

<reason>ACCEPTED</reason>

</Response>

The following XML demonstrates a response to an unsuccessful setup request.

Example XML response to an unsuccessful session setup

<datacash_reference>4000900012345671</datacash_reference>

<information>new_session is not a valid HPS method</information>

<reason>Invalid transaction type</reason>

</Response>

2.2.8.4.2 Query Response

Example XML Query Response For A Successful Data Capture

<card_scheme>VISA</card_scheme>

<issuer>Halifax Plc</issuer>

<capture_status>populated</capture_status>

<cv2_captured>No</cv2_captured>

</HpsTxn>

<datacash_reference>4000900012345671</datacash_reference>

<information>You have queried an HPS transaction, which has stored

data that has not yet been used</information>

<reason>ACCEPTED</reason>

</Response>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example XML Query Response For A Pending Data Capture

<capture_status>pending</capture_status>

</HpsTxn>

<datacash_reference>4000900012345671</datacash_reference>

<information>You have queried an HPS transaction, whose data capture

is pending</information>

<reason>ACCEPTED</reason>

</Response>

Example XML Query Response For A Successful Data Capture

<card_scheme>VISA</card_scheme>

<issuer>Halifax Plc</issuer>

<capf1>A. N. Other</capf1>

</DynamicCapture>

</HpsTxn>

<datacash_reference>4000900012345671</datacash_reference>

<information>You have queried an HPS transaction, which has stored

data that has not yet been used</information>

<reason>ACCEPTED</reason>

</Response>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example XML Query Response For A Pending Data Capture

<datacash_reference>4000900012345671</datacash_reference>

<information>You have queried an HPS transaction, whose data

capture is pending</information>

<reason>ACCEPTED</reason>

</Response>

2.2.8.4.3 Payment Response

There are no changes to the XML response where data captured with HCC has been

used. See section 2.2.1.4 for example XML responses.

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.2.9 Hosted Payment Service

The Hosted Payment Service (HPS) enables DataCash to capture sensitive cardholder

data and authorise payments on behalf of merchants. Unlike the HCC Service, the

merchant does not need to send subsequent requests in order to authorise the

payment. The session setup contains template values that the HPS system uses to

process the payment choice that the customer makes on the HPS card capture page.

This can include the data required to allow the customer to pay by card or by PayPal.

Further information on HPS is available on the website:

http://www.datacash.com/gettingproducts.php?id=Fully-Hosted-Payments-Pages-

Overview/

2.2.9.1 Schema Elements for Request

In this section, the required fields for all transaction types are presented along with

example XML for those fields.

HPS setup_full

The setup_full transaction iniciates the setup of the HPS session. The main sections of

setup messages are shown below.

 Request

o Authentication – section 2.1.1.2

o Transaction

 TxnDetails – see also section 2.2.9.1.1. This contains payment information

that will be displayed to the customer.

 ThreeDSecure – see also section 2.4.4.1.1. This contains contains all the

details required to initiate the 3-D Secure check.

 The3rdMan – see also section 2.4.7.1.1 This contains additional

information about the customer to be used for Batched Fraud Screening.

 CardTxn – see also section 2.2.1.1.2. This contains the type of card

transaction and other information that will be used if the customer attempts

to pay by card.

 Card – see also section 2.2.1.1.1. In HPS Session Setup, this element is

only used as a container for the Cv2Avs element.

o Cv2Avs – see also section 2.4.3.1.8. This contains cv2 and address

details.

 PayPalTxn – see also section 2.8.1.1.2. This optional element contains all of

the details specific to the PayPal transaction, if the customer chooses to pay

by PayPal.

 HpsTxn – this section contains all the details specific to the HPS session

setup request, section 2.2.9.1.5

Query of HPS setup_full

At any time following a successful session setup_full, a query can be sent to

determine the current state of the transaction. This can be used to determine which

stage of the payment process the customer has reached, and whether a payment

attempt has been made successfully:

 Request

o Authentication – section 2.1.1.2

o Transaction

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

 HistoricTxn – section 2.2.9.1.6

Query of Payment attempts

If a query has been submitted on the setup_full, one or more payment attempts may

be present in the query response. To obtain detailed information about any of those

payment attempts, the Merchant may submit additional query transactions against one

or more of those payment attempts (as required). The XML Request elements and XML

Requests are the same for both Bankcard and PayPal attempts and are discussed

discussed within section 2.8.6.

Fulfillment of Payment attempts

Successful Payment attempts can be fulfilled (as required) as outlined in sections:

 Bankcard payments – use the fulfill transaction – section 2.2.1

 PayPal Auth Capture payments – use the do_capture transaction – section 2.8.1

Cancellation of Payment

Successful Payment attempts can be cancelled prior to settlement (were appropriate)

as outlined in sections:

 Bankcard payments – use the cancel transaction – section 2.2.1

 PayPal Auth Capture payments – use the do_void transaction – section 2.8.1

Refunding Successful Payments

Successful Payment attempts can be cancelled prior to settlement (were appropriate)

as outlined in sections:

 Bankcard payments – use the txn_refund transaction – section 2.2.1

 PayPal payments – use the txn_refund transaction – section 2.8.1

2.2.9.1.1 TxnDetails

All of the following elements and attributes are mandatory in an HPS session setup

request.

Element Name:

TxnDetails

Position:

Request.Transaction

Elements of TxnDetails

Element Name

Description

Values / Limitations

ThreeDSecure

as specified in section 2.4.4.1.1

The3rdMan

as specified in section 2.4.7.1.1

merchantreference

A unique reference

number for each

transaction

Minimum 6, maximum 30

alphanumeric characters. Must be

unique.

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

amount

The value of the

transaction

Attributes for Elements of TxnDetails

Attribute

Name

Attribute of

Element

Values / Limitations

currency

amount

Currency is passed in the 3 character ISO 4217

Alphabetic format (Default is GBP)

e.g. GBP, USD, EUR

2.2.9.1.2 CardTxn

Element Name:

CardTxn

Position:

Request.Transaction

Elements of CardTxn

Element

Name

Description

Values / Limitations

Required

Card

See section 2.2.9.1.3

method

The transaction

type

May only have the values “auth” or

“pre”

R

This element is mandatory.

2.2.9.1.3 Card

Element Name:

Card

Position:

Request.Transaction.CardTxn

In a Full HPS Session Setup this element can only contain the Cv2Avs element. No

other elements are permitted.

Elements of CvsAvs

Element

Name

Description

Values / Limitations

Required

Cv2Avs

as specified in section 2.4.3.1.8 . There are no additional

restrictions

O

2.2.9.1.4 PayPalTxn

Element Name:

PayPalTxn

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Position:

Request.Transaction

The PayPalTxn element in an HPS Session Setup Request can contain the elements that

are specified in section 2.8.1.1.2 that are indicated as permitted in

set_express_checkout, get_express_checkout_details,

do_express_checkout_payment, do_authorization or do_void with the exceptions of

return_url and cancel_url.

The following additional restrictions apply:

Elements of TxnDetails

Element Name

Description

Values / Limitations

Required

method

The transaction type

When PayPalTxn is included in

an HPS Session Setup, this

must have the value

set_express_checkout.

R

payment_action

Specifies the type of

PayPal service to use

(Express Checkout or

Auth and Capture).

When PayPalTxn is included in

an HPS Session Setup, this

must have the value order.

R

The PayPalTxn element should be present if the payment page presented to the

customer will have an option to pay by PayPal.

2.2.9.1.5 HpsTxn

Element Name:

HpsTxn

Position:

Request.Transaction

Elements of TxnDetails

Element

Name

Description

Values /

Limitations

Required

method

The action that is being requested

Must have the

value setup_full

R

page_set_id

An ID number that signifies the “page

set” that should be used when presenting

the data capture screen to the customer.

An integer value of

a page set that has

already been

configured.

R

return_url

A URL from the customer’s website. If

this value is supplied, then when the data

capture process has been completed, the

customer will be redirected to this URL

instead of the default URL configured

within HPS.

Max size 2083.

O

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

expiry_url

A URL from the customer’s website. If

this value is specified, the customer will

be redirected to this URL instead of the

default expiry URL configured within HPS

on attempting to visit an expired session.

Max size 2083.

O

2.2.9.1.6 HistoricTxn

This element should only be presented for query transactions.

Element Name:

HistoricTxn

Position:

Request.Transaction

Elements of HistoricTxn

Element

Name

Description

Values /

Limitations

method

The transaction type

query

R

reference

The datacash_reference of the HPS

session setup request

R

Example XML Request Fragment for HistoricTxn complex elements

<method>query</method>

</HistoricTxn>

2.2.9.2 Example XML Requests

2.2.9.2.1 Example Session Setup XML Requests

Example XML request to set up a session, including optional XML elements

</Authentication>

<capturemethod>ecomm</capturemethod>

<merchant_url>https://www.example-merchant.co.uk/</merchant_url>

<purchase_datetime>20120121 09:31:40</purchase_datetime>

<purchase_desc>goods</purchase_desc>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

<accept_headers>*.*</accept_headers>

<user_agent>Mozilla</user_agent>

</Browser>

</ThreeDSecure>

...

</The3rdMan>

</TxnDetails>

<Card>

<street_address1>...</street_address1>

<street_address2>...</street_address2>

<street_address3>...</street_address3>

<street_address4>...</street_address4>

</Cv2Avs>

</Card>

</CardTxn>

<method>set_express_checkout</method>

<email>foo@example.com</email>

<max_amount>1000.00</max_amount>

<description>Twenty NeverFail(tm) Widgets</description>

<req_confirmed_shipping>0</req_confirmed_shipping>

<no_shipping>0</no_shipping>

<override_address>0</override_address>

<header_style img="https://www.example.com/header.png/"

bordercolor="black" bgcolor="red" />

<page_style stylename="My Style" bgcolor="white" />

<street_address1>1 Main Terrace</street_address1>

<street_address2>Highgate</street_address2>

<city>Wolverhampton</city>

<region>West Midlands</region>

<country_code>GB</country_code>

<telephone_number>0121 231 3122</telephone_number>

</ShippingAddress>

</PayPalTxn>

<method>setup_full</method>

<page_set_id>1</page_set_id>

<return_url>https://shop.example.com/process/</return_url>

</HpsTxn>

</Transaction>

</Request>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.2.9.2.2 Example Query Request

Example XML Session Setup Query

</Authentication>

<method>query</method>

</HistoricTxn>

</Transaction>

</Request>

2.2.9.3 Schema Elements for Response

The standard XML response elements are always returned. See 2.1.1.3 above.

Note that for query transactions, if the status returned has the value “1”, then this

indicates that the query has been successful. It does not indicate that the queried

transaction was successful.

A successful setup is indicated by a status code of 1 being returned. Any another code

indicates a rejected request or an error.

When querying an HPS session setup request, the contents of the “information”

element in the response indicate the status of the queried transaction. The values of

these are shown in the FAQ:

https://datacash.custhelp.com/cgi-

bin/datacash.cfg/php/enduser/std_adp.php?p_faqid=1074

2.2.9.4 HpsTxn

This element may appear for both setup_full and query Responses. For query

responses, it will only appear if the customer has made at least one payment attempt.

Element Name:

HpsTxn

Position:

Response

Elements of HpsTxn

Element Name

Description

Limitations

S

Q

AuthAttempts

See section 2.2.9.4.2

-

O

datacash_reference

The datacash_reference of

the successful payment

attempt

Will only be present

if one of the

payment attempts

was successful

-

O

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

hps_url

The HPS URL.

O

-

session_id

A unique value that

corresponds to the session

that has been set up within

the HPS.

O

-

The hps_url and session_id should be used by the merchant to re-direct the cardholder

to the hosted page.

Example HpsTxn Element for a setup_full transactions

<hps_url>https://testserver.datacash.com/hps/</hps_url>

<session_id>f2d1530f-bdb3-41f3-97b0-104dc2a48a32</session_id>

</HpsTxn>

Example HpsTxn Element for a query transactions

With successful payment:

<datacash_reference>4700201011629830</datacash_reference>

</HpsTxn>

without successful attempts:

</HpsTxn>

2.2.9.4.1 AuthAttempts

This element contains a list of the payment attempts made during the session. This

element will only appear if the customer has made at least one payment attempt.

Element Name:

AuthAttempts

Position:

Response.HpsTxn

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example AuthAttempts Element with a query with two payment attempts:

</AuthAttempts>

2.2.9.4.2 Attempt

This element provides details of a payment attempt made during the session.

Element Name:

Attempt

Position:

Response.HpsTxn.AuthAttempts

Elements of Attempt

Element Name

Description

Values /

Limitations

datacash_reference

The datacash reference of the auth attempt

for the payment

dc_response

The status code for the result of the

attempt

reason

The reason for the auth attempt

Example AuthAttempt Element for a successful payment attempt:

<datacash_reference>4700201011629830</datacash_reference>

<dc_response>1</dc_response>

<reason>ACCEPTED</reason>

</AuthAttempt>

Example AuthAttempt Element for an unsuccessful payment attempt:

<datacash_reference>4700201011629830</datacash_reference>

<dc_response>179</dc_response>

<reason>3DS Payer failed Verification</reason>

</AuthAttempt>

2.2.9.4.3 PayPalTxn

This element will be present if submitting a query against a payment attempt which

was made via PayPal. It provides details of a payment attempt made during the

session.

Element Name:

PayPalTxn

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Position:

Response

Elements of HpsTxn

Element

Name

Description

Values / Limitations

last_activity

Indicates that last step of the PayPal

express checkout process that was

performed as part of the payment

attempt.

set_express_checkout

get_express_checkout_details

do_express_checkout_payment

do_authorization

do_void

do_capture

Example PayPalTxn XML element when querying a PayPal Attempt

<last_activity>get_express_checkout_details</last_activity>

</PayPalTxn>

2.2.9.5 Example XML Responses

2.2.9.5.1 Example Session Setup XML Responses

Example XML response to a successful session setup

<hps_url>https://dpg.example.com/hps/</hps_url>

<session_id>1172</session_id>

</HpsTxn>

<datacash_reference>4000900012345671</datacash_reference>

<reason>ACCEPTED</reason>

</Response>

Example XML response to an unsuccessful session setup

<datacash_reference>4000900012345671</datacash_reference>

<information>new_session is not a valid HPS method</information>

<reason>Invalid transaction type</reason>

</Response>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.2.9.5.2 XML Example Query Responses

Example XML Query Response on a setup_full where a successful payment

attempt has been made after 2 unsuccessful attempts:

<session_id>1172</session_id>

<datacash_reference>4000900012345674</datacash_reference>

<datacash_reference>4000900012345672</datacash_reference>

<reason>Declined</reason>

</Attempt>

<datacash_reference>4000900012345673</datacash_reference>

<reason>Declined</reason>

</Attempt>

<datacash_reference>4000900012345674</datacash_reference>

<reason>ACCEPTED</reason>

</Attempt>

</AuthAttempts>

</HpsTxn>

<datacash_reference>4000900012345671</datacash_reference>

<reason>ACCEPTED</reason>

</Response>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example XML Query Response on a setup_full where all payment attempts

have failed:

<session_id>1172</session_id>

<datacash_reference>4000900012345672</datacash_reference>

<reason>Declined</reason>

</Attempt>

<datacash_reference>4000900012345673</datacash_reference>

<reason>Declined</reason>

</Attempt>

<datacash_reference>4000900012345674</datacash_reference>

<reason>Declined</reason>

</Attempt>

</AuthAttempts>

</HpsTxn>

<datacash_reference>4000900012345671</datacash_reference>

<information>You have queried an HPS transaction, where the all retry

attempts were exhausted.</information>

<reason>HPS: The maximum number of retry transaction was

breached</reason>

</Response>

2.2.9.5.3 XML Example PayPal Attempt Query Response

Example XML PayPal Attempt Query Response

<last_activity>get_express_checkout_details</last_activity>

</PayPalTxn>

<datacash_reference>4000900012345673</datacash_reference>

<reason>HPS: Paypal - Waiting for customer to confirm

payment.</reason>

</Response>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.2.10 Verify Transactions

The Verify transaction allows Bank Card details to be checked for validity without

attempting to authorize a payment.

2.2.10.1.1 Schema Elements for Request

2.2.10.1.1.1 TxnDetails

All of the following elements and attributes are mandatory in an HPS session setup

request.

Element Name:

TxnDetails

Position:

Request.Transaction

Elements of TxnDetails

Element Name

Description

Values / Limitations

merchantreference

A unique reference

number for each

transaction

Minimum 6, maximum 30

alphanumeric characters. Must be

unique.

amount

The value of the

transaction

Must be 0.00 for a verify

transaction

Attributes for Elements of TxnDetails

Attribute

Name

Attribute of

Element

Values / Limitations

currency

amount

Currency is passed in the 3 character ISO 4217

Alphabetic format (Default is GBP)

e.g. GBP, USD, EUR

2.2.10.1.1.2 CardTxn

Element Name:

CardTxn

Position:

Request.Transaction

Elements of CardTxn

Element Name

Description

Values / Limitations

Required

method

The transaction type

May only have the values “verify”

R

This element is mandatory.

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.2.10.1.1.3 Card

Element Name:

Card

Position:

Request.Transaction.CardTxn

This element is as specified in 2.2.1.1.1.

2.2.10.1.1.4 Cv2Avs

Element Name:

Cv2Avs

Position:

Request.Transaction.CardTxn.Card

This element is as specified in section 2.4.3.1.8 . There are no additional restrictions.

Example XML request for Verify

</Authentication>

</TxnDetails>

<method>verify</method>

<Card>

</Card>

</CardTxn>

</Transaction>

</Request>

2.2.10.1.2 Schema Elements for Response

The response for a verify transaction may contain the same elements as for an auth or

pre transaction. See section 2.2.1.3.

A status element of “1” indicates that the card details were successfully verified. Other

statuses have the same meanings as for auth or pre transactions.

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example XML response for Verify

<card_scheme>VISA</card_scheme>

<country>United Kingdom</country>

</CardTxn>

<datacash_reference>4700903000000011</datacash_reference>

<reason>ACCEPTED</reason>

</Response>

Back to Contents

2.3 REPEAT CARD PAYMENTS

2.3.1 Payment Tokenization

A technical introduction to this Service is available on the website:

http://www.datacash.com/gettingproducts.php?id=Payment-Tokenization-Pre-

Registered-Card-

2.3.1.1 Schema Elements for Request

In this section the required fields for each transaction type will be presented, along

with example XML for those fields. If a transaction type is specified in the XML, this

is highlighted to indicate that other transaction types can be used in its place.

This document assumes that the Credit and Debit Card Service has already been

integrated and the reader is familiar with it.

The data for the Payment Tokenization Service is passed in these distinct places in

the schema:

2.3.1.1.1 Request

o Authentication - section 2.1.1.2

o Transaction

 CardTxn – the type and datacash_reference of the original transaction,

section 2.7.1.1.2

 Secure – to be used if the 3-D Secure check using a 3rd Party MPI is

required, section 2.4.6.1.2

 Card

 Cv2Avs – to be used if the CV2AVS check is required, section 2.4.3.1.8

 TxnDetails – section 2.2.1.1.3

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

 ThreeDSecure – to be used if the 3-D Secure check using the DataCash

MPI is required, section 2.4.4.1.1

2.3.1.1.2 CardTxn

The details of the initial Credit and Debit Card transaction, plus the method to be used

for the Payment Tokenization transaction are submitted in the CardTxn element. If the

CV2AVS check is being used, this information is also presented within this element:

Element Name:

CardTxn

Position(s)

Request.Transaction

Elements of CardTxn

Element

Name

Description

Values / Limitations

Card

To be used if the CV2AVS

check is required.

Please refer to section 2.7.1.1.5

method

The transaction type

auth

pre

refund

erp

card_details

The datacash_reference of

the initial transaction

Initial transaction must have taken

place within the previous 13 months,

and have a status=1

Attributes for Elements of CardTxn

Attribute Name

Attribute of element

Value

type

card_details

preregistered

Example XML for CardTxn elements

<card_details type="preregistered">2185999900000001</card_details>

</CardTxn>

Example XML for CardTxn elements

<card_details type="preregistered">2185999900000008</card_details>

</CardTxn>

2.3.1.2 XML Examples Requests

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example XML Request for pre

</Authentication>

</TxnDetails>

<card_details type="preregistered">2185999900000001

</card_details>

</CardTxn>

</Transaction>

</Request>

If the method is changed, the same XML could also be used for auth, refund and erp

transactions.

It is also possible to use a Payment Token in conjunction with the HCC service – see

section 2.2.9.

For examples with the CV2AVS check, please refer to section 2.4.3.1.8. Examples using

3-D Secure are available in section 2.4.4 (DataCash MPI) and section 2.4.6 (3rd Party

MPI).

2.3.1.3 Schema Elements for Response

The Payment Tokenization Service will return same structure of Response as the Credit

and Debit Card Service. Please refer to section 2.3.1 of this document.

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.3.1.4 XML Examples Responses

The Payment Tokenization Service will return the same structure of Response as the

Credit and Debit Card Service. Examples of successful, declined and referred

responses are given in section 2.3.1 of this document.

The initial transaction is older than 13 months, does not exist or was

unsuccessful

<datacash_reference>2185999900005678</datacash_reference>

<reason>Prereg: Invalid reference</reason>

</Response>

The account is not currently configured for the Payment Tokenization

Service

<datacash_reference>21859999000005679</datacash_reference>

<information>This vTID is not configured to process

pre-registered card transactions.</information>

<reason>Prereg: Merchant Not Subscribed</reason>

</Response>

2.3.2 Capture Method Recurring Transactions

A technical introduction to this Service is available on the website:

http://www.datacash.com/gettingproducts.php?id=Capture-Method-Recurring-

Transactions

This service is utilised by sending a normal Credit and Debit Card Service Request

with additional information. This section of the documentation assumes the reader is

familiar with it. The Credit and Debit Card Service is described in section 2.2.1

2.3.2.1 Schema Elements for Request

In this section the required fields for each capture method type will be presented,

along with example XML for those fields. If a capture method is specified in the XML,

this is highlighted to indicate that other capture method types can be used in its

place.

The data for the Capture Method Recurring Transactions Service is passed in three

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

distinct places in the schema:

2.3.2.1.1 Request

o Authentication - section 2.1.1.2

o Transaction

 CardTxn – the type and authorisation code, see section 2.2.1.1.2

 Card – this contains all the information about the Card, section 2.2.1.1.1

 TxnDetails – contains details of the transaction, see section 2.3.2.1.2

When using this Service, a single extra element is provided within the TxnDetails

parent for transactions.

2.3.2.1.2 TxnDetails

Element Name:

TxnDetails

Position(s)

Request.Transaction

Elements of TxnDetails

Element Name

Description

Values / Limitations

merchantreference

Please refer to section 2.2.1.1.3

amount

capturemethod

Specifies the environment of transaction

ecomm

cnp

cont_auth

ivr

Please note that refund transaction types (including erp and txn_refund) cannot be

processed in a cont_auth environment. These should instead be processed using your

normal environment flag.

Example XML Elements

</TxnDetails>

</TxnDetails>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.3.2.1.2.1 NatWest Merchants

If you are processing transactions through NatWest Streamline, the following additional

information should also be presented:

Attributes of child elements in TxnDetails

Attribute Name

Element Name

Description

Values /

Limitations

Streamline_CA_environment

capturemethod

Specifies the

environment of

original transaction

ecomm

cnp

Example XML Elements for NatWest merchants

<capturemethod>ecomm</capturemethod>

</TxnDetails>

cont_auth</capturemethod>

</TxnDetails>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.3.2.2 XML Example Request

2.3.2.2.1 Ecomm and CNP Transactions

Example XML Request for an initial ecomm transaction

</Authentication>

<capturemethod>ecomm</capturemethod>

</TxnDetails>

<Card>

</Card>

</CardTxn>

</Transaction>

</Request>

If the capturemethod above is changed, the same XML could also be used for cnp

transactions.

When a ‘refund of an existing transaction’ (txn_refund) is being performed, the DPG

will automatically use the same capturemethod as the existing transaction. However, if

the existing transaction is a cont_auth transaction, the capturemethod should be explicitly

set to the normal (i.e. ecomm or cnp) value.

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example XML Request for a txn_refund

</Authentication>

<capturemethod>ecomm</capturemethod>

</TxnDetails>

<method>txn_refund</method>

</HistoricTxn>

</Transaction>

</Request>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.3.2.2.2 Cont_Auth Transactions

2.3.2.2.2.1 Non-NatWest Merchants

To send a cont_auth transaction, non-NatWest merchants can use the same XML

Request as shown in section 2.3.2.2.1, merely by changing the value of the

capturemethod.

2.3.2.2.2.2 NatWest Merchants

Example XML Request for a NatWest recurring transaction

</Authentication>

<capturemethod

Streamline_CA_environment="cnp">cont_auth</capturemethod>

</TxnDetails>

<Card>

</Card>

</CardTxn>

</Transaction>

</Request>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.3.3 Historic Recurring Transactions

A technical introduction to this Service is available on the website:

http://www.datacash.com/gettingproducts.php?id=Historic-Recurring-Cards

This section of the documentation assumes the reader is familiar with the Credit and

Debit Card Service, which is discussed in section 2.2.1.

2.3.3.1 Schema Elements for Request

In this section the required fields for each transaction type will be presented, along

with example XML for those fields.

For Recurring Account Setups

To authorise the first payment and setup an account for a card, information needs to

be collected and set in the following places within the schema:

2.3.3.1.1 Request

o Authentication - section 2.1.1.2

o Transaction

 TxnDetails – contains details of the transaction, see section 2.3.2.1.2

 CardTxn

o Card – this element contains the details about the card, for setups

only. These details are the same as for one-off payments, which are

covered in section 2.2.1.1.1

 ContAuthTxn – section 2.3.3.1.2

For the Repeat Payments

Once the account has been setup, repeat payments can be taken from it.

 Request

o Authentication – section 2.1.1.2

o Transaction

 TxnDetails – contains details of the transaction, section 2.4.2.1.2

o HistoricTxn – section 2.3.3.1.3

For Cancellations of Payments and Accounts

Cancellations of accounts and payments are performed using the same data as for

normal Bank Card cancellations:

 Request

o Authentication – section 2.1.1.2

o Transaction

 HistoricTxn – section 2.3.3.1.3

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.3.3.1.2 ContAuthTxn

This element should be presented with setup and repeat payment Requests. It has one

attribute and no children.

Element Name:

ContAuthTxn

Position

Request.Transaction

Attributes of ContAuthTxn

Attributes

Attribute of

Element

Description

Values /

Limitations

type

ContAuthTxn

Indicates whether the

transaction is a setup or a

repeat payment

setup

historic

Example XML ContAuthTxn elements

2.3.3.1.3 HistoricTxn

This element is required for the repeat payments and cancellations of

payments/accounts. It should not be presented with the setup transaction.

Element Name:

HistoricTxn

Position

Request.Transaction

Elements of HistoricTxn

Element

Name

Description

Values / Limitations

method

Indicates the transaction type

pre

auth

cancel

reference

Two references are returned from the initial setu request – the first

payment reference and the ca_reference.

For Payments: the ca_reference of the

account from which the payment is to be

taken

Must be a valid

account

For Cancellations: the ca_reference of the

account or payment to be cancelled

Must be a valid

account or payment

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example XML HistoricTxn elements

</HistoricTxn>

<method>cancel</method>

</HistoricTxn>

2.3.3.2 Example XML Requests

Example XML Request for account setup. The initial transaction will be

processed as ecomm

<password>mypasswd</password>

</Authentication>

<capturemethod>ecomm</capturemethod>

</TxnDetails>

<Card>

</Card>

</CardTxn>

</Transaction>

</Request>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example XML Request for account setup. The initial transaction will be

processed as cnp

<password>mypasswd</password>

</Authentication>

<Card>

</Card>

</CardTxn>

</TxnDetails>

</Transaction>

</Request>

Example XML Request for a repeat payment

</TxnDetails>

</HistoricTxn>

</Transaction>

<password>mypasswd</password>

</Authentication>

</Request>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example XML Request to cancel a payment or account

<password>mypasswd</password>

</Authentication>

<method>cancel</method>

</HistoricTxn>

</Transaction>

</Request>

2.3.3.3 Schema Elements for Response

In addition to the elements covered in this section, responses for this service will

contain the general response elements outlined in section 2.1.1.3.

The CardTxn element will also be present, as described in section 2.2.1.3.1.

2.3.3.3.1 ContAuthTxn

Element Name:

ContAuthTxn

Position

Response

Elements of ContAuthTxn

Element Name

Description

ca_reference

The reference number of the account

account_status

Provides additional information about the account status

Example ContAuthTxn element

<account_status>Account setup. CNP transaction

sent successfully</account_status>

<ca_reference>4500200040151462</ca_reference>

</ContAuthTxn>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.3.3.4 Example Responses

2.3.3.4.1 Successful Responses

Example XML Response for a successful setup

<card_scheme>Mastercard</card_scheme>

<country>United Kingdom</country>

</CardTxn>

<account_status>Account setup. ECOMM transaction sent

successfully</account_status>

<ca_reference>4700200040641889</ca_reference>

</ContAuthTxn>

<datacash_reference>4700200040641890</datacash_reference>

<merchantreference>setupreference12345680</merchantreference>

<reason>ACCEPTED</reason>

</Response>

Example XML Response for a successful repeat payment

<card_scheme>VISA</card_scheme>

<country>United Kingdom</country>

</CardTxn>

<account_status>Using account ref 4500200040925092. CONT_AUTH

transaction complete</account_status>

</ContAuthTxn>

<datacash_reference>4000200040925117</datacash_reference>

<reason>ACCEPTED</reason>

</Response>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example XML Response for a successfully cancelled account

<datacash_reference>4400200040943162</datacash_reference>

<information>Continuous authority account cancelled</information>

<reason>CANCELLED</reason>

</Response>

2.3.3.4.2 Failed or Rejected Responses

Example XML Response for a rejected setup. The initial payment was

declined, so the account could not be set up.

<authcode>DECLINED</authcode>

<card_scheme>VISA Delta</card_scheme>

<country>United Kingdom</country>

</CardTxn>

<account_status>Account not setup. CNP transaction was not

successfully authed</account_status>

</ContAuthTxn>

<datacash_reference>4500200040641890</datacash_reference>

<reason>DECLINED</reason>

</Response>

Example XML Response where a recurring payment Request was declined

<authcode>NOT AUTHORISED</authcode>

<card_scheme>American Express</card_scheme>

</CardTxn>

<account_status>Using account ref 3900200040457927.

CONT_AUTH transaction complete</account_status>

</ContAuthTxn>

<datacash_reference>3800200040465541</datacash_reference>

<reason>DECLINED</reason>

</Response>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example XML Response where the account could not be found or has

already been cancelled

<datacash_reference>4500200040373397</datacash_reference>

<information>Failed to find live CA account with

reference=47002000405791371</information>

<merchantreference>historicreference12345690</merchantreference>

<reason>Failed to find corresponding CA account</reason>

</Response>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.3.4 Recurring Transaction Enquiry Service (VAU/ABU)

This service is currently available as an addition to Historic Recurring Transactions

through Lloyds for MasterCard and Visa recurring accounts only.

Submitting an RTES request will prompt an update on the cardholder details associated

with the recurring account. Details of the status of the update and any changes made

will be presented in response to a query against the recurring account.

2.3.4.1 Schema Elements for Request

In this section the required fields for each transaction type will be presented, along

with example XML for those fields.

For RTES Requests

To request an RTES update on the recurring account, information needs to be collected

and set in the following places within the schema:

 Request

o Authentication – section 2.1.1.2

o Transaction

 TxnDetails – contains details of the next predicted payment

o HistoricTxn – contains the recurring account reference

Elements of HistoricTxn

Element

Name

Description

Values / Limitations

method

The transaction type

rtes_request

R

reference

The reference of the

transaction to be queried

DataCash Reference of

the recurring account

R

Example XML Request for HistoricTxn complex elements

<method>rtes_request</method>

</HistoricTxn>

Elements of TxnDetails

Element Name

Description

Values / Limitations

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

predicted_payment_date

The date of

the next

expected

payment

YYYY-MM-DD

R

amount

The predicted

amount of the

next payment

An amount and currency

attribute, as standard

R

Example XML Request for TxnDetails complex elements

<predicted_payment_date>2012-01-15</predicted_payment_date>

</TxnDetails>

2.3.4.1.1 XML Example – RTES Update Request

Example XML Query

</Authentication>

<predicted_payment_date>2012-01-15</predicted_payment_date>

</TxnDetails>

<method>rtes_request</method>

</HistoricTxn>

</Transaction>

</Request>

2.3.4.1.2 Schema Elements for RTES Request Response

There are no complex elements in the response – the information element will contain

confirmation that the RTES request was accepted.

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Querying the Recurring Account

Query transactions can be submitted against the DataCash reference of a recurring

account, the results of which will include RTES update information.

 Request

o Authentication – section 2.2.1.1

o Transaction

 HistoricTxn – contains the reference of the recurring account

Elements of HistoricTxn

Element

Name

Description

Values / Limitations

method

The transaction type

query

R

reference

The reference of the

transaction to be queried

DataCash Reference of

the recurring account

R

Example XML Request for HistoricTxn complex elements

<method>query</method>

</HistoricTxn>

2.3.4.1.3 XML Example – Recurring Account Query Transaction

Example XML Query

</Authentication>

<method>query</method>

</HistoricTxn>

</Transaction>

</Request>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.3.4.1.4 Schema Elements for Recurring Account Query Response

Element Name:

QueryTxnResult

Position:

Response

The QueryTxnResult complex element contains the retrieved details for the transaction

reference provided in the request. The contents of the following elements all relate to

the original transaction being queried, and not the query transaction itself.

Elements of QueryTxnResult

Element Name

Description

ContAuthTxn

Complex element containing details about the recurring account

transaction being queried

datacash_reference

DataCash reference

merchant_reference

Merchant reference

reason

DataCash response message.

status

DataCash response code

transaction_date

Date of processing by DPG

Elements of ContAuthTxn

Element Name

Description

enquiry_date

The date of the last enquiry against this account

expirydate

The expiry date of the currently associated card, MMYY

pan

The first six and last four digits of the currently associated card

number (the intervening digits are obscured).

response_date

The date of the response from the VAU or ABU service to the

RTES request.

scheme

The scheme associated with the account – MasterCard or Visa

status

Textual indication of the status of the update request / result

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.3.5 Fire and Forget Recurring Transactions

A technical introduction to this Service is available on the website:

http://www.datacash.com/gettingproducts.php?id=Bank-Card-Fire-Forget-

This section of the documentation assumes the reader is familiar with the Credit and

Debit Card Service, which is discussed in section 2.2.1.

2.3.5.1 Schema Elements for Request

In this section the required fields for each transaction type will be presented, along

with example XML for those fields. As not all fields are mandatory, the following key

will be used:

 R - Required

 O - Optional

For Recurring Account Setups

The information required to set up an account is passed in several places in the

schema:

All ElavonUS ContAuth Fire and Forget account interactions must be sent using XML

request ‘version 2’.

2.3.5.1.1 Request

o Authentication - section 2.1.1.2

o Transaction

 CardTxn – the type and authorisation code, see section 2.2.1.1.2

 Card – this contains all the information about the Card. These details are

the same as for one-off payments, which are covered in section 2.2.1.1.1

 ContAuthTxn – contains all the information about the payments which are

to be taken from the account, section 2.3.3.1.2

 FirstPayment – enables an initial payment to be specified, section

2.3.5.1.4

 LastPayment – enables a final payment to be specified, section 2.3.5.1.5

For Cancellations of Payments and Accounts

Account and Payment Cancellations are performed using the same data as for normal

Bank Card cancellations:

2.3.5.1.2 Request

o Authentication - section 2.1.1.2

o Transaction

 HistoricTxn – – details the transaction method cancel, and the reference

number of the payment/account to cancel, section 2.2.1.1.4

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.3.5.1.3 ContAuthTxn

This element must be presented when setting up an account.

Element Name:

ContAuthTxn

Position

Request.Transaction

Elements of ContAuthTxn

Element Name

Description

Values / Limitations

method

Indicates the transaction type

pre (not supported for For

accounts that are acquired by

ElavonUS)

auth

R

start_date

The date on which the first

regular payment will be

taken. Subsequent payments

will be based from this date.

Must be at least the day after

the transaction is sent.

For all acquirers except

ElavonUS: dd/mm/yyyy. Must

be at least one day ahead of

either the current date or the

FirstPayment date

For accounts that are

acquired by ElavonUS: ISO

8601 Ext (YYY-MM-DD).

Must be at least one day

ahead of either the current

date or the FirstPayment

date

R

period

The frequency of payments

weekly

monthly

quarterly

annual

R

amount

The value of each regular

payment

R

number_of_payments

Used to restrict the number of

regular payments to be

collected. Note: this is not the

total number of payments if

first and/or last payments

have been set.

Must be an integer.

If acquired by ElavonUS,

cannot be more than 99

payments (including the first

and final payments).

O

FirstPayment

Details of any initial payment to be made. This is in addition

to the regular payments. See section 2.3.5.1.4

O

LastPayment

Details of any final payment to be made. This is in addition to

the regular payments. See section 2.3.5.1.5

O

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Attributes of ContAuthTxn

Attributes

Attribute of

Element

Description

Values /

Limitations

currency

amount

Currency in the ISO 4217

Alphabetic format. E.g. GBP, USD,

AUD

Will default to GBP if

not specified

Example ContAuthTxn element. Monthly payments will be taken until the

account is cancelled

<start_date>31/03/2005</start_date>

<period>monthly</period>

</ContAuthTxn>

Example ContAuthTxn element with first and last payments

<start_date>10/02/2003</start_date>

<period>weekly</period>

<number_of_payments>5</number_of_payments>

</ContAuthTxn>

2.3.5.1.4 FirstPayment

This optional element enables an initial payment to be taken which varies in both value

and timing from the regular transactions.

If this element is presented for a transaction, both its children must be populated.

Element Name:

FirstPayment

Position

Request.Transaction.ContAuthTxn

Elements of FirstPayment

Element

Name

Description

Values / Limitations

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

date

The date the first payment is to be

taken

For all acquirers other than

ElavonUS: dd/mm/yyyy

Must be at least one day ahead of

the current date

For account acquired by ElavonUS:

ISO 8601 Ext (YYY-MM-DD). Can

be today or any date upto 13

months in the future.

amount

The value of the first payment. This

may vary from the regular

payments. Currency attribute may

be specified if required

Example FirstPayment element

</FirstPayment>

2.3.5.1.5 LastPayment

This optional element enables a final payment to be taken which varies in both value

and timing from the regular transactions. The element may only be presented if the

number_of_payments element has been specified (section 2.3.5.1.3). If this element is

presented for a transaction, both its children must be populated.

Element Name:

LastPayment

Position

Request.Transaction.ContAuthTxn

Elements of LastPayment

Element

Name

Description

Values / Limitations

date

The date the last payment is

to be taken

For all acquirers other than

ElavonUS: dd/mm/yyyy

For accounts acquired by ElavonUS:

ISO 8601 Ext (YYY-MM-DD)

Must be at least one day after the last

regular payment

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

amount

The value of the last payment.

This may vary from the

regular payments. Currency

attribute may be specified if

required

Example LastPayment element

</LastPayment>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.3.5.2 Example XML Requests

Example Request for an initial charge of £7.50, followed by regular weekly

payments of £5 until a cancellation Request is received

</Authentication>

<Card>

</Card>

</CardTxn>

<start_date>15/07/2005</start_date>

<period>weekly</period>

</FirstPayment>

</ContAuthTxn>

<capturemethod>ecomm</capturemethod>

</TxnDetails>

</Transaction>

</Request>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example Request for nine quarterly payments of £69.99

</Authentication>

<Card>

</Card>

</CardTxn>

<start_date>31/07/2005</start_date>

<period>quarterly</period>

<number_of_payments>9</number_of_payments>

</ContAuthTxn>

<merchantreference>annual0000432432a</merchantreference>

<capturemethod>ecomm</capturemethod>

</TxnDetails>

</Transaction>

</Request>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example Request for an initial charge of $30, twelve regular payments of

$10 on the first of each month and a final payment of $20

<password>mypasswd</password>

</Authentication>

<Card>

</Card>

</CardTxn>

<start_date>01/10/2005</start_date>

<period>monthly</period>

<number_of_payments>12</number_of_payments>

</FirstPayment>

</LastPayment>

</ContAuthTxn>

</TxnDetails>

</Transaction>

</Request>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

As above, but acquired by ElavonUS (Example Request for an initial charge

of $30, twelve regular payments of $10 on the first of each month and a

final payment of $20)

<password>mypasswd</password>

</Authentication>

<Card>

</Card>

</CardTxn>

<start_date>2005-10-01</start_date>

<period>monthly</period>

<number_of_payments>12</number_of_payments>

</FirstPayment>

</LastPayment>

</ContAuthTxn>

</TxnDetails>

</Transaction>

</Request>

2.3.5.3 Schema Elements for Response

In addition to the elements covered in this section, responses for this service will

contain the general response elements outlined in section 2.1.1.3.

Accounts that will acquire by ElavonUS will have a card verify transaction processed

against the card at the time of the setup. If that fails, the Contauth account will not be

setup and further information will be returned in the response.

2.3.5.3.1 ContAuthTxn

Element Name:

ContAuthTxn

Position

Response

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Elements of ContAuthTxn

Element Name

Description

account_status

Returns information about the status of the account

Example XML element ContAuthTxn

<account_status>Account setup. First transaction due to be

batched on 30/06/2005</account_status>

</ContAuthTxn>

2.3.5.4 Example XML Responses

Example XML Response for an account which has been successfully set up

<account_status>Account setup. First transaction due to be

batched on 09/10/2006</account_status>

</ContAuthTxn>

<datacash_reference>4200200040373186</datacash_reference>

<information>Continuous Authority account set up</information>

<reason>ACCEPTED</reason>

</Response>

Example XML Response for a card type which is not supported by the

service

<datacash_reference>4200200040609090</datacash_reference>

<information>Continuous authority is not supported on

this card</information>

<reason>CA Not Supported</reason>

</Response>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example XML Response for an invalid start date

<datacash_reference>4600200040609088</datacash_reference>

<information>The date of the first payment must be from

tomorrow onwards</information>

<reason>Invalid Date</reason>

</Response>

Example XML Response for a ElavonUS rejected account setup

<card_scheme>VISA</card_scheme>

<country>United Kingdom</country>

</CardTxn>

<account_status>Account was not setup. The initial payment was

not successful.</account_status>

</ContAuthTxn>

<acquirer>ElavonUS</acquirer>

<datacash_reference>4800903000000001</datacash_reference>

<information>SERV NOT ALLOWED</information>

<reason>DECLINED</reason>

</Response>

2.3.5.5 Notifications

Whenever a payment is taken from an account, an email will be generated containing

the results of the payment(s). The email will contain up to five attachments. Each

attachment will take the form of a CSV file and be named one of:

 declined.csv – for declined payments

 error.csv – payments which generated an error message

 expiring.csv – payments on cards which will expire before the next payment date

 referred.csv – for referred payments

 authorized.csv – for successful payments

These notifications can also be downloaded from Reporting.

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Format for CSV files

Name

Description

1

Account

Reference

The DataCash reference of the account from which the payment

was requested.

2

Merchant

Reference

Your reference for the account. As supplied when you setup the

account.

3

DataCash

Reference

The DataCash reference of the payment that failed. This is not

supplied for referred.csv

Example CSV file

Account Reference,Merchant Reference,DataCash Reference

37707655,acc000045452,4300200040945208

37699077,SMITH0001245432,4100200040945209

37699081,Green458934,4900200040945210

37701359,qwerty12345,4700200040945211

37709097,rtuier49rsw,4500200040945212

37709891,egr3t434,4300200040945213

Back to Contents

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.4 FRAUD PREVENTION

2.4.1 AVSCV2

A technical introduction to this Service is available on the website:

http://www.datacash.com/gettingproducts.php?id=Address-and-Security-Code-

Verification

This section covers the elements to be populated with the cv2 and address details. It

also covers the sending of standard and extended policy information within the

transaction.

This service is utilised by sending a normal Credit and Debit Card Service Request with

additional information. This section of documentation assumes the Credit and Debit

Card Service has already been integrated and the reader is familiar with it. The Credit

and Debit Card Service is described in section 2.2.1.

It may also be used in conjunction with the Pre-Registered Card Service, which is

described in section 2.3.1.

2.4.1.1 Schema Elements for Request

In this section the fields that can be submitted when using the AVSCV2 service will be

presented, along with example XML for those fields.

Each field will be labelled with the following key:

 O - Optional

 R - Required, field must be presented

 C - Checked, the optional field will be checked if presented

 M - Mandatory if available, if the information is available, it should be presented

The following additional schema elements can be presented when performing an

AVSCV2 check:

2.4.1.1.1 Request

o Transaction

 CardTxn

 Card

o Cv2Avs – see section 2.4.1.1.2

 ExtendedPolicy – see section 2.4.1.1.3

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.4.1.1.2 Cv2Avs

This parent element should be populated with the information that you require to be

checked. When using the either Standard or Extended Policy, this information is also

passed here – only one of these elements should be presented. If you wish to use the

default policy, neither element should be presented.

Please remember that if you are only presenting a particular subset of the AVSCV2

data to be checked, you must choose a policy that does not require the all fields to be

checked – this would otherwise result in all transactions being rejected.

None of the child elements of Cv2Avs are mandatory. If the cv2 element is presented,

the length of its contents will be checked to ensure the number is the correct length for

the card type. American Express cards have four digits and all other card types have

three. An empty cv2 number will cause the rejection of the transaction.

Element Name:

Cv2Avs

Position

Request.Transaction.CardTxn.Card.Cv2Avs

Elements of Cv2Avs

Element Name

Description

Values / Limitations

Required

street_address1

The statement

address (excluding

postcode) of the

customer.

Though only the numeric data can

be checked, the full details can be

submitted if required. Any non-

numeric data will be stripped out

and the numeric data will be

concatenated prior to checking.

C

street_address2

street_address3

street_address4

city

The statement city

Must be alphanumeric.

C

state_province

The statement

state/province

Must be alphanumeric.

C

country

The statement

country

Use the numeric country codes

C

postcode

The statement

postcode

A maximum of 9 alphanumeric

characters.

C

cv2

The cv2 number

from the card

Must be 4 digits for Amex, or 3

digits for all other card types.

C

policy

The Standard Policy

required for the

transaction.

1, 2, 3, 5, 6, 7. Please refer to the

website for definitions

O1

ExtendedPolicy

For use with Extended Policy only. See section

2.4.1.1.3

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

1 Either of the policy or ExtendedPolicy elements can be presented. To use the default

policy configured on the account, neither element should be presented. If a transaction

contains both standard and extended policy information, it will be rejected.

Example Cv2Avs elements for default, standard and extended policy

transactions respectively. In each example, the numeric data for the address

and postcode is identical and so would return the same result from the bank.

<street_address1>1 High Street</street_address1>

<street_address2>This Town</street_address2>

<street_address3>Somewhere</street_address3>

<street_address4>United Kingdom</street_address4>

</Cv2Avs>

<street_address1>1 High Street</street_address1>

<state_province>Somewhere</state_province>

</Cv2Avs>

<street_address1>1 High Street,

This Town, Somewhere,

United Kingdom</street_address1>

</Cv2Avs>

<street_address1>1</street_address1>

</Cv2Avs>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.4.1.1.3 ExtendedPolicy

When using the extended policy, each element and attribute must be presented.

Element Name:

ExtendedPolicy

Position

Request.Transaction.CardTxn.Card.Cv2Avs.ExtendedPolicy

Elements of ExtendedPolicy

Element Name

Description

Values / Limitations

Required

cv2_policy

Each of these elements has five attributes – see below.

R

postcode_policy

R

address_policy

R

Attributes for the child elements of ExtendedPolicy

Attribute

Name

Element Name

Description

Values /

Limitations

Required

notprovided

postcode_policy

cv2_policy

address_policy

Specifies whether to accept

or reject each of the five

possible bank responses for

the three individual

elements

accept

reject

R

notchecked

R

matched

R

notmatched

R

partialmatch

R

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example Extended policy element

<cv2_policy notprovided="reject"

notchecked="accept"

matched="accept"

notmatched="reject"

partialmatch="reject"/>

<postcode_policy notprovided="reject"

notchecked="accept"

matched="accept"

notmatched="reject"

partialmatch="accept"/>

<address_policy notprovided="reject"

notchecked="accept"

matched="accept"

notmatched="reject"

partialmatch="accept"/>

</ExtendedPolicy>

2.4.1.2 XML Example Requests

2.4.1.2.1 Default Policy

Example Default Policy Request

</Authentication>

</TxnDetails>

<Card>

<street_address1>Flat 7</street_address1>

<street_address2>89 Jumble

Street</street_address2>

<street_address3>Mytown</street_address3>

</Cv2Avs>

</Card>

</CardTxn>

</Transaction>

</Request>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example Default Policy with Payment Tokenization Cards

</Authentication>

</TxnDetails>

<card_details type="preregistered">

2185999900000001</card_details>

<Card>

<street_address1>Flat 7</street_address1>

<street_address2>89 Jumble

Street</street_address2>

<street_address3>Mytown</street_address3>

</Cv2Avs>

</Card>

</CardTxn>

</Transaction>

</Request>

See also section 2.2.8.2.3 for examples using HCC and default policy

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.4.1.2.2 Extended Policy

Example Extended Policy Request

</Authentication>

</TxnDetails>

<Card>

<street_address1>Flat 7</street_address1>

<street_address2>89 Jumble

Street</street_address2>

<street_address3>Mytown</street_address3>

<cv2_policy notprovided="reject"

notchecked="accept"

matched="accept"

notmatched="reject"

partialmatch="reject"/>

<postcode_policy notprovided="reject"

notchecked="accept"

matched="accept"

notmatched="reject"

partialmatch="accept"/>

<address_policy notprovided="reject"

notchecked="accept"

matched="accept"

notmatched="reject"

partialmatch="accept"/>

</ExtendedPolicy>

</Cv2Avs>

</Card>

</CardTxn>

</Transaction>

</Request>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example Extended Policy Request when using a Payment Token in place of

the Card details

</Authentication>

</TxnDetails>

<card_details type="preregistered">

4800200052555666</card_details>

<Card>

<street_address1>Flat 7</street_address1>

<street_address2>89 Jumble

Street</street_address2>

<street_address3>Mytown</street_address3>

<cv2_policy notprovided="reject"

notchecked="accept"

matched="accept"

notmatched="reject"

partialmatch="reject"/>

<postcode_policy notprovided="reject"

notchecked="accept"

matched="accept"

notmatched="reject"

partialmatch="accept"/>

<address_policy notprovided="reject"

notchecked="accept"

matched="accept"

notmatched="reject"

partialmatch="accept"/>

</ExtendedPolicy>

</Cv2Avs>

</Card>

</CardTxn>

</Transaction>

</Request>

See also section 2.2.8.2.3 for examples using HCC and extended policy

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.4.1.3 Schema Elements for Response

AVSCV2 results are returned in the Cv2Avs element for successfully authorised or

referred transactions. If a transaction is DECLINED, the AVSCV2 results will not be

available either in the XML response or on the Reporting pages.

2.4.1.3.1 Cv2Avs

Element Name:

Cv2Avs

Position

Response.CardTxn

Most child elements and attributes of Cv2Avs are dependent upon whether the

default/standard or extended policy checks where used.

Attributes of child elements in Cv2Avs

Attribute

Name

Element Name

Description

Values /

Limitations

reversal

cv2avs_status

The result of the

reversal request for

transactions failing to

meet the chosen policy

0 – failed

1 - successful

2.4.1.3.1.1 Standard and Default Policies

Elements of Cv2Avs

Element Name

Description

Values / Limitations

cv2avs_status

The overall result of the

transaction

NO DATA MATCHES

ADDRESS MATCH ONLY

SECURITY CODE MATCH ONLY

ALL MATCH

DATA NOT CHECKED

Policy

The policy the transaction was checked against.

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example Response elements for a transaction checked using either the

default or standard policy

<cv2avs_status reversal="1">SECURITY CODE MATCH

ONLY</cv2avs_status>

</Cv2Avs>

<cv2avs_status reversal="0">ADDRESS MATCH ONLY</cv2avs_status>

</Cv2Avs>

<cv2avs_status>ALL MATCH</cv2avs_status>

</Cv2Avs>

2.4.1.3.1.2 For Extended Polices

Elements of Cv2Avs

Element Name

Description

Values / Limitations

cv2avs_status

The overall result of the

transaction

ACCEPTED

REJECTED

address_result

The result of the check

for that particular

element

One of:

notprovided

notchecked

matched

notmatched

partialmatch

cv2_result

postcode_result

address_policy

The policy the transaction was checked

against. These have the same format as in the

Request – see section 2.4.1.1.2.

cv2_policy

postcode_policy

Attributes of child elements within Cv2Avs

Attribute

Name

Element Name

Description

Values / Limitations

numeric

address_result

cv2_result

postcode_result

The numerical

result returned

by the bank for

each element.

0 – not provided

1 – not checked

2 – matched

4 - not matched

8 – partial match

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example Response Elements for extended policy transactions

<address_policy notprovided="reject"

notchecked="accept"

matched="accept"

notmatched="reject"

partialmatch="accept"/>

<address_result numeric='0'>notprovided</address_result>

<cv2_policy notprovided="reject"

notchecked="accept"

matched="accept"

notmatched="reject"

partialmatch="reject"/>

<cv2_result numeric='2'>matched</cv2_result>

<cv2avs_status reversal='1'>REJECTED</cv2avs_status>

<postcode_policy notprovided="reject"

notchecked="accept"

matched="accept"

notmatched="reject"

partialmatch="accept"/>

<postcode_result numeric='4'>notmatched</postcode_result>

</Cv2Avs>

<address_policy notprovided="reject"

notchecked="accept"

matched="accept"

notmatched="reject"

partialmatch="accept"/>

<address_result numeric='2'>matched</address_result>

<cv2_policy notprovided="reject"

notchecked="accept"

matched="accept"

notmatched="reject"

partialmatch="reject"/>

<cv2_result numeric='1'>not checked</cv2_result>

<cv2avs_status>ACCEPTED</cv2avs_status>

<postcode_policy notprovided="reject"

notchecked="accept"

matched="accept"

notmatched="reject"

partialmatch="accept"/>

<postcode_result numeric='2'>matched</postcode_result>

</Cv2Avs>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.4.1.4 XML Example Responses

2.4.1.4.1 Successful AVSCV2 Responses

An example response for transactions successfully passing the standard or

default policy AVSCV2 check

<card_scheme>VISA</card_scheme>

<cv2avs_status>SECURITY CODE MATCH ONLY</cv2avs_status>

</Cv2Avs>

</CardTxn>

<datacash_reference>4000000098765888</datacash_reference>

<reason>ACCEPTED</reason>

</Response>

An example response for transactions successfully passing the extended

policy AVSCV2 check

<card_scheme>VISA</card_scheme>

<address_policy notprovided="reject"

notchecked="accept" matched="accept"

notmatched="reject" partialmatch="accept"/>

<address_result numeric='2'>matched</address_result>

<cv2_policy notprovided="reject"

notchecked="accept" matched="accept"

notmatched="reject" partialmatch="reject"/>

<cv2_result numeric='1'>not checked</cv2_result>

<cv2avs_status>ACCEPTED</cv2avs_status>

<postcode_policy notprovided="reject"

notchecked="accept" matched="accept"

notmatched="reject" partialmatch="accept"/>

<postcode_result numeric='2'>matched</postcode_result>

</Cv2Avs>

</CardTxn>

<datacash_reference>4000000098765433</datacash_reference>

<reason>ACCEPTED</reason>

</Response>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.4.1.4.2 AVSCV2 Declined Responses

An example response for transactions failing to match the standard or

default policy chosen

<card_scheme>VISA</card_scheme>

<cv2avs_status reversal="1">ADDRESS MATCH ONLY

</cv2avs_status>

</Cv2Avs>

</CardTxn>

<datacash_reference>4000000098765889</datacash_reference>

<reason>CV2AVS DECLINED</reason>

</Response>

An example response for transactions failing to match the extended policy

chosen

<card_scheme>VISA</card_scheme>

<country>United Kingdom</country>

<address_policy notprovided="reject" notchecked="accept"

matched="accept" notmatched="reject" partialmatch="accept"/>

<address_result numeric="1">notchecked</address_result>

<cv2_policy notprovided="reject" notchecked="accept"

matched="accept" notmatched="reject" partialmatch="reject"/>

<cv2_result numeric="2">matched</cv2_result>

<cv2avs_status reversal="1">REJECTED</cv2avs_status>

<postcode_policy notprovided="reject"

notchecked="accept" matched="accept" notmatched="reject"

partialmatch="accept"/>

<postcode_result numeric="4">notmatched</postcode_result>

</Cv2Avs>

</CardTxn>

<datacash_reference>4000000098765432</datacash_reference>

<reason>CV2AVS DECLINED</reason>

</Response>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.4.1.4.3 Referred Transactions

If a transaction is referred by the bank, AVSCV2 information will still be available. If

the transaction failed AVSCV2 checking, then any attempt to submit an

authorize_referral_request or fulfill transaction with a new authorisation code

will be declined.

An example response for referred transactions successfully passing the

standard or default policy AVSCV2 check

<authcode>CALL AUTH CENTRE</authcode>

<card_scheme>VISA</card_scheme>

<cv2avs_status>SECURITY CODE MATCH ONLY</cv2avs_status>

</Cv2Avs>

</CardTxn>

<datacash_reference>4000000098765888</datacash_reference>

<reason>REFERRED</reason>

</Response>

Example XML Response for a successful authorize_referral_request

<cv2avs_status>SECURITY CODE MATCH ONLY</cv2avs_status>

</Cv2Avs>

</CardTxn>

<datacash_reference>3900200000000001</datacash_reference>

<reason>ACCEPTED</reason>

</Response>

An example response for referred transactions failing to match the standard

or default policy chosen

<authcode>CALL AUTH CENTRE</authcode>

<card_scheme>VISA</card_scheme>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.4.1.4.4 Declined Transactions

If a transaction is declined by the bank, no AVSCV2 information will be available. The

transaction Response will therefore be the same as a declined transaction with no

AVSCV2 checking. Please refer to section 2.2.1.4 for examples.

<cv2avs_status>ADDRESS MATCH ONLY

</cv2avs_status>

</Cv2Avs>

</CardTxn>

<datacash_reference>4000000098765889</datacash_reference>

<reason>REFERRED</reason>

</Response>

Example XML Response for a declined authorize_referral_request

<cv2avs_status>ADDRESS MATCH ONLY

</cv2avs_status>

</Cv2Avs>

</CardTxn>

<datacash_reference>4000000098765889</datacash_reference>

<reason>CV2AVS DECLINED</reason>

</Response>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.4.2 URU®

A technical introduction to this Service is available on the website:

http://www.datacash.com/gettingproducts.php?id=Age-Identity-Verification-Overview

This Service allows an individual’s identity and personal information to be authenticated

against a number of databases, and the results of previous authentications to be

retrieved.

Some data elements used in this service use the Universal Unique ID format (UUID).

This format is xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx and unless otherwise

indicated is hexadecimal.

2.4.2.1 Schema Elements for Request

In this section the required fields for URU® requests will be presented, along with

example XML for those fields.

As the two transaction types do not use the same fields, each field will be labelled with

the following key:

 O – Optional

 R – Required

 X – Excluded, presenting this field for the transaction type will cause the

transaction to fail.

It should be noted that these indicate the status of the field within the DPG only. If you

are integrating this service, we strongly advise that you discuss with URU® the fields

that must be used in order to gain optimum results from the service.

Authentications

The information required to process an identity authentication - authenticate - is

passed in several distinct places in the schema:

2.4.2.1.1 Request

o Authentication - section 2.1.1.2

o Transaction

 TxnDetails – contains the merchantreference, section 2.4.2.1.2

 URUTxn - contains the data relating to the individual being authenticated,

along with the method authenticate, section 2.4.2.1.3

 Basic – basic details about the customer, section 2.4.2.1.4

 UKData – customer details for UK customers, section 2.4.2.1.5

 Address1, Address2, Address3 & Address4 – details for up to four

addresses, section 2.4.2.1.6

 Passport – details for UK passports, section 2.4.2.1.7

 Electric – details of the electricity bill, section 2.4.2.1.8

 Telephone – details about the telephone number, section 2.4.2.1.9

 Driver – details of the driving licence, section 2.4.2.1.11

 Birth – details about the place of birth of the customer and mother’s

maiden name, section 2.4.2.1.11

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

 USData - customer details for US customers. Includes social security

number, driving licence and telephone number. Section 2.4.2.1.12

 USAddress1, USAddress2, USAddress3 & USAddress4 – details for up

to four addresses, section 2.4.2.1.13

 Employment – employment history, section 2.4.2.1.14

 CreditDebitCard – credit and debit card details, section 2.4.2.1.15

 InternationalPassport – details of the machine-readable

international passport, section 2.4.2.1.17

 Authenticate – details of the URU account to be used for the

transaction, section 2.4.2.1.18

Log Requests

The log of a previous authentication may be retrieved using this method,

get_log_by_authentication_id

 Request

 Authentication – section 2.1.1.2

 Transaction

 TxnDetails - contains the merchantreference, section 2.4.2.1.2.

 URUTxn - contains the query reference for the authentication being

retrieved, along with the method get_log_by_authentication_id, section

2.4.2.1.3

2.4.2.1.2 TxnDetails

Element Name:

TxnDetails

Position(s)

Request.Transaction

Elements of TxnDetails

Element Name

Description

Values /

Limitations

Authenticate

Log

Request

merchantreference

A unique

reference number

for each

transaction

Between six and

thirty alphanumeric

characters

R

Example XML for TxnDetails elements

<merchantreference>123402ABCDE12</merchantreference>

</TxnDetails>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.4.2.1.3 URUTxn

This is the base element for submission of URU specific information. As well as holding

information about an individual for authentication, it contains the transaction type and,

in the case of log requests, the original authentication ID.

In the case of authentication transactions, only the method element is mandatory.

However, at least one of the other user data sub-elements must be present.

Element Name:

URUTxn

Position(s)

Request.Transaction

Elements of URUTxn

Element Name

Description

Values / Limitations

Authenti

cate

Log

Request

method

Identifies the

transaction type as

an authentication,

or a log request

authenticate

get_log_by_authentication

_id

R

Basic

Basic information

about an

individual’s name

and date of birth

See section 2.4.2.1.4

O

X

Employment

Information about

an individual’s

employment

See section 2.4.2.1.14

O

X

CreditDebitCard

Information about

an individual’s

Payment Card

See section 2.4.2.1.15

O

X

InternationalPassport

Information about

an individual’s

international

machine-readable

passport

See section 2.4.2.1.17

O

X

guid

The query reference

of the original

transaction

UUID

X

R

UKData

Information for UK

residents

See section 2.4.2.1.5

O

X

USData

Information for US

Residents

See section 2.4.2.1.12

O

X

Authenticate

Information about

the URU account

which is to be used

for the transaction

See section 2.4.2.1.18

O

X

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example XML Element URUTxn for an authentication

<method>authenticate</method>

</URUTxn>

Example XML Element URUTxn for a log request

<method>get_log_by_authentication_id</method>

<guid>01234567-89ab-dcef-0123-456789abcdef</guid>

</URUTxn>

2.4.2.1.4 Basic

This element holds information about an individual’s name and date of birth. Unless

otherwise specified, all string fields accept up to 256 characters. All sub-fields are

optional.

Element Name:

Basic

Position(s)

Request.Transaction.URUTxn

Elements of Basic

Element Name

Description

Values /

Limitations

dob_day

The day of the month of the

individual’s birthday

int 1-31

dob_month

The month of the year of the

individual’s birthday

int 1-12

dob_year

The year of the individual’s birth

int 0-9999

forename

The individual’s forename

string

gender

The individual’s gender

Male

Female

Unknown

Unspecified

middle_initial

The individual’s middle initial(s)

string

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

surname

The individual’s surname

string

title

The title of the individual (e.g. Mr,

Miss)

string

Example XML Element Basic

<Basic>

<dob_day>14</dob_day>

<dob_month>12</dob_month>

<dob_year>1972</dob_year>

<middle_initial>F</middle_initial>

<surname>Bloggs</surname>

</Basic>

2.4.2.1.5 UKData

This contains a number of complex elements – Address1 through to Address4,

Electric, Telephone, Passport, Driver and Birth. All elements are complex (i.e.

contain sub elements) and optional.

Element Name:

UKData

Position(s)

Request.Transaction.URUTxn

Elements of UKData

Element

Name

Description

Values / Limitations

Address1

See section 2.4.2.1.6

Address2

Address3

Address4

Passport

See section 2.4.2.1.7

Electric

See section 2.4.2.1.8

Telephone

See section 2.4.2.1.9

Driver

See section 2.4.2.1.11

Birth

See section 2.4.2.1.11

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example XML Element UKData

...

</Telephone>

</UKData>

Example XML Element UKData

</UKData>

2.4.2.1.6 Address#n

Up to four addresses may be specified for addresses in the UK, labelled Address1,

Address2, Address3 and Address4. Each takes the same format. Unless otherwise

specified, all string fields accept up to 256 characters. All sub-fields are optional.

Element Name:

Address#n

Position(s)

Request.Transaction.URUTxn.UKData

Elements of Address#n

Element Name

Description

Values / Limitations

postcode

The postcode of the address

string

building_name

The building name of the

address

string

building_no

The building number of the

address

string

sub_building

The sub-building

name/number of the

address

string

organisation

The organisation name of

the address

string

street

The street name of the

address

string

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

sub_street

The sub-street name of the

address

string

town

The town name of the

address

string

district

The district name of the

address

string

first_year_of_residence

The first year the individual

was at this address

int 0-9999

last_year_of_residence

The last year the individual

was at this address

int 0-9999

Example XML Element Address1

<building_name>Duncodin</building_name>

<building_no>1</building_no>

<sub_building>3F2</sub_building>

<organisation>Company Ltd</organisation>

<street>Main Street</street>

<sub_street>East End</sub_street>

<town>Littleton</town>

<district>Central</district>

<first_year_of_residence>2003</first_year_of_residence>

<last_year_of_residence>2004</last_year_of_residence>

</Address1>

Example XML Element Address2

<building_no>8</building_no>

<street>High Street</street>

</Address2>

2.4.2.1.7 Passport

This block holds information about an individual’s UK passport. International passports

should use the InternationalPassport element, section 2.4.2.1.17. The passport

number is split into six parts, and submitted as number1 to number6. All sub-fields are

optional.

Element Name:

Passport

Position(s)

Request.Transaction.URUTxn

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Elements of Passport

Element Name

Description

Values / Limitations

number1

The first 10 digits of the passport

number (9 digit number plus

checksum)

string, 10 characters

number2

The next 3 digits of the passport

number (Issuing State code)

string, 3 characters

number3

The next 7 digits of the passport

number, (date of birth plus

checksum)

string, 7 characters

number4

The next 1 character of the

passport number (gender)

string, 1 character

number5

The next 7 characters of the

passport number (passport expiry

date plus checksum)

string, 7 characters

number6

The final 2 digits of the passport

number (checksum digits)

string, 2 characters

expiry_day

The day of the month of the

passport expiry

int, 1-31

expiry_month

The month of the year of the

passport expiry

int, 1-12

expiry_year

The year of the passport expiry

int, 0-9999

Example XML Passport elements

<expiry_day>12</expiry_day>

<expiry_month>5</expiry_month>

<expiry_year>2010</expiry_year>

</Passport>

<expiry_day>23</expiry_day>

<expiry_month>9</expiry_month>

<expiry_year>2008</expiry_year>

</Passport>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.4.2.1.8 Electric

This block holds information about an individual’s electricity bill. The bill number is

split into four parts and submitted as number1 to number4. Unless otherwise specified,

strings accept a maximum of 256 characters. All sub-fields are optional.

Element Name:

Electric

Position(s)

Request.Transaction.URUTxn

Elements of Electric

Element

Name

Description

Values / Limitations

number1

The first 2 digits of the bill number

string, 2 characters

number2

The next 4 digits of the bill number

string, 4 characters

number3

The next 4 digits of the bill number

string, 4 characters

number4

The final 3 digits of the bill number

string, 3 character

mail_sort

The mail sort code of the bill

address

string

postcode

The postcode the bill is sent to

string

Example XML Electric elements

<mail_sort>AB123</mail_sort>

</Electric>

</Electric>

2.4.2.1.9

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.4.2.1.10 Telephone

This block holds information about an individual’s telephone number. An optional

attribute will be accepted that indicates whether or not the number is ex-directory.

Unless otherwise specified, strings accept a maximum of 256 characters. All sub-fields

are optional.

Element Name:

Telephone

Position(s)

Request.Transaction.URUTxn

Attributes of Telephone

Attribute Name

Description

Values / Limitations

exdirectory

Whether or not the telephone is ex-

category

LineItem

category of offer

S - Standard

P - Promotion

O

manpartno

LineItem

manufacturers part

number

30 characters max, inc spaces

O

manufacturer

LineItem

manufacturers

name

50 characters max, inc spaces

O

product_code

LineItem

your product code

18 characters max, inc spaces

O

quantity

LineItem

number of items

ordered

12 digits max

O

sku

LineItem

product ID or SKU

18 characters max, inc spaces

O

type

LineItem

Product type

P - physical goods

D - digital goods, e.g. software

C - digital content, e.g. images

S - shareware

M - a mixture of the above

O

unit_price

LineItem

Cost per item

If a decimal point is included, it

must be followed by two digits

O

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

upc

LineItem

product UPC

12 characters max, inc spaces

O

wrapped

gift

Is the item/order

wrapped?

XML Boolean

O

Example XML for LineItem with one item

<gift card="G" wrapped="false">Congratulations!</gift>

</LineItem>

Example XML for LineItem with eight copies of one product

Example XML for an order with two products

<LineItem category="S" manpartno="part number 1J800" manufacturer="Dell"

product_code="DELL-1J800" quantity="1" type="P" unit_price="900">

<description>Desktop</description>

…

</Shipping>

</LineItem>

<LineItem category="P" manpartno="CD0001" manufacturer="Sony"

product_code="SONY-CD0001" quantity="20" sku="sku 2" unit_price="0.50"

upc="upc 2">

<description>CD boxes</description>

…

</Shipping>

</LineItem>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.4.3.1.11 Order

The majority of the extra information is contained within this element.

Elements of Order

Element Name

Description

Values /

Limitations

Customer

See section 2.4.3.1.6

MS

BillingAddress

See section 2.4.3.1.4

MS

Recipient

See section 2.4.3.1.13

O

OrderDetails

See section 2.4.3.1.12

O

Shipping

See section 2.4.3.1.14

O

returns_allowed

Indicates if you enable the customer to

return goods to you

XML

Boolean

O

gift

For gifts, any message attached to the

entire order. May also be specified on a

per item basis in the LineItem element

(section 3.3.2.1.6)

160 max

O

Attributes of Order

Attribute Name

Attribute of

Description

Values / Limitations

wrapped

gift

Is the item/order wrapped?

XML Boolean

O

card

gift

Gift occasion

See Appendix 5

O

Example XML elements for Order

<Order>

<returns_allowed>true</returns_allowed>

</Order>

<Order>

</Order>

2.4.3.1.12 OrderDetails

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Element Name:

OrderDetails

Position(s)

Request.Transaction.TxnDetails.Order

Elements of OrderDetails

Element

Name

Description

Values / Limitations

handling

Shipping and handling charges

If a decimal point is

included

it must be followed by two

digits

O

subtotal

Order subtotal, without tax, shipping and

handling

O

tax

Order tax

O

LineItem

See section 3.3.2.1.6

O

Example XML element for OrderDetails

</OrderDetails>

2.4.3.1.13 Recipient

This element enables information about the recipients of the order to be submitted. For

example, if the customer is placing the order on behalf of a third party, details of that

person can be passed for screening. Orders that are being shipped to several people

can be presented by using one Recipient element for each person.

Element Name:

Recipient

Position(s)

Transaction.TxnDetails.Order.Recipient

Elements in the PartyType box are common to both Customer and Recipient are

described in section 2.4.3.1.6

Elements of Recipient

Element Name

Description

Values / Limitations

Address

See 2.4.3.1.3

R

age

See 2.4.3.1.6

I

alt_telephone

O

email

O

fax

O

forename

O

max_age

I

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

middlename

O

min_age

I

salutation

O

surname

O

telephone

O

LineItem

See 3.3.2.1.6

O

Example XML element for Recipient

<forename>Julia</forename>

<tracking_number>123</tracking_number>

<comments>FAO Mrs Jane White</comments>

</Recipient>

2.4.3.1.14 Shipping

This element enables information about the method of shipment to be entered. It may

be presented in one of three places in the schema.

Element Name:

Shipping

Position(s)

Request.Transaction.TxnDetails.Order.OrderDetails.LineItem

Request.Transaction.TxnDetails.Order.Recipient.LineItem

Request.Transaction.TxnDetails.Order

If all items within the order are being shipped within the same parcel, the

Order.Shipping element should be used. If the items are being shipped to the

customer as they become available, the OrderDetails.LineItem.Shipping elements

should be used for each item within the order. For orders which are being shipped to

several different recipients, the Recipient.LineItem.Shipping element should be

used for each item within the order.

Elements of Shipping

Element Name

Description

Values / Limitations

carrier

Shipment carrier for order/item

F - FedEx

P - USPS

U - UPS

L – Purolator

G - Greyhound

D - DHL

O - Other

O

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

comments

Additional text for shipment of

order/item

160 max

O

instructions

When the shipment is to be made

C - when order is complete

A - as items become available

D - on a specified date

O

method

The delivery method

N - Next Day/Overnight

T - Two Day Service

W - Three Day Service

C - Lowest Cost

D - Carrier designated by

Customer

I - International

M - Military

P - Store delivery service

O - Other

O

tracking_number

shipment tracking number for

item/order

max 19

O

Example XML element for Shipping

<tracking_number>123</tracking_number>

<comments>FAO Mrs Jane White</comments>

</Shipping>

2.4.3.1.15 TxnDetails

Element Name:

TxnDetails

Position(s)

Request.Transaction

Elements of TxnDetails

Element Name

Description

Values / Limitations

transactionsource

The environment in which the

transaction was made. Particularly

important if a single ReD account is used

to screen transactions from several

sources

ecommerce

mail-

order/telephone-

order

O

Order

0

R

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example XML elements for TxnDetails

<transactionsource>ecommerce</transactionsource>

</TxnDetails>

<transactionsource>mail-order/telephone-order</transactionsource>

</TxnDetails>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.4.3.2 Example XML Request

Example XML Request where the order is being shipped to two different

recipients

<Order>

<surname>Brown</surname>

<streetaddress>10 Front Street</streetaddress>

<city>Edinburgh</city>

<region>Lothian</region>

</Address>

<email>j.brown@compuserve.com</email>

<alt_telephone>44 131 999 8888</alt_telephone>

</Customer>

<forename>Jenny</forename>

<surname>Black</surname>

<streetaddress>26 The High Street</streetaddress>

<city>Cardiff</city>

</Address>

<LineItem manufacturer="CO Q" quantity="1"

unit_price="20.00">

<description>Present</description>

<gift card="R" wrapped="true">Happy Christmas</gift>

</LineItem>

</Recipient>

<forename>Laura</forename>

<surname>Green</surname>

<streetaddress>99 Royal York Crescent</streetaddress>

<city>London</city>

</Address>

<LineItem manufacturer="ABC" quantity="2"

unit_price="10.00">

<description>Present</description>

<gift card="R" wrapped="true">Happy Christmas</gift>

</LineItem>

</Recipient>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

</Order>

</TxnDetails>

</Transaction>

</Request>

Example XML Request where ReD and AVSCV2 checks are being used

<Order>

<forename>Sandra</forename>

<surname>Littlejohn</surname>

<streetaddress>37 Queen Street</streetaddress>

<city>Oxford</city>

</Address>

<email>slittlejohn@ox.co.uk</email>

<alt_telephone>0870 1234 4566</alt_telephone>

<ip_address>48.12.3.4</ip_address>

</Customer>

</Order>

…

</TxnDetails>

<Card>

<cv2_present>1</cv2_present>

<street_address1>37 Queen Street</street_address1>

<street_address2>Oxford</street_address2>

</Cv2Avs>

</Card>

</CardTxn>

</Transaction>

</Request>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example XML Request where the billing address is not the same as the

customer’s address

<Order>

<surname>Brown</surname>

<streetaddress>10 Front Street</streetaddress>

<city>Edinburgh</city>

<region>Lothian</region>

</Address>

<email>joe.brown@compuserve.com</email>

<alt_telephone>44 131 999 8888</alt_telephone>

<ip_address>231.0.0.1</ip_address>

</Customer>

<streetaddress>Main Street</streetaddress>

<moreaddress>Newtown</moreaddress>

<city>London</city>

</BillingAddress>

</Order>

...

</TxnDetails>

</Transaction>

</Request>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example XML Request element to override a fraud challenged transaction

<password>thepassword</password>

</Authentication>

<method>accept_fraud</method>

</HistoricTxn>

</Transaction>

</Request>

2.4.3.3 Schema Elements for Response

When a transaction is screened using this service, the general Response elements

(section 2.1.1.3) and CardTxn elements (section 2.2.1.3.1) elements will be present. An

additional element will also be present for authorisation Responses.

2.4.3.3.1 EbitGuard

This element contains the results of the fraud screening.

Element Name:

EbitGuard

Position(s)

Response.CardTxn

Elements of EbitGuard

Element Name

Description

Values

orderid

The ReD order ID. This uniquely identifies the order

fraud_status

The overall result of the transaction

Accept

Deny

Challenge

Attributes for Elements of EbitGuard

Attribute

Name

Attribute of

element

Description

Values

score

fraud_status

The ReD return

code

4 digit numeric

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example XML elements for EbitGuard

<fraud_status score="0150">Accept</fraud_status>

</EbitGuard>

<fraud_status score="0800">Deny</fraud_status>

</EbitGuard>

2.4.3.4 Example Responses

Example XML Response XML element for fraud declined transaction

<card_scheme>VISA Delta</card_scheme>

<country>United States</country>

<fraud_status score="0200">Deny</fraud_status>

</EbitGuard>

</CardTxn>

<datacash_reference>4700200040952107</datacash_reference>

<reason>FRAUD DECLINED 0200</reason>

</Response>

Example XML Response XML element for fraud challenged transaction,

authorised by the bank

<fraud_status score="0600">Challenge</fraud_status>

</EbitGuard>

…

</CardTxn>

<datacash_reference>4600200040952400</datacash_reference>

<reason>FRAUD CHALLENGED 0600</reason>

</Response>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example XML Response XML element for fraud challenged transaction,

declined by the bank

<authcode>NOT AUTHORISED</authcode>

<fraud_status score="0600">Challenge</fraud_status>

</EbitGuard>

…

</CardTxn>

<datacash_reference>4600200040500007</datacash_reference>

<reason>DECLINED</reason>

</Response>

Example XML Response XML element for an accepted transaction

<card_scheme>VISA</card_scheme>

<country>United Kingdom</country>

<fraud_status score="0100">Accept</fraud_status>

</EbitGuard>

</CardTxn>

<datacash_reference>4600200040500130</datacash_reference>

<reason>ACCEPTED</reason>

</Response>

Example XML. A successful accept_fraud transaction

<datacash_reference>4600200040952400</datacash_reference>

<reason>ACCEPT FRAUD CHALLENGE OK</reason>

</Response>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example XML. A failed accept_fraud

<datacash_reference>4300200040500382</datacash_reference>

<reason>accept_fraud attempted on CV2AVS DECLINED

transaction</reason>

</Response>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.4.4 3-D Secure, with DataCash MPI

This service enables you to perform a 3-D Secure check using the DataCash MPI and

then authorize the payment via the DPG. A technical introduction to this Service is

available on the website: http://www.datacash.com/gettingproducts.php?id=3D-

Secure-MPI-Service

The DataCash MPI service is utilised by sending a normal Credit and Debit Card Service

Request with several pieces of extra information. This section of the documentation

assumes the reader is familiar with the Credit and Debit Card Service, as described in

section 2.2.1.

It is also possible to use this service in conjunction with the Pre-Registered Card

Service, as outlined in section 2.3.1.

The following key will be used in this section of the document:

 R – Required

 M –Mandatory if 3D-Secure check is to be performed

 O – Optional

Cardholder Verification Check

The auth and pre transaction types require the same information about the transaction

to be provided.

This data is passed using the following schema elements:

 Request

o Authentication – section 2.1.1.2

o Transaction

 CardTxn - details about the card, section 2.2.1.1.2

 TxnDetails - contains details of the transaction, section 2.4.2.1.2

 ThreeDSecure – contains all the details required to initiate the 3-D

Secure check, section 2.4.4.1.1

 Browser – details of the browser the cardholder is using, section

2.4.4.1.2

Authorization and Referred Authorization

The threedsecure_authorization_request and

threedsecure_authorize_referral_request transaction types require information to

be provided in the HistoricTxn element:

 Request

o Authentication – section 2.1.1.2

o Transaction

 HistoricTxn – section 2.4.4.1.2

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.4.4.1 Schema Elements for Request

2.4.4.1.1 ThreeDSecure

This element contains all of the extra details which are required for the 3-D Secure

check to be initiated and should be provided for auth and pre Requests.

Element Name:

ThreeDSecure

Position:

Request.Transaction.TxnDetails

Elements of ThreeDSecure

Element Name

Description

Values / Limitations

Required

verify

Indicates whether the

transaction should be checked

for enrolment in the 3-D

Secure system

yes

no

R

merchant_url

The URL of the website on

which the payment is being

made. Will be displayed to

cardholder by ACS

1-2048 characters.

Must be fully qualified

(i.e. include https://)

M

purchase_desc

A short description of what

has been purchased. This is

shown to the card holder by

the ACS.

1-125 characters

M

purchase_datetime

The date and time of the

transaction

YYYYMMDD HH:MM:SS

format

M

Browser

See section 2.4.4.1.2

M

Example XML for ThreeDSecure complex elements

<merchant_url>https://www.widgets.com/</merchant_url>

<purchase_desc>DVD</purchase_desc>

<purchase_datetime>20120731 21:59:42</purchase_datetime>

</ThreeDSecure>

</ThreeDSecure>

2.4.4.1.2 Browser

The Browser element contains all the information about the browser the cardholder is

using to access your website, and must be provided for auth and pre requests where

the 3-D Secure check is to be performed.

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Element Name:

Browser

Position:

Request.Transaction.TxnDetails.ThreeDSecure

Elements of Browser

Element Name

Description

Values /

Limitations

Required

accept_headers

The MIME types of the headers

accepted by this device

R

user_agent

The User Agent associated with the

device

R

Example XML for Browser complex elements

<accept_headers>*/*</accept_headers>

<user_agent>IE/6.0</user_agent>

</Browser>

<accept_headers>txt/xml, application/xml, application/xhtml+xml,

text/html;q=0.9, text/plain;q=0.8,video/x-mng, image/png,

image/jpeg, image/gif;q=0.2, text/css, */*;q=0.1

</accept_headers>

<user_agent>Mozilla/5.0 (Macintosh; U; PPC Mac OS X; en)

AppleWebKit/417.9 (KHTML, like Gecko) Safari/417.9.2

</user_agent>

</Browser>

2.4.4.1.3 HistoricTxn

The HistoricTxn element is used for threedsecure_authorization_request,

threedsecure_authorize_referral_request and fulfill transactions. It enables

these transactions to be tied back to the original transaction.

Element Name:

HistoricTxn

Position:

Request.Transaction

Elements of HistoricTxn

Element Name

Description

Values /

Limitations

3DS ref1

3DS

aut2

3DS ful3

reference

The datacash_reference

number for the

transaction

16 digits

R

authcode

The authorisation code

provided by your Bank’s

Authorisation Centre

-

R

n/a

R

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Method

The transaction type

See bullets

below

R

pares_message

The Payer

Authentication Response

(PARes) returned by the

ACS

As returned

by the ACS

O

n/a

1 threedsecure_authorize_referral_request

2 threedsecure_authorization_request

3 fulfill

Attributes of elements within HistoricTxn

Attribute

Name

Attribute of

Element

Description

Values /

Limitations

Required

tx_status_u

method

Accepts the transaction if the

ACS is unable to complete the

validation of the card holder

accept

O

Example XML for HistoricTxn complex elements

<method>threedsecure_authorization_request</method>

<pares_message>uyt45t89cnwu3rhc98a4hterjklth4o8c

tsrjzth4</pares_message>

</HistoricTxn>

threedsecure_authorization_request</method>

<pares_message>4o7sbvohyv8s4075mytudriotu0359ucmi

udtoyuu</pares_message>

</HistoricTxn>

Example XML for HistoricTxn complex elements for transactions which

cannot be 3-D Secure checked (e.g. card scheme not supported, non-

enrolled cards)

<method>threedsecure_authorization_request</method>

</HistoricTxn>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example XML for HistoricTxn complex elements for referred authorisation

<method>threedsecure_authorize_referral_request</method>

<pares_message>w5670w5689kg74u76490wf

uvaero5ielktekt=vre</pares_message>

</HistoricTxn>

Example XML for HistoricTxn complex elements for a fulfill

<method>fulfill</method>

</HistoricTxn>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.4.4.2 XML Example Requests

2.4.4.2.1 Cardholder Verification Requests

Example XML for pre transactions which by-pass the 3-D Secure check

</Authentication>

<merchantreference>387545924AdkWdd</merchantreference>

</ThreeDSecure>

</TxnDetails>

<Card>

</Card>

</CardTxn>

</Transaction>

</Request>

</Authentication>

<capturemethod>ecomm</capturemethod>

<merchant_url>https://www.mywebsite.com/12/</merchant_url>

<purchase_desc>CDs and DVDs</purchase_desc>

<purchase_datetime>20120531 13:06:28</purchase_datetime>

<accept_headers>*/*</accept_headers>

<user_agent>IE/6.0</user_agent>

</Browser>

</ThreeDSecure>

</TxnDetails>

<Card>

</Card>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

</CardTxn>

</Transaction>

</Request>

Example XML for an auth request, requesting verification

</Authentication>

<capturemethod>ecomm</capturemethod>

<merchant_url>https://www.mywebsite.com/</merchant_url>

<purchase_desc>CDs and DVDs</purchase_desc>

<purchase_datetime>20120206 23:59:59</purchase_datetime>

<accept_headers>*/*</accept_headers>

<user_agent>IE/6.0</user_agent>

</Browser>

</ThreeDSecure>

</TxnDetails>

<Card>

</Card>

</CardTxn>

</Transaction>

</Request>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example XML for a Pre-Registered Card request, requesting verification

</Authentication>

<capturemethod>ecomm</capturemethod>

<merchant_url>https://www.mywebsite.com/</merchant_url>

<purchase_desc>CDs and DVDs</purchase_desc>

<purchase_datetime>20120201 23:59:59</purchase_datetime>

<accept_headers>*/*</accept_headers>

<user_agent>IE/6.0</user_agent>

</Browser>

</ThreeDSecure>

</TxnDetails>

<card_details type="preregistered">

4100200043070870</card_details>

</CardTxn>

</Transaction>

</Request>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.4.4.2.2 Historic Transactions

Example XML for a threedsecure_authorization_request, with PARes

</Authentication>

threedsecure_authorization_request</method>

<pares_message>w48gj6s5ty45ty8cviozdtrjgd </pares_message>

</HistoricTxn>

</Transaction>

</Request>

Example XML for a threedsecure_authorization_request without a PARes.

E.g. for a non-enrolled card, or a card scheme which is not supported by 3-D

Secure

</Authentication>

<method>threedsecure_authorization_request</method>

</HistoricTxn>

</Transaction>

</Request>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example XML for a threedsecure_authorize_referral_request

</Authentication>

<method>threedsecure_authorize_referral_request</method>

</HistoricTxn>

</Transaction>

</Request>

Please refer to section 2.2.1.2.2 for an example fulfill request.

2.4.4.3 Schema Elements for Response

2.4.4.3.1 ThreeDSecure

This element will be returned in response to a card enrolment check, if the card is

enrolled. If the card is not enrolled or is not supported, this element will not be

present.

Element Name:

ThreeDSecure

Position:

Response.CardTxn

Elements of ThreeDSecure

Element Name

Description

pareq_message

The PAReq

acs_url

The URL of the ACS, to which the cardholder needs to be re-

directed. In the test environment this will be the URL of the

testserver ACS. In the live environment this will be the URL of

the Issuing Bank’s ACS.

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example XML for ThreeDSecure complex elements

<acs_url>https://secure.barclaycard.co.uk/barclays/tdsecure/pa.jsp?

partner=barclaycard.visa&VAA=B/</acs_url>

<pareq_message>eJxdUltugzAQ/M8pUA+AHyEQKscSLR/NB1HU5AKWsypIBRIb

StrT14Y4JkGAdnYWdjRjdiwVQH4A2SvgiyBgBWgtviCoTpuXswgjuiZ4tU

xeLGnoffYJl6k26AeUrtqGkxCHlCEHHV2AkqVoOtcwLSEvb9sdj5MkSglD

N+j5GtQ252lKcJxgzNCEPd+IGvhBKFEyNNaekm3fdOqXr2nMkAOe7tU3H4

YhPIlOSKHLULY1Q7br5KJnvWzf24aeb7lWJ17k2TB/dvk2Ko4ZKf7khiE7

4efNOuAU4xhTTAK6fF2l5mZo7M98qa1gTnCII2PLhDx9tkIyN2NH5p2ZB7

1S0Ehngk7ntgHzjYnrXs/Ugpa8A90Zgba8W/PsBHv/eEhVdiYmowwv7Wu6

xnxH4mF/ZWIh1LI3cF/i/mnWuWNmQxkPJF8w9HhY/w</pareq_message>

</ThreeDSecure>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.4.4.4 XML Example Responses

2.4.4.4.1 Cardholder Verification Response

Example XML Response for a card which is not enrolled

<card_scheme>Visa</card_scheme>

<country>United Kingdom</country>

<issuer>Prudential Banking PLC</issuer>

</CardTxn>

<datacash_reference>4300200042810617</datacash_reference>

<reason>3DS Card not Enrolled</reason>

</Response>

Example XML Response for a card which is enrolled

<card_scheme>Mastercard</card_scheme>

<country>United Kingdom</country>

<acs_url>https://www.clicksafe.lloydstsb.com/Lloyds/

tdsecure/pa.jsp?partner=mc&VAA=B/</acs_url>

<pareq_message>eJxdUltugzAQ/M8pUA+AHyEQKscSLR/NB1H

U5AKWsypIBRIbStrT14Y4JkGAdnYWdjRjdiwVQH4A2Svgiy

BgBWgtviCoTpuXswgjuiZ4tUxeLGnoffYJl6k26AeUrtqGk

xCHlCEHHV2AkqVoOtcwLSEvb9sdj5MkSglDN+j5GtQ252lK

cJxgzNCEPd+IGvhBKFEyNNaekm3fdOqXr2nMkAOe7tU3H4Y

hPIlOSKHLULY1Q7br5KJnvWzf24aeb7lWJ17k2TB/dvk2Ko

4ZKf7khiE74efNOuAU4xhTTAK6fF2l5mZo7M98qa1gTnCII

2PLhDx9tkIyN2NH5p2ZB71S0EhngkN+AK7ntgHzjYnrXs/U

gpa8A90Zgba8W/PsBHv/eEhVdiYmowwv7Wu6xnxH4mF/ZWI

h1LI3cF/i/mnWuWNmQxkPJF8w9HhY/wFTsbsh

</pareq_message>

</ThreeDSecure>

</CardTxn>

<datacash_reference>4300200042810537</datacash_reference>

<reason>3DS Payer Verification Required</reason>

</Response>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.4.4.4.2 Cardholder Authorisation Responses

Example XML Response when the PARes returned is invalid

<datacash_reference>3000100226001681</datacash_reference>

<information>[2:Error] Expected PARes node: got

'Error'</information>

<reason>3DS invalid pares</reason>

</Response>

Example XML Response were a referral response is received

<card_scheme>Visa</card_scheme>

<country>United Kingdom</country>

<issuer>Prudential Banking PLC</issuer>

</CardTxn>

<datacash_reference>3000100226001681</datacash_reference>

<merchantreference>13542DSDWK21</merchantreference>

<reason>3DS call auth centre</reason>

</Response>

2.4.4.4.3 Authorisation of Referred Cards

Example XML Response were a referral response to a

three3dsecure_authorize_referral_request

<datacash_reference>4900200043070079</datacash_reference>

<merchantreference>13542DSDWK21</merchantreference>

<reason>ACCEPTED</reason>

</Response>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.4.4.5 Using inline “Redirect Page”

Due to the increasing use of software known as “Popup Killers”, Visa and MasterCard

are recommending that merchants be aware that a “Popup” window may not be the

best way to direct cardholders to their issuer for authentication. Indeed, the 3-D

Secure specifications have explicitly banned the use of “Popup” windows as of October

2004. The recommended way to allow Cardholders to authenticate themselves is via an

in-line Redirect Page generated either via an <iframe /> type system or as a separate

“framed” page.

Example using the <iframe /> mechanism

<html>

<head>

<title>Please Authenticate</title>

</head>

<form name="downloadForm"

action="https://mybank.com/vbyv/verify/" method="POST">

<textarea name="PaReq"

style="display:none">thePaReqWithBreaks</textarea>

<input type="hidden" name="TermUrl" value="https://www.

MyWidgits.Com/next.cgi/">

</form>

<!--

function OnLoadEvent(){

document.downloadForm.target = "ACSframe";

document.downloadForm.submit();

}

//-->

</script>

height="450" frameborder="0"> </iframe>

</body>

</html>

In this example, no Popup window is created. The ACS dialogue takes place within a

floating frame on your page. After the cardholder has authenticated themselves they

will be returned to your site by their issuers ACS posting the results to the script

defined in the TermURL variable.

2.4.4.6 ACS Simulator & Magic Card Functionality

Please refer to the Developer’s Guide Appendices (Appendix 2 & Appendix 3) for

detailed information on the DataCash ACS Simulator and Magic Card Functionality. It is

intended that these are used during merchant integration of 3DS With DataCash MPI as

well as MPI Only integration, see section 2.4.5.

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.4.5 MPI Only

2.4.5.1 Summary of Service

Using this service, it is possible for merchants to perform 3-D Secure authentication of

a transaction using the DataCash MPI, and authorize the transaction with a 3rd party

Payment Gateway.

In order to use the decoupled DataCash MPI for 3-D Secure transactions a variety of

different transaction types are required. Initially an enrolment check transaction must

be performed which will contain all details required to initiate the 3-D Secure

authentication process as well as transaction details relating to the MPI-Only

transaction. The response to this message will indicate whether the cardholder is

enrolled.

If the cardholder is enrolled this can be followed by a validation authentication

transaction containing the PARes message returned from the ACS and a historic

reference. A successful response to this transaction will provide the merchant with

enough 3-D Secure information to allow the merchant to authorize the transaction with

a 3rd party Payment Gateway.

Alternatively, a merchant can optionally authorize the transaction using the DPG.

2.4.5.2 Schema elements for Request

This element contains all of the extra details which are required for the 3-D Secure

check to be initiated and should be provided for auth and pre Requests.

Element Name:

MpiTxn

Position:

Request.Transaction

Elements of MpiTxn

Element Name

Description

Values / Limitations

Required

method

The method of the

transaction

mpi

R

Card

The card details of

the transaction to be

authenticated. This

element contains sub

elements. See

2.1.1.1 for more

information

See 2.1.1.1 for more

information

M

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

card_details

If subscribed to the

preregistered card

service, this element

can be used instead

of the Card block

above. See 0 for an

example.

See 2.3.1 for more

information about

the preregistered

card service.

XML Attribute

type=”preregistered”

should be supplied in

the opening tag.

The value contained

should be the

datacash_reference of

the card transaction.

M

2.4.5.3 End to end walkthrough: Cardholder enrolled

The following scenario uses the DataCash MPI to successfully authorize a 3-D Secure

transaction where the cardholder is enrolled.

2.4.5.3.1 Enrolment Check

The first stage of 3-D Secure authentication is to perform an enrolment check. The

enrolment check transaction is similar to the existing Cardholder Verification Check

message type as used to perform normal (i.e. coupled with Card Authorization) 3-D

Secure transactions with the DataCash MPI. The main difference between these two

transaction types being that the enrolment check transaction holds card details within

the MpiTxn block.

It should be noted that neither Cv2Avs data, nor the Verify element will be allowed in

the enrolment check transaction. CV2/AVS data can be provided in a subsequent

authorization transaction if required.

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example Enrolment Check Request

</Authentication>

<merchant_url>http://www.mywebsite.com/</merchant_url>

<purchase_desc>CDs and DVDs</purchase_desc>

<purchase_datetime>20060201 3:59:59</purchase_datetime>

<accept_headers>*/*</accept_headers>

<user_agent>IE/6.0</user_agent>

</Browser>

</ThreeDSecure>

</TxnDetails>

<Card>

</Card>

</MpiTxn>

</Transaction>

</Request>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

The following is an example of the xml message response for an enrolled card. The

response contains the encoded PAReq message along with an ACS URL link.

Example Enrolment Check Response

<reason>3DS Payer Verification Required</reason>

<datacash_reference>4300200042810537</datacash_reference>

<pareq_message>eJxdUltugzAQ/M8pUA+AHyEQKscSLR/NB1H

U5AKWsypIBRIbStrT14Y4JkGAdnYWdjRjdiwVQH4A2Svgiy

BgBWgtviCoTpuXswgjuiZ4tUxeLGnoffYJl6k26AeUrtqGk

xCHlCEHHV2AkqVoOtcwLSEvb9sdj5MkSglDN+j5GtQ252lK

cJxgzNCEPd+IGvhBKFEyNNaekm3fdOqXr2nMkAOe7tU3H4Y

hPIlOSKHLULY1Q7br5KJnvWzf24aeb7lWJ17k2TB/dvk2Ko

4ZKf7khiE74efNOuAU4xhTTAK6fF2l5mZo7M98qa1gTnCII

2PLhDx9tkIyN2NH5p2ZB71S0EhngkN+AK7ntgHzjYnrXs/U

gpa8A90Zgba8W/PsBHv/eEhVdiYmowwv7Wu6xnxH4mF/ZWI

h1LI3cF/i/mnWuWNmQxkPJF8w9HhY/wFTsbsh

</pareq_message>

<acs_url>https://www.clicksafe.lloydstsb.com/Lloyds/

tdsecure/pa.jsp?partner=mc&VAA=B/</acs_url>

</ThreeDSecure>

</CardTxn>

</Response>

2.4.5.3.2 Validate Authentication

In order to authenticate an enrolled card, the merchant is required to submit a

‘threedsecure_validate_authentication’ transaction. This request will use the

datacash_reference from the enrolment check as the historic reference along with the

resulting PARes message received from the ACS.

An example threedsecure_validate_authentication transaction is shown below:

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example Validate Authentication Request

</Authentication>

<method>threedsecure_validate_authentication</method>

<pares_message>

uyt45t89cnwu3rhc98a4hterjklth4o8ctsrjzth4</pares_message>

</HistoricTxn>

</Transaction>

</Request>

The response to a threedsecure_validate_authentication where the cardholder was

successfully authenticated is shown below. This response contains the necessary fields

should the merchant wish to authorise the transaction using a 3rd Party Payment

Gateway.

Example Validate Authentication Response

<cardholder_registered>yes</cardholder_registered>

<security_code>Q0FWVkNBVlZDQVZWQ0FWVkNBVlY=</security_code>

<xid>MDAwMDAwMDAwMDAwMTIzNDU2NzE=</xid>

</ThreeDSecure>

</CardTxn>

<datacash_reference>3200900012345671</datacash_reference>

<reason>ACCEPTED</reason>

</Response>

Validate Authentication Requests support multiple versions. Where the request version

is not supplied or is equal to 1 then the above functionality will be in effect. Version 2

functionality differs from version 1 in the formatting of the Response. When supplied

version greater than 1 then an additional elements are returned: ‘mid’ and

‘acquirer’ are added to the response element. All MPI transactions return the

ThreeDSecure block in the response. ‘cavvAlgorithm’ is added to the ThreeDSecure

element of the response and the ‘security_code’ element is replaced with the ‘aav’

element.

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example Validate Authentication Response from version 2 request

<cardholder_registered>yes</cardholder_registered>

<aav>Q0FWVkNBVlZDQVZWQ0FWVkNBVlY=</aav>

<xid>MDAwMDAwMDAwMDAwMTIzNDU2NzE=</xid>

</ThreeDSecure>

</CardTxn>

<datacash_reference>3200900012345671</datacash_reference>

<reason>ACCEPTED</reason>

</Response>

If you use the version 2 for a Chase or Omnipay acquirer, 2 additional fields will be

returned by the Payment Gateway:

- ‘extended_status’ : containing the extended status code obtained from the

acquirer.

- ‘extended_response_message’: containing the extended description or reason

obtained from the acquirer.

Example of transaction using Chase and version 2:

<cardholder_registered>yes</cardholder_registered>

<aav>Q0FWVkNBVlZDQVZWQ0FWVkNBVlY=</aav>

<xid>MDAwMDAwMDAwMDAwMTIzNDU2NzE=</xid>

</ThreeDSecure>

</CardTxn>

<datacash_reference>3200900012345671</datacash_reference>

<acquirer>Chase Paymentech</acquirer>

<extended_status>100</extended_status>

<extended_response_message>Approved</extended_response_message>

<reason>ACCEPTED</reason>

</Response>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.4.5.3.3 Authorization via the DPG

The subsequent authorization of an MPI Only transaction by the DPG is entirely

optional. Enough information will have been returned to the merchant by the DPG in

response to the validation authentication transaction to permit authorization using 3-D

Secure with an alternative Payment Service Provider.

An example authorization request with the DPG is illustrated below. This authorization

is similar to that used for pre-registered card transactions. The method types permitted

for a subsequent authorization attempts are auth or pre and the type of the

transaction must state from_mpi.

CV2/AVS details can be optionally provided with the authorization request as part of

CardTxn details using the new Card element.

Additionally a transaction amount can also optionally be supplied. If a new amount is

supplied, then the transaction currency must also be provided and must match the

currency presented in the original enrolment check. Where a new amount is specified,

that amount will be used instead of the amount supplied in the original enrolment

check.

If the new amount is specified in an authorisation is greater than that specified in the

original authentication transaction, it is at the discretion and risk of the merchant.

DataCash make no claims with regard to liability shift.

Example Authorisation Request with the DPG

</Authentication>

<merchantreference>387545924AdkWdd</merchantreference>

</TxnDetails>

<card_details type="from_mpi">3200900012345671</card_details>

<Card>

<street_address1>1 High Street</street_address1>

<street_address2>This Town Town</street_address2>

<street_address3>Somewhere</street_address3>

<street_address4>United Kingdom</street_address4>

</Cv2Avs>

</Card>

</CardTxn>

</Transaction>

</Request>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

The response to a subsequent authorization of an MPI Only transaction will be as per

standard bankcard responses.

Example Authorisation Response from the DPG

<card_scheme>VISA</card_scheme>

<country>United Kingdom</country>

</CardTxn>

<datacash_reference>3000900012345672</datacash_reference>

<reason>ACCEPTED</reason>

</Response>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.4.5.4 End to end walkthrough: Cardholder not enrolled

As can be seen in the example xml response message below, where the cardholder is

not enrolled the ECI value will be returned to the merchant. If the merchant wishes to

continue with an authorization, they can do so using an alternative PSP or via the DPG.

2.4.5.4.1 Enrolment Check

An example response whereby the cardholder is not enrolled is shown below. This

response will contain an ECI value indicating that the cardholder authentication could

not be performed.

Example Enrolment Check Response – Cardholder not enrolled

<cardholder_registered>no</cardholder_registered>

</ThreeDSecure>

</CardTxn>

<datacash_reference>4300200042810537</datacash_reference>

<reason>3DS Card not Enrolled</reason>

</Response>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.4.5.4.2 Validate Authentication

For an MPI Only transaction with a cardholder that is not enrolled, a ThreeDSecure

validate authentication transaction will not be permitted. Such transactions will be

rejected by the DPG.

The following example response message would be returned in response to a

threedsecure_validate_authentication where the enrolment check determined that the

cardholder is not enrolled.

Example Validate Authentication Response – Cardholder not enrolled

<datacash_reference>3200900012345671</datacash_reference>

<reason>Authentication can only be performed for enrolled

cards</reason>

</Response>

2.4.5.4.3 Authorization via the DPG

Authorization of an MPI Only transaction where the cardholder was not enrolled can

optionally be performed via the DPG. The request and response messages for a

successful authorization are as shown in 2.1.1.3, the section for the Authorization of an

enrolled card.

2.4.5.5 Preregistered Card support

Preregistered cards can be used in the MpiTxn segment of the Enrolment check instead

of the Card block.

The following scenario uses the MPI to authenticate a 3-D Secure transaction using

preregistered card details.

The enrolment check specifies which earlier (successful) transaction to use to retrieve

the card details as highlighted below:

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example Enrolment Check using Preregistered Card Details

</Authentication>

<merchant_url>http://www.mywebsite.com/</merchant_url>

<purchase_desc>CDs and DVDs</purchase_desc>

<purchase_datetime>20080808 23:59:59</purchase_datetime>

<accept_headers>*/*</accept_headers>

<user_agent>IE/6.0</user_agent>

</Browser>

</ThreeDSecure>

</TxnDetails>

<card_details

type="preregistered">4300200042810536</card_details>

</MpiTxn>

</Transaction>

</Request>

DataCash will use the specified transaction to retrieve the card details to be used for

the new transaction.

The process of completing 3-D Secure authentication using the preregistered card

service differs only in how the card details are specified in the initial enrolment check

transaction. All responses will be as if the card details had been supplied explicitly with

the exception of the additional return code of 250 indicating that the details for the

supplied reference cannot be found.

2.4.5.6 ACS Simulator & Magic Card Facility

Please refer to the Developer’s Guide Appendices (Appendix 2 & Appendix 3) for

detailed information on the DataCash ACS Simulator and Magic Card Functionality. It is

intended that these are used during merchant integration of the MPI Only service as

well as 3DS with DataCash MPI service as described in section 2.4.4.1.1.

2.4.6 3-D Secure, with 3rd party MPI

This service enables you to authorize a payment via the DPG which has already been 3-

D Secure checked by a 3rd party MPI. A technical introduction to this Service is

available on the website:

http://www.datacash.com/gettingproducts.php?id=3D-Secure-Third-Party-MPI-Service

This service is utilised by sending a normal Credit and Debit Card Service Request with

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

up to four pieces of extra information. This section of the documentation assumes the

reader is familiar with the Credit and Debit Card Service, as described in section 2.2.1.

The service may also be used in conjunction with the Pre-Registered Card service, as

outlined in section 2.3.1

2.4.6.1 Schema Elements for Request

The data for the service is passed in five distinct places in the schema. The additional

information for this Service is all passed in the Secure element:

2.4.6.1.1 Request

o Authentication – section 2.1.1.2

o Transaction

 CardTxn – as described in 2.7.1.1.2

 Card – section 2.2.1.1.1

 Secure – up to four extra pieces of information about the card

transaction, section 2.4.6.1.2

 TxnDetails – see section 2.4.2.1.2

2.4.6.1.2 Secure

The Secure element contains the extra information for the 3-D Secure transaction. The

data within this element is obtained from your MPI.

Element Name:

Secure

Position:

Request.Transaction.TxnDetails.CardTxn

Elements of Secure

Element Name

Description

Values / Limitations

security_code

The Cardholder Authentication

Verification Value (CAVV) for Visa

cards, or Universal Cardholder

Authentication Field (UCAF) for

MasterCard, (Amex) for American

Express

M

cardholder_registered

Indicates whether the cardholder was

registered for 3-D Secure and the

PARes / VERes status

yes

no

attempted –

enrolled, PARes

status ‘A’

ch_enrolled_u –

VERes status ‘U’

tx_status_u –

enrolled, PARes

status ‘U’

R

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

eci

The Electronic Commerce Indicator

(ECI) obtained from your MPI

01

02

05

06

00

M

transactionID

The XID from PARes.Purchase.xid

As copied from the

PARes

M

Example Secure complex element

<cardholder_registered>no</cardholder_registered>

</Secure>

<security_code>AAABAwRzYAAAAAAAAAAAAAAAAAA=</security_code>

<cardholder_registered>yes</cardholder_registered>

<transactionID>TbwiW8VLThG3TjDuI7KS5wAJCAI=</transactionID>

</Secure>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.4.6.2 XML Example Requests

Example Request XML for 3-D Secure with a 3rd party MPI, for a registered

card

</Authentication>

<capturemethod>ecomm</capturemethod>

</TxnDetails>

<Card>

</Card>

<security_code>BwABCEYiBQAAAAAGViIFAAA

AAAA=</security_code>

<cardholder_registered>yes</cardholder_registered>

<transactionID>TbwiW8VLThG3TjDuI7KS5wAJ

CAI=</transactionID>

</Secure>

</CardTxn>

</Transaction>

</Request>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example Request XML for 3-D Secure with a 3rd party MPI, for a registered

card using the Pre-Registered Card service

</Authentication>

<capturemethod>ecomm</capturemethod>

</TxnDetails>

<card_details type="preregistered">

4900200053281123</card_details>

<security_code>BwABCEYiBQAAAAAGViIFAAA

AAAA=</security_code>

<cardholder_registered>yes</cardholder_registered>

<transactionID>TbwiW8VLThG3TjDuI7KS5wAJ

CAI=</transactionID>

</Secure>

</CardTxn>

</Transaction>

</Request>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example Request XML for 3-D Secure with a 3rd party MPI, for an un-

registered card

</Authentication>

<capturemethod>ecomm</capturemethod>

</TxnDetails>

<Card>

</Card>

<cardholder_registered>no</cardholder_registered>

</Secure>

</CardTxn>

</Transaction>

</Request>

Example Request XML for a card scheme which is not supported for the 3-D

Secure check

</Authentication>

<capturemethod>ecomm</capturemethod>

</TxnDetails>

<Card>

</Card>

</CardTxn>

</Transaction>

</Request>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.4.6.3 Schema Elements for Response

This service does not have any service-specific elements in the response. Please refer

to the Bank Card Service (section 2.2.1) and General Response Elements (section

2.1.1.3) for details of the generic elements returned for credit and debit card transaction.

2.4.7 Batched Fraud Screening

The Batched Fraud Screening Service is utilised by sending a normal Bank Card or

PayPal XML Request with additional information.

Details of XML Request and Response elements which are not specific to the Batched

Fraud Screening Service are available in sections 2.1 and 2.8.1

For Bank Card

The Batched Fraud Service check is carried out after authorisation for any pre and auth

transactions.

For Paypal

The Batched Fraud Service check is carried out after authorisation for any

do_express_checkout_payment , do_authorization and do_reference transactions. The

additional information should be presented within the do_express_checkout_payment or

do_reference transaction. When used with PayPal, some of the fields which would

normally be provided specifically for the fraud screening service should not be used as

they conflict with information which is available from PayPal or via fields provided by

the Merchant in the PayPalTxn element. These fields will be highlighted within this

document.

2.4.7.1 Schema Elements For Batched Screening Request

While all of the fields described within this document are optional, to ensure the

Merchant obtains the best results from the Batched Fraud Screening Service, certain

fields are recommended. These fields vary depending upon the sector the Merchant is

operating in:

 R – Retail and General

 H – Hotels

 T – Travel

 G - Gaming

The data is passed within the The3rdMan element in the schema:

 The3rdMan

o CustomerInformation – additional details about the customer, section

2.4.7.1.2

o DeliveryAddress – details the delivery address for the order, section

2.4.7.1.3

o BillingAddress – details of the Payer Billing Address, section 2.4.7.1.4

o AdditionalDeliveryAddress – to be used if the order is being delivered

to multiple locations, section 2.4.7.1.5

 DeliveryAddress – up to four additional delivery addresses,

section 2.4.7.1.3

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

o AccountInformation – contains details of any account the Payer may

have with the Merchant, section 2.4.7.1.6

 Address – as held on the Payers account with the Merchant,

section 2.4.7.1.7

 BankInformation – information related to any bank details which

may be held by the Merchant, section 2.4.7.1.8

 PreviousDetails – section 2.4.7.1.9

 PurchaseInformation – section 2.4.7.1.10

 UserDetails – section 2.4.7.1.11

o AltPayment – to be used if alternative payment methods have been used

in addition to the Card/PayPal used for the transaction, section 2.4.7.1.12

 BillingAddress – the Billing Address used for the alternative

payment, section 2.4.7.1.4

 Card – details of any card used for alternative payment, section

2.4.7.1.13

 CustomerInformation - section 2.4.7.1.2Response – the result of

the alternative payment, section 2.4.7.1.14

 Secure – details of the 3-D Secure check used for the alternative

payment, section 2.4.7.1.15

o OrderInformation – details about the order, section 2.4.7.1.16

 Products – a container element for each product, section

2.4.7.1.17

 Product – details about the individual products within the

order, section 2.4.7.1.18

o AirlineInformation – for Airline Merchants only,

section 2.4.7.1.19

o AdditionalInformation – extra information. To be used only by prior

agreement, section 2.4.7.1.20

2.4.7.1.1 The 3rdMan

Element Name:

The3rdMan

Position:

Request.Transaction.TxnDetails

Elements of The3rdMan

Element Name

Description

Values / Limitations

CustomerInformation

See section 2.4.7.1.2

DeliveryAddress

See section 2.4.7.1.3. N/A for PayPal – use

PayPalTxn.ShippingAddress instead

BillingAddress

See section 2.4.7.1.3. N/A for PayPal. To receive the full billing

address in the response and automatically send the biling

address to GateKeeper, you need to set the req_billing_address

element in the set_express_checkout message to 1.

AltPayment

See section 2.4.7.1.12

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

OrderInformation

See section 2.4.7.1.16

Example XML for The3rdMan complex elements

<BillingAddress...</BillingAddress>

</The3rdMan>

</The3rdMan>

2.4.7.1.2 CustomerInformation

This element contains details of the customer. It may be provided within two places in

the XML Request schema:

o The3rdMan

o CustomerInformation – the main customer information

o AltPayment – if a second (alternative) payment method is used, this element

provides the details specific to that transaction, see section 2.4.7.1.12

 CustomerInformation – for the alternative payment. May all be provided

for PayPal transactions.

Element Name:

CustomerInformation

Position:

Request.Transaction.TxnDetails.The3rdMan

Request.Transaction.TxnDetails.The3rdMan.AltPayment

Unless otherwise stated, all child elements may only be presented within the

The3rdMan.CustomerInformation position in the schema.

Elements of CustomerInformation

Element Name

Description

Values / Limitations

Sectors

alt_telephone

Alternative

Telephone

Number

Max 20 characters

International numbers: include

Country code, exclude access code

RHTG

customer_dob

Customer

Date Of

Birth

YYYY-MM-DD format

G

customer_reference

Customer

reference

Max 50 characters. N/A for PayPal.

Gateway will automatically use

TxnDetails.merchantreference

RHTG

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

delivery_forename

The first

name of the

person to

which the

order is

being

delivered

Max 50 characters. N/A for PayPal,

use

PayPalTxn.ShippingAddress.name.

R

delivery_phone_number

The phone

number of

the person

to which the

order is

being

delivered

Max 20 characters. N/A for PayPal,

use PayPalTxn.ShippingAddress.

telephone_number

-

delivery_surname

The

surname of

the person

to which the

order is

being

delivered

Max 50 characters.

N/A for PayPal, use

PayPalTxn.ShippingAddress.name.

R

delivery_title

The title of

the person

to which the

order is

being

delivered

Max 10 characters.

N/A for PayPal, use

PayPalTxn.ShippingAddress.name

R

driving_licence_number

Driving

Licence

Number

Max 30 characters. N/A for PayPal

-

email

Email

Address.

Max 50 characters

N/A for PayPal. Gateway will

automatically use the email returned

by PayPal

RHTG

first_purchase_date

First

Purchase

Date By

Customer

YYYY-MM-DD format

G

forename

Customer

first name

Max 50 characters. Gateway will

automatically use the firstname

returned by PayPal

RHTG

For AltPayment: Max 50 characters.

-

introduced_by

Customer

Ref Of

Introducing

Customer

Max 50 characters

-

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

ip_address

IP Address

Must be in "dotted-quad" notation

RHTG

order_number

Order

Number

Max 60 characters. N/A for PayPal,

Gateway will automatically use the

PayPal.invum.

RHTG

previous_purchases

See below

sales_channel

Type of sale

1 – Mail order

2 – Telephone order

3 – Internet

4 - Other

5 – In store

6 - Kiosk

7 – Mobile

N/A for PayPal transactions –

Gateway will automatically use 4

RHTG

surname

Customer

Surname

Max 50 characters. Gateway will

automatically use the lastname

returned by PayPal

RHTG

For AltPayment: Max 50 characters

-

telephone

Telephone

Number

A maximum of 20 characters.

International numbers: include

Country code, exclude access code.

RHTG

time_zone

Customer's

time zone

Customer's time zone. Should be of

the form "GMT", "GMT+1", "CET",

etc. Websites such as

http://wwp.greenwichmeantime.com/

list possible time zones.

-

title

Customer

Title (Mr,

Mrs etc)

Max 10 characters. Gateway will

automatically use the salutation

returned by PayPal

RHTG

For AltPayment: Max 10 characters

-

Attributes for Elements of CustomerInformation

Attribute Name

Attribute of element

Value / Limitations

Sector

count

previous_purchases

Number of previous

purchases. Numeric

G

amount

previous_purchases

Total value of previous

purchases. Max 15 numeric

including decimal point

G

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example XML for CustomerInformation complex elements

<customer_reference>CUSTREF000001</customer_reference>

<surname>Smith</surname>

<alt_telephone>0131 123 1234</alt_telephone>

<email>jsmith@devnull.co.uk</email>

<ip_address>192.168.0.1</ip_address>

<customer_dob>1980-03-12</customer_dob>

<first_purchase_date>2004-02-21</first_purchase_date>

<previous_purchases count="5" value="58.94"/>

<introduced_by>CUSTREF0004444</introduced_by>

<driving_license_number>SMITH0987654321</driving_license_number>

<time_zone>GMT</time_zone>

</CustomerInformation>

<surname>Smith</surname>

<delivery_forename>Alice</delivery_forename>

<delivery_surname>Smith</delivery_surname>

<delivery_phone_number/>

</CustomerInformation>

2.4.7.1.3 DeliveryAddress

This element contains the delivery details. It has two places within the Request

Schema:

o The3rdMan

o DeliveryAddress – for the main delivery address. Should not be provided for

PayPal transactions – use PayPalTxn.ShippingAddress instead.

o AdditionalDeliveryAddress – to be used if items are being shipped to multiple

addresses. May be provided for PayPal transactions. See section 2.4.7.1.5

 DeliveryAddress - Up to four additional delivery addresses can be

provided within the AdditionalDeliveryAddresses element. Each

DeliveryAddress element should have the “number” attribute set with

a value of 1 to 4. May be provided for PayPal transactions.

Element

Name:

DeliveryAddress

Position:

Request.Transaction.TxnDetails.The3rdMan

Request.Transaction.TxnDetails.The3rdMan.AdditionalDeliveryAddresses

Unless otherwise stated, all child elements may be presented within either position in

the schema.

The Sector recommendation only applies for The3rdMan.DeliveryAddress. This

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

recommendation does not apply for AdditionalDeliveryAddress elements.

Elements of DeliveryAddress

Element Name

Description

Values / Limitations

Sectors

(see

above)

title

For additional delivery addresses only. Max

10 characters

-

forename

For additional delivery addresses only. Max

50 characters

-

surname

For additional delivery addresses only. Max

50 characters

-

street_address_1

First

address line

Max 100 characters. For PayPal, use

ShippingAddress.street_address1

RHT

street_address_2

Second

address line

Max 100 characters. For PayPal, use

ShippingAddress.street_address2

RHT

city

City

Max 20 characters. For PayPal, use

ShippingAddress.city

RHT

county

County

Max 30 characters. For PayPal, use

ShippingAddress.region

RHT

postcode

Postcode

Max 9 characters (or 10 for Amex

transactions). For PayPal, use

ShippingAddress.postcode

RHT

country

Country

Code

Use the numeric country codes. For PayPal,

use ShippingAddress.country_code

RHT

Example XML for DeliveryAddress complex elements

<street_address_1>10 Stratford Road</street_address_1>

<street_address_2>Windsor</street_address_2>

<city>London</city>

<county>London</county>

</DeliveryAddress>

Example XML for DeliveryAddress complex elements

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

<surname>Jones</surname>

<street_address_1>10 Stratford Road</street_address_1>

<street_address_2>Windsor</street_address_2>

<city>London</city>

</DeliveryAddress>

<surname>Sutherland</surname>

<street_address_1>12 Stratford Road</street_address_1>

<street_address_2>Windsor</street_address_2>

<city>London</city>

</DeliveryAddress>

</AdditionalDeliveryAddresses>

Example XML for PayPalTxn ShippingAddress complex elements

</The3rdMan>

</TxnDetails>

<Items>

</Item>

</Items>

<street_address2>Fraud Street</street_address2>

<street_address1>Stark's Park</street_address1>

<country_code>GB</country_code>

<name>Mr Fraud Ster</name>

<city>London</city>

</ShippingAddress>

</PayPalTxn

</ Transaction>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.4.7.1.4 BillingAddress

The BillingAddress element has two places within the Request Schema:

o The3rdMan

o BillingAddress – for the main billing address. For PayPal transactions, you

must set the req_billing_address element in the set_express_checkout message

to 1. This will return the full billing address to the merchant in the response

from the get_express_checkout message and will automatically pass the

address to GateKeeper as the billing address. If you don’t set the element and

pass a shipping address, only the shipping address will be displayed in

GateKeeper and GateKeeper will assume it is both the billing and shipping

address. If you don’t pass a Shipping Address, PayPal will return the shipping

address as selected by the buyer on the PayPal page. If you wish to use the

billing address feature for PayPal, you will need to contact them and request

that the billing address request is enabled on your PayPal account. All elements

within BillingAddress are recommended for Merchants in all sectors, including

Gaming.

o AltPayment – to be used multiple payment methods are being used. May be

provided for PayPal transactions. See section 2.4.7.1.12.

o BillingAddress - if an Alternative Payment is being made, this element

contains the Billing Address details supplied with that payment. These

elements may all be provided with PayPal transactions.

Element Name:

BillingAddress

Position:

Request.Transaction.TxnDetails.The3rdMan

Request.Transaction.TxnDetails.The3rdMan.AltPayment

Elements of BillingAddress

Element Name

Description

Values / Limitations

Sectors

(see

above)

street_address_1

First

address line

Max 100 characters. For PayPal, use

ShippingAddress.street_address1

RHTG

For AltPayment: Max 100 characters.

-

street_address_2

Second

address line

Max 100 characters. For PayPal, use

ShippingAddress.street_address2

RHTG

For AltPayment: Max 100 characters.

-

city

City

Max 20 characters. For PayPal, use

ShippingAddress.city

RHTG

For AltPayment: Max 20 characters

-

county

County

Max 30 characters. For PayPal, use

ShippingAddress.region

RHTG

For AltPayment: Max 30 characters.

-

postcode

Postcode

Max 9 characters (or 10 for Amex

transactions). For PayPal, use

ShippingAddress.postcode

RHTG

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

For AltPayment: Max 9 characters (or 10

for Amex transactions).

-

country

Country

Code

Use the numeric country codes. For PayPal,

use ShippingAddress.country_code

RHTG

For AltPayment: Use the numeric country

codes.

-

Example XML for BillingAddress complex elements

<street_address_1>Mulberry House</street_address_1>

<street_address_2>15 Acacia Place</street_address_2>

<city>Edinburgh</city>

<county>Lothian</county>

</BillingAddress>

<street_address_1>10 Banana Gardens</street_address_1>

<city>Chepstowe</city>

<county>Lothian</county>

</BillingAddress>

2.4.7.1.5 AdditionalDeliveryAddresses

Up to four additional delivery addresses can be provided within the

AdditionalDeliveryAddresses element. Each DeliveryAddress element should have

the “number” attribute set with a value of 1 to 4.

Element Name:

AdditionalDevliveryAddresses

Position:

Request.Transaction.TxnDetails.The3rdMan

Elements of AdditionalDeliveryAddresses

Element Name

Description

Values / Limitations

DeliveryAddress

See section 2.4.7.1.3

2.4.7.1.6 AccountInformation

Element Name:

AccountInformation

Position:

Request.Transaction.TxnDetails.The3rdMan

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Elements of AccountInformation

Element Name

Description

Values / Limitations

Sector

Address

See section 2.4.7.1.7

G

BankInformation

See section 2.4.7.1.8

PreviousDetails

See section 2.4.7.1.9

PurchaseInformation

See section 2.4.7.1.10

UserDetails

See section 2.4.7.1.11

account_profit_loss

Format

NNNNNNNNNNNN.NN

account_status

Max 50 characters

alt_email

Max 50 characters.

authentication_method

KYC check

Max 30 characters.

balance

This field supports the

currency attribute. See

example below.

Format

NNNNNNNNNNNN.NN

browser_language

Max 30 characters

current_use

Max 30 characters

derived_language

Max 30 characters

discount_amount

Format

NNNNNNNNNNNN.NN

exposure_amount

Format

NNNNNNNNNNNN.NN

forename

Max 50 characters

G

fraud_status

Max 30 characters

games_most_played

Max 50 characters

loyalty

Max 50 characters

number_bonus_taken

Numeric

number_cards_registered

Numeric

numbers

Max 50 characters

open_date

Format YYYY-MM-DD

G

order_status

Max 30 characters

phone

Max 20 characters

previous_guest

Max 10 characters

previous_use

Max 30 characters

proposition_date

Format YYYY-MM-DD

rake

Max 30 characters

remaining

Max 30 characters

session_id

Max 100 characters

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

surname

Max 50 characters

G

title

Max 10 characters

G

total_account_withdrawal

Format

NNNNNNNNNNNN.NN

vendor_id

Max 30 characters

Example XML for AccountInformation complex elements

<forename>Steven</forename>

<surname>Benson</surname>

<open_date>2010-12-02</open_date>

<current_use>usage</current_use>

<previous_use>previous</previous_use>

<remaining>remaining</remaining>

<account_profit_loss>600.53</account_profit_loss>

<account_status>Active</account_status>

<alt_email>test@datacash.com</alt_email>

<authentication_method>POST</authentication_method>

<browser_language>EN</browser_language>

<derived_language>EN</derived_language>

<discount_amount>5.50</discount_amount>

<exposure_amount>2.50</exposure_amount>

<fraud_status>OK</fraud_status>

<games_most_played>Bejewelled</games_most_played>

<number_bonus_taken>5</number_bonus_taken>

<number_cards_registered>2</number_cards_registered>

<order_status>SENT</order_status>

<previous_guest>Yes</previous_guest>

<proposition_date>2010-11-15</proposition_date>

<session_id>1IHKD32</session_id>

<total_account_withdrawal>55.55</total_account_withdrawal>

<vendor_id>123</vendor_id>

</AccountInformation>

2.4.7.1.7 Address

The elements within the AccountInformation.Address element are recommended for

Gaming Merchants. They may all be provided with PayPal transactions.

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Element Name:

Address

Position:

Request.Transaction.TxnDetails.The3rdMan.AccountInformation

The child elements of Address are the same as DeliveryAddress. See section 2.4.7.1.3

for a description of these elements.

2.4.7.1.8 BankInformation

These elements may all be provided for PayPal transactions.

Element Name:

BankInformation

Position:

Request.Transaction.TxnDetails.The3rdMan.AccountInformation

Elements of BankInformation

Element Name

Description

Values / Limitations

Sectors

account_number

Max 30 characters

-

bank_address

Max 100 characters

-

bank_country

-

bank_name

Max 50 characters

-

customer_name

Max 50 characters

-

sort_code

Max 20 characters

-

Example XML for BankInformation element

<account_number>00000000</account_number>

<bank_address>12 Bank Street</bank_address>

<bank_country>Scotland</bank_country>

<bank_name>Santander</bank_name>

<customer_name>MR J K BANK</customer_name>

<sort_code>00-00-00</sort_code>

</BankInformation>

2.4.7.1.9 PreviousDetails

This container element holds up to five PreviousDetail elements. This element is

described in the table below. The “number” attribute should be provided on each

PreviousDetail element. Please see the example XML at the end of this section for

typical usage. These elements may all be provided for PayPal transactions.

Element Name:

PreviousDetails

Position:

Request.Transaction.TxnDetails.The3rdMan.AccountInformation

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Elements of PreviousDetail

Element

Name

Description

Values / Limitations

Sector

amount_in

Format NNNNNNNNNNNN.NN

-

amount_out

Format NNNNNNNNNNNN.NN

-

currency

ISO currency code standard

(ISO 4217)

(e.g. GBP, EUR, USD). Max 3

characters

-

date

YYYY-MM-DD HH:MM:SS

-

details

Max 100 characters

-

Example XML for PreviousDetails complex element

<amount_in>52.52</amount_in>

<amount_out>30.65</amount_out>

<details>Detail text</details>

</PreviousDetail>

<amount_in>552.63</amount_in>

<amount_out>125.25</amount_out>

<details>Detail text</details>

</PreviousDetail>

</PreviousDetails>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.4.7.1.10 PurchaseInformation

These elements may all be provided for PayPal transactions.

Element Name:

PurchaseInformation

Position:

Request.Transaction.TxnDetails.The3rdMan.AccountInformation

Elements of PurchaseInformation

Element Name

Description

Values / Limitations

Sector

avg

Format NNNNNNNNNNNN.NN

-

max

Format NNNNNNNNNNNN.NN

-

min

Format NNNNNNNNNNNN.NN

-

Example XML for PreviousDetails element

</PurchaseInformation>

</AccountInformation>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.4.7.1.11 UserDetails

These elements may all be provided for PayPal transactions.

Element Name:

UserDetails

Position:

Request.Transaction.TxnDetails.The3rdMan.AccountInformation

Elements of UserDetails

Element

Name

Description

Values /

Limitations

Sector

alias

Max 50

characters

-

id

Max 50

characters

G

profile

This field supports the “number” attribute which

allows the profile number to be specified (1-3).

See example below. For Gaming: "withdrawal" for

card withdrawals or "refund" for refunds

Max 100

characters

G

machine_id

Max 100

characters

G

Example XML for UserDetails element

<id>testid</id>

<profile number="1">profile1</profile>

<profile number="2">profile2</profile>

<profile number="3">profile3</profile>

<machine_id>xc334sv</machine_id>

</UserDetails>

</AccountInformation>

2.4.7.1.12 AltPayment

Details of any additional card payment the Card Holder has used in the transaction.

These elements may all be provided for PayPal transactions.

Element Name:

AltPayment

Position:

Request.Transaction.TxnDetails.The3rdMan

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Elements of AltPayment

Element Name

Description

Values / Limitations

Sector

BillingAddress

See section 2.4.7.1.4

-

Card

See section 2.4.7.1.13

-

CustomerInformation

See section 2.4.7.1.2

-

Response

See section 2.4.7.1.14

-

Secure

See section 2.4.7.1.15

-

amount

The transaction amount.

Format NNNNNNNNNNNN.NN

-

payment_method

-

Example XML for AltPayment element

</AltPayment>

2.4.7.1.13 Card

If an Alternative Payment is being made, this element contains the details of the card

supplied with that payment. These elements may all be provided with PayPal

transactions.

Element Name:

Card

Position:

Request.Transaction.TxnDetails.The3rdMan.AltPayment

Elements of Card

Element Name

Description

Values /

Limitations

alt_pan

The full card number. If you prefer

not to provide this you can provide

alt_bin, alt_last_4_digits and

alt_pan_sha1 instead.

Numeric. Max

length 19

alt_bin

First 8 digits of card number

Numeric. Max

length 8.

alt_last_4_digits

Last 4 digits of card number

Numeric. Max

length 4.

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

alt_pan_sha1

May be provided as an alternative to

the alt_pan field. Please contact

support for additional data to be

added to each card prior to SHA-1

hashing.

Upper case

Hex. Max

length 50

alt_expirydate

The card expiry date.

MMYY Format

alt_issuenumber_or_startdate

The card issue number or start_date

Numberic.

Max length 2

Example XML for Card element

<Card>

<alt_pan>0000000000000000</alt_pan>

<alt_expirydate>1012</alt_expirydate>

</Card>

</AltPayment>

2.4.7.1.14 Response

If an Alternative Payment is being made, this element contains the CV2/CSC, AVS and

Bank Response for that payment. These elements may all be provided for PayPal

transactions.

Element Name:

Response

Position:

Request.Transaction.TxnDetails.The3rdMan.AltPayment

Elements of Response

Element Name

Description

Values /

Limitations

auth_code

The bank authorisation code may be null

if not applicable and is represented as the

empty string. If the transaction type is

Update, bank authorisation code should

contain the status of the transaction

(either OK, Rejected, Chargeback or

Chargeback Fraud)

Max 30

characters

avs_address_response

0 = not given

1 = not

checked

2 = pass

4 = fail

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

avs_postcode_response

0 = not given

1 = not

checked

2 = pass

4 = fail

bank_response_code

The response code as received from the

bank

Numeric. Max

length 2

bank_response_message

The authorisation message as received

from the bank

Max 100

characters

cv2_response

Security code response

0 = not given

1 = not

checked

2 = pass

4 = fail

2.4.7.1.15 Secure

If an Alternative Payment is being made, this element contains the outcome of the 3-D

Secure check which may have been performed with that payment. These elements may

all be provided for PayPal transactions.

Element Name:

Secure

Position:

Request.Transaction.TxnDetails.The3rdMan.AltPayment

Elements of Response

Element Name

Description

Values / Limitations

eci

Transaction ECI Status.

Numeric. Max length 2

security_code

Visa transactions – CAVV

Mastercard transactions –AVV

Max 50 characters

2.4.7.1.16 OrderInformation

Element Name:

OrderInformation

Position:

Request.Transaction.TxnDetails.The3rdMan

Elements of OrderInformation

Element Name

Description

Values /

Limitations

Sector

Products

See section 2.4.7.1.17. N/A for PayPal – use

PayPalTxn.Items elements instead.

RHT

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

brand

The brand, if the sales channel

supports multiple brands

Max 30

characters

consumer_opt_in

Customer opt-in flag

0 – no

1 - yes

destination_location

Used for travel and ticketing. Route

codes may be used and defined as

required.

Max 50

characters

distribution_channel

The distribution channel

Max 30

characters

event_date

The date the event takes place, e.g.

date of travel, or date of show or

delivery date

YYYY-MM-DD

format

R

event_location

The event location

Max 50

characters

gift_message

Message entered on gift card

Max 100

characters

installation_requested

Whether goods are to be supplied

together with physical installation

Yes

No

loyalty_card_number

The loyalty card number, if held by

customer

Max 50

characters

operator_id

Max 30

characters

payment_method

route_via_location

Routing information

Max 50

characters

Example XML for OrderInformation complex elements

<distribution_channel>First Class Post</distribution_channel>

</OrderInformation>

XML Example for PayPalTxn Items complex elements

</The3rdMan>

</TxnDetails>

<Items>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

</Item>

</Items>

<street_address2>Fraud Street</street_address2>

<street_address1>Stark's Park</street_address1>

<country_code>GB</country_code>

<name>Mr Fraud Ster</name>

<city>London</city>

</ShippingAddress>

</PayPalTxn>

</Transaction>

2.4.7.1.17 Products

This element enables details of the items within the order to be passed. Should not be

provided for PayPal transaction – use PayPalTxn.Items elements instead.

Element Name:

Products

Position:

Request.Transaction.TxnDetails.The3rdMan.OrderInformation

Elements of Products

Element

Name

Description

Values / Limitations

Sector

Product

See section

2.4.7.1.18

One element for each distinct item

ordered

RHT

Attributes of Products

Attribute

name

Description

Values / Limitations

Sector

count

Total number of items

in the order

Must match the total of the items

specified in the Product.count fields.

RHT

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example XML for Products complex elements

</Products>

</Products>

Example XML for PayPal Items complex elements

</The3rdMan>

</TxnDetails>

<Items>

</Item>

</Items>

<street_address2>Fraud Street</street_address2>

<street_address1>Stark's Park</street_address1>

<country_code>GB</country_code>

<name>Mr Fraud Ster</name>

<city>London</city>

</ShippingAddress>

</PayPalTxn

</Transaction>

2.4.7.1.18 Product

This enables specific information about each distinct item within the order to be

presented. If the Products element is specified, at least one Product element must be

present.

This element enables details of the items within the order to be passed. Should not be

provided for PayPal transaction – use PayPalTxn.Items elements instead.

Element

Name:

Product

Position:

Request.Transaction.TxnDetails.The3rdMan.OrderInformation.Products

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Elements of Product

Element Name

Description

Values /

Limitations

Sector

AirlineInformation

See section 2.4.7.1.19

T

code

The product code for the item. For PayPal,

use Item.number.

Max 30

characters

RHT

price

The unit cost of a single item. For PayPal,

use Item.amount.

Numeric with

decimal point

RHT

prod_category

The product category, hotel name or

departure airport. There is no equivalent

for PayPal.

Max 50

characters

HT

prod_description

The product description. For travel use

departure date in DD MMM YYYY HH:MM

(e.g. 27 Feb 2014 17:50). For Hotel use

the check-in to check-out date (e.g. 24

Sep 2012 – 29 Sep 2012). For PayPal, use

Item.name

Max 100

characters

RHT

prod_id

The product ID, supports the type

attribute. See example below.

prod_risk

The level of risk associated with the

product. For Hotel, use the hotel city.

Max 50

characters

H

prod_type

The type of product. For Travel please

use 3 character IATA airport code (E.g.

CDG) for the departure airport. For Hotel,

please use the hotel country.

Max 50

characters

HT

quantity

The number of items of this product

ordered. For PayPal, use Item.quantity

Non-negative

integer

R

Example XML for Product complex element

<prod_id type="a">125</prod_id>

</Product>

<code>Double ensuite</code>

<prod_id type="a">125</prod_id>

</Product>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example XML for PayPalTxn Product complex elements

</The3rdMan>

</TxnDetails>

<Items>

</Item>

</Items>

<street_address2>Fraud Street</street_address2>

<street_address1>Stark's Park</street_address1>

<country_code>GB</country_code>

<name>Mr Fraud Ster</name>

<city>London</city>

</ShippingAddress>

</PayPalTxn

</Transaction>

2.4.7.1.19 AirlineInformation

This element cannot be provided for PayPal transactions

Element Name:

AirlineInformation

Position:

...The3rdMan.OrderInformation.Products.Product

Elements of AirlineInformation

Element Name

Description

Values /

Limitations

Sectors

flight_carrier

This should be a 2 character IATA

airline code.

Max 30

characters

dob

The passengers date of birth.

YYYY-MM-DD

fare_class

The fare class for the airline ticket.

Max 30

characters

flight_number

The flight number.

Max 30

characters

loyalty_indicator

The loyalty indicator for the passenger.

Max 30

characters

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

loyalty_number

The passenger loyalty number

Max 30

characters

nationality

The passenger nationality.

Max 30

characters

passport_or_ssn

The passengers passport or social

security number.

Max 50

characters

route_via

If multiple points then separate with -

(e.g. LHR-DUB). Do not supply

departure and destination points

Max 50

characters

T

Example XML for AirlineInformation elements

<flight_carrier>BA</flight_carrier>

<fare_class>Y</fare_class>

<flight_number>059</flight_number>

<loyalty_indicator>Y</loyalty_indicator>

<loyalty_number>9876</loyalty_number>

<passport_or_ssn>456789032</passport_or_ssn>

<route_via>LHR-DUB</route_via>

</AirlineInformation>

2.4.7.1.20 AdditionalInformation

The following additional elements can be used to send additional information to the

Batched Fraud Screening Service. The contents of these fields should be agreed with

the Batched Fraud Screening Service Provider before they are used. These elements

may all be provided for PayPal transactions.

Element Name:

AdditionalInformation

Position:

Request.Transaction.TxnDetails.The3rdMan

Elements of AdditionalInformation

Element

Name

Description

Values /

Limitations

count

Requires the “number” attribute to be set (see example).

Up to 3 separate counts can be provided (1-3).

Numeric

generic

Requires the “number” attribute to be set (see example).

Up to 17 generic fields can be provided (1-14 16-18).

Number 15 is reserved.

Max 100

characters

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example XML for AdditionalInformation elements

<generic number="1">Data as agreed</generic>

<generic number="2">Data as agreed</generic>

<generic number="3">Data as agreed</generic>

<generic number="4">Data as agreed</generic>

<generic number="5">Data as agreed</generic>

</AdditionalInformation>

2.4.7.2 Example PayPal Request

<alt_telephone>0987 654654</alt_telephone>

<ip_address>212.188.171.55</ip_address>

</CustomerInformation>

<surname>Fraudster</surname>

<alt_email>accept@datacash.com</alt_email>

</AccountInformation>

<event_date>2013-02-26</event_date>

</OrderInformation>

</The3rdMan>

</TxnDetails>

<Items>

</Item>

</Items>

<street_address2>FraudStreet</street_address2>

<street_address1>Stark's Park</street_address1>

<country_code>GB</country_code>

<name>Mr Fraud Ster</name>

<city>London</city>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

</ShippingAddress>

<method>do_express_checkout_payment</method>

<payment_action>order</payment_action>

</PayPalTxn>

</Transaction>

</Request>

2.4.7.3 Schema Elements for Batched XML Response

As the results of the service will be returned to you directly by the DCFS, there are no

additional XML Response elements for this service.

2.4.7.4 HTTPS Responses, Batched and Realtime

Responses for each transaction are posted back to your server on a transaction-by-

transaction basis. This is referred to as a callback. The server the callback response is

sent to is configured on your GateKeeper account.

This will be in the form of an HTTP POST which contains the following fields in XML or

as Name=Value fields separated by ‘&’.

The Merchant system must acknowledge the callback response within 1 second. This

will then enable the Batched Fraud Screening system to record a successful post. An

acknowledge mean can take the form of simply passing back the word “ok” or

“successful”

If the initial post does fail then the system will re-try 10 times with a 2 minute pause

in-between. If the system still doesn’t record a successful post after the 10th try, a

report will be generated to the support team to try a manual re-send at a later date.

If you wish to use HTTPS you must have a signed certificate to accept SSL

authentication.

Additional fields can be added to the existing response – please request these before

starting the implementation process or as soon into the process as possible.

2.4.7.5 Schema Elements for HTTPS Response, Batched and Realtime

Description

Format

(maximum

length)

aggregator_identifier

Unique identifier for an aggregator (for

example a PSP).

15

merchant_identifier

gatekeeper client ID

15

merchant_order_ref

The reference number the merchant

gives to the order

250

unique_id

3rd Man internal identifier. Used for

later calls such as the rules string

request.

Score

-999 to +999

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

recommendation

Recommendation

0=Release

1=Hold

2=Reject

9=Under

Investigation

2.4.7.5.1 Example Responses

2.4.7.5.1.1 XML Response

<aggregator_identifier/>

<merchant_identifier>5567</merchant_identifier>

<merchant_order_ref>12345</merchant_order_ref>

<t3m_id>333333333</t3m_id>

<message_digest></message_digest>

</RealTimeResponse>

2.4.7.5.1.2 Key Value Pair Response

merchant_identifier=30000&merchant_order_ref=12345&t3m_id=333333333&score

=0&recommendation=1&message_digest=

2.4.8 Realtime Fraud Screening

The Real Time Fraud Screening Service is utilised by sending a normal Bank Card or

PayPal XML Request with additional information.

Details of XML Request and Response elements which are not specific to the Real Time

Fraud Screening Service are available in section 2.1

Bank Card XML Requests

This documentation assumes the Bank Card has already been integrated and the

reader is familiar with it.

When subscribed to this service, additional information about the customer needs to be

presented with the transaction in order to trigger the screening. The Real Time Fraud

Service check is carried out after authorisation for any pre and auth transactions.

PayPal XML Requests

The Realtime Fraud Service check is carried out after authorisation for any

do_express_checkout_payment , do_authorization and do_reference transactions. The

additional information should be presented within the do_express_checkout_payment

or do_reference transaction.

When used with PayPal, certain fields that would normally be provided specifically for

the fraud screening service should not be used. These fields conflict with information

available from PayPal or via fields provided by the Merchant in the PayPalTxn element.

These conflicting fields are highlighted throughout the developer’s guide.

2.4.8.1 Schema Elements for Realtime Request

All of the elements outlined for Batched Fraud Screening in section 2.4.7.1 can be

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

used for Real Time Fraud Screening.

For Real Time Fraud Screening, there is one additional elements within the The3rdMan

element in the schema:

 The3rdMan

o RealTime – details for Real Time Callback, section 2.4.8.1.2

Please refer to section 2.4.7.1 for details of the other elements.

2.4.8.1.1 The3rdMan

To enable a transaction to be screened in Real Time, it must be flagged using the

realtime attribute.

Additional Elements of The3rdMan

Element Name

Description

Values / Limitations

RealTime

See section 2.4.8.1.2

Optional

Attributes for Elements of The3rdMan

Attribute

Name

Attribute of

Element

Values / Limitations

type

The3rdman

realtime

Example XML for The3rdMan complex elements

</The3rdMan>

2.4.8.1.2 RealTime

When sending a request in for Realtime Fraud Checking, an additional complex element

can be supplied. This element is only valid for:

 HPS - setup_full requests

 HCC – pre or auth requests

 Direct Submission – pre or auth requests

If presented, the information within it will be used instead of the default settings

configured on the Merchant Account.

Element Name:

Realtime

Position:

Request.Transaction.TxnDetails.The3rdMan

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Elements of Realtime

Element Name

Description

Values / Limitations

real_time_callback_format

The interface used to call the

realtime system. Defaults to

HTTP.

XML

real_time_callback

The callback URL used by

this transaction if applicable

Max length 200

real_time_callback_options

2

Example XML for Realtime complex elements

<real_time_callback_format>XML</real_time_callback_format>

<real_time_callback>http://www.callback.com/cgibin/

callback.cgi/</real_time_callback>

<real_time_callback_options>2</real_time_callback_options>

</Realtime>

2.4.8.2 Schema Elements for Realtime Response

2.4.8.2.1 AuthAttempts

This element provides details of a payment attempt made during the HPS session. This

element may be present in the XML Response to a query performed against a

setup_full.

Element Name:

AuthAttempts

Position:

Response.HpsTxn

Elements of AuthAttempt

Element Name

Description

Values / Limitations

Attempt

Will be present for each attempt the Card Holder has made. See

section 2.4.8.2.2.

Example XML for AuthAttempts element, with two attempts

2.4.8.2.2 Attempt

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

This element provides details of a payment attempt made during the HPS session. This

element may be present in the XML Response to a query performed against a

setup_full.

Element Name:

Attempt

Position:

Response.HpsTxn.AuthAttempts

Elements of Attempt

Element Name

Description

Values / Limitations

The3rdManRealtime

See section 2.4.8.2.3

Will only be present

if fraud screened

datacash_reference

The datacash_reference of the auth attempt

for the payment

dc_response

A numeric response code

reason

Text string expanding on the dc_response

Example XML for Attempt element

<datacash_reference>4100203001856542</datacash_reference>

<dc_response>7</dc_response>

<reason>DECLINED</reason>

</Attempt>

<datacash_reference>4400203001856550</datacash_reference>

<dc_response>179</dc_response>

<reason>3DS Payer failed Verification</reason>

</Attempt>

<datacash_reference>4700203001856619</datacash_reference>

<dc_response>1</dc_response>

<reason>ACCEPTED</reason>

</Attempt>

2.4.8.2.3 The 3rdManRealtime

This element has several positions within the schema, depending upon how the

response is generated:

 Response

o The3rdManRealtime – for responses to pre or auth XML requests

o QueryTxnResult

 The3rdManRealtime – for responses to query XML Requests which

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

are submitted against pre or auth transaction

o HpsTxn

 AuthAttempts

 Attempt

o The3rdManRealtime – for responses to query XML

Requests which are submitted against HPS

setup_full transactions

Element Name:

The3rdManRealtime

Position:

Response

Response.QueryTxnResult

Response.HpsTxn.AuthAttempts.Attempt

Elements of Attempt

Element Name

Description

Values / Limitations

score

The risk score

-999 to 999

recommendation

The action recommendation

0, 1, 2

(accept, refer,

reject)

error

If an error message is received in response

to the fraud check, this element will appear,

populated with the error message.

Example XML for The3rdManRealtime element

</The3rdManRealtime>

<error>UnknownCustomer</error>

</The3rdManRealtime>

2.4.8.2.4 QueryTxnResult

The QueryTxnResult complex element contains the retrieved details for the transaction

reference provided in the request. It will only be present in response to a query

transaction when querying a payment attempt. It will not be present when querying a

setup_full.

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Element Name:

QueryTxnResult

Position:

Response

Elements of QueryTxnResult

Element Name

Description

Card

See DPG_DataCash_Developers_Reference_v3.2.docx

The3rdManRealtime

See section 2.4.8.2.3

ThreeDSecure

See DPG_DataCash_Developers_Reference_v3.2.docx

acquirer

Acquiring bank

authcode

Bank authorisation response

datacash_reference

The unique Gateway reference for the transaction

environment

Processing environment

fulfill_date

Date of fulfillment. If empty, transaction has not yet been

fulfilled

fulfill_timestamp

UNIX timestamp value at the point of fulfillment. If empty,

the transaction has not yet been fulfilled.

cancel_date

Date of cancellation. Only present if the transaction was

cancelled.

cancel_timestamp

UNIX timestamp associated with the cancellation. Only

present if the transaction was cancelled.

merchant_reference

Merchant reference

reason

Response message. For a ‘duplicate transaction’ reason this

will also contain the datacash_reference of the original, which

may then be queried.

sent

Sent status – indicates whether the transaction was sent for

settlement

status

Numeric response code

transaction_date

Date of processing by gateway

transaction_timestamp

UNIX timestamp at the point the gateway processed the

transaction.

Example XML Response for QueryTxnResult complex elements

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

<ThreeDSecure>…</ThreeDSecure

<datacash_reference>4000900012345671</datacash_reference>

<environment>ecomm</environment>

<fulfill_date/>

<merchant_reference>123401</merchant_reference>

<reason>ACCEPTED</reason>

<transaction_date>2009-12-08 11:35:48</transaction_date>

</QueryTxnResult>

<datacash_reference>4000203001855883</datacash_reference>

<environment>ecomm</environment>

<fulfill_date>2011-07-20 15:38:20</fulfill_date>

<merchant_reference>14bab328bf6cd337a3</merchant_reference>

<reason>FULFILLED OK</reason>

<sent>Settled</sent>

<transaction_date>2011-07-19 14:51:35</transaction_date>

</QueryTxnResult>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.4.9 Fraud Only Transactions

A Fraud Only transaction type exists which allows information to be sent to the

DataCash Fraud Service (DCFS). As the name suggests, this transaction type exists

purely to send information to The DCFS, and will not result in any bank communication

/ authorisations taking place.

Element Name:

FraudOnlyTxn

Position:

Request.Transaction.FraudOnlyTxn

Elements of FraudOnlyTxn

Attribute name

Description

Values /

Limitations

Card

See section 2.4.7.1.13

response

See section 2.4.7.1.14

secure

See section 2.4.7.1.15

amount

The transaction amount.

Supports the

currency attribute.

tran_type

The payment transaction type associated with a

transaction

FraudOnly

Auth

Refund

Pre-auth

Deferred

Manual

Repeat

Repeat Deferred

Void

Cancel

Update

SuperSearch

Account

Registration

Account

Amendment

Buyer Registration

Seller Registration

KYC

Withdrawal

Amendment

Bank Response

Update

Other

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

alt_tran_type

The payment transaction type associated with a

transaction. If the transaction is being passed to

T3M to notify them of a

status (e.g. an order has been set to Rejected,

OK, Chargeback or Chargeback Fraud - a

transaction type of Update should be given)

FraudOnly

Auth

Refund

Pre-auth

Deferred

Manual

Repeat

Repeat Deferred

Void

Cancel

Update

SuperSearch

Account

Registration

Account

Amendment

Buyer Registration

Seller Registration

KYC

Withdrawal

Amendment

Bank Response

Update

Other

acquirer

The merchant acquirer’s name

Max 30

Example XML for FraudOnlyTxn element

...

</TxnDetails>

<tran_type>...</tran_type>

</FraudOnlyTxn>

</Transaction>

...

</Request>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.4.9.1 Card

Element Name:

Card

Position:

Request.Transaction.FraudOnlyTxn

Elements of Card

Element Name

Description

Values /

Limitations

Pan

The full card number. If you prefer

not to provide this you can provide

alt_bin, alt_last_4_digits and

alt_pan_sha1 instead.

Numeric. Max

length 19

Bin

First 8 digits of card number

Numeric. Max

length 8.

last_4_digits

Last 4 digits of card number

Numeric. Max

length 4.

pan_sha1

May be provided as an alternative

to the alt_pan field. Please contact

support for additional data to be

added to each card prior to SHA-1

hashing.

Upper case Hex.

Max length 50

expirydate

The card expiry date.

MMYY Format

issuenumber_or_startdate

The card issue number or

start_date

Issue Number

(Numeric 2)

Start Date

(MMYY)(Numeric

4)

Back to Contents

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.4.10 Risk Services Gateway (RSG)

Note that in order to use the RSG service, you must first be subscribed. If you require

additional information, please contact support. The RSG service cannot be used in

conjunction with any other fraud screening services that have been enabled for your

vTID, such as ReD or T3M.

This section of documentation assumes the reader is familiar with the Credit and Debit

Card Service, which is discussed in section

2.4.10.1 Service Overview

The RSG service provides the merchant with the ability to send their transaction

information to Risk Systems for fraud screening. It is also possible to send a number

of additional data fields containing information relevant to the transaction in order to

aid the screening process. These additional fields will be explained in detail throughout

the sections that follow.

2.4.10.2 Formulating a Request

The following sections explain the additional XML Elements that should be sent in the

request in order to use the RSG service.

2.4.10.2.1 Risk Element

The Risk element acts as a container for all additional transaction information which will

be passed to Risk Systems for fraud screening. This element can be presented to the

DPG within the TxnDetails Element of a transaction. Note that the Risk element can

only be provided when using the “pre”, “auth, or “refund” for MasterCard Payment Of

Winnings) methods. No other methods are supported.

The RSG supports fraud screening for Fire and Forget Continuous Authority and Historic

Continuous Authority. For transactions processed by the DPG and screened for fraud,

Fire and Forget Continuous Authority and Historic Continuous Authority are not

supported.

Element Name:

Risk

Position:

Request.Transaction.TxnDetails

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.4.10.2.2 Action Element

The Action container is defined as containing the service instruction, as well as all

relevant data containers in order to execute the actions related to the services

requested.

Element Name:

Action

Position:

Request.Transaction.TxnDetails.Risk

Attributes of Action

Attribute

name

Description

Values /

Limitations

Service

This will indicate the action(s) to be performed,

based on a set of predefined services.

Values can be:

 “1” for pre-authorisation fraud screening request

 “2” for post-authorisation fraud screening request

Must be either “1”

or “2”

2.4.10.2.3 Modes of Operation / Service Instruction

The DPG supports two modes of operation. Pre-Auth or Post-Auth fraud checking.

There is an important distinction in behaviour between these two modes which will be

explained below.

2.4.10.2.3.1 Post-Auth Fraud Checking Mode

In Post-Auth fraud checking mode, your transaction will be sent to the bank for

authorisation in the normal manner. Your transaction details including any additional

data fields are then sent to the Risk Services Gateway along with the bank response for

the authorisation. The transaction response XML returned to you will include the

screening response generated by the RSG.

You can examine this response and determine whether or not to continue with the

transaction. It is important to note that in Post-Auth fraud checking mode, the RSG

response acts as an aid in determining the best course of action for a particular

transaction. If you decide that a particular transaction is too risky based on the

information returned in the RSG response, the responsibility lies with you and/or your

systems to correctly follow up on any decisions (e.g. cancel the transaction by sending

a “cancel” request to the DPG).

2.4.10.2.3.2 Pre-Auth Fraud Checking Mode

In Pre-Auth fraud checking mode, the DPG takes an active role in managing potentially

risky transactions. Your transaction details, including any additional data fields will be

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

sent to the Risk Services Gateway before it is sent to the bank for authorisation.

Please note that pre-auth fraud checking is the only mode supported for

refund transactions.

The DPG will then analyse the response from the Risk Services Gateway and take 1 of

3 actions:

If the response from the RSG indicates that the transaction is of relatively low risk.

The DPG will continue as normal by sending the transaction to the bank for

authorisation. The RSG screening response will be present in the DPG response XML,

which you can store for your records.

If the response from the RSG indicates that the transaction is of a medium risk, the

DPG will mark the transaction for review and it will not be sent for authorisation at this

time. You will receive response code 1127 “RSG: review” in the DPG response XML

along with the screening response from the RSG. Transactions which have been

marked for review can be inspected manually by yourself and/or systems and

continued by sending a follow up “accept_review” transaction. The DPG will then

proceed to send an authorisation message to the bank in the usual manner. It should

be noted that this behaviour can be overridden by our support team on a merchants

request , preventing transactions being marked for review, thus requiring no manual

intervention.

If the RSG has indicated in it’s response that the transaction is extremely risky, the

DPG will outright reject the transaction and it will not be sent for authorisation. You

will receive response code 1126 “RSG: rejected” in the DPG response XML. It is

important to note that transactions which have been rejected with this response cannot

be continued.

2.4.10.2.4 Data Elements / Containers

Element Name(s):

MerchantConfiguration

CustomerDetails

VerificationDetails

Position:

Request.Transaction.TxnDetails.Risk.Action

Each message type has distinct data requirements needed to process the requested

message.

The current API supports 3 different types of request message structures for service

requests 1 and 2, these message structures depend on the industry which the

merchant has been setup for, i.e. gaming, telephony, e-wallet funding, retail or airline.

The gaming message structure is a basic, generic structure and also serves to

be used by telephony merchants and e-wallet providers where the funding of

the e-wallet is screened (from here on referred to as e-wallet funding).

The gaming model is the most generic and serves as a base model for retail and airline,

where additional data containers have been added that are retail and airline specific.

The data for screening service requests (“1” & “2”) must be supplied under the

following headings:

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

 Merchant Configured Details

 Verification Details

 Profile ID

 Customer Details

 Risk Details

 Personal Details

 Address Details

 Shipping Details **

 Payment Details

 Order Details

 Line Item Details **

 Journey Details ***

 Leg Items ***

 Passenger Items ***

Note: The data sections displayed in black above are the basic data

structures that should be used for all screening requests (service 1

and 2) for gaming, telephony, e-wallet funding, retail and airline,

unless otherwise indicated in the field descriptions, where it might

state that a field is only required for airline or retail.

**Note: These data sections must only be included when sending screening

requests for merchants that have been configured as retail

merchants (in addition to the basic data containers shown in black

above). Where multiple items are ordered, multiple item detail

headings should be sent, one for each distinct line item, as

appropriate.

***Note: These sections are airline industry specific message sections, and

only need to be included when sending a screening request for a

merchant that has been configured as an airline merchant (in

addition to the basic data containers shown in black above).

The following table describes all the data fields that can be used across all actions and

is applicable to incoming messages. The table also indicates the required data fields for

each incoming message.

Additionally, there is an indication of requirements around each field, where the

following criteria were applied:

Key

Description

•

Tag is required and needs to be populated with a value.

°

Tag or value is not required.

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.4.11 Pre & Post Authorisation Fraud Screening

Industry

Gaming

Telephony

Retail

Airline

Merchant Configuration

•

Field

Type

tag name: channel

definition: This reflects the manner

in which the customer transaction

has been captured. (This will be

used to distinguish the ‘ticketless’

on-line purchaser, from Moto taken

orders directly by a booking

system)

possible values:

P = Physical

M = Moto

W = Web

K = Kiosk

I = In-Store

S = Mail Order

O = Other

Char (1)

°

•

tag name: merchant_location

definition: This represents the

location of stores or outlets for a

reseller or airline.

Varchar (30)

°

•

Merchant Configuration

•

- Callback Configuration

°

Field

Type

tag name: callback_format

definition:

possible values:

HTTP

XML

SOAP

Varchar(4)

°

tag name: callback_url

definition: The callback URL used

by this transaction if applicable.

Varchar(200)

°

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

tag name: callback_options

definition: Use either/or both the

response and the

customer/aggregator registered

callback.

possible values:

0 = Immediate real-time callback

or

1 = Customer

2 = This callback (default)

3 = Both

4 = Polled when not available

or

combination of the two.

i.e. 02 would be realtime callback

and callback on backend response.

Char(2)

°

Verification Details

°

Field

Type

tag name: profile_id

definition: a GUID passed by the

merchant which will determine

which rules the verification service

provider will run when verifying

the transactions.

Varchar (40)

°

Customer Details

•

- Risk Details

•

Field

Type

tag name: account_number

definition: An account

number/unique ref number at the

Merchant associated with the

individual who is transacting with

the merchant.

Varchar (30)

•

°

•

tag name: email_address

definition: Customer's Email

Address.

Note: These are generally

associated with the individual who

is transacting with the merchant.

Varchar (64)

°

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

tag name: alt_email_address

definition: Alternative e-mail

address

Note: These are generally

associated with the individual who

is transacting with the merchant.

Varchar(64)

°

tag name: session_id

definition: a web server generated

session id.

Varchar (255)

°

tag name: ip_address

definition: Customer’s IP Address.

Varchar (15)

Format

255.255.255.2

°

tag name: user_id

definition: This is a Merchant

configurable data field typically

used to identify a customer

uniquely within the system,

regardless of the amount of

accounts that the customer has.

Varchar (36)

°

tag name: usermachine_id

definition: This is an ID used to

identify the computer (actual

hardware) uniquely within the

system, regardless of the amount

of customers or accounts that's

using the computer. Examples of

the User Machine ID are

Motherboard ID, Hard drive ID,

CPU ID, etc.

Varchar (255)

°

tag name: user_profile

definition: This is a customizable

field that may be used by the

merchant to supplement fraud

screening processes according to a

risk classification set by the

merchant.

(e.g. VIP flag, Indication whether

the transaction is part of a

promotion, a confidence level

around the identity of the

customer, etc.)

Varchar (20)

°

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

tag name: user_profile_2

definition: This is a customizable

field that may be used by the

merchant to supplement fraud

screening processes according to a

risk classification set by the

merchant.

(See above examples.)

Varchar (20)

°

tag name: user_profile_3

definition: This is a customizable

field that may be used by the

merchant to supplement fraud

screening processes according to a

risk classification set by the

merchant. (See above examples.)

Varchar (20)

°

tag name:

register_consumer_watch

definition: Register the consumer

associated with this transaction for

the consumer product.

possible values:

Y = Yes

N = No

Char(1)

°

tag name: browser_language

definition: Language setting of the

respective browser

Varchar(30)

°

tag name: execution_order

definition: Execution order for

fraud screening and verification

requests.

Possible values:

1 = screening only

2 = screening, then verification

3 = verification, then screening

(blank) = default execution order

for merchant

Int

°

Customer Details

•

- Personal Details

•

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Note - these are generally associated with the individual who consents to the

merchant’s customer terms & conditions and is transacting with the merchant.

Field

Type

tag name: first_name

definition: Customer’s name.

Note: The first_name field and

the surname field combined

should not exceed 32 characters.

Varchar (32)

•

tag name: surname

definition: Customer’s surname

Note: The first_name field and the

surname field combined should not

exceed 32 characters.

Varchar (32)

•

tag name: telephone

definition: Customer's telephone

number.

Varchar (20)

•

°

•

tag name: telephone_2

definition: Alternative telephone

number.

Varchar (20)

°

tag name: date_of_birth

definition: Customer’s date of

birth.

Datetime

Format yyyy-

mm-dd

°

tag name: nationality

definition: Customer's nationality,

represented by a 2-character code.

Please reference Appendix 11 for

further details.

Note: This is generally used in

respect of certain 3rd party

electronic ID verification services.

Char (2)

°

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

tag name: id_number

definition: Passport, ID, or other

verification document number.

Note: This is generally used in

respect of certain 3rd party

electronic ID verification services.

Varchar (40)

°

tag name: id_type

definition: A code that defines the

type of verification document

supplied.

possible values:

1 = Passport

2 = Personal ID

3 = Identity Card

4 = Driver’s License

8 = Travel Document

12 = Residence Permit

13 = Identity Certificate

16 = Registro Federal de

Contribuyentes

17 = Credential de Elector

Note: This is generally used in

respect of certain 3rd party

electronic ID verification services.

Int

°

tag name: ssn

definition: Last 4 digits of the SSN

number (US residents).

Note: This is generally used in

respect of certain 3rd party

electronic ID verification services.

Int

°

Customer Details

•

- Address Details

□

Note - these are generally associated with the individual who consents to the

merchant’s customer terms & conditions and is transacting with the merchant.

Field

Type

tag name: address_line1

definition: Customer’s address line

1.

Varchar (60)

•

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

tag name: address_line2

definition: Customer’s address line

2.

Varchar (60)

°

tag name: city

definition: Customer's City.

Varchar (25)

•

tag name: state_province

definition: Customer's

State/Province/District/ County.

Note: For USA and Ireland, Canada

and the UK, a 2-character code

needs to be supplied where the

Merchant requests verification

services in these countries. Please

reference Appendix 25.

Varchar (25)

°

tag name: country

definition: Customer's Country.

Note: This is a 2-character code

that needs to be supplied. Please

reference Appendix 11 for further

details.

Char (2)

•

°

tag name: zip_code

definition: Customer's Zip/Postal

code.

Varchar (10)

°

Customer Details

•

- Shipping Details

•

Note - these are generally associated with the dispatch of goods/services to intended

recipients.

Field

Type

tag name: title

definition: Recipient’s title

Varchar(10)

°

tag name: first_name

definition: Recipient’s first name.

Varchar (50)

°

tag name: surname

definition: Recipient’s surname.

Varchar (50)

°

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

tag name: address_line1

definition: Customer’s shipping

address line 1.

Varchar (60)

°

tag name: address_line2

definition: Customer’s shipping

address line 2.

Varchar (60)

°

tag name: city

definition: Customer’s shipping

city.

Varchar (25)

°

tag name: state_province

definition: Customer’s shipping

state or province.

Note: For USA, Ireland, Canada

and UK a 2-character code can be

supplied for verification purposes,

if additional verification checks are

required on billing address

(verification checks use primary

address details). Please reference

Appendix 25.

Varchar (25)

°

tag name: country

definition: Customer’s shipping

country.

Note: This is a 2-character code

that needs to be supplied. Please

reference Appendix 11 for further

details.

Char (2)

°

tag name: zip_code

definition: Customer’s shipping zip

code.

Varchar (10)

°

tag name: delivery_date

definition: Delivery date

Datetime

Format yyyy-

mm-dd

°

tag name: delivery_method

definition: Method of delivery

Varchar(30)

°

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

tag name:

installation_requested

definition: Indicates whether

goods are supplied together with a

physical installation.

possible values:

Y = Yes

N = No

Char(1)

°

Customer Details

•

- Payment Details

•

Field

Type

tag name:

transaction_type

definition: The payment

transaction type associated with a

transaction.

possible values:

Auth

Blank

Instant

Other

Varchar(20)

°

tag name: payment_method

definition: This is the mechanism

with which the client chooses to

purchase.

Note: For the screening of non-

card based payments, please

consult with DataCash as new

options will be added.

possible values:

please refer to Appendix 26

Payment Method Codes.

Varchar (2)

•

Customer Details

•

- Payment Details

•

- - Wallet Details

•

Note – this is for any funding account details other than cards.

Field

Type

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

tag name: acquirer_number

definition: Customer’s electronic

wallet account number or bank

account used for purchasing. The

value will be associated with the

payment_method used for the

transaction.

Varchar (60)

°

Customer Details

•

- Order Details

•

Field

Type

tag name: discount_value

definition: The discount amount

relevant to the transaction in the

smallest unit of the currency i.e.

cents or pence, e.g. US$100.01 =

10001 or ¥100 = 100.

Int

°

tag name: time_zone

definition: Local time zone, GMT

+/- hours (GMT = 0)

example: +01:00

Time format

(+/-hh:mm)

°

tag name: proposition_date

definition: Similar to a picking

date, can be used to prioritise the

referral queue so that delivery

deadlines are met.

Datetime

Format yyyy-

mm-dd

°

Customer Details

•

- Order Details

•

- - Billing Details

•

Note - these are associated with the owner of the card number or acquirer number

used to fund the respective purchase.

Field

Type

tag name: name

definition: The billing account

owner’s name associated with the

transaction.

Varchar (50)

°

tag name: address_line1

definition: The billing account

owner’s billing address line 1.

Varchar (60)

°

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

tag name: address_line2

definition: The billing account

owner’s billing address line 2.

Varchar (60)

°

tag name: city

definition: The billing account

owner’s billing city.

Varchar (25)

°

tag name: state_province

definition: The billing account

owner’s state or province.

Note: For USA, Ireland, Canada

and UK a 2-character code can be

supplied for verification purposes,

if additional verification checks are

required on billing (verification

checks use primary address

details). Please reference Appendix

25.

Varchar (25)

°

tag name: country

definition: The billing account

owner’s billing country.

Note: This is a 2-character code

that needs to be supplied. Please

reference Appendix 11 for further

details.

Char (2)

•

°

•

tag name: zip_code

definition: The billing account

owner’s billing zip code

Varchar (10)

°

Customer Details

•

- Order Details

•

- - Line Items

°

Note - these are generally associated with shopping cart details within the retail sector

where it is important to screen the items being purchased.

- - - Item

•

Field

Type

tag name: product_code

definition: Line item product code.

Note: If any one of the Line Item

fields is submitted, then all Line

Item fields become mandatory.

Varchar (50)

°

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

tag name:

product_description

definition: Line item description.

Varchar (50)

°

tag name: product_category

definition: Type of item, as

classified by the Merchant.

Varchar (80)

°

tag name: product_risk

definition: Indication of how

susceptible the product is to fraud.

possible values:

High

Medium

Low

Varchar(50)

°

tag name: order_quantity

definition: Number of items

ordered.

Note: If any one of the Line Item

fields is submitted, then all Line

Item fields become mandatory.

Int

°

tag name: unit_price

definition: The amount of the

transaction in the smallest unit of

the currency i.e. cents or pence,

e.g. US$100.01 = 10001 or ¥100

= 100.

Int

°

Customer Details

•

- Airline Details

•

- - Journey

•

Field

Type

tag name: ticket_number

definition: the ticket number

assigned to the journey.

Varchar (30)

°

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

tag name: payer_travelling

definition: an indication whether

the person paying is also travelling

on the ticket.

possible values:

Y = Yes

N = No

Char(1)

°

tag name: pnr

definition: Passenger Name Record

Varchar(10)

°

Customer Details

•

- Airline Details

•

- - Journey

•

Note - A journey is a connected series of one or more legs that are sold as a unit. A

one-way trip consists of a single leg. A round trip consists of two legs (outbound and

return). There may be more than two legs. Legs should be presented in the sequence

of travel, starting with the first leg of the journey.

- - - Legs

•

- - - - Leg

•

Field

Type

tag name: depart_airport

definition: Departure point airport.

Note: this is a 3 character code

IATA airport code that needs to be

supplied. http://www.iata.org/

Char (3)

•

tag name: depart_country

definition: Departure Country.

Note: This is a 2-character code

that needs to be supplied. Please

reference Appendix 11 for further

details.

Char (2)

°

tag name: depart_datetime

definition: Local Date & time of

scheduled departure.

Datetime

Format yyyy-

mm-dd

hh:mm:ss

•

tag name:

depart_airport_timezone

definition: Local time zone, GMT

+/- hours.

example: +01:00

Time format

(+/- hh:mm)

•

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

tag name: arrival_airport

definition: Arrival point.

Note: this is a 3 character code

IATA airport code that needs to be

supplied. For more information on

these codes visit

http://www.iata.org/

Char (3)

•

tag name: carrier

definition: Flight carrier for the

journey.

Note: this is a 2 character IATA

airline code that needs to be

supplied. For more information on

these codes visit

http://www.iata.org/

Char (2)

•

tag name: flight_number

definition: Flight number for the

journey.

(Data Capture – not fed into rules

engine)

Char (4)

•

tag name: fare_basiscode

definition: The fare basis code

provides information about the

specific fare in addition to the class

of service required for booking.

example: HL7LNR

Char (10)

•

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

tag name: fare_class

definition: Class of flight.

example:

F (=Unrestricted First Class)

FR (=Restricted First Class)

F (=Unrestricted Business Class)

CR (=Restricted Business Class)

Y (=Unrestricted Coach/Economy

Class)

YD (=Restricted Coach/Economy

Class)

(Data Capture – not fed into rules

engine)

Char (3)

•

tag name: base_fare

definition: The amount of the

transaction, excluding taxes and

fees, in the smallest unit of the

currency i.e. cents or pence.

(e.g. US$100.01 = 10001 OR

¥100 = 100).

(Data Capture – not fed into rules

engine. For reporting/review

purposes. Fraud screening and

related velocity calculations will

initially be based upon the total

value of the purchase transaction)

Int

°

tag name: currency_code

definition: This is the ISO numeric

code for the currency in which the

transaction should be processed.

See Appendix 10 for applicable

codes.

This is mandatory if a base_fare

is supplied.

(Data Capture – not fed into rules

engine. For reporting/review

purposes)

Char (3)

°

Customer Details

•

- Airline Details

•

- - Journey

•

- - - Passengers

•

- - - - Passenger

•

Field

Type

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

tag name: first_name

definition: Passenger’s name.

Note: The first-name field and the

surname field combined should not

exceed 32 characters. If any

passenger details are submitted,

then the first-name field become

Mandatory.

Varchar (32)

°

tag name: surname

definition: Passenger’s surname

Note: The first-name field and the

surname field combined should not

exceed 32 characters. If any

passenger details are submitted,

then the surname field become

Mandatory.

Varchar (32)

°

tag name: passenger_type

definition: The type of passenger

travelling, e.g. Adult, Child, Infant.

possible values:

A = Adult

C = Child

I = Infant

Char (1)

•

tag name: nationality

definition Customer's Nationality,

represented by a 2-character code.

Please reference Appendix 11 for

further details.

Char (2)

°

tag name: id_number

definition: Passport, ID, or other

verification document number.

Note: fraud screening block lists

may include a composite

nationality and id_number value.

Varchar (40)

°

tag name: loyalty_number

definition: Passenger’s loyalty

scheme number.

Varchar (20)

°

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

tag name: loyalty_type

definition: Passenger’s loyalty

scheme

(e.g. .... Voyager, )

Varchar (20)

°

tag name: loyalty_tier

definition: Passenger’s loyalty

scheme status or level

possible values:

1 = highest tier level e.g. platinum

2 = second highest tier level e.g.

gold

3 = third highest tier level e.g.

silver…,etc

Int

•

2.4.11.1.1 Example XML Request

The XML below serves as an example of sending all possible information fields to be

risk screened.

Example XML Element Risk for an RSG Transaction

<Risk>

<merchant_location>Edinburgh</merchant_location>

</MerchantConfiguration>

<account_number>24972343</account_number>

<email_address>email@example.com</email_address>

<session_id>FJW35798FHI</session_id>

<ip_address>127.0.0.1</ip_address>

<user_id>333</user_id>

<usermachine_id>38744</usermachine_id>

<user_profile>profile</user_profile>

<user_profile_2>profile1</user_profile_2>

<user_profile_3>profile2</user_profile_3>

</RiskDetails>

<first_name>Steven</first_name>

<surname>Partridge</surname>

<telephone_2>032749874738</telephone_2>

<date_of_birth>1978-03-10</date_of_birth>

<id_number>43579</id_number>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

<id_type>1</id_type>

</PersonalDetails>

<address_line1>123 Brick Lane</address_line1>

<address_line2>South Brickford</address_line2>

<city>Livingston</city>

<state_province>West Lothian</state_province>

<zip_code>LI43 0SA</zip_code>

</AddressDetails>

<address_line1>123 Brick Lane</address_line1>

<address_line2>Brickford South</address_line2>

<city>Livingston</city>

<state_province>West Lothian</state_province>

<zip_code>EH7 8EA</zip_code>

</ShippingDetails>

<payment_method>CC</payment_method>

<acquirer_number>458</acquirer_number>

</WalletDetails>

</PaymentDetails>

<name>Mr Steven Partridge</name>

<address_line1>34 Fake Street</address_line1>

<address_line2>District 7</address_line2>

<city>Terminalville</city>

<state_province>Western Docklands</state_province>

<zip_code>347595</zip_code>

</BillingDetails>

<Item>

<product_code>PRN383</product_code>

<product_description>Pair of socks</product_description>

<product_category>Clothing</product_category>

<order_quantity>11</order_quantity>

<unit_price>411</unit_price>

</Item>

<Item>

<product_code>FHEUF</product_code>

<product_description>Model dog</product_description>

<product_category>Keepsake</product_category>

<order_quantity>2</order_quantity>

<unit_price>5.32</unit_price>

</Item>

</LineItems>

</OrderDetails>

<ticket_number>478935793</ticket_number>

<Legs>

<Leg>

<depart_airport>EDI</depart_airport>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

<depart_country>UK</depart_country>

<depart_datetime>2030-10-01 13:23:11</depart_datetime>

<depart_airport_timezone>+00:00</depart_airport_timezone>

<arrival_airport>WRO</arrival_airport>

<flight_number>508</flight_number>

<fare_basiscode>LWC</fare_basiscode>

<fare_class>Y</fare_class>

<base_fare>3000</base_fare>

<currency_code>GBP</currency_code>

</Leg>

<Leg>

<depart_airport>JHB</depart_airport>

<depart_country>SA</depart_country>

<depart_datetime>2030-08-01 13:23:11</depart_datetime>

<depart_airport_timezone>+01:00</depart_airport_timezone>

<arrival_airport>LHW</arrival_airport>

<carrier>SuperJet</carrier>

<flight_number>404</flight_number>

<fare_basiscode>FR</fare_basiscode>

<fare_class>Buisiness</fare_class>

<base_fare>7844.00</base_fare>

<currency_code>ZAR</currency_code>

</Leg>

</Legs>

<first_name>Daniel</first_name>

<surname>Moore</surname>

<passenger_type>A</passenger_type>

<id_number>666</id_number>

<loyalty_number>32974</loyalty_number>

<loyalty_type>Super Loyal</loyalty_type>

<loyalty_tier>3</loyalty_tier>

</Passenger>

<first_name>Fed</first_name>

<surname>McFed</surname>

<passenger_type>A</passenger_type>

<id_number>574</id_number>

<loyalty_number>433</loyalty_number>

<loyalty_type>Disloyal</loyalty_type>

<loyalty_tier>1</loyalty_tier>

</Passenger>

</Passengers>

</Journey>

</AirlineDetails>

</CustomerDetails>

</Action>

</Risk>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.4.11.2 XML Response

The following sections detail the response returned from the DPG and RSG respectively.

2.4.11.2.1 Pre-Authorisation Fraud Screening RSG Response

On receiving a pre-auth fraud screening request message, the Risk Services Gateway

will send a response message back to the Merchant. The following table describes the

return values of the response message:

Field Name

Description

Screening Response

transaction_id

This is the DataCash reference of the original transaction

which was sent for risk screening.

response_code

This is a status/return code. It indicates whether the

transaction was received and/or the result of the screening

process.

00 – reflecting that the transaction was accepted by Risk

Services

01 – reflecting that the transaction was rejected by Risk

Services

02 – reflecting that the transaction was flagged for review by

Risk Services

For the full set of response codes, refer to Appendix 24

response_message

This is a text field used to give a short text description of the

status/return code.

Transaction Approved

Transaction not Approved

Transaction marked for Review

For the full set of response codes, refer to Appendix 24

cpi_value

This is a Risk assessment score for a customer, available

within select industries. Values can be 1-5 and will be based

on definition discussed between the Merchant and DataCash.

Additional Messages

message

This field will display any additional relevant response

information. There can be more than one message tag for

this purpose.

Verification Response

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

response_code

This is a status/return code. It indicates whether the

transaction was received and/or the result of the verification

process.

00 – reflecting that the transaction was approved

01 – reflecting that the transaction was not approved

02 – reflecting that the transaction was marked for review

response_message

This is a text field used to give a short text description of the

status/return code.

Transaction Approved

Transaction not Approved

Transaction marked for Review

response_reference

This is the reference from the verification service provider.

Additional Messages

message

This field will display any additional relevant response

information. There can be more than one message tag for

this purpose.

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.4.11.2.2 Example Pre-Auth Response XML

Example XML Response for an RSG transaction.

<card_scheme>VISA</card_scheme>

</CardTxn>

<Risk>

<action_response>

<bankresult_response>

<cpi_value>-1</cpi_value>

<response_code>00</response_code>

<response_message>Successful</response_message>

<transaction_id>3200900010000275</transaction_id>

</bankresult_response>

<screening_response>

<cpi_value>0</cpi_value>

<response_code>00</response_code>

<response_message>Transaction Approved</response_message>

<transaction_id>3200900010000275</transaction_id>

</screening_response>

</action_response>

</Risk>

<datacash_reference>3200900010000275</datacash_reference>

<reason>ACCEPTED</reason>

</Response>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.4.11.2.3 Post- Authorisation Fraud Screening RSG Response

On receiving a post-auth fraud screening request message, the Risk Services Gateway

will send a response message back to the Merchant. The following table describes the

return values of the response message:

Field Name

Description

Screening Response

transaction_id

This is the DataCash reference of the original transaction which

was sent for risk screening.

response_code

This is a status/return code. It indicates whether the transaction

was received and/or the result of the screening process.

00 – reflecting that the transaction was accepted by Risk Services

01 – reflecting that the transaction was rejected by Risk Services

02 – reflecting that the transaction was flagged for review by Risk

Services

For the full set of response codes, refer to Appendix 24

response_message

This is a text field used to give a short text description of the

status/return code.

Transaction Approved

Transaction not Approved

Transaction marked for Review

cpi_value

This is a Risk assessment score for a customer, available within

select industries. Values can be 1-5 and will be based on

definition discussed between the Merchant and DataCash.

Additional Messages

message

This field will display any additional relevant response

information. There can be more than one message tag for this

purpose.

Bank Result Response

response_code

This is a status/return code. It indicates whether the transaction

was received and/or the result of the screening process.

00 – reflecting that the bank result was updated successfully

01 – reflecting that the bank result was not updated successfully

response_message

This is a text field used to give a short text description of the

status/return code.

Successful

Unsuccessful

Additional Messages

message

This field will display any additional relevant response

information. There can be more than one message tag for this

purpose.

Verification Response

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

response_code

This is a status/return code. It indicates whether the transaction

was received and/or the result of the verification process.

00 – reflecting that the transaction was approved

01 – reflecting that the transaction was not approved

02 – reflecting that the transaction was marked for review

response_message

This is a text field used to give a short text description of the

status/return code.

Transaction Approved

Transaction not Approved

Transaction marked for Review

response_referen

ce

This is the reference from the verification service provider.

Additional Messages

message

This field will display any additional relevant response

information. There can be more than one message tag for this

purpose.

2.4.11.2.4 Accepting a Transaction Marked for Review

If you have sent a Pre-Authorisation service instruction and receive response code

1127 “RSG: review”, you can accept/continue this transaction by sending a follow up

“accept_review” transaction.

A typical response indicating a transaction has been marked for review is shown below:

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example XML Response for an RSG transaction which has been marked for

review.

<card_scheme>VISA</card_scheme>

</CardTxn>

<Risk>

<action_response>

<screening_response>

<cpi_value>0</cpi_value>

<response_code>02</response_code>

<response_message>Transaction marked for

Review</response_message>

<transaction_id>3200900010000124</transaction_id>

</screening_response>

</action_response>

</Risk>

<datacash_reference>3200900010000124</datacash_reference>

<information>Transaction marked for review by the RSG</information>

<reason>Transaction marked for review</reason>

</Response>

Example XML Request for an “accept_fraud” transaction.

</Authentication>

<method>accept_review</method>

</HistoricTxn>

</Transaction>

</Request>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.4.12 HTTPS Responses

Responses for each transaction are posted back to your server on a transaction-by-

transaction basis. This is referred to as a callback.

This will be in the form of an HTTP POST which contains the following fields in XML or

as Name=Value fields separated by ‘&’.

CallBack response will look as follows:

2.4.12.1 XML Response

<?xml version="1.0" ?>

<aggregator_identifier/>

<merchant_identifier>5567</merchant_identifier>

<merchant_order_ref>12345</merchant_order_ref>

<t3m_id>333333333</t3m_id>

<message_digest></message_digest>

</RealTimeResponse>

2.4.12.2 Key Value Pair Response

merchant_identifier=30000&merchant_order_ref=12345&t3m_id=333333333&score

=0&recommendation=1&message_digest=

2.4.12.3 Considerations

Description

Format (maximum

length)

aggregator_identifi

er

Unique identifier for an aggregator

(for example a PSP).

15

merchant_identifier

gatekeeper client ID

15

merchant_order_ref

The reference number the merchant

gives to the order

250

t3m_id

3rd Man internal identifier. Used for

later calls such as the rules string

request.

Score

-999 to +999

Recommendation

0=Release

1=Hold

2=Reject

9=Under Investigation

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Customer systems must acknowledge the callback response within 1 second. This will

then enable Datacash Fraud Systems to record a successful post. An acknowledge

mean can take the form of simply passing back the word “ok” or “successful”

If the initial post does fail then the system will re-try 10 times with a 2 minute pause

in-between. If the system still doesn’t record a successful post after the 10th try, a

report will be generated to the support team to try a manual re-send at a later date.

If you wish to use HTTPS you must have a signed certificate to accept SSL

authentication.

Additional fields can be added to the existing response – please request these before

starting the implementation process or as soon into the process as possible.

2.4.12.4 Additional Information

A full list of RSG response codes can be found in the appendix.

Back to Contents

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.5 BACS SERVICE

2.5.1 Direct Debit

Additional non-technical information about this Service is available on the website:

http://www.datacash.com/gettingproducts.php?id=Direct-Credit-Direct-Credit-

Overview

2.5.1.1 Schema Elements for Request

In this section the required fields for each stage in the Direct Debit process will be

presented, along with example XML for those fields. The XML is presented in italics for

those fields that are not required for all situations. In the XML examples where a field

has been highlighted fields, this indicates a situation in which other values can be

presented in its place – for example setup in place of presetup.

Optional fields for each transaction type are indicated with an O, required fields with an

R.

Please refer to the website for definitions of the transaction types and examples of

when you may wish to implement them.

The Initial Setup –Setup and Presetup

The setup and presetup methods both require the same fields to be populated.

This information is passed in two distinct places in the schema:

 Request

o Authentication – section 2.1.1.2

o Transaction

 DirectDebitTxn – contains all the information about the customer

and the method, section 2.5.1.1.1

 TxnDetails - section 2.5.1.1.2

Updating Setups – Confirm and Revoke

If you are using the two stage model, you will need to confirm the presetup in order

to activate it. Once all payments on a DDI have been completed, the DDI can be

cancelled by submitting a revoke request.

Both of these transaction types update the existing DDI and the information is

passed in two distinct schema paths:

 Request

o Authentication – section 2.1.1.2

o Transaction

 HistoricTxn – the datacash_reference of the original setup or

presetup plus the method, section 2.5.1.1.3

 TxnDetails - contains the reference number, section 2.5.1.1.2

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Taking Payments

Once a DDI is active, a drawdown can then be processed against it. A drawdown may

also be cancelled, if required, using a cancel.

 Request

o Authentication – section 2.1.1.2

o Transaction

 HistoricTxn – the datacash_reference of the original

transaction, plus the method and for drawdowns (optionally) the

due date and transaction code, section 2.5.1.1.3

 TxnDetails - for drawdowns only, contains the reference number

and the amount, section 2.5.1.1.2

2.5.1.1.1 DirectDebitTxn

The DirectDebitTxn element contains the details of the customer and their bank

account. It also contains the method which allows you to choose the one stage setup

or two stage presetup models. Each element is required for both models.

Element Name:

DirectDebitTxn

Position(s)

Request.Transaction

Elements of DirectDebitTxn

Element Name

Description

Values / Limitations

sortcode

The sort code of the customer's

bank

Six digits

Can contain additional hyphens

and spaces

R

accountnumber

The customer's account number

Eight digits

Can contain additional hyphens

and spaces

R

accountname

The name of the account holder

A maximum of 18

alphanumerics

R

method

determines the processing

model to be used

setup - for one stage

processing

presetup - for two stage

processing

R

In addition to these elements, there are also two attributes that may be populated -

these are both optional:

Optional Attributes of DirectDebitTxn

Attribute

Name

Description

Values /

Limitations

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

active

Enables an existing setup to be transferred to

the DataCash system

true

O

type

Enables a non_AUDDIS DDI to be converted

into an AUDDIS DDI

conversion

O

Example XML for DirectDebitTxn elements

<accountname>Mr A. N. Other</accountname>

<method>setup</method>

</DirectDebitTxn>

<accountname>Mr A. N. Other</accountname>

<method>presetup</method>

</DirectDebitTxn>

2.5.1.1.2 TxnDetails

Element Name:

TxnDetails

Position(s)

Request.Transaction

Elements of TxnDetails

Element Name

Description

Values /

Limitations

Confirm

Draw

down

Revoke

Setup

&

Preset

up

Cancel

merchantrefe

rence

The

reference

number of

the DDI

mandate

Must be of

the format

agreed with

your

Sponsoring

Bank.

Character

limitations

apply

R

-

amount

The

drawdown

value

-

R

-

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example XML Request for TxnDetails elements

</TxnDetails>

2.5.1.1.3 HistoricTxn

Element Name:

HistoricTxn

Position(s)

Request.Transaction

Elements of HistoricTxn

Element

Name

Description

Values /

Limitations

Confirm

Revoke

Drawdown

Cancel

method

Allows the type of

HistoricTxn to be set

confirm

revoke

drawdown

R

reference

The

datacash_reference

of the original

transaction

R

duedate

Allows a future date

for the drawdown to

be set if required. If

this field is not

presented, the next

available date will be

used

yyyymmdd

format

Must be at

least 3

working

days in the

future

-

O

-

The DataCash service automatically calculates the BACS Transaction Code for all

drawdown transactions. If the drawdown is the first made against a new DDI setup, the

transaction code is set to 01, otherwise the transaction code is set to 17.

You may need to set the transaction code yourself however, depending upon whether

the drawdown is a representation of a previously rejected drawdown, or if this is the

last drawdown to be made against a DDI setup.

Optional Attribute of duedate

Attribute

Name

Description

Values / Limitations

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

tran_code

The Transaction Code

for the drawdown

01 – the first drawdown

17

18 - a drawdown that is being re-presented

19 - the final drawdown. The drawdown will be

processed and then the mandate will be

cancelled

Example XML Request for HistoricTxn elements

<method>confirm</method>

</HistoricTxn>

<method>drawdown</method>

</HistoricTxn>

<method>drawdown</method>

</HistoricTxn>

<method>drawdown</method>

</HistoricTxn>

<method>cancel</method>

</HistoricTxn>

2.5.1.2 XML Example Requests

2.5.1.2.1 The Initial DataCash Setup

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example XML Request for presetup

</Authentication>

<accountname>Mr A. N. Other</accountname>

<method>presetup</method>

</DirectDebitTxn>

</TxnDetails>

</Transaction>

</Request>

Example XML Request for setup transferring an existing mandate to

DataCash

</Authentication>

<accountname>Mr A. N. Other</accountname>

<method>setup</method>

</DirectDebitTxn>

</TxnDetails>

</Transaction>

</Request>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example XML Request for a setup

This will convert an existing non-AUDDIS mandate to AUDDIS

</Authentication>

<accountname>Mr A. N. Other</accountname>

<method>setup</method>

</DirectDebitTxn>

</TxnDetails>

</Transaction>

</Request>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.5.1.2.2 Updating Setups

Example XML Request for confirm

</Authentication>

<method>confirm</method>

</HistoricTxn>

</TxnDetails>

</Transaction>

</Request>

If the method was changed, the same XML could be used for a revoke.

2.5.1.2.3 Taking Payments

Example XML Request for a drawdown

</Authentication>

<method>drawdown</method>

</HistoricTxn>

</TxnDetails>

</Transaction>

</Request>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example XML Request for a drawdown with a duedate

</Authentication>

<method>drawdown</method>

</HistoricTxn>

</TxnDetails>

</Transaction>

</Request>

Example XML Request for a drawdown with a tran_code

</Authentication>

<method>drawdown</method>

</HistoricTxn>

</TxnDetails>

</Transaction>

</Request>

2.5.1.2.4 Cancelling Payments

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example XML Request for a drawdown cancellation

</Authentication>

<method>cancel</method>

</HistoricTxn>

</Transaction>

</Request>

2.5.1.3 XML Example Responses

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

In addition to the standard fields, each Response will contain a DirectDebitTxn

element.

Element Name:

DirectDebitTxn

Position(s)

Response

Not all elements will be returned for all transaction types, for successful Responses

these are outlined below.

Failures will generally contain less of these elements - additional information about the

reason for failure will be returned in the reason and information elements. Examples

of failures are available in the Support Centre.

Elements of DirectDebitTxn Response

Element

Name

Description

Values /

Limitations

Setup

Presetup

Confirm

Revoke

Drawdown

Cancel

stage

The current

stage of the

mandate

See

Support

Centre

yes

n/a

method

The method

sent through

with the

Request

yes

startdate

Indicates

the first

date that a

drawdown

can be

submitted

Will be five

working

days

hence

yes

n/a

yes

n/a

duedate

The date the

drawdown

will be taken

from the

account

n/a

yes

n/a

Once a successful Response for a setup or presetup has been received, the

datacash_reference must be stored, as this must be presented with any future

transactions referring to that mandate.

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.5.1.3.1 The Initial DataCash Setup

Example XML Response for a successful setup

<datacash_reference>12345672</datacash_reference>

<method>setup</method>

<stage>active DDI</stage>

</DirectDebitTxn>

<reason>ACKNOWLEDGEMENT</reason>

</Response>

Example XML Response for a successful presetup

<datacash_reference>12345672</datacash_reference>

<method>presetup</method>

<stage>confirm required</stage>

</DirectDebitTxn>

<mode>ACCREDITATION</mode>

<reason>ACKNOWLEDGEMENT</reason>

</Response>

Example XML Response for a successful setup of an existing DDI

<datacash_reference>12345672</datacash_reference>

<method>setup</method>

<stage>existing</stage>

</DirectDebitTxn>

<reason>ACKNOWLEDGEMENT</reason>

</Response>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.5.1.3.2 Updating Setups

Example XML Response for a successful confirm

<method>confirm</method>

<stage>active DDI</stage>

</DirectDebitTxn>

<reason>ACKNOWLEDGEMENT</reason>

</Response>

Example XML Response for a successful revoke

<method>revoke</method>

<stage>revoked</stage>

</DirectDebitTxn>

<reason>ACKNOWLEDGEMENT</reason>

</Response>

2.5.1.3.3 Taking Payments

Example XML Response for a successful drawdown

<datacash_reference>12345672</datacash_reference>

<method>drawdown</method>

</DirectDebitTxn>

</Response>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example XML Response for a successful drawdown

<datacash_reference>12345672</datacash_reference>

<method>drawdown</method>

</DirectDebitTxn>

</Response>

2.5.1.3.4 Cancelling Payments

Example XML Response for a successful drawdown cancellation

<datacash_reference>12345671</datacash_reference>

<method>cancel</method>

</DirectDebitTxn>

<reason>CANCELLED OK</reason>

</Response>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.5.1.4 Notifications

This section is only applicable if you have completed the relevant paperwork at your

Sponsoring Bank, enabling DataCash to collect notifications of any rejections,

cancellations and changes of your setups. These changes will be automatically reflected

in the DataCash System.

To allow your system to also be kept up to date and prevent drawdown submission on

cancelled mandates, these will be mailed to you in a standard format attachment.

The following information will be included in the attachment:

 merchant_ref – your setup reference

 uniq_ref – the datacash_reference of the mandate

 reason_code – the ADDACS / AUDDIS reason code

 reason_code_text – further information about the reason_code

 effective_date – the date on which the notification takes affect

Full details about the reason codes are available in the Originators Guide and Rules to

the Direct Debit Scheme which is available from your bank. These are also detailed in

the Support Centre.

Email notifying of nine modifications to Direct Debits

Direct Debit Advices: BACS ID 556622

Please find attached your CSV file containing Direct Debit advices.

Total updated: 9

Total cancelled: 6

Total changed: 2

Total reinstated: 1

Example attachment with six cancellations, two changes and one

reinstatement - the changes are reason_codes C and E

merchant_ref,uniq_ref,reason_code,reason_code_text,effective_date

"ABC001","99990001","1","Instruction Cancelled by Payer","2010-01-30"

"ABCDE1","99990000","0","Instruction Cancelled - Refer to

Payer","2010-01-30"

"ABC053","99992222","2","Payer deceased","2010-02-01"

"ABC296","89898989","1","Instruction Cancelled by Payer","2010-02-03"

"ABC00A","99995555","1","Instruction Cancelled by Payer","2010-01-31"

"ABC009","99991111","C","Account transferred to a different

account/branch of Bank/Building Society","2010-01-30"

"ABCDE9","99993333","G","Bank will not accept Direct Debit on

Account","2010-02-22"

"ABC921","99966633","E","Instruction Amended","2010-01-31"

"ABC828","99779977","R","Instruction Reinstated","2010-01-30"

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.5.1.5 Returned Drawdown Notifications

This section is only applicable if you have completed the relevant paperwork at your

Sponsoring Bank, enabling DataCash to collect ARUDD notifications (Automated Return

of Unpaid Direct Debits) on your behalf.

To allow your system to also be kept up to date, these will be mailed to you in a

standard format attachment.

The following information will be included in the attachment:

 Reference – merchant’s reference

 datacash_ref – full 16-digit datacash_reference (please refer to 2.1.1.3)

 uniq_ref – the DataCash OTR (please refer to the Support Centre)

 return_code – ARUDD reason code

 return_code_text – further information about the return_code

 original_processing_date – original BACS processing date

 due_date - The date the drawdown was due to be taken from the account

 amount – the drawdown value

 currency – the drawdown currency

Full details about the reason codes are available in the Originators Guide and Rules to

the Direct Debit Scheme which is available from your bank. These are also detailed in

the Support Centre.

Email notifying of nine returned debit items

Direct Debit ARUDDS Reports: BACS ID 766000

Please find attached your CSV file containing a list of returned debit

items.

Total Returned Debit Items: 9

Please contact our Technical Support desk if you have any queries

relating to this advice.

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example attachment

Reference,datacash_ref,uniq_ref,return_code,return_code_text,original_pro

cessing_date,due_date,amount,currency

"ABCDEF368","3200100963845000","963845000","1","Instruction

Cancelled","06/25/2010","06/28/2010","238.19","GBP"

"ABCDEF956","3500100963845001","963845001","0","Refer to

Payer","06/25/2010","06/28/2010","238.19","GBP"

"ABCDEF905","3300100963845002","963845002","0","Refer to

Payer","06/25/2010","06/28/2010","87.76","GBP"

"ABDFR3749","3500100973919000","973919000","0","Refer to

Payer","07/02/2010","07/09/2010","84.01","GBP"

"ABCR93037","3800100969104000","969104000","0","Refer to

Payer","07/08/2010","07/05/2010","274.26","GBP"

"ABCD38303","3900100969104001","969104001","B","Account

Closed","07/08/2010","07/05/2010","137","GBP"

"3802JFDEW","3300100974762000","974762000","1","Instruction

Cancelled","06/29/2010","07/12/2010","74.07","GBP"

"84ABC3935","3800100974762001","974762001","0","Refer to

Payer","06/29/2010","07/12/2010","80.63","GBP"

"23445ABC2","3200100980386000","980386000","1","Instruction

Cancelled","07/12/2010","07/13/2010","82","GBP"

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.5.2 Direct Debit Continuous Authority

This Service allows drawdowns to be automatically created against a DDI.

A technical introduction to this Service is available on the website:

http://www.datacash.com/gettingproducts.php?id=Direct-Debit

2.5.2.1 Schema Elements for Request

In this section the required fields for Direct Debit refunds will be presented, along with

example XML for those fields. The XML is presented in italics for those fields that are

not required for all situations. In the XML examples where a field has been highlighted

fields, this indicates a situation in which other values can be presented in its place – for

example weekly in place of monthly.

Optional fields for each transaction type are indicated with an O, required fields with an

R.

Setting up a Direct Debit Continuous Authority Account

The information required to set up a Direct Debit Continuous Authority Account is

passed in these distinct places in the schema:

 Request

o Authentication – section 2.1.1.2

o Transaction

 ContAuthTxn – details of the account to be set up and its regular

payments, section 2.5.2.1.1

 FirstPayment – optional first payment date & amount,

section 2.5.2.1.2

 LastPayment – optional last payment date & amount, section

2.5.2.1.3

 TxnDetails – your reference number for the account, section

2.5.2.1.4

 HistoricTxn – details of the DDI to create an account for, section

2.5.1.1.3

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Cancelling a Continuous Authority Account

The Direct Debit Continuous Authority Account can also be cancelled by using the

cancel transaction type. This transaction type requires information passed in one

distinct place in the schema:

 Request

o Authentication – section 2.1.1.2

o Transaction

 HistoricTxn – the datacash_reference of the account, plus the

method, section 2.5.1.1.3

2.5.2.1.1 ContAuthTxn

The elements within this parent may only be presented for drawdown transactions.

They are excluded for cancel transactions.

Element Name:

ContAuthTxn

Position(s)

Request.Transaction

Elements of ContAuthTxn

Element Name

Description

Values / Limitations

start_date

The date on which the first

regular payment will be

taken. Subsequent

payments will be based on

this date.

Must be more than

three days after the

transaction is sent. Date

in the format

dd/mm/yyyy

R

number_of_payments

Number of regular

payments to be collected.

Payments will be taken

until the Continuous

Authority account is

cancelled if a value is

not specified

O

FirstPayment

Details of any initial payment to be taken. This is in

addition to the regular payments. See section

2.5.2.1.2

O

LastPayment

Details of any final payment to be taken. This is in

addition to the regular payments. See section

2.5.2.1.3

O

period

The frequency of

payments

weekly

monthly

quarterly

annually

R

method

The transaction method

drawdown

R

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

amount

The value of the drawdown

Must be specified to two

decimal places. GBP

only

R

flagging

This element has two attributes. If the element is

supplied, both attributes must be supplied. See

table below for more information

O

Attributes of Flagging

Element

Name

Description

Values / Limitations

first

Indicates whether the first payment made using the

Cont Auth account is to be flagged as the first

drawdown

yes

no

O

last

Indicates whether the last payment made using the

Cont Auth account is to be flagged as the last

drawdown

yes

no

O

For further information about drawdown flagging, please refer to section 2.5.1.1.3.

Example XML for ContAuthTxn elements

<method>drawdown</method>

<start_date>26/02/2006</start_date>

<period>weekly</period>

</ContAuthTxn>

<method>drawdown</method>

<start_date>01/04/2005</start_date>

<period>annually</period>

<number_of_payments>3</number_of_payments>

</ContAuthTxn>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.5.2.1.2 FirstPayment

The elements within this parent may only be presented for drawdown transactions, in

which case both child elements must be completed.

This element is excluded for cancel transactions.

Element Name:

FirstPayment

Position(s)

Request.Transaction.ContAuthTxn

Elements of FirstPayment

Element

Name

Description

Values / Limitations

date

The date the first

payment is to be

taken

Must be in dd/mm/yyyy format. Must be at least

three days from the current date. It must also be at

least one day ahead of the start_date

amount

The value of the

first payment

If a currency is supplied, it must be GBP

Example XML for FirstPayment element

</FirstPayment>

2.5.2.1.3 LastPayment

The elements within this parent may only be presented for drawdown transactions, in

which case both child elements must be completed.

This element is excluded for cancel transactions.

The LastPayment element can only be used if a set number of drawdowns have been

specified.

Element Name:

LastPayment

Position(s)

Request.Transaction.ContAuthTxn

Elements of LastPayment

Element

Name

Description

Values / Limitations

date

The date the last

payment is to be taken

Must be in dd/mm/yyyy format; must be a

minimum of one date after the last regular

payment

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

amount

The value of the last

payment

If a currency is supplied, it must be GBP

Example XML for LastPayment

</LastPayment>

2.5.2.1.4 TxnDetails

The elements within this parent may only be presented for drawdown transactions.

They are excluded for cancel transactions.

Element Name:

TxnDetails

Position(s)

Request.Transaction

Elements of TxnDetails

Element Name

Description

Values / Limitations

merchantreference

A unique reference number to identify

the individual Direct Debit Continuous

Authority account

Between 6 and 26

alphanumeric

characters

Example XML for TxnDetails elements

</TxnDetails>

2.5.2.1.5 HistoricTxn

Element Name:

HistoricTxn

Position(s)

Request.Transaction

Elements of HistoricTxn

Element

Name

Description

Values /

Limitations

Drawdown

Cancel

method

cancellations only

cancel

-

R

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

reference

The datacash_reference of the

original transaction

R

Example XML element for cancel

<method>cancel</method>

</HistoricTxn>

Example XML element for drawdown

</HistoricTxn>

2.5.2.2 XML Example Requests

2.5.2.2.1 Payments

Example XML Request for a five weekly payments of 10.00

</Authentication>

<method>drawdown</method>

<start_date>10/02/2005</start_date>

<period>weekly</period>

<number_of_payments>5</number_of_payments>

</ContAuthTxn>

</TxnDetails>

</HistoricTxn>

</Transaction>

</Request>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example XML Request for an unknown number of payments to be taken on

the 31st of each month

</Authentication>

<method>drawdown</method>

<start_date>31/03/2005</start_date>

<period>monthly</period>

</ContAuthTxn>

</TxnDetails>

</HistoricTxn>

</Transaction>

</Request>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example XML Request for eight payments: six regular payments, and

separate first and last payments

The first payment is a one off administration fee of £30, followed by 6

monthly payments of £25 and a final payment of £20. The first and last

payments are to be flagged with "01" and "19" respectively, which will

cancel the underlying DDI after the final payment.

</Authentication>

<method>drawdown</method>

<start_date>31/05/2005</start_date>

<period>monthly</period>

<number_of_payments>6</number_of_payments>

</FirstPayment>

</LastPayment>

</ContAuthTxn>

</TxnDetails>

</HistoricTxn>

</Transaction>

</Request>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.5.2.2.2 Cancellations

Example XML Request for cancel

</Authentication>

<method>cancel</method>

</HistoricTxn>

</Transaction>

</Request>

Merchants using the Credit and Debit Card Services may note that this XML structure is

the same as for cancelling a card payment – section 2.2.1.4.2.

2.5.2.3 Schema Elements for Response

There are no Response elements specific to this service. The general Response

elements are returned, these are discussed in section 2.1.1.3.

2.5.2.4 XML Example Responses

Example XML Response for a successful account setup

<datacash_reference>9910670039375669</datacash_reference>

<information>Direct Debit Continuous Authority account

set up</information>

<reason>ACCEPTED</reason>

</Response>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.5.2.5 Notifications

There are two types of notifications, one for batched drawdowns and one for account

cancellations.

2.5.2.5.1 Batched Drawdowns

Each day a payment is taken from an account, you will receive an email summarising

the payments taken that day, in a standard CSV format attachment.

The following information will be included in the attachment:

 Account Reference – the last 11 digits of the datacash_reference number of

the account

 Merchant Reference – the DDI mandate number (merchantreference) against

which the drawdown will be processed

 DataCash Reference – the datacash_reference of the drawdown

Email notifying of batched drawdowns

Drawdown Results for Mon 17-Oct-2010

Attachments: batched.csv

This email contains details of drawdowns which have been processed on

Live production site by DataCash on your behalf, for 2185**** Mon 17-

Oct-2010.

If you have any questions please contact our support team.

Example attachment with two drawdowns

Account Reference,Merchant Reference,DataCash Reference

41740256,1823362AHC,4200200040467707

41756562,1825472RHP,4400200040373171

2.5.2.5.2 Account Cancellations

If a DDI is cancelled or revoked, the account will be automatically cancelled.

To allow your system to also be kept up to date, details of these will be mailed to you

in a standard format CSV attachment.

The following information will be included in the attachment:

 Account reference – the last 11 digits of the datacash_reference number of the

account

 Merchant Reference – the merchantreference of the account

 Cancel DataCash Reference – the datacash_reference number of the

transaction which cancelled the account. If the account was automatically

cancelled when a DDI revoke is submitted, this field will be the same as DDI

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Setup Reference

 DDI Setup Reference – the datacash_reference number of the DDI setup

 DDI Merchant Reference – your mandate number

 DDI Stage – the stage of the DDI

Email notifying of account cancellations

Account Cancellations for Mon 17-Oct-2010

Attachments: cancelled.csv

This email contains details of Direct Debit Recurring Transaction

accounts which have been cancelled on Live production site by DataCash

on your behalf, for 2185*** Mon 17-Oct-2010, where the associated DDI

setup is no longer active.

Example attachment with four cancellation notifications

Account Reference,Merchant Reference,Cancel DataCash Reference,DDI

Setup Reference,DDI Merchant Reference,DDI Stage

46453486,EFG987456,4600200040488736,4600200040488741,ABC1234562,revoked

47453828,EFG453454,4200200040493495,4000200040493496,ABC483,cancelled

at source

47455267,EFG456454,4300200040493522,4400200040493526,SJI45l,cancelled

at source

47511296,EFG15648,4100200041248347,4800200041260637,HUR45423,revoked

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.5.3 Direct Credit – Direct Debit Refunds

This Service allows funds to be returned to any DDI held within the DPG.

A technical introduction to this service is available on the website:

http://www.datacash.com/gettingproducts.php?id=Direct-Debit-Refunds

2.5.3.1 Schema Elements for Request

In this section the required fields for Direct Debit refunds will be presented, along with

example XML for those fields.

Refunding Direct Debits

The information required to process a direct debit refund - ddrefund - is passed in

these distinct places in the schema:

2.5.3.1.1 Request

o Authentication – section 2.1.1.2

o Transaction

 TxnDetails – contains the merchantreference number and the amount,

section 2.5.2.1.4

 HistoricTxn - the datacash_reference of the original mandate and the

method, section 2.5.1.1.3.

Cancelling Direct Debit Refunds

The information required to cancel a ddrefund is passed in these distinct places in

the schema:

2.5.3.1.2 Request

o Authentication – section 2.1.1.2

o Transaction

 HistoricTxn - the datacash_reference of the original ddrefund and the

method, section 2.5.1.1.3.

2.5.3.1.3 TxnDetails

The elements within this parent are required for ddrefund transactions. They are

excluded for cancel transactions.

Element Name:

TxnDetails

Position(s)

Request.Transaction

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Elements of TxnDetails

Element Name

Description

Values / Limitations

merchantreference

The reference number of the

DDI mandate

Between six and eighteen

alphanumeric characters

amount

The value of the refund

Example XML for TxnDetails elements

</TxnDetails>

2.5.3.1.4 HistoricTxn

The elements within this parent are required for both cancel and ddrefund transaction

types.

Element Name:

HistoricTxn

Position(s)

Request.Transaction

Elements of HistoricTxn

Element

Name

Description

Values /

Limitations

method

Identifies the transaction type as a refund of a

direct debit

ddrefund

cancel

reference

The datacash_reference of the original

transaction

Example XML for HistoricTxn element for a ddrefund

<method>ddrefund</method>

</HistoricTxn>

Example XML for HistoricTxn element for a cancel

<method>cancel</method>

</HistoricTxn>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.5.3.2 XML Example Requests

Example XML Request for a ddrefund

</Authentication>

<method>ddrefund</method>

</HistoricTxn>

<merchantreference>ABCDEF456</merchantreference>

</TxnDetails>

</Transaction>

</Request>

Example XML Request for a cancel

</Authentication>

<method>cancel</method>

</HistoricTxn>

</Transaction>

</Request>

2.5.3.3 Schema Elements for Response

There are no additional XML elements returned for specifically for this Service. The

general XML elements in the Response are covered in section 2.1.1.3.

2.5.3.4 XML Example Responses

2.5.3.4.1 Refunds

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example XML Response for a successful ddrefund

<datacash_reference>4800200040644359</datacash_reference>

<merchantreference>ABCDEF456</merchantreference>

<reason>Accepted</reason>

</Response>

Example XML Response for an unsuccessful ddrefund

<datacash_reference>4000000059832491</datacash_reference>

<information>Unable to locate matching DDI

transaction</information>

<reason>Unable to locate matching DDI transaction</reason>

</Response>

2.5.3.4.2 Cancellations

Example XML Response for a successfully cancelled Direct Credit

<datacash_reference>39375274</datacash_reference>

<reason>CANCELLED OK</reason>

</Response>

Example XML Response for an unsuccessful Direct Credit cancellation

<information>Direct Credit has already been

cancelled</information>

<reason>Already Cancelled</reason>

</Response>

2.5.4 Direct Credit – Standard

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

This Service allows funds to be returned to a customer by placing them directly into

their bank account.

A technical introduction to this service is available on the website:

http://www.datacash.com/gettingproducts.php?id=Direct-Credit

2.5.4.1 Schema Elements for Request

In this section the required fields for Standard Direct Credit will be presented, along

with example XML for those fields. The XML is presented in italics for those fields that

are not required for all situations.

Optional fields for each transaction type are indicated with an O, required fields with an

R.

Performing Direct Credits

The information required to process a direct credit - directcredit - is passed in

these distinct places in the schema:

2.5.4.1.1 Request

o Authentication – section 2.1.1.2

o Transaction

 TxnDetails – contains the merchantreference number and the amount,

section 2.5.2.1.4

 DirectCreditTxn - the details of the customers bank account, plus the

method, section 2.5.1.1.1

Cancelling Direct Debit Refunds

The information required to cancel a directcredit is passed in these distinct places in

the schema:

2.5.4.1.2 Request

o Authentication – section 2.1.1.2

o Transaction

 HistoricTxn - the datacash_reference of the original directcredit and

the method, section 2.5.1.1.3

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.5.4.1.3 DirectCreditTxn

The elements within this parent may only be presented for directcredit transactions.

They are excluded for cancel transactions.

Element Name:

DirectCreditTxn

Position(s)

Request.Transaction

Elements of DirectCreditTxn

Element Name

Description

Values / Limitations

Required?

method

Identifies the transaction

type as a standard Direct

Credit

directcredit

R

sortcode

The sort code of the

account to be credited

Valid UK sortcode

R

accountnumber

The account number to be

credited

Valid UK account number

R

accountname

The name of the account

holder(s)

Up to 18 characters, alpha

numerics and spaces only

R

bankreference

Up to 18 characters, alpha

numerics and spaces only

O

Example XML Element DirectCredit

<accountname>Julia McDonald</accountname>

<method>directcredit</method>

</DirectCreditTxn>

<accountname>Michael Johnson</accountname>

<bankreference>return of goods</bankreference>

<method>directcredit</method>

</DirectCreditTxn>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.5.4.1.4 TxnDetails

The elements within this parent are required for directcredit transactions, but

excluded for cancel transactions.

Element Name:

TxnDetails

Position(s)

Request.Transaction

Elements of TxnDetails

Element Name

Description

Values /

Limitations

merchantreference

A unique reference number for each

transaction

Up to 30

characters

amount

The value of the refund

Example XML for TxnDetails elements

</TxnDetails>

2.5.4.1.5 HistoricTxn

The elements within this parent must be presented for cancel transactions. They are

excluded for directcredit transactions.

Element Name:

HistoricTxn

Position(s)

Request.Transaction.HistoricTxn

Elements of HistoricTxn

Element

Name

Description

Values /

Limitations

method

Identifies the transaction type as a cancellation

cancel

reference

The datacash_reference of the original

transaction

16 digits

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example XML Element HistoricTxn for a cancel

<method>cancel</method>

</HistoricTxn>

2.5.4.2 XML Example Requests

Example XML Request

</Authentication>

</TxnDetails>

<method>directcredit</method>

</DirectCreditTxn>

</Transaction>

</Request>

Example XML Request with optional bankreference

</Authentication>

<merchantreference>ABDYC003</merchantreference>

</TxnDetails>

<method>directcredit</method>

<accountname>Jane Smith</accountname>

<bankreference>Money for Petrol</bankreference>

</DirectCreditTxn>

</Transaction>

</Request>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example XML Request for a cancel

</Authentication>

<method>cancel</method>

</HistoricTxn>

</Transaction>

</Request>

2.5.4.3 Schema Elements for Response

The XML Responses for this Service only contain those elements that are discussed in

section 2.1.1.3. There are no additional XML elements returned specifically for this

Service

2.5.4.4 XML Example Responses

Example XML Response for a successful directcredit

<datacash_reference>4803000012345672</datacash_reference>

<merchantreference>ABDYC003</merchantreference>

<reason>Accepted</reason>

</Response>

Example XML Response for an unsuccessful directcredit

<information>Invalid format for Account Name</information>

<reason>Invalid format for Account Name</reason>

</Response>

Examples of directcredit cancellations are available in section 2.5.3.4.2.

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.5.5 Direct Credit – Card Collection Accounts

This Service allows funds to be returned to a cardholder by using their card collection

account.

A technical introduction to this service is available on the website:

http://www.datacash.com/gettingproducts.php?id=Payments-to-Card-Collection-

Accounts

2.5.5.1 Schema Elements for Request

In this section the required fields for Direct Credit to Card Collection Accounts will be

presented, along with example XML for those fields. The XML is presented in italics for

those fields that are not required for all situations.

Optional fields for each transaction type are indicated with an O, required fields with an

R.

Performing Card Account Payments

The information required to process a direct debit refund - cardaccountpayment - is

passed in these distinct places in the schema:

2.5.5.1.1 Request

o Authentication – section 2.1.1.2

o Transaction

 TxnDetails – contains the merchantreference number and the amount,

section 2.5.5.1.4

 DirectCreditTxn – details of the customers card, plus the method, section

2.5.1.1.1.

Cancelling Direct Debit Refunds

The information required to cancel a cardaccountpayment is passed in these distinct

places in the schema:

2.5.5.1.2 Request

o Authentication – section 2.1.1.2

o Transaction

 HistoricTxn - the datacash_reference of the cardaccountpayment and

the method, section 2.5.5.1.5.

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.5.5.1.3 DirectCreditTxn

The elements within this parent may only be presented for cardaccountpayment

transactions. They are excluded for cancel transactions.

Element Name:

DirectCreditTxn

Position(s)

Request.Transaction

Elements of DirectCreditTxn

Element

Name

Description

Values / Limitations

Required?

method

Identifies the

transaction type as a

refund to a card

collection account

cardaccountpayment

R

pan

The card number

Card must be Visa or MasterCard

branded and issued in the UK

R

expirydate

The card expiry date

MM/YY format

O

cardname

The card holder’s

name

Up to 18 characters. “COLLECTION

ACCOUNT” will be automatically used

if this element is not presented

O

2.5.5.1.4 TxnDetails

Element Name:

TxnDetails

Position(s)

Request.Transaction

Elements of TxnDetails

Element Name

Description

Values /

Limitations

merchantreference

A unique reference number for each

transaction

Up to 30

characters

amount

The value of the refund

Example XML for TxnDetails elements

</TxnDetails>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.5.5.1.5 HistoricTxn

Element Name:

HistoricTxn

Position(s)

Request.Transaction.HistoricTxn

Elements of HistoricTxn

Element

Name

Description

Values /

Limitations

method

Identifies the transaction type as a cancellation

cancel

reference

The datacash_reference of the original

transaction

16 digits

Example XML Element HistoricTxn for a cancel

<method>cancel</method>

</HistoricTxn>

2.5.5.2 XML Example Requests

Example XML Request for cardaccountpayment

</Authentication>

</TxnDetails>

<method>cardaccountpayment</method>

</DirectCreditTxn>

</Transaction>

</Request>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example XML Request for cardaccountpayment

</Authentication>

</TxnDetails>

<method>cardaccountpayment</method>

<cardname>Wes Scantlin</cardname>

</DirectCreditTxn>

</Transaction>

</Request>

Example XML Request for a cancel

</Authentication>

<method>cancel</method>

</HistoricTxn>

</Transaction>

</Request>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.5.5.3 Schema Elements for Response

The XML Responses for this Service only contain those elements that are discussed in

section 2.1.1.3. There are no additional XML elements returned specifically for this

Service.

2.5.5.4 XML Example Responses

Example XML Response for a successful cardaccountpayment

<datacash_reference>4000200045345250</datacash_reference>

<reason>Accepted</reason>

</Response>

Example XML Requests for unsuccessful cardaccountpayment

<datacash_reference>4900200043479577</datacash_reference>

<information>The card number does not pass the standard

Luhn checksum test</information>

<reason>Bad checksum</reason>

</Response>

<datacash_reference>3600200044366081</datacash_reference>

<information>No payment details for this card</information>

<reason>Unknown Payment Details</reason>

</Response>

Examples of cancellations are available in section 2.5.3.4.2.

Back to Contents

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.6 BATCH INPUT

The Batch Input Service allows many of the DPG Services to be utilised via batch

process, instead of submitting the transactions in real time. Further non-technical

information about this service is available on the website:

http://www.datacash.com/services/batch/overview.shtml

The transaction data may be presented in either a XML or a CSV file format. This file

will be referred to in this document as the Batch Request XML (or CSV). This file must

then be Zlib-compressed and Base64 encoded.

The compressed and encoded Batch Request file is then placed within the Batch

Submission Request document, which is itself an XML document. The Batch Submission

Request is then sent to DataCash and a Batch Submission Response is returned.

To collect the results of the batch, a Batch Query Request is sent to DataCash. A Batch

Query Response will be returned. This will contain the results of the batch, which have

been Zlib –compressed and Base64 encoded. These results will be referred to as the

Batch Response XML (or CSV). The format of the Batch Response document will match

that of the Batch Request.

Naturally, the data you need to supply will depend upon the particular service you are

using. However there are certain aspects of Batch Input that are common to each

service that it can be used with. The features common to all services will be covered

first

Available DPG Services – section 2.6.1

Common Elements - each of these elements are independent of the service used,

section 2.6.2

File Formats Attributes, section 2.6.2.1

Batch Submission elements - also independent of format, section 2.6.2.2

Batch Query elements - also independent of format, section 2.6.2.3

Batch Request elements - for both XML and CSV, section 2.6.2.5

Batch Response elements - for both XML and CSV, section 2.6.2.6

SERVIce Specific Elements – these are specific to both the service and the file format

used, section 2.6.3.1

The following key will be used for this section:

 O - Optional

 R - Required, field must be presented

 M - Mandatory if Available, if the information is available, it should be

presented

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.6.1 Available DPG Services

Various DPG Services can be accessed via the Batch Input Service using both the XML

and CSV file formats. These are outlined in the table below.

Service

Type

DPG Service Name

Restrictions

Additional

Information

Credit

and

Debit

Cards

Bank Card

-

Section 2.2.1

Pre-Registered Cards

Account must be

configured for this service

Section 2.3.1

Recurring

Transactions –

Capture Method

Account must be

configured for this service

Section 2.3.2

Chip and PIN

Account must be

configured for this service.

Transaction method must

be auth or refund.

Section 2.7.1.1

BACS

Services

Standard Direct Debit

Account must be

configured for this service

Section 2.5.1.1

Direct Credit:

DDrefunds

Account must be

configured for this service

Section 2.5.3

Standard Direct

Credit

Account must be

configured for this service

Section 2.5.4

Direct Credit: Card

Collection Accounts

Account must be

configured for this service

Section 2.5.5

In addition, the following Fraud Screening Services may be used in conjunction with

the Credit and Debit Card Services:

Service

Type

DPG Service

Name

Restrictions

Additional

Information

Fraud

Prevention

for Cards

ReD

Account must be

configured for this service.

The extended dataset

cannot be provided.

Section 2.4.3

AVSCV2

AVS check only. Not

available for Chip and PIN

Section 2.4.1

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.6.2 Overview of Common Elements and Attributes

2.6.2.1 File Formats Attributes

The individual transactions within each file may be presented in either XML or CSV

format. Each format has a name, which is passed within both the Batch Submission

document and the Batch Request. The file names are presented below.

XML File Formats

Format

Service

Details in

xml_cardtxn

Credit and Debit Cards

Section 2.6.3.1

xml_chp_cardtxn

Cardholder Present Cards

Section 2.6.3.2

xml_directcredit

BACS – Direct Credit

Section 2.6.3.3

xml_directdebit

BACS - Direct Debit

Section 2.6.3.1

CSV file Formats

Format

Service

Used for

Details in

csv_avs_card_txn

Credit and

Debit Cards

Authorisations with standard

AVS checking

Section

2.6.3.6

csv_card_txn

Credit and

Debit Cards

Authorisations

Section

2.6.3.4

csv_chp_card_txn

Cardholder

Present

auth and refund transactions

Section

2.6.3.2

csv_historic

Credit and

Debit Cards

Historic transactions:

fulfill, txn_refund,

cancel, accept_fraud

authorize_referral_request

Section

2.6.3.8

csv_prereg

Credit and

Debit Cards

Pre-Registered Cards

Section

2.6.3.9

csv_dc_cc_account

BACS

Services

Direct Credit

cardaccountpayment

Section

2.6.3.10

csv_dc_ddrefund

BACS

Services

Direct Credit ddrefunds

Section

2.6.3.11

csv_dc_std

BACS

Services

Standard Direct Credit

Section

2.6.3.12

csv_dd_drawdown

BACS

Services

Direct Debit drawdown

Section

2.6.3.13

csv_dd_setup

BACS

Services

Direct Debit setup and

presetup

Section

2.6.3.14

csv_dd_setup_edit

BACS

Services

Direct Debit confirm and

revoke

Section

2.6.3.15

2.6.2.2 Batch Submission Elements

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

These elements are common to all of the Batch Input Services, regardless of the

service or format used.

2.6.2.2.1 Schema Elements for Batch Submission

Each batch contains header information:

2.6.2.2.2 Request

o Authentication – each Batch Submission can contain transactions for only

one DataCash account (vTID). The Authentication element is covered in

section 2.1.1.2

o Transaction

 BatchInputTxn – section 2.6.2.2.2.1

2.6.2.2.2.1 BatchInputTxn

Element Name:

BatchInputTxn

Position:

Request.Transaction

Elements of BatchInputTxn

Element

Name

Description

Values / Limitations

batchfile

The Batch Request,

compressed using Zlib

compression, then Base64

encoded

Uncompressed Batch Request must

be less than 1MB

R

txn_count

The total number of

transactions in the batchfile

Must be an integer > 0.

R

total_amount

The total gross value of

transactions in the

batchfile, regardless of

currency and transaction

type

Tolerant to 0.001. If the format of

the transactions within the Batch

Request does not contain an amount,

the total_amount must be set to

zero

R

Attributes of batchfile

Element

Name

Description

Values / Limitations

format

The format of the file you are

submitting

Please refer to section

2.6.2

R

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

XML Examples of Batch Submission for BatchInputTxn

complex elements

<txn_count>3</txn_count>

<total_amount>395.99</total_amount>

</BatchInputTxn>

<txn_count>16</txn_count>

<total_amount>0</total_amount>

</BatchInputTxn>

<txn_count>4</txn_count>

<total_amount>75.60</total_amount>

</BatchInputTxn>

<txn_count>29</txn_count>

<total_amount>0</total_amount>

</BatchInputTxn>

<txn_count>63</txn_count>

<total_amount>1565.09</total_amount>

</BatchInputTxn>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.6.2.2.3 XML Example Batch Submission

Example XML Batch Submission for a Batch Request in

XML format containing three transactions

</Authentication>

<txn_count>3</txn_count>

<total_amount>395.99</total_amount>

</BatchInputTxn>

</Transaction>

</Request>

Example XML Batch Submission for a Batch Request in CSV

format containing five transactions

</Authentication>

<txn_count>5</txn_count>

<total_amount>2501.00</total_amount>

</BatchInputTxn>

</Transaction>

</Request>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example XML Batch Submission for a Batch Request in XML

format containing five transactions

</Authentication>

<txn_count>5</txn_count>

<total_amount>395.99</total_amount>

</BatchInputTxn>

</Transaction>

</Request>

Example XML Batch Submission for a Batch Request in CSV

format containing eighteen transactions

</Authentication>

<txn_count>18</txn_count>

<total_amount>156.00</total_amount>

</BatchInputTxn>

</Transaction>

</Request>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.6.2.2.4 Schema Elements for Response

The Response for Batch Submission contains the normal Response fields. These are

covered in section 2.1.1.3

The datacash_reference returned is the reference number for the Batch Submission.

This should be stored to allow a Batch Query (section 2.6.2.3) to be performed. The

merchantreference returned is extracted from within the Batch Request.

2.6.2.2.5 XML Example Batch Submission Response

Two Batch Submission Responses are shown below.

A full list of return codes for this service is available on the website here.

Example XML Batch Submission Responses for a successful and

a rejected batch submission

<datacash_reference>3900900100010001</datacash_reference>

<merchantreference>batch_ABCDEF</merchantreference>

<reason>ACCEPTED</reason>

</Response>

<datacash_reference>3800900100010006</datacash_reference>

<information>Supplied and actual transaction counts do

not match</information>

<merchantreference>batch_XYZ</merchantreference>

<reason>BatchInput: Error in batch data</reason>

</Response>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.6.2.3 Batch Query

The Batch Query allows you to receive the results of each transaction within the Batch

Submission.

2.6.2.3.1 Schema Elements for Batch Submission Query

2.6.2.3.2 Request

o Authentication – section 2.1.1.2

o Transaction

 HistoricTxn - see section 2.6.2.3.2.1.

2.6.2.3.2.1 HistoricTxn

Element Name:

HistoricTxn

Position:

Request.Transaction

Elements of HistoricTxn

Element

Name

Description

Values /

Limitations

method

The transaction type

query

R

reference

The datacash_reference of the Batch

Submission

R

Example XML Request for HistoricTxn complex elements

<method>query</method>

</HistoricTxn>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.6.2.3.3 XML Example Batch Submission Query

Example XML Batch Query

</Authentication>

<method>query</method>

</HistoricTxn>

</Transaction>

</Request>

2.6.2.4 Schema Elements for Query Response

2.6.2.4.1.1 BatchInputTxn

Element Name:

BatchInputTxn

Position:

Response

The element BatchInputTxn contains the Zlib compressed and Base64 encoded results

of the Batch Request.

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.6.2.4.2 XML Example Query Response

Two Example XML Batch Query Responses

<datacash_reference>3900900100010001</datacash_reference>

<merchantreference>batch_ABCDEF</merchantreference>

<reason>ACCEPTED</reason>

</Response>

<datacash_reference>3400900100010008</datacash_reference>

<information>You have queried a Batch Input Transaction,

which is currently being processed</information>

<merchantreference>batch_ABCDEG</merchantreference>

<reason>BatchInput: Processing</reason>

</Response>

2.6.2.5 Batch Input Request and Response - Common XML Elements

2.6.2.5.1 Schema Elements for Batch Request

2.6.2.5.2 BatchInputRequest

o Header – see section 2.6.2.5.2.1

o Transactions – see section 2.6.2.5.2.2

2.6.2.5.2.1 Header

Element Name:

Header

Position:

BatchInputRequest

Elements of Header

Element

Name

Description

Values / Limitations

format

The name of the file

format used

See section 2.6.2 for list. Must match that

listed in the Batch Submission

R

reference

A reference number for

the entire Batch

Must be between six and thirty

alphanumeric in length

R

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example XML Request for Header complex elements

<format>xml_cardtxn</format>

<reference>mybatch0002</reference>

</Header>

<format>xml_directdebit</format>

<reference>mybatch_0003</reference>

</Header>

2.6.2.5.2.2 Transactions

Element Name:

Transactions

Position:

BatchInputRequest

Elements of Transactions

Element

Name

Description

Values / Limitations

Request

One Request

element per

transaction

Each Request must have identical Authentication

elements, which must also be the same as those supplied

in the Authentication element of the Batch Submission

R

Example XML for Transactions complex elements. There are 3 transactions.

...

</Request>

...

</Request>

...

</Request>

</Transactions>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.6.2.5.3 Example XML Batch Request

<format>xml_cardtxn</format>

<reference>batchref1234</reference>

</Header>

...

</Request>

...

</Request>

...

</Request>

</Transactions>

</BatchInputRequest>

2.6.2.5.4 Schema Elements for Batch Response

2.6.2.5.5 BatchInputResponse

Header – this element is currently unpopulated

Transactions – see section 2.6.2.5.2.2

2.6.2.5.5.1 Transactions

Element Name:

Transactions

Position:

BatchInputResponse

Elements of Transactions

Element Name

description

Response

One Response element per original transaction

Example XML for Transactions complex elements.

There are 2 transactions present

...

</Response>

...

</Response>

</Transactions>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.6.2.5.6 Example XML Batch Response

Example XML for a Batch Response, without the transaction details

shown

</Transactions>

</BatchInputResponse>

An Example XML Response, with 3 transactions

<card_scheme>Mastercard</card_scheme>

<country>United Kingdom</country>

<cv2avs_status>ADDRESS MATCH ONLY</cv2avs_status>

</Cv2Avs>

<issuer>BARCLAYS BANK PLC</issuer>

</CardTxn>

<datacash_reference>3300900100010037</datacash_reference>

<reason>ACCEPTED</reason>

</Response>

<datacash_reference>3300900100010037</datacash_reference>

<reason>Prereg: Merchant Not Subscribed</reason>

</Response>

</CardTxn>

<datacash_reference>3300900100010037</datacash_reference>

<reason>ACCEPTED</reason>

</Response>

</Transactions>

</BatchInputResponse>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.6.2.6 Batch Request and Response - Common CSV Elements

2.6.2.6.1 CSV File Format Definition

The definition of CSV format used is as follows

 Allowable characters within a CSV field include 0x09 (tab) and the inclusive range

of 0x20 (space) through 0x7E (tilde).

 A field within CSV may be surrounded by double-quotes. Double quoting is used

by default to surround fields in CSV format responses.

 A field within CSV must be surrounded by double-quotes to contain a comma.

 A field within CSV must be surrounded by double-quotes to contain an embedded

double-quote, represented by a pair of consecutive double-quotes.

 A CSV field may be terminated by 0x0A (line feed) or by 0x0D, 0x0A (carriage

return, line feed).

 Blank lines and lines starting with 0x23 (#) are ignored.

2.6.2.6.2 CSV Request Headers

Each CSV file contains should contain a header line containing these fields:

Headers for CSV format, in order

Element

Name

Description

Values / Limitations

format

The name of the file format

used

See section 2.6.2 for list. Must match

that listed in the Batch Submission

R

reference

A reference number for the

entire Batch

Must be between six and thirty

alphanumeric in length

R

client

The vTID of the account the

batch is to be processed

against

Must be the same as those supplied in

the Authentication element of the

Batch Submission

R

password

The password of the account

the batch is to be processed

against

R

Two CSV Examples for a Batch Request Headers

csv_card_txn,batch_csv_card_txn_6,99000001,mypasswd

csv_prereg,batch_csv_prereg_3,99000001,mypasswd

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.6.2.6.3 CSV Response

The Response elements returned will be the same for each file format. These are:

Fields for CSV responses

Element Name

Description

XML equivalent

1

merchant_ref

The merchant_ref of the

original transaction

merchant_reference

2

datacash_ref

The datacash_reference of the

transaction

datacash_reference

3

response_code

The DataCash Response Code

status

4

status_message

Additional information about the

response_code

reason

5

authcode

The result of the authorisation

request, for transactions

submitted for authorisation only

–otherwise blank

authcode

6

time

The Unix Timestamp of the

transaction

time

Example CSV responses

“ABCD9876”,“3000900100010005”,“7”,“REFERRED”,“CALL AUTH”,“1080920429”

“3400900100010008”,“3400900100010008”,“1”,“CANCELLED

OK”,“”,“1080920429”

“payment_1223”,“3600900100010889”,“1”,“ACCEPTED”,“896786”,“1080920430”

“ACBD9877”,“3600900100010890”,“1”,“ACCEPTED”,“548620”,“1080920431”

"valid_ddrefund","3000900100010048","1","ACCEPTED","","1080920435"

"ddrefund_no_setup","3800900100010049","137","Unable to locate

matching DDI transaction","","1080920436"

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.6.3 Example Batch Requests

This section covers the Batch Request file, for all services.

Please note that the maximum size of a single Batch Request – before compression – is

1MB (1024KB). Any files larger than this will be rejected.

2.6.3.1 xml_cardtxn

An example file with three transactions is shown below. The file contains three

transactions, one Pre-Registered and two Credit and Debit Card (a pre with AVS data

and a cancel). The transactions could be screened using either the ReD or T3M

services if the account is configured for this at DataCash. A Batch Submission example

for this file is shown in section 2.6.2.2.

Example XML Batch Request containing three transactions with a total value

of 395.99

<format>xml_cardtxn</format>

<reference>batchref1234</reference>

</Header>

</Authentication>

<Card>

<street_address1>1 High Street, UK </street_address1>

</Cv2Avs>

</Card>

</CardTxn>

</TxnDetails>

</Transaction>

</Request>

</Authentication>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

</TxnDetails>

<card_details type="preregistered">

310000008888881212</card_details>

</CardTxn>

</Transaction>

</Request>

</Authentication>

<method>txn_refund</method>

</HistoricTxn>

</Transaction>

</Request>

</Transactions>

</BatchInputRequest>

2.6.3.2 xml_chp_cardtxn

Example XML Batch Request containing three transactions with a total value

of 120.72 in two currencies

<format>xml_chp_cardtxn</format>

<reference>batchref1234</reference>

</Header>

</Authentication>

<capturemethod>parked</capturemethod>

<merchantreference>1234567890blahh</merchantreference>

</TxnDetails>

<card_details type="track2_data">

****************</card_details>

<terminal_capabilities ic_reader="true"

magnetic_stripe_reader="true" manual_card_entry="true"/>

<features_capabilities pin_pad_available="true"/>

</Terminal>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

<reason_online_code>10</reason_online_code>

<receipt_no>000123</receipt_no>

<ICC>

<seq_or_issue_number>*</seq_or_issue_number>

<auth_response_code>00</auth_response_code>

<crypto_txn_amount>54.00</crypto_txn_amount>

<crypto_tran_type>00</crypto_tran_type>

<term_txn_date>031107</term_txn_date>

<txn_currency_code>826</txn_currency_code>

<txn_country_code>826</txn_country_code>

<issuer_app_data>**************</issuer_app_data>

<app_usage_control>****</app_usage_control>

<crypto_info_data>**</crypto_info_data>

<term_app_ver_no>****</term_app_ver_no>

<txn_status_info>****</txn_status_info>

<term_type>**</term_type>

<term_capabilities>******</term_capabilities>

<pos_entry_mode>32</pos_entry_mode>

<other_card_data>**************</other_card_data>

</ICC>

</CardTxn>

</Transaction>

</Request>

</Authentication>

<capturemethod>keyed</capturemethod>

</TxnDetails>

<terminal_capabilities ic_reader="true"

magnetic_stripe_reader="true" manual_card_entry="true"/>

<features_capabilities pin_pad_available="true"/>

</Terminal>

<receipt_no>000124</receipt_no>

<ICC>

<term_type>**</term_type>

</ICC>

<Card>

</Card>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

</CardTxn>

</Transaction>

</Request>

</Authentication>

<capturemethod>swiped</capturemethod>

</TxnDetails>

<card_details type="track2_data">

****************</card_details>

<terminal_capabilities ic_reader="true"

magnetic_stripe_reader="true" manual_card_entry="true"/>

<features_capabilities pin_pad_available="true"/>

</Terminal>

<receipt_no>000125</receipt_no>

<ICC>

<term_type>**</term_type>

</ICC>

</CardTxn>

</Transaction>

</Request>

</Authentication>

<capturemethod>keyed</capturemethod>

</TxnDetails>

<terminal_capabilities ic_reader="true"

magnetic_stripe_reader="true" manual_card_entry="true"/>

<features_capabilities pin_pad_available="true"/>

</Terminal>

<method>refund</method>

<receipt_no>000126</receipt_no>

<ICC>

<term_type>**</term_type>

</ICC>

<Card>

</Card>

</CardTxn>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

</Transaction>

</Request>

</Transactions>

</BatchInputRequest>

2.6.3.3 xml_direct_credit

Example XML Batch Request xml_directcredit containing two transactions

with a total value of 80.00

<format>xml_directcredit</format>

</Header>

</Authentication>

<merchantreference>standardDC0000054</merchantreference>

</TxnDetails>

<method>directcredit</method>

<accountname>Jo Bloggs</accountname>

</DirectCreditTxn>

</Transaction>

</Request>

</Authentication>

<merchantreference>ddrefund00434582</merchantreference>

</TxnDetails>

<method>ddrefund</method>

</HistoricTxn>

</Transaction>

</Request>

</Transactions>

</BatchInputRequest>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.6.3.4 xml_directdebit

An example xml_directdebit file with four transactions is shown below. The file

contains one setup, one revoke, two drawdowns and a confirm. A Batch Submission

example for this file is shown in section .

Example XML Batch Request containing five transactions with a total value of

395.99

<format>xml_directdebit</format>

<reference>batchref1236</reference>

</Header>

</Authentication>

<accountname>Mr A. N. Other</accountname>

<method>setup</method>

</DirectDebitTxn>

</TxnDetails>

</Transaction>

</Request>

</Authentication>

</TxnDetails>

<method>drawdown</method>

</HistoricTxn>

</Transaction>

</Request>

</Authentication>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

</TxnDetails>

<method>drawdown</method>

</HistoricTxn>

</Transaction>

</Request>

</Authentication>

<method>revoke</method>

</HistoricTxn>

</TxnDetails>

</Transaction>

</Request>

</Authentication>

<method>confirm</method>

</HistoricTxn>

</TxnDetails>

</Transaction>

</Request>

</Transactions>

</BatchInputRequest>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.6.3.5 csv_card_txn

This CSV file format should be used to obtain authorisation for Credit and Debit Card

transactions using the Bank Card Service. It can be used for both the one stage

processing model and the first stage of the two stage processing model.

If you are using the Capture Method model of Recurring Transactions, this file format

can be used. For this Service, the capturemethod should be specified.

Fields for format csv_card_txn

Element

Name

Description

Values / Limitations

1

pan

As described in section 2.2.1.1.1

R

2

expiry_date

R

3

start_date

M

4

issue

M

5

amount

As described in section 2.2.1.1.3

R

6

currency

R

7

merchant_ref

R

8

method

The transaction type

auth

pre

refund

erp

R

9

capturemethod

As described in section 2.8.3.10.2

M1

10

authcode

The authorisation code

received from the bank

If presented, must be value

received from Banks Authorisation

centre

O

1Mandatory if the account is configured with multiple merchant ID environments

Example csv_card_txn file – six transactions with a value of

2697.31

csv_card_txn,batch_csv_card_txn_6, 99000001,mypasswd

4444333322221111,01/09,,,99.99,GBP,myref0000023,pre,ecomm,

5473000000000007,01/09,,,530.01,GBP, myref0000024,auth,ecomm,

343434343434343,01/09,,,13.00,USD, myref0000025,pre,,

4936000000000000001,01/09,,2,9.95,GBP,

myref0000026,erp,ecomm,

6759000000000026,01/09,01/01,,44.36,GBP,

myref0000027,refund,ecomm,

5473000000000007,01/09,,,2000.00,GBP,

myref123,auth,ecomm,123456

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.6.3.6 csv_avs_card_txn

This CSV file format is similar to csv_card_txn format (section 2.6.3.5), but it also

allows AVS information to be provided with the Credit and Debit Card transactions if

required. CV2 information cannot be provided as the CV2 number should not be stored.

Fields for format csv_avs_card_txn

Element Name

Description

Values /

Limitations

1-10

As described in section 2.6.3.5

11

address_line_1

As described in section 2.4.1.1.2

O

12

address_line_2

O

13

address_line_3

O

14

address_line_4

O

15

postcode

O

16

policy_number

The Standard Policy against which the

transaction is to be checked against

See

website1

O2

1 While all of these values are valid, as only the AVS check can be carried out, only

policies 1 or 5 should be chosen.

2 The default policy registered against the account will be used if not value is set

Example csv_avs_card_txn file – two transactions for a total value

of 3.96

csv_avs_card_txn,batch_csv_avs_card_txn_2,99000001,mypasswd

4444333322221111,01/09,,,1.98,GBP,ABC123,auth,,,Flat 12,345 Main

Street,Putney,,A9 87XY,5

5473000000000007,01/09,,,1.98,GBP,ABC124,auth,ecomm,,Flat 12,345

Main Street,Putney,,X1 23AB,5

# Note: the line wrapping is this example should not

# be used in a real file

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.6.3.7 csv_chp_card_txn

This CSV file format is used for Cardholder Present transactions.

Fields for format csv_chp_card_txn

Element Name

Description

Values / Limitations

1-

7

As described in section 2.6.3.5

8

method

The transaction type

auth

refund

R

9

capturemethod

Indicates how the transaction

was accepted at the POS

keyed

swiped

R

10

authcode

The authorisation code

generated for the transaction

-

R

11

authcode_method

Indicates how the authcode

was obtained

terminal

online

telephone

O

12

cashback

The amount of cashback

required by the customer

Amount in

Major.Minor currency

units (i.e. 10.98)

O

13

tid

The Terminal ID (TID) used

for the transaction

DataCash will advise

R

14

hot_card_file

Indicates which Hot Card File

was used during the

transaction

none

reserved

Switch 400

Switch 8000

O

15

ic_reader

Whether the Terminal has

Chip reading capability

true

false

R

16

magnetic_stripe_reader

Whether the Terminal has

magnetic stripe reading

capability

true

false

R

17

manual_card_entry

Whether the Terminal has the

facility to enable card details

to be manually entered

true

false

R

18

pin_pad_available

Whether the Terminal has a

keypad to enable the PIN to

be entered

true

false

R

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example csv_chp_card_txn file containing three transactions with a value of

643

csv_chp_card_txn,batch_csv_chp_card_txn_0008,99000001,mypasswd

4444333322221111,01/09,,,99.99,GBP,myref0000023,refund,keyed,482135,ter

minal,

85621087,,true,true,true,true

5473000000000007,01/09,,,530.01,GBP,myref0000024,auth,swiped,955AU3,tel

ephone,

85621087,,true,true,true,true

343434343434343,01/09,,,13.00,USD,myref0000025,auth,swiped,FLDURN,termi

nal,

85621086,,true,true,true,true

# Note: the line wrapping is this example should not

# be used in a real file

2.6.3.8 csv_historic

This CSV file format is used for the Credit and Debit Card Services to complete two

stage processing using the fulfilltransaction and to perform cancel, txn_refund,

accept_fraud and authorize_referral_request transactions.

Fields for format csv_historic

Element

Name

Description

Values / Limitations

1

reference

DataCash unique reference of

the original transaction

-

R

2

method

The transaction type

fulfill

txn_refund

cancel

accept_fraud

authorize_referral_request

R

3

authcode

The authorisation code of the

original pre or erp

transaction, or the value

obtained from the Banks

Authorisation centre if the

transaction was referred.

For fulfill or

authorize_referral_request

only

R

4

amount

The value of the transaction

For fulfill or txn_refund only

O1

1 Transactions will be fulfilled/refunded for the full value of the original transaction if

this field is empty.

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example csv_historic file containing five transactions

with a value of 2501.00

csv_historic,batch_csv_historic_0008,99000001,mypasswd

# fulfill supplying amount

3000900100010005,fulfill,100000,1001.00

# cancel

3400900100010008,cancel,,

# fulfill, for the full value of the original txn

3800900100010025, ,100001,

# txn_refund, two refunds to the same original txn

3600900100010026,txn_refund,,1000.00

3600900100010026,txn_refund,,500.00

2.6.3.9 csv_prereg

This CSV file format allows the Pre-Registered Card Service to be utilised.

Fields for format csv_prereg

Element Name

Description

Values /

Limitations

1

merchant_ref

As described in section 2.7.1.1.2

R

2

reference

DataCash unique reference of the original transaction

R

3

amount

As described in section 2.7.1.1.5

R

4

currency

R

5

method

R

6

capturemethod

O

7

authcode

O

Example csv_prereg file containing three transactions for a

total value of 2023.34

csv_prereg,batch_csv_prereg_3,99000001,mypasswd

# card txns using card details from previous historic txns

prereg_230006,2185000198760000,1000.00,GBP,auth,ecomm,

prereg_230007,3200900100010014,1000.00,USD,refund,,

# using prereg to carry out manual auth of previous

# referred txn

prereg_230008,3700900100010021,23.34,GBP,pre,ecomm,123123

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.6.3.10 csv_dc_cc_account

This CSV file format enables the Direct Credit Card Collection Account Service to be

accessed.

Fields for format csv_dc_cc_account

Element Name

Description

Values / Limitations

1

merchant_ref

The reference number of the

drawdown

See limitations

R

2

pan

The card number

R

3

amount

The value to credit

Major.minor currency

units (i.e. (10.99)

R

4

card_name

The card holders name

O

5

expiry_date

The card expiry date

-

O

Example csv_dc_cc_account file containing two transactions

with a value of 20.00

csv_dc_cc_account,batch000134,99000001,mypasswd

valid_cardaccountpayment,4560720000000007,10.00,,

optional_fields,4560720000000007,10.00,MR FOO BAR,12/09

2.6.3.11 csv_dc_ddrefund

This CSV format supports Direct Credit ddrefund transactions.

Fields for format csv_dc_ddrefund

Element

Name

Description

Values / Limitations

1

merchant_ref

The reference number of the DDI

See limitations

R

2

reference

The datacash_reference of the

original transaction

-

R

3

amount

The amount to credit

Major.minor currency

units (i.e. (10.99)

R

Example csv_dc_ddrefund file containing two transactions with a

value of 25.00

csv_dc_ddrefund,batch000131,99000001,mypasswd

ddrefundABCD000345,10000003,10.00

45347ACBD,3400900100010008,15.00

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.6.3.12 csv_dc_std

This CSV format enables the Standard Direct Credit service to be used.

Fields for format csv_dc_standard

Element

Name

Description

Values / Limitations

1

merchant_ref

The reference number of the

drawdown

See limitations

R

2

amount

The value to credit

Major.minor currency units (i.e.

(10.99)

R

3

sort_code

The customer’s sort code

6 digits

R

4

acc_num

The customer’s account

number

-

R

5

acc_name

The customer’s account name

Maximum of 18 characters

R

6

bank_ref

See limitations

O

Example csv_dc_std file containing two transactions with a

value of 60.00

csv_dc_standard,batch000130,99000001,mypasswd

directcredit00006,30.00,826300,80000990,Bert Weiss,

credit00009,30.00,826300,80000990,Bert Weiss,Money for petrol

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.6.3.13 csv_dd_drawdown

This CSV file format supports drawdown transactions for the Standard Direct Debit

Service.

Fields for format csv_dd_drawdown

Element Name

Description

Values / Limitations

1

merchant_ref

The reference number of the

drawdown

See limitations

R

2

reference

The datacash_reference number of

the DDI

-

R

3

amount

The value to debit

Major.minor currency

units (i.e. (10.99)

R

4

duedate

The date to perform the drawdown

yyyymmdd format

O

5

bacs_tran_code

Enables the BACS transaction code

to be explicitly set

01

17

18

19

O

Example csv_dd_drawdown file containing three transactions

with a value of 30.00

csv_dd_drawdown,batch000130,99000001,mypasswd

drawdown_BE30006,10000003,10.00,,

drawdown_HI90135,10000004,10.00,20041212,

drawdown_JG00042,10000005,10.00,,18

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.6.3.14 csv_dd_setup

This CSV format is used for the Standard Direct Debit Service to perform setup and

presetup transactions.

Fields for format csv_dd_setup

Element Name

Description

Values / Limitations

1

merchant_ref

The reference number of the DDI

Must be of the format

agreed with your

Sponsoring bank. See

limitations.

R

2

sort_code

The sort code of the customer’s

bank

6 digits

R

3

acc_num

The customer’s account number

-

R

4

acc_name

The name of the account holder

Maximum of 18

characters

R

5

method

Determines the processing model to

be used

setup

presetup

R

6

active

Enables an existing setup to be

transferred to the DataCash system

true

O

7

type

Enables a non_AUDDIS DDI to be

converted to an AUDDIS DDI

conversion

O

Example csv_dd_setup file containing four transactions with a

value of 0.00 (no amount values present)

csv_dd_setup,batch000128,99000001,mypasswd

valid_setup,938611,02149187,MR F BAR,setup,,

setup_active,938612,02149188,MR A N OTHER,setup,true,

setup_conversion,938613,02149189,MR A N

OTHER,setup,,conversion

# DD presetup transaction

valid_presetup,938611,02149187,MR F BAR,presetup,,

valid_presetup456, 938611,02149236,”J, M & P

Smith“,presetup,,

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.6.3.15 csv_dd_setup_edit

This CSV file format is used with the Direct Debit Service to perform for confirm and

revoke transactions.

Fields for format csv_dd_setup_edit

Element

Name

Description

Values / Limitations

1

merchant_ref

The reference number of the DDI

As supplied for the

original

R

2

reference

The datacash_reference of the original

transaction

-

R

3

method

The operation required

confirm

revoke

R

Example csv_dd_setup_edit file containing four transactions

with a value of 0.00 (no amount values present)

csv_dd_setup_edit,batch000129,99000001,mypasswd

# confirm presetup with 8 digit Unique Reference

confirm_presetup,12345678,confirm

# revoke setup with 8 digit Unique Reference

revoke_setup,12345679,revoke

# confirm presetup with 16 digit DataCash Reference returned

by previous query response

confirm_presetup2,3400900100010008,confirm

# revoke previous setup in the same batch

revoke_previous_setup,3400900100010008,revoke

Back to Contents

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.7 CARD HOLDER PRESENT

2.7.1 Chip and Pin

A technical introduction to this service is available on the website:

http://www.datacash.com/gettingproducts.php?id=Chip-PIN

2.7.1.1 Schema Elements for Request

As different fields may be presented in different situations, each field will be labelled

with the following key:

 O - Optional

 R - Required, field must be presented

 M – Mandatory, field must be presented if it is available

 X – Excluded, field is excluded in specific situations

Transactions with Card Details

The creditcheck and auth transaction types require certain information to be

presented. This is passed in several places in the schema:

 Request

o Authentication – section 2.1.1.2

o Transaction

 TxnDetails - section 2.7.1.1.1

 CardTxn – section 2.7.1.1.2

 Card – section 2.7.1.1.5

 ICC – section 2.7.1.1.4

 Terminal – section 2.7.1.1.3

Historic Transactions

The cancel and authorize_referral_request transaction types require information

to be passed in:

 Request

o Authentication – section 2.1.1.2

o Transaction

 HistoricTxn - section 2.4.3.1.9

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.7.1.1.1 TxnDetails

Element Name:

TxnDetails

Position:

Request.Transaction

Elements of TxnDetails

Element Name

Description

Values /

Limitations

Required?

merchantreference

A unique reference number to

distinguish each transaction

See Answer

R

amount

The value of the transaction

R

capturemethod

Indicates how the transaction was

accepted at the POS

parked

keyed

swiped

R

Attributes of TxnDetails

Attribute

Name

Attribute of

element

Description

Required?

cashback

amount

The amount of cashback requested by the

customer (Cannot be supplied with

cashadvance attribute)

O

cashadvance

amount

Indicates whether the transaction was a

Cash Advance (Cannot be supplied with

cashback attribute)

O

Example XML for TxnDetails element

<capturemethod>parked</capturemethod>

</TxnDetails>

<capturemethod>swiped</capturemethod>

</TxnDetails>

<capturemethod>swiped</capturemethod>

</TxnDetails>

2.7.1.1.2 CardTxn

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Element Name:

CardTxn

Position:

Request.Transaction

Elements of CardTxn

Element Name

Description

Values /

Limitations

Keyed

Swiped

Parked

authcode

The authorisation code,

if on-line authorisation

is not required

See note

below

O

X

Card

See section 2.7.1.1.5

R

X

card_details

Data read from the

magnetic stripe of the

card, or equivalent

from the ICC

Must be

Base64

encoded

-

X

hotcardfile

Indicates which Hot

Card File was used

during the transaction

-

O

ICC

See section 2.7.1.1.4

-

R

method

The transaction

method

auth

creditcheck

R

reason_online_code

For on-line transactions: the reason

for being on-line. As defined by APACs

O

Terminal

See section 2.7.1.1.3

R

Note: For swiped and parked transactions, card details may be presented in either the

Card element or the card_details element:

1. The Card element is required if an authorisation code is submitted.

2. The card_details element is required if the authorisation code is not

submitted.

Attributes of CardTxn

Attribute Name

Attribute of

element

Description

Values / Limitations

Required?

method

authcode

Indicates how the

authcode was

obtained.

Must be present if

authcode element is

presented:

online

terminal

telephone

R

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

auth_datetime

authcode

The actual date &

time of the

transaction

As a unixtimestamp

R1

type

card_details

Indicates the type

of data

track2_data

R

1 Field is required for merchants using NatWest Streamline. For other Acquiring Banks

this field is optional.

Example XML for CardTxn element, for a parked transaction

<card_details type="track2_data">

NDkyOTQ5ODMxMTQwMDAwMj0wODAzMjAxMDA5ODgwMDAwMDAwMR8wMA==

</card_details>

<method>creditcheck</method>

<reason_online_code>10</reason_online_code>

</CardTxn>

Example XML for CardTxn element, for a swiped transaction without an

authcode

<card_details type="track2_data">

NDkyOTQ5ODMxMTQwMDAwMj0wODAzMjAxMDA5ODgwMDAwMDAwMR8wMA==

</card_details>

<method>creditcheck</method>

</CardTxn>

Example XML for CardTxn element, for a swiped or

parked transaction with authcode

<method>creditcheck</method>

<authcode method="terminal"

auth_datetime="1164821283">451576</authcode>

</CardTxn>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example XML for CardTxn element, for a keyed transaction

</CardTxn>

2.7.1.1.3 Terminal

Element Name:

Terminal

Position:

Request.Transaction.CardTxn

Elements of Terminal

Element Name

terminal_capabilities

features_capabilities

message_capabilities

Attributes of Terminal and its children

Attribute Name

Attribute of

element

Description

Values

Required?

id

Terminal

The terminal or TID

number

DataCash

will advise

R

ic_reader

terminal_

capabilities

Chip reading

functionality

true

false

R

magnetic_stripe_

reader

terminal_

capabilities

Magnetic stripe

reading functionality

true

false

R

manual_card_

entry

terminal_

capabilities

Facility to manually

enter card details

true

false

R

cardholders_

device

features_

capabilities

Cardholder’s device

(eg. personal

computer, mobile

phone, digital TV or

similar device)

true

false

O

card_capture_

device

features_

capabilities

Terminal or operator

able to capture cards

true

false

O

pin_pad_

available

features_

capabilities

Keypad to enable PIN

to be entered

true

false

R

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

unattended_

device

features_

capabilities

Indicates whether

transaction is

processed from an

unattended terminal

true

false

O

downline_load_

floor_limit

message_

capabilities

As per APACS

standard 70 book 2

appendix A.9

true

false

O

downline_

load_referral

message_

capabilities

true

false

O

hold_capability

message_

capabilities

true

false

O

response_additional

_data_support

message_

capabilities

true

false

O

Example XML for Terminal element

<terminal_capabilities ic_reader="true"

magnetic_stripe_reader="true"

manual_card_entry="true"/>

<features_capabilities pin_pad_available="true"/>

<message_capabilities downline_load_floor_limit="false"

downline_load_referral="false"

hold_capability="false"

response_additional_data_support="true"/>

</Terminal>

2.7.1.1.4 ICC

This parent element contains the data relating to the Chip & Pin functionality. All

elements within this parent are mandatory. Please refer to APACS29 v18 (page 77) and

APACS30 v18 (page 73) for definitions of these elements.

Element Name:

ICC

Position:

Request.Transaction.CardTxn

2.7.1.1.5 Card

This element is only required for keyed transactions.

Element Name:

Card

Position:

Request.Transaction.CardTxn

Elements of Card

Element Name

Description

Values / Limitations

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

pan

The card number

Must be a valid card

number

R

expiry_date

expiry date for the card

MM/YY format

R

start_date

start date for the card

MM/YY format

M

issue_number

issue number of the card

One or two digits

M

Example XML for Card element

<Card>

</Card>

<Card>

</Card>

2.7.1.1.6 HistoricTxn

This element should be presented for cancel or authorize_referral_request

transactions only.

Element Name:

HistoricTxn

Position:

Request.Transaction

Elements of HistoricTxn

Element Name

Description

Values / Limitations

cancel

authorize

_referral

_request

method

The transaction type

cancel

authorize_referra

l_request

R

datacash_reference

The

datacash_reference

of the transaction to

be cancelled

Must be valid

transaction

R

authcode

Value received from

Banks Authorisation

centre

X

R

Attributes of Elements in HistoricTxn

Attribute Name

Attribute

of

element

Description

Values / Limitations

cancel

authorize

_referral

_request

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

reversal

method

Indicates

whether a

reversal should

be attempted

true

false

O

X

method

authcode

Indicates how

the authcode

was obtained.

online

terminal

telephone

X

R

auth_datetime

authcode

The actual date

& time of the

transaction

As a unixtimestamp

X

R1

1 Field is required for merchants using NatWest Streamline. For other Acquiring Banks

this field is optional.

Example XML for HistoricTxn element

<method reversal="true">cancel</method>

</HistoricTxn>

<method>cancel</method>

</HistoricTxn>

<method>authorize_referral_request</method>

</HistoricTxn>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.7.1.2 Example XML Requests

Example XML Request for a parked transaction

<password>mypasswd</password>

</Authentication>

<merchantreference>57483573457gegrreg</merchantreference>

<capturemethod>parked</capturemethod>

</TxnDetails>

<terminal_capabilities ic_reader="true"

magnetic_stripe_reader="true" manual_card_entry="true"/>

<features_capabilities pin_pad_available="true"/>

</Terminal>

<reason_online_code>10</reason_online_code>

<card_details type="track2_data">NDkyOTQ5ODMxMTQwMDAwMj

0wODAzMjAxMDA5ODgwMDAwMDAwMR8wMA==</card_details>

<ICC>

<seq_or_issue_number>00</seq_or_issue_number>

<crypto_tran_type>00</crypto_tran_type>

<txn_currency_code>826</txn_currency_code>

<term_country_code>826</term_country_code>

<issuer_app_data>06FE0A03A4A800</issuer_app_data>

<crypto_info_data>80</crypto_info_data>

<term_app_ver_no>0084</term_app_ver_no>

<term_capabilities>7546</term_capabilities>

</ICC>

<method>creditcheck</method>

</CardTxn>

</Transaction>

</Request>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example XML Request for a swiped transaction

<password>mypasswd</password>

</Authentication>

<capturemethod>swiped</capturemethod>

</TxnDetails>

<terminal_capabilities magnetic_stripe_reader="true"

manual_card_entry="true" ic_reader="true"/>

<features_capabilities pin_pad_available="true"/>

</Terminal>

<card_details type="track2_data">OzQ5Mjk0OTgzMTE0MDAwMDI9MDg

wMzIwMTAwOTg4MDAwMDAwMDE/Pw==</card_details>

<method>creditcheck</method>

</CardTxn>

</Transaction>

</Request>

Example XML Request for a cancellation

<password>mypasswd</password>

</Authentication>

<method reversal="true">cancel</method>

</HistoricTxn>

</Transaction>

</Request>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.7.1.3 Schema Elements for Response

2.7.1.3.1 Response

The following additional elements returned in the Response element. Please refer to

section 2.1.1.3 for descriptions of the general elements.

Additional Elements of Response

Element Name

Description

referral_tel_no

As described in the APACS30 Response

floorlimit

issuer_auth_data

issuer_script_data

authorising_entity

Indicates (where available) the party who provided the

authorisation. Only returned for creditcheck transactions. The

returned value will be one of:

 card acceptor

 acquirer

 card scheme

 card issuer

Attributes of Elements in Response

Attribute Name

Attribute of element

Description

reversal

reason

Indicates the status of reversal requests

2.7.1.4 Example XML Responses

Example XML Response to an auth or creditcheck

<acquirer_message>AUTH CODE:100100</acquirer_message>

<acquirer_response_code>00</acquirer_response_code>

<card_scheme>VISA</card_scheme>

<country>United Kingdom</country>

</CardTxn>

<datacash_reference>…</datacash_reference>

<floor_limit>020</floor_limit>

<reason>ACCEPTED</reason>

<referral_telephone_number>MDIyMjQ0=</referral_telephone_number>

</Response>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example XML Responses to Cancellation Requests

<datacash_reference>…</datacash_reference>

<information>Too much time has elapsed between the original

txn and the reversal request.</information>

<reason reversal="not attempted">CANCELLED OK</reason>

</Response>

<datacash_reference>…</datacash_reference>

<information>Reversal ACCEPTED status=1

authcode=100100</information>

<reason reversal="success">CANCELLED OK</reason>

</Response>

Example XML Response for an authorize_referral_request

<datacash_reference>…</datacash_reference>

<reason>ACCEPTED</reason>

</Response>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.7.2 Preallocated References

Additional non-technical information about this service is available on the website:

http://www.datacash.com/gettingproducts.php?id=Pre-allocated-Reference-

Transactions-Chip-PIN-

2.7.2.1 Schema Elements for Request

In this section the fields required to preallocate references will be given.

Preallocations

The information required to preallocate a DataCash reference is passed in two places in

the schema:

 Request

o Authentication – section 2.1.1.2

o Transaction

 TxnDetails – contains the merchants reference, section 2.7.2.1.1

 CardTxn – contains the mehod allocate_reference

Performing Transactions

The information required to use a preallocated transaction is very similar to a normal

transaction:

 Request

o Authentication – section 2.1.1.2

o Transaction

 TxnDetails – section 2.7.2.1.1

 CardTxn – section 2.7.1.1.2

 Card – section 2.7.1.1.5

 ICC – section 2.7.1.1.4

 Terminal – section 2.7.1.1.3

Cancellations and Reversals

The cancel transaction type is the same as for the normal CHP transactions:

 Request

o Authentication – section 2.1.1.2

o Transaction

 HistoricTxn – section 2.4.3.1.9

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.7.2.1.1 TxnDetails

These elements are only required for payments made with the allocated reference –

they are not required for the allocate_reference transactions.

Element Name:

TxnDetails

Position(s)

Request.Transaction

Elements of TxnDetails

Element Name

Description

Values /

Limitations

allocated_reference

The datacash_reference returned from

an allocate_reference transaction

16 digit number

amount

The value of the transaction

Example XML Element TxnDetails for a preallocated reference transaction

<allocated_reference>3000100012345671</allocated_reference>

</TxnDetails>

2.7.2.1.2 CardTxn

This section shows the fields required for the allocate_reference transactions. Please

refer to section 2.7.1.1.2 for those required for auth and creditcheck transactions.

Element Name:

CardTxn

Position(s)

Request.Transaction

Elements of CardTxn

Element Name

Description

Values / Limitations

method

The transaction type

allocate_reference

Example XML CardTxn element

<method>allocate_reference</method>

</CardTxn>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.7.2.2 Example Request

Example XML Request for allocate_reference

</TxnDetails>

<method>allocate_reference</method>

</CardTxn>

</Transaction>

</Request>

Example XML Request

<allocated_reference>4800200040913907</allocated_reference>

<capturemethod>parked</capturemethod>

</TxnDetails>

<terminal_capabilities ic_reader="true"

magnetic_stripe_reader="true" manual_card_entry="true"/>

<features_capabilities pin_pad_available="true"/>

</Terminal>

<card_details type="track2_data">NDkyOTQ5ODMxMTQwMDAwMj

0wODAzMjAxMDA5ODgwMDAwMDAwMR8wMA==</card_details>

<ICC>

<reason_online_code>10</reason_online_code>

<seq_or_issue_number>00</seq_or_issue_number>

<crypto_tran_type>00</crypto_tran_type>

<txn_currency_code>826</txn_currency_code>

<term_country_code>826</term_country_code>

<issuer_app_data>06FE0A03A4A800</issuer_app_data>

<crypto_info_data>80</crypto_info_data>

<term_app_ver_no>0084</term_app_ver_no>

<term_capabilities>7546</term_capabilities>

</ICC>

<method>creditcheck</method>

</CardTxn>

</Transaction>

</Request>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.7.2.3 Schema Elements for Response

The response to transactions performed using this service contains no fields beyond the

CHP response elements, covered in section 2.1.1.3

2.7.2.4 Example Response

Example XML Request for an allocate_reference request

<datacash_reference>3000100012345671</datacash_reference>

<reason>ACCEPTED</reason>

</Response>

Back to Contents

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.8 OTHER DPG SERVICES

2.8.1 PayPal

This service allows you to process Express Checkout and Auth and Capture PayPal

transactions via your DataCash account. Successful payments can be refunded back to

the customer's PayPal account. The service can be seamlessly integrated into your

systems, enabling your customers and Customer Service teams to experience fast and

efficient processing and management of transactions.

An introduction to this service, including the transaction types, is available on the

website:

http://www.datacash.com/gettingproducts.php?id=PayPal---Express-Checkout

2.8.1.1 Schema Elements for Request

In this section the required fields for each transaction type will be presented, along

with example XML for those fields.

The data for the PayPal Service is passed in these distinct places in the schema:

 Request

o Authentication – section 2.1.1.2

o Transaction

 TxnDetails – section 2.8.1.1.1

 PayPalTxn – this section contains all of the details specific to the PayPal transaction,

see section 2.8.1.1.2

 Items – details of all items in the order, section 2.8.1.1.4

o Item – details of each item within the order, section 2.8.1.1.5

 ShippingAddress - details of the shipping address, section 2.8.1.1.6

 AirlineItineraryData – details of flights for Airline transactions, section 2.8.1.1.7

o FlightDetails – details of flight legs, section 2.8.1.1.8

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.8.1.1.1 TxnDetails

Note that most fields are only available for specific transaction types.

 S – set_express_checkout

 G – get_express_checkout_details

 D – do_express_checkout_payment

 X – txn_refund, used to perform refunds of existing payments

 A – do_authorization

 C – do_capture

 CB – create_billing_agreement

 UB – update_billing_agreement

 DR – do_reference_transaction

Element Name:

TxnDetails

Position(s)

Request.Transaction

Elements of TxnDetails

Element Name

Description

Values / Limitations

Required

S

G

D

X

A

C

CB

UB

DR

amount

The value of

the transaction

May be ‘0’ only for D,

where a Billing

Agreement is to be

created with no

initial payment

taken. For DR it may

be ‘0’ for S if no

initial payment is to

be taken.

R

-

R

O

R

-

R

merchantreference

A unique

reference

number for

each

transaction

Minimum 6,

maximum 30

alphanumeric

characters. Must be

unique

R

O

-

R

For a txn_refund, an amount may be specified if the refund is for a smaller amount

than the original transaction. The value must be less than or equal to the value of the

original transactions, minus any previous partial refunds.

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Attributes of elements of TxnDetails

Attribute

name

Attribute of

Element

Description

Values / Limitations

currency

amount

The currency for

the payment

AUD

CAD

CHF

CZK

DKK

EUR

GBP

HKD

HUF

JPY

NOK

NZD

PLN

SEK

SGD

USD

May not be specified for

txn_refund,

do_authorization or

do_capture

Example XML for TxnDetails element

</TxnDetails>

<merchantreference>46548tretr</merchantreference>

</TxnDetails>

2.8.1.1.2 PayPalTxn

All data specifically relating to PayPal transactions are submitted in this element and

associated sub-elements. Note that most fields are only available for specific

transaction types.

 S – set_express_checkout

 G – get_express_checkout_details

 D – do_express_checkout_payment

 R – txn_refund

 A – do_authorization

 C – do_capture

 V – do_void

 CB – create_billing_agreement

 UB – update_billing_agreement

 DR – do_reference_transaction

Element Name:

PayPalTxn

Position(s)

Request.Transaction

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Elements of PayPalTxn

Element Name

Description

Values / Limitations

Required

S

G

D

R

A

C

V

C

B

UB

D

R

cancel_url

URL to which the

customer is returned

if (s)he does not

approve the use of

PayPal

URL should be URL-encoded

R

-

method

The transaction type

set_express_checkout

get_express_checkout_

details

do_express_checkout_

payment

txn_refund

do_authorization

do_capture

do_void

create_billing_

agreement

update_billing_agreement

do_reference_transaction

R

reference

The 16 digit

datacash_reference,

referring to a previous

successfully processed

transaction

G uses ref from S

D uses ref from S

R uses ref from either D or C

A uses ref from S

C uses ref from A

V uses ref from A (or D when

payment_action is order)

CB uses ref from S

UB uses ref from D or CB

DR uses ref from D or CB

-

R

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

return_url

URL to which the

customer’s browser is

returned.

Recommended to be

the final review page

on which the customer

confirms the order

and payment/billing

agreement

URL should be URL-encoded

R

-

billing_type

Type of billing

agreement.

MerchantInitiatedBilling –

creates a billing agreement

even if there is an existing

billing agreement

MerchantInitiatedBillingSi

ngleSource – creates a billing

agreement only if there is no

existing billing agreement with

the buyer

R

-

billing_agreement_st

atus

The new/current

status of the billing

agreement

Active

Cancelled

Note: an agreement which has

a status of Cancelled can not

be further updated.

-

O

-

billing_agreement_de

scription

Description of goods

or services associated

with the billing

agreement

127 single-byte characters

O

-

O

-

billing_agreement_cu

stom

Custom annotation

field for your own use

255 single-byte characters

O

-

O

-

buttonsource

An identification code

for use by third party

applications to identify

transactions

32 single-byte alphanumeric

characters

-

O

-

channel_type

Type of channel

Merchant – non-auction seller

eBayItem - ebay auction

O

-

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

completed

Indicates the final

do_capture being

processed against a

successful

do_authorization,

thus completing the

authorisation

Yes

-

O

-

custom

A free-form field for

your own use, such as

a tracking number of

other value you want

PayPal to return on

get_express_checkou

t_details and

do_express_checkout

_payment

255 single-byte alphanumeric

characters

O

-

O

-

O

description

Description of the

items the customer is

purchasing

127 single-byte characters

O

-

O

-

O

email

Email address of the

buyer. Used to pre-fill

the PayPal

membership sign-up

portion of the PayPal

login page

O

-

O

handling_total

Total handling costs

for this order

-

O

-

O

header_style

Defines the image,

border colour and

background colours

for the image in the

header of the

payment page.

Header space is 750px

wide by 90 px high.

See attributes table below

O

-

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

invnum

Your own unique

invoice or tracking

number. Is returned

in the

do_express_checkout

_payment response

O

-

O

-

O

-

O

Items

Please refer to section

2.8.1.1.5

Alphanumerics

- (dash)

* (asterisk)

. (period)

{space}

-

O

-

item_total

Sum of cost of all

items in this order

Numeric with two decimal

places. Must not exceed

$10,000 in any currency. Max

value 9,999,999.99

-

O

-

O

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

localecode

Locale of pages

displayed by PayPal

during checkout

Character length and

limitations: 2-character

country code

 AU – Australia

 AT – Austria

 BE – Belgium

 BR – Brazil

 CA – Canada

 CH – Switzerland

 CN – China

 DE – Germany

 ES – Spain

 GB – United Kingdom

 FR – France

 IT – Italy

 NL – Netherlands

 PL – Poland

 PT – Portugal

 RU – Russia

 US – United States

The following 5-character

codes are also supported for

languages in specific

countries:

 da_DK – Danish (for

Denmark only)

 he_IL – Hebrew (all)

 id_ID – Indonesian (for

Indonesia only)

 jp_JP – Japanese (for

Japan only)

 no_NO – Norwegian

(for Norway only)

 pt_BR – Brazilian

Portuguese (for

Portugal and Brazil

only)

 ru_RU – Russian (for

Lithuania, Latvia, and

Ukraine only)

 sv_SE – Swedish (for

Sweden only)

 th_TH – Thai (for

Thailand only)

 tr_TR – Turkish (for

Turkey only)

 zh_CN – Simplified

Chinese (for China

only)

O

-

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

 zh_HK – Traditional

Chinese (for Hong Kong

only)

 zh_TW – Traditional

Chinese (for Taiwan

only)

For the most current list,

please refer to the following

link:

https://cms.paypal.com/us/cgi

-bin/?cmd=_render-

content&content_ID=develope

r/e_howto_api_nvp_r_SetExpr

essCheckout

max_amount

The expected

maximum total

amount of the

complete order,

including shipping and

tax

Numeric with two decimal

places. Must not exceed

$10,000 in any currency. Max

value 9,999,999.99

O

-

no_shipping

Indicates whether the

shipping address fields

should be displayed

on the PayPal pages

0 - fields displayed (default)

1 - fields not displayed

O

-

note

Custom memo about

the refund

255 single-byte alphanumeric

characters

22 single-byte characters

comprised of:

Alphanumerics

- (dash)

* (asterisk)

. (period)

{space}

-

O

-

O

-

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

notify_url

Your URL for receiving

Instant Payment

Notification (IPN)

about this transaction

2048 single-byte alphanumeric

characters

-

O

-

O

override_address

Indicates whether the

shipping address fields

(as set by you) should

be displayed on the

PayPal pages, rather

than the shipping

address details held

on file at PayPal

0 – displays details held on file

(default)

1 – displays details set by you

O

-

payment_action

Specifies the type of

PayPal service to use

`sale` - will

use Express Checkout

instant payment

(default)

`order` - will use

Auth Capture

sale (default)

order

order must be supplied during

S for Auth and Capture txns.

An order may be converted to

a sale during the D txn.

For Auth and Capture must be

order for S

may be order for D, or sale if

wishing to convert the existing

txn

O

-

O

-

O

page_style

Sets the Custom

Payment Page Style of

the payment pages.

This corresponds to

the HTML variable

page_style for

customising payment

pages

Value must be equal to the

Page Style Name as chosen by

you when adding/editing the

page style from the My

Profile  Profile subtab of

your PayPal Account

O

-

payment_type

Specifies type of

PayPal payment you

require for the billing

agreement

Any

InstantOnly

O

-

req_billing_address

Specifies whether you

require the customers

billing address from

PayPal. This is

returned the

get_express_checkou

t_details response.

0 – Billing address not

required (default)

1 – Billing address required

O

-

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

req_confirmed_shippi

ng

Indicates whether the

customer’s shipping

address on file with

PayPal must be a

confirmed address

0 – need not be confirmed

(default)

1 – must be confirmed

O

-

shipping_total

Total shipping cost for

this order

-

O

-

O

soft_descriptor

Per transaction

description of the

payment that is

passed to the

consumer’s credit card

255 single-byte alphanumeric

characters

22 single-byte characters

comprised of:

Alphanumerics

- (dash)

* (asterisk)

. (period)

{space}

-

O

-

O

solution_type

Type of checkout flow

Sole – for Express Checkout

auctions

Mark – normal Express

Checkout

O

-

tax_total

Sum of tax for all

items in this order

255 single-byte alphanumeric

characters

22 single-byte characters

comprised of:

Alphanumerics

- (dash)

* (asterisk)

. (period)

{space}

-

O

-

O

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

token

Time stamped token –

token expires after

three hours

Normally this is

generated by PayPal

and does not need to

be supplied.

20 single-byte characters max

O

-

ShippingAddress

Please refer to section

2.8.1.1.6

255 single-byte alphanumeric

characters

22 single-byte characters

comprised of:

Alphanumerics

- (dash)

* (asterisk)

. (period)

{space}

-

O

-

AirlineItineraryData

Please refer to section

2.8.1.1.7

-

O

-

O

Attributes for Elements of PayPalTxn

Attribute Name

Attribute of element

Value / limitations

Require

d

bgcolor

header_style

Background colour for the payment page header. Six

character HTML hexadecimal colour code in ASCII.

O

bordercolor

header_style

Sets the colour of the 2px border around the header

of the payment page. Six character HTML

hexadecimal colour code in ASCII.

O

img

header_style

URL of the image to appear on the top left of the

payment page. Max image size 750px wide by 90px

high. Recommended to be HTTPS link. 127 single-

byte characters max, URL-encoded.

O

stylename

page_style

Used to select the style of checkout pages. Styles are

configurable in PayPal account settings.

O

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example XML for PayPal elements

<method>set_express_checkout</method>

<return_url>https://www.example.com/myshoppingcard?action=

complete&sale_id=xyz123/</return_url>

<cancel_url>https://www.example.com/myshoppingcard?action=

cancel&sale_id=xyz123/</cancel_url>

<payment_action>order</payment_action>

</PayPalTxn>

Example XML for PayPal elements for txn_refund

<method>txn_refund</method>

</PayPalTxn>

<method>txn_refund</method>

<note>Refund of half the order, as promised</note>

</PayPalTxn>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example XML for PayPal elements for do_authorization

<method>do_authorization</method>

</PayPalTxn>

Example XML for PayPal elements for get_express_checkout_details

<method>get_express_checkout_details</method>

</PayPalTxn>

Example XML for PayPal elements for do_express_checkout_payment

<method>do_express_checkout_payment</method>

</PayPalTxn>

<method>do_express_checkout_payment</method>

<description>Twenty NeverFail(tm) Widgets</description>

<buttonsource>foobar</buttonsource>

<notify_url>http://www.example.com/mynotifyurl?id=abc123/

</notify_url>

<item_total>85.00</item_total>

<shipping_total>10.00</shipping_total>

<handling_total>5.00</handling_total>

<tax_total>11.97</tax_total>

</PayPalTxn>

<method>do_express_checkout_payment</method>

</PayPalTxn>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example XML for PayPal elements for do_capture

<method>do_capture</method>

</PayPalTx

<method>do_capture</method>

<note>Finally, I have captured some funds</note>

<soft_descriptor>FooCorp LLC</soft_descriptor>

</PayPalTxn>

<method>do_capture</method>

<note>This is the last capture for this

authorization</note>

<soft_descriptor>FooCorp LLC</soft_descriptor>

</PayPalTxn>

Example XML for PayPal elements for do_void

</PayPalTxn>

<note>Excess funds released</note>

</PayPalTxn>

Example XML for PayPal elements for create_billing_agreement

<method>create_billing_agreement</method>

</PayPalTxn>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example XML for PayPal elements for update_billing_agreement

<method>update_billing_agreement</method>

<billing_agreement_status>Cancelled

</billing_agreement_status>

</PayPalTxn>

<method>update_billing_agreement</method>

<billing_agreement_description>Subscription to FOO

Magazine</billing_agreement_description>

<billing_agreement_custom>Part of our CHEAP09

promotion</billing_agreement_custom>

</PayPalTxn>

2.8.1.1.3 Example XML for PayPal elements for do_reference_transaction

<method>do_reference_transaction</method>

<description>Twenty NeverFail(tm) Widgets</description>

<buttonsource>foobar</buttonsource>

<notify_url>http://www.example.com/mynotifyurl?id=abc123/

</notify_url>

<item_total>85.00</item_total>

<shipping_total>10.00</shipping_total>

<handling_total>5.00</handling_total>

<tax_total>11.97</tax_total>

</PayPalTxn>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.8.1.1.4 Items

The Items element is optional. It contains an Item child element for each individual

product or service purchased.

Element Name:

Items

Position(s)

Request.Transaction.PayPalTxn

Elements of Items

Element Name

Description

Values /

Limitations

Required

S

G

D

R

DR

Item

See section 2.8.1.1.5

-

O

-

O

Example XML for Items element

<Items>

</Items>

2.8.1.1.5 Item

The Item elements contain details of each product within the order.

Element Name:

Item

Position(s)

Request.Transaction.PayPalTxn.Items

Elements of Item

Element Name

Description

Values /

Limitations

Required

S

G

D

R

DR

amount

Cost of item

Must not exceed

$10,000 in any

currency. Max value

9,999,999.99

-

O

-

O

ebay_item_auction_

txn_id

Auction transaction

identification number

225 single-byte

characters

-

O

-

O

ebay_item_number

Auction item number

765 single-byte

characters

-

O

-

O

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

ebay_item_order_id

Auction identification

number

64 single-byte

characters

-

O

-

O

name

The item name

127 single-byte

characters

-

O

-

O

number

The item number

-

O

-

O

quantity

The item quantity

Positive integer

-

O

-

O

taxamt

Item sales tax

Must not exceed

$10,000 in any

currency. Max value

9,999,999.99

-

O

-

O

Attributes for Elements of Item

Attribute Name

Attribute of

element

Value / Limitations

Required

id

Item

Must start from 0 and be

contiguous

R

Example XML for Item elements for do_express_checkout_payment

<name>Widgets</name>

</Item>

Example XML for Item elements for do_express_checkout_payment

<ebay_item_number>9988775544</ebay_item_number>

<ebay_item_auction_txn_id>123456123</ebay_item_auction_txn_id>

<ebay_item_order_id>abc123def890</ebay_item_order_id>

</Item>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.8.1.1.6 ShippingAddress

This parent element is used to present information about the shipping address. While

the parent element itself is optional, if it is sent certain elements must be provided.

Element Name:

ShippingAddress

Position(s)

Request.Transaction.PayPalTxn

Elements of ShippingAddress

Element Name

Description

values /

limitations

Required

city

The name of the city

40 single-byte

characters max

R

country_code

The country code, as

defined in ISO 3166-1

2 character

R

name

The person’s name

associated with the

shipping address

32 single-byte

characters max

R

postcode

UK postcode, US ZIP

code or other country-

specific postal code

20 single-byte

characters max

R

region

The state, province or

region

40 single-byte

characters max

R for US

addresses

only

street_address1

The first line of the

address

100 single-byte

characters max

R

street_address2

The second line of the

address

100 single-byte

characters max

O

telephone_number

Phone number

20 single-byte

characters max

O

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example XML for ShippingAddress elements

<name>Joe Bloggs</name>

<street_address1>3 Fish Street</street_address1>

<street_address2>Castle Street</street_address2>

<country_code>GB</country_code>

<telephone_number>01234 345 6789</telephone_number>

</ShippingAddress>

<name>John Smith</name>

<street_address1>144 Main Street</street_address1>

<country_code>US</country_code>

</ShippingAddress>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.8.1.1.7 AirlineItineraryData

This parent element is used to present flight data for Airline transactions. While this

element itself is optional, if it is sent then certain elements must be provided.

This element is supported for the following transaction types, depending on the value

of the payment_action element.

 D – do_express_checkout_payment

 C – do_capture

Where the payment_action of a transaction is sale, Airline data should be provided in

the do_express_checkout_payment request.

Where the payment_action is order, Airline Data should be provided in the do_capture

request.

Element Name:

AirlineItineraryData

Position(s)

Request.Transaction.PayPalTxn

Elements of AirlineItineraryDetails

Element Name

Description

Values / Limitations

Required

D

C

clearing_count

Numeric code to identify each

clearing record message in

those cases where multiple

clearing messages are

allowed per authorized

transaction. Applicable to

multiple captures against an

authorization. In the case of

single capture against an

authorization, the value

should be 1

Positive integer

R

clearing_sequence

Numeric code to identify each

clearing record message in

cases where multiple clearing

messages are allowed per

authorised transaction.

Applicable to multiple

captures against an

authorisation. In the case of

single capture against an

authorisation, the value

should be 1

Positive integer

R

FlightDetails

Please refer to section 2.8.1.1.8

-

R

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

issuing_carrier_code

Airline code for the airline

issuing the ticket. Obtain the

airline code from the official

Airline Guide or its equivalent

4 single-byte

characters max

R

passenger_name

Name of the passenger

25 single-byte

characters max

R

restricted_ticket

Indicated whether the ticket

is restricted (refundable)

0 – Ticket is not

restricted

1 – Ticket is restricted

R

ticket_number

The ticket number. If

multiple tickets are

purchased with one

transaction, you should

provide the primary ticket

number

16 single-byte

characters max

R

customer_code

A code that the cardholder

supplied to you. Can be used

for passing in the frequent

flyer number of the customer

17 single-byte

characters max

O

issue_date

Date of issue recorded in the

airline system. In case of

multiple issuances of the

same ticket, use the last

ticket date

YYYYMMDD format

O

total_fare

Total fare for all legs on this

ticket, excluding taxes and

fees

Numeric with two

decimal places. Must

not exceed $10,000 in

any currency. Max

value 9,999,999.99

O

total_fee

Total fee for all legs on the

ticket

O

total_taxes

Total taxes for all legs on the

ticket

O

travel_agency_code

The travel agency code. In an

integration by the airline, this

is the airline code from the

official Airline Guide or its

equivalent

8 single-byte

characters max

O

travel_agency_name

Name of the travel agency

issuing the ticket. In an

integration by an airline, this

is the airline name

25 single-byte

characters max

O

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example XML for AirlineItineraryData elements

<passenger_name>Joseph Bloggs</passenger_name>

<issue_date>20090701</issue_date>

<travel_agency_name>Super Agents</travel_agency_name>

<travel_agency_code>SUPER1</travel_agency_code>

<ticket_number>BLAH1234567890</ticket_number>

<issuing_carrier_code>ABCD</issuing_carrier_code>

<customer_code>JBLOGGS09713</customer_code>

<total_fare>85.00</total_fare>

<total_taxes>10.00</total_taxes>

<total_fee>5.00</total_fee>

<restricted_ticket>0</restricted_ticket>

<clearing_sequence>1</clearing_sequence>

<clearing_count>1</clearing_count>

...

</FlightDetails>

...

</FlightDetails>

</AirlineItineraryData>

<passenger_name>Joseph Bloggs</passenger_name>

<ticket_number>BLAH1234567890</ticket_number>

<issuing_carrier_code>ABCD</issuing_carrier_code>

<restricted_ticket>0</restricted_ticket>

<clearing_sequence>1</clearing_sequence>

<clearing_count>1</clearing_count>

...

</FlightDetails>

</AirlineItineraryData>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.8.1.1.8 FlightDetails

The FlightDetails elements contain details of each leg of the trip.

Element Name:

FlightDetails

Position(s)

Request.Transaction.PayPalTxn.AirlineItineraryData

Elements of FlightDetails

Element Name

Description

Values /

Limitations

Requir

ed

D

C

arrival_airport_code

The arrival airport code. Obtain

the code from the official Airline

Guide or its equivalent

5 single-byte

characters max

R

carrier_code

Standard abbreviation for airline

carrier. Obtain the code from the

official Airline Guide or its

equivalent

2 single-byte

characters

R

departure_airport_cod

e

The departure airport code.

Obtain the code from the official

Airline Guide or its equivalent

5 single-byte

characters max

R

departure_time

The departure time in local time

at the departure airport

HH:MM format,

between 00:00

and 23:59

R

fare_basis_code

The alphanumeric code that

carriers assign to a particular

ticket type, such as business

class, discounted, or non-

refundable

15 single-byte

characters max

R

flight_number

The flight number assigned by the

airline carrier

5 single-byte

characters max

R

service_class

The type of service; for example,

first class or coach. Obtain the

service class from the official

Airline Guide or equivalent

2 single-byte

characters

R

stopover_code

A code indicating a non-direct

flight or route on the same ticket

number

0 – Stopover not

permitted

1 – Stopover

permitted

R

travel_date

The date of travel in local time at

the departure airport

YYYYMMDD

format

R

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

conjunction_ticket

Ticket issued to a passenger in

conjunction with another ticket

that constitutes a single contract

of carriage

14 single-byte

characters max

O

coupon_number

The coupon number associated

with this leg of the trip. A ticket

can contain several legs of travel,

and each leg of travel requires a

separate coupon

1 single-byte

character

O

endorsement_or_restri

ctions

An endorsement can be an

agency-added notation or a

mandatory government required

notation such as value added tax.

A restriction is a limitation based

on the type of fare such as a

ticket with a non-refundable or 3-

day minimum stay.

20 single-byte

characters max

O

exchange_ticket

New ticket number that is issued

when a ticket is exchanged

15 single-byte

characters max

O

fare

Amount of the ticket for this leg of

the trip excluding taxes and fees

Numeric with two

decimal places.

Must not exceed

$10,000 in any

currency. Max

value

9,999,999.99

O

fee

Fee amount for this leg of the trip

O

taxes

Amount of the taxes for this leg of the trip

O

Attributes for Elements of FlightDetails

Attribute Name

Attribute of

element

Value / limitations

Required

leg_id

FlightDetails

Must start from 0 and be

contiguous

R

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example XML for FlightDetails elements

<conjunction_ticket>CONTKT12345678</conjunction_ticket>

<exchange_ticket>EXTKT123456789</exchange_ticket>

<coupon_number>X</coupon_number>

<service_class>A1</service_class>

<travel_date>20090801</travel_date>

<carrier_code>AB</carrier_code>

<stopover_code>0</stopover_code>

<departure_airport_code>EDI</departure_airport_code>

<arrival_airport_code>LHR</arrival_airport_code>

<flight_number>FOO12</flight_number>

<departure_time>12:34</departure_time>

<arrival_time>13:37</arrival_time>

<fare_basis_code>CHEAP1</fare_basis_code>

<endorsement_or_restrictions>non-

refundable</endorsement_or_restrictions>

</FlightDetails>

<service_class>A1</service_class>

<travel_date>20090801</travel_date>

<carrier_code>AB</carrier_code>

<stopover_code>0</stopover_code>

<departure_airport_code>EDI</departure_airport_code>

<arrival_airport_code>LHR</arrival_airport_code>

<flight_number>FOO12</flight_number>

<departure_time>12:34</departure_time>

<fare_basis_code>CHEAP1</fare_basis_code>

</FlightDetails>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.8.1.2 XML Example Requests

This section provides full XML examples for each transaction type.

2.8.1.2.1 set_express_checkout

Example XML Request

<client>xxxxxxxx</client>

<password>xxxxxxxx</password>

</Authentication>

</TxnDetails>

<method>set_express_checkout</method>

<return_url>https://www.example.com/myshoppingcard?

action=complete&sale_id=xyz123/</return_url>

<cancel_url>https://www.example.com/myshoppingcard?

action=cancel&sale_id=xyz123/</cancel_url>

<email>homer@example.com</email>

<max_amount>1000.00</max_amount>

<description>Twenty NeverFail(tm) Widgets</description>

<req_confirmed_shipping>0</req_confirmed_shipping>

<no_shipping>0</no_shipping>

<override_address>0</override_address>

<header_style img="https://www.example.com/header.png/"

bordercolor="black" bgcolor="red"/>

<page_style stylename="My Style" bgcolor="white"/>

<street_address1>1 Main Terrace</street_address1>

<street_address2>Highgate</street_address2>

<city>Wolverhampton</city>

<region>West Midlands</region>

<country_code>GB</country_code>

<telephone_number>0121 231 3122</telephone_number>

</ShippingAddress>

</PayPalTxn>

</Transaction>

</Request>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example XML for Request

<client>xxxxxxxx</client>

<password>xxxxxxxx</password>

</Authentication>

</TxnDetails>

<method>set_express_checkout</method>

<return_url>https://www.example.com/myshoppingcard?

action=complete&sale_id=xyz123/</return_url>

<cancel_url>https://www.example.com/myshoppingcard?

action=cancel&sale_id=xyz123/</cancel_url>

<header_style img="https://www.example.com/header.png/"

bordercolor="black" bgcolor="red"/>

<page_style stylename="My Style" bgcolor="white"/>

</PayPalTxn>

</Transaction>

</Request>

Example XML for Request

<client>xxxxxxxx</client>

<password>xxxxxxxx</password>

</Authentication>

</TxnDetails>

<method>set_express_checkout</method>

<return_url>https://www.example.com/myshoppingcard?

action=complete&sale_id=xyz123/</return_url>

<cancel_url>https://www.example.com/myshoppingcard?

action=cancel&sale_id=xyz123/</cancel_url>

<channel_type>Merchant</channel_type>

<solution_type>Mark</solution_type>

<billing_type>MerchantInitiatedBilling</billing_type>

<billing_agreement_description>Delivery by 10pm

Tuesday</billing_agreement_description>

<billing_agreement_custom>Remember to tell

Bob</billing_agreement_custom>

<payment_type>InstantOnly</payment_type>

</PayPalTxn>

</Transaction>

</Request>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.8.1.2.2 get_express_checkout_details

Example XML for Request

<client>xxxxxxxx</client>

<password>xxxxxxxx</password>

</Authentication>

<merchantreference>46548tretr</merchantreference>

</TxnDetails>

<method>get_express_checkout_details</method>

</PayPalTxn>

</Transaction>

</Request>

2.8.1.2.3 do_express_checkout_payment

<client>xxxxxxxx</client>

<password>xxxxxxxx</password>

</Authentication>

</TxnDetails>

<method>do_express_checkout</method>

<Items>

<ebay_item_number>9988775544</ebay_item_number>

<ebay_item_auction_txn_id>123456123

</ebay_item_auction_txn_id>

<ebay_item_order_id>abc123def890</ebay_item_order_id>

</Item>

</Items>

<street_address1>1 Main Terrace</street_address1>

<city>Wolverhampton</city>

<country_code>GB</country_code>

</ShippingAddress>

</PayPalTxn>

</Transaction>

</Request>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example XML for Request

<client>xxxxxxxx</client>

<password>xxxxxxxx</password>

</Authentication>

</TxnDetails>

<method>do_express_checkout_payment</method>

</PayPalTxn>

</Transaction>

</Request

Example XML for Request

<client>xxxxxxxx</client>

<password>xxxxxxxx</password>

</Authentication>

</TxnDetails>

<method>do_express_checkout_payment</method>

<description>Twenty NeverFail(tm) Widgets</description>

<buttonsource>foobar</buttonsource>

<notify_url>http://www.example.com/mynotifyurl?id=

abc123/</notify_url>

<item_total>85.00</item_total>

<shipping_total>10.00</shipping_total>

<handling_total>5.00</handling_total>

<tax_total>11.97</tax_total>

</PayPalTxn>

</Transaction>

</Request>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example XML for Request

<client>xxxxxxxx</client>

<password>xxxxxxxx</password>

</Authentication>

</TxnDetails>

<method>do_express_checkout_payment</method>

<passenger_name>Joseph Bloggs</passenger_name>

<ticket_number>BLAH1234567890</ticket_number>

<issuing_carrier_code>ABCD</issuing_carrier_code>

<restricted_ticket>0</restricted_ticket>

<clearing_sequence>1</clearing_sequence>

<clearing_count>1</clearing_count>

<service_class>A1</service_class>

<travel_date>20090801</travel_date>

<carrier_code>AB</carrier_code>

<stopover_code>0</stopover_code>

<departure_airport_code>EDI</departure_airport_code>

<arrival_airport_code>LHR</arrival_airport_code>

<flight_number>FOO12</flight_number>

<departure_time>12:34</departure_time>

<fare_basis_code>CHEAP1</fare_basis_code>

</FlightDetails>

</AirlineItineraryData>

</PayPalTxn>

</Transaction>

</Request>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example XML for Request without initial payment to be processed via the

PayPal Auth Capture Service

<client>xxxxxxxx</client>

<password>xxxxxxxx</password>

</Authentication>

</TxnDetails>

<method>set_express_checkout</method>

<return_url>https://www.example.com/myshoppingcard?

action=complete&sale_id=xyz123/</return_url>

<cancel_url>https://www.example.com/myshoppingcard?

action=cancel&sale_id=xyz123/</cancel_url>

<billing_type>MerchantInitiatedBilling</billing_type>

<billing_agreement_description>Subscription to

Magazine</billing_agreement_subscription>

</PayPalTxn>

</Transaction>

</Request>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.8.1.2.4

Example XML for Request with initial payment of £45.99 to be processed via

the PayPal Auth Capture Service

<client>xxxxxxxx</client>

<password>xxxxxxxx</password>

</Authentication>

</TxnDetails>

<method>set_express_checkout</method>

<return_url>https://www.example.com/myshoppingcard?

action=complete&sale_id=xyz123/</return_url>

<cancel_url>https://www.example.com/myshoppingcard?

action=cancel&sale_id=xyz123/</cancel_url>

<billing_type>MerchantInitiatedBillingSingleSource</billing_type>

</PayPalTxn>

</Transaction>

</Request>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.8.1.2.5

2.8.1.2.6 txn_refund

Example XML for a full refund

<client>xxxxxxxx</client>

<password>xxxxxxxx</password>

</Authentication>

<method>txn_refund</method>

</PayPalTxn>

<merchantreference>4655eubtr</merchantreference>

</TxnDetails>

</Transaction>

</Request>

Example XML for Request with initial payment of £45.99 to be

processed via the PayPal Auth Capture Service

<client>xxxxxxxx</client>

<password>xxxxxxxx</password>

</Authentication>

</TxnDetails>

<method>set_express_checkout</method>

<return_url>https://www.example.com/myshoppingcard?

action=complete&sale_id=xyz123/</return_url>

<cancel_url>https://www.example.com/myshoppingcard?

action=cancel&sale_id=xyz123/</cancel_url>

<billing_type>MerchantInitiatedBillingSingleSource</billing_type>

<payment_action>order</payment_action>

</PayPalTxn>

</Transaction>

</Request>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example XML for a partial refund

<client>xxxxxxxx</client>

<password>xxxxxxxx</password>

</Authentication>

<merchantreference>45gy7byrty</merchantreference>

</TxnDetails>

<method>txn_refund</method>

<note>Here's the refund I promised</note>

</PayPalTxn>

</Transaction>

</Request>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.8.1.2.7 do_authorization

Example XML for do_authorization

<client>xxxxxxxx</client>

<password>xxxxxxxx</password>

</Authentication>

</TxnDetails>

<method>do_authorization</method>

</PayPalTxn>

</Transaction>

</Request>

2.8.1.2.8 do_capture

Example XML for do_capture

<client>xxxxxxxx</client>

<password>xxxxxxxx</password>

</Authentication>

</TxnDetails>

<method>do_capture</method>

</PayPalTxn>

</Transaction>

</Request>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example XML for do_capture

<client>xxxxxxxx</client>

<password>xxxxxxxx</password>

</Authentication>

</TxnDetails>

<method>do_capture</method>

<note>Finally, I have captured some funds</note>

<soft_descriptor>FooCorp LLC</soft_descriptor>

</PayPalTxn>

</Transaction>

</Request>

2.8.1.2.9 do_void

Example XML for do_void

<client>xxxxxxxx</client>

<password>xxxxxxxx</password>

</Authentication>

</PayPalTxn>

</Transaction>

</Request>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example XML for do_void

<client>xxxxxxxx</client>

<password>xxxxxxxx</password>

</Authentication>

<note>Excess funds released</note>

</PayPalTxn>

</Transaction>

</Request>

2.8.1.2.10 create_billing_agreement

Example XML for create_billing_agreement

<client>xxxxxxxx</client>

<password>xxxxxxxx</password>

</Authentication>

<method>create_billing_agreement</method>

</PayPalTxn>

</Transaction>

</Request>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.8.1.2.11 update_billing_agreement

Example XML for update_billing_agreement for cancelling a billing

agreement

<client>xxxxxxxx</client>

<password>xxxxxxxx</password>

</Authentication>

<method>update_billing_agreement</method>

<billing_agreement_status>Cancelled</billing_agreement_status>

</PayPalTxn>

</Transaction>

</Request>

Example XML for update_billing_agreement to update the description

and custom field

<client>xxxxxxxx</client>

<password>xxxxxxxx</password>

</Authentication>

<method>update_billing_agreement</method>

<billing_agreement_description>Subscription to FOO Magazine

</billing_agreement_description>

<billing_agreement_custom>Part of our CHEAP09 prom

</billing_agreement_custom>

</PayPalTxn>

</Transaction>

</Request>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.8.1.2.12 do_reference_transaction

Example XML for do_reference_transaction, with immediate settlement

of funds.

<client>xxxxxxxx</client>

<password>xxxxxxxx</password>

</Authentication>

<method>do_reference_transaction</method>

<description>Twenty NeverFail(tm) Widgets</description>

<buttonsource>foobar</buttonsource>

<notify_url>http://www.example.com/mynotifyurl?id=abc123/

</notify_url>

<item_total>85.00</item_total>

<shipping_total>10.00</shipping_total>

<handling_total>5.00</handling_total>

<tax_total>11.97</tax_total>

</PayPalTxn>

</Transaction>

</Request>

Example XML for do_reference_transaction, with delayed settlement of

funds

</Authentication>

</TxnDetails>

<method>do_reference_transaction</method>

<payment_action>order</payment_action>

</PayPalTxn>

</Transaction>

</Request>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.8.1.3 Schema Elements for Response

The following section will highlight elements which are specific to PayPal transactions.

In addition to these, some general elements will be returned. Please refer to section

2.1.1.3 of the Developers Guide for descriptions of these elements.

2.8.1.3.1 PayPalTxn

The PayPalTxn element returns all of the details which are specific to the PayPal

Service. It should be noted that this document shows all possible fields which may be

returned by PayPal. The fields that are actually returned will depend upon the data

provided by your customer to PayPal, plus how your own merchant account at PayPal is

set up. The following key will be used:

 R – always returned

 A – returned if available

Many fields are only available for specific transaction types:

 S – set_express_checkout

 G – get_express_checkout_details

 D – do_express_checkout_payment

 R – txn_refund

 A – do_authorization

 C – do_capture

 V – do_void

 CB – create_billing_agreement

 UB – update_billing_agreement

 DR – do_reference_transaction

 E – error messages

Element Name:

PayPalTxn

Position(s)

Response.Transaction

Elements of PayPalTxn

Element Name

Description

Values /

Limitations

Provided (if available)?

S

G

D

R

A

C

V

C

B

U

B

D

R

E

ack

Success

SuccessWith

Warning

Failure

FailureWithW

arning

Warning

A

addressid

-

A

-

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

addressstatus

Status of street

address on file with

PayPal

Confirmed

None

Unconfirmed

-

A

-

amt

The final amount

charged, including

any shipping and

taxes from your

PayPal Merchant

Profile

Must not

exceed

$10,000 in

any currency.

Max value

9,999,999.99

-

A

-

A

-

A

-

billing_agreement_

accepted

Whether or not the

customer accepted

the billing

agreement

1 – the

customer

accepted the

billing

agreement

0 – the

customer did

not agree to

the billing

agreement

-

A

-

billing_agreement_

id

The value of the

Billing Agreement

ID originally

returned from

do_express_checko

ut_payment or

create_billing_ag

reement

-

A

-

A

-

billing_agreement_

description

The description held

by PayPal for the

Billing Agreement

127 single-

byte

characters

-

A

-

billing_agreement_

custom

The custom

annotation field held

by PayPal for the

Billing Agreement

255 single-

byte

characters

-

A

-

build

A string

representing the

specific software

build that processes

the request and

generated the

response

A

business

Payer’s business

name

127 single-

byte

characters

-

A

-

correlationid

A string that

identifies the exact

API request that

produced this

response

Max 41

characters

A

-

A

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

countrycode

Payer’s country of

residence

As defined in

ISO 3166-1

-

A

-

currencycode

The currency of the

transaction

-

A

-

A

-

custom

As section 2.8.1.1

-

A

-

email

As section 2.8.1.1

-

A

-

Errors

Returned for error and warning transactions. Please refer to

section 2.8.1.3.3

exchangerate

Exchange rate if a

currency conversion

occurred. Relevant

only if you are

billing in the

customer’s non-

primary currency. If

the customer

chooses to pay with

a currency other

than the primary

currency, the

conversion occurs in

the customer’s

account.

Decimal.

Max size 17

characters

including

decimal

point

-

A

-

A

-

feeamt

PayPal fee amount

charged for the

transaction

Must not

exceed

$10,000 in

any

currency.

Max value

9,999,999.9

9

-

A

-

A

-

A

-

feerefundamount

Transaction fee

refunded to original

recipient of payment

-

A

-

firstname

Payer’s first name

25 single-

byte

characters

-

A

-

grossrefundamt

Amount of money

refunded to original

payer

Must not

exceed

$10,000 in

any

currency.

Max value

9,999,999.9

9

-

A

-

invnum

As section 2.8.1.1

-

A

-

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

lastname

Payer’s last name

25 single-

byte

characters

-

A

-

middlename

Payer’s middle name

25 single-

byte

characters

-

A

-

netrefundamt

Amount subtracted

from PayPal balance

of original recipient

payment to make

this refund

Must not

exceed

$10,000 in

any

currency.

Max value

9,999,999.9

9

-

A

-

ordertime

Time/date stamp of

the payment, in ISO

8601 (UTC/Zulu

time)

YYYY-MM-

DDTHH:MM:S

SZ

-

A

-

A

-

A

-

payerid

Unique PayPal

customer account

identification

number

13 single-

byte

characters

-

A

-

payerstatus

The status of the

payer

verified

unverified

-

A

-

paymentstatus

Status of the

payment

See table

below for

values

-

A

-

A

-

A

-

paymenttype

Indicates whether

the payment is

instant or delayed

none

echeck

instant

-

A

-

A

-

A

-

pendingreason

The reason the

payment is pending

See table

below for

possible

values

-

A

-

A

-

phonenum

Payer’s contact

telephone number

-

A

-

reasoncode

The reason for the

reversal, if

transactiontype is

reversal

See table

below

-

A

-

refundtransactioni

d

Unique transaction

ID for the refund

17 single-

byte

characters

-

A

-

salutation

Payer’s salutation

20 single-

byte

characters

-

A

-

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

settleamt

Amount deposited in

your PayPal account

after currency

conversion

Must not

exceed

$10,000 in

any

currency.

Max value

9,999,999.9

9

-

A

-

A

-

A

-

ShippingAddress

If returned, this data will be in the same format as described in

section 2.8.1.1.6

suffix

Payer’s suffix

12 single-

byte

characters

-

A

-

taxamt

Tax charged on the

transaction

Must not

exceed

$10,000 in

any

currency.

Max value

9,999,999.9

9

-

A

-

A

-

A

-

timestamp

Date/time of

response in ISO

8601 (UTC/Zulu

time)

YYYY-MM-

DDTHH:MM:SS

Z

A

token

A timestamped

token by which you

identify to PayPal

that you are

processing this

payment with

Express Checkout.

Token expires after

three hours

20 single-

byte

characters

R

A

-

transactionid

Unique transaction

ID for the payment

19 single-

byte

characters

-

A

-

A

-

A

-

transactiontype

The type of

transaction

express-

checkout

reversal

merchtpmt

-

A

-

A

-

A

-

version

PayPal API service

version number

A

authorizationid

Value of

transactionid

returned in response

of

do_authorization

19 single-

byte

characters

-

A

-

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

parenttransactioni

d

Value of

transactionid

returned in response

of

do_authorization

19 single-

byte

characters

-

A

-

receipt

Receipt identification

number

19 single-

byte

characters

-

A

-

Values for paymentstatus

Value

Meaning

Completed

The payment has been completed, and the funds have been added

successfully to your account balance.

Pending

The payment is pending. See the pendingreason element for more

information.

Values for pendingreason

Value

Meaning

none

No pending reason.

address

The payment is pending because your customer did not include a

confirmed shipping address and your Payment Receiving Preferences is

set such that you want to manually accept or deny each of these

payments. To change your preference, go to the Preferences section of

your Profile.

echeck

The payment is pending because it was made by an eCheck that has not

yet cleared.

intl

The payment is pending because you hold a non-U.S. account and do not

have a withdrawal mechanism. You must manually accept or deny this

payment from your Account Overview.

multi-

currency

You do not have a balance in the currency sent, and you do not have your

Payment Receiving Preferences set to automatically convert and accept

this payment. You must manually accept or deny this payment.

verify

The payment is pending because you are not yet verified. You must verify

your account before you can accept this payment.

other

The payment is pending for a reason other than those listed above. For

more information, contact PayPal customer service.

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Values for reasoncode

Value

Meaning

none

No reason code

chargeback

A reversal has occurred on this transaction due to a chargeback by

your customer.

guarentee

A reversal has occurred on this transaction due to your customer

triggering a money-back guarantee.

buyer-

complaint

A reversal has occurred on this transaction due to a complaint about

the transaction from your customer.

refund

A reversal has occurred on this transaction because you have given

the customer a refund.

other

A reversal has occurred on this transaction due to a reason not listed

above.

Example XML for PayPal elements, for set_express_checkout

<method>set_express_checkout</method>

<return_url>https://www.example.com/myshoppingcard?action=

complete&sale_id=xyz123/</return_url>

<cancel_url>https://www.example.com/myshoppingcard?action=

cancel&sale_id=xyz123/</cancel_url>

<payment_action>order</payment_action>

</PayPalTxn>

Example XML for PayPal elements, for set_express_checkout

<ack>Success</ack>

</PayPalTxn>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example XML for PayPal elements, for get_express_checkout_details

<ack>Success</ack>

<addressid>PayPal</addressid>

<addressstatus>Confirmed</addressstatus>

<billing_agreement_accepted>1

</billing_agreement_accepted>

<custom>my_custom_data</custom>

<email>abc_11_1191417836_per@example.com</email>

<middlename>Arther</middlename>

<payerstatus>unverified</payerstatus>

</PayPalTxn>

Example XML for PayPal elements, for do_express_checkout_payment

<ack>Success</ack>

<billing_agreement_id>billing123</billing_agreement_id>

<paymentstatus>Completed</paymentstatus>

<paymenttype>instant</paymenttype>

<transactiontype>expresscheckout</transactiontype>

</PayPalTxn>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example XML for PayPal elements, for refund

<ack>Success</ack>

</PayPalTxn>

Example XML for PayPal elements, for do_authorization

<ack>Success</ack>

</PayPalTxn>

Example XML for PayPal elements, for do_capture

<ack>Success</ack>

<paymentstatus>Completed</paymentstatus>

<paymenttype>instant</paymenttype>

<transactiontype>express-checkout</transactiontype>

</PayPalTxn>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example XML for PayPal elements, for do_void

<ack>Success</ack>

</PayPalTxn>

Example XML for PayPal elements, for create_billing_agreement

<ack>Success</ack>

<billing_agreement_id>B-4C465615S44462100

</billing_agreement_id>

</PayPalTxn>

Example XML for PayPal elements, for update_billing_agreement

<ack>Success</ack>

<billing_agreement_custom>Part of our CHEAP09 promo

</billing_agreement_custom>

<billing_agreement_description>9.99 per month subscription to

FOO Magazine</billing_agreement_description>

<billing_agreement_id>B-4C465615S44462100

</billing_agreement_id>

</PayPalTxn>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example XML for PayPal elements, for do_reference_transaction

<ack>Success</ack>

<authorizationid>HOFAOW8973H4FA</authorizationid>

<paymentstatus>Completed</paymentstatus>

<paymenttype>instant</paymenttype>

<transactionid>AUWEHRGLUH92374</transactionid>

<transactiontype>merchtpmt</transactiontype>

</PayPalTxn>

Additional XML Example:

<client>xxxxxxxx</client>

<password>xxxxxxxx</password>

</Authentication>

</TxnDetails>

<method>do_express_checkout_payment</method>

<payment_action>order</payment_action>

</PayPalTxn>

</Transaction>

</Request>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.8.1.3.2 Errors

This element will only be returned if a PayPal error or warning occurs.

Elements of Errors

Value

Description

Error

See section 2.8.1.3.3

Example XML for Errors element

…

</Errors>

2.8.1.3.3 Error

This element will only be returned if a PayPal error or warning occurs. PayPal can

return multiple Errors for a single transaction. The ID numbering of these errors will

correspond to the number used by PayPal in their message response.

Elements of Errors

error_code

short_message

long_message

severity_code

Each error code which is returned will contain the short and long message. Please refer

to Appendix A (page 159) of the Name-Value Pair API Developer Guide and Reference

for a full list of error codes and their explanations.

Example XML for Error element

<error_code>81104</error_code>

<short_message>Missing Parameter</short_message>

<long_message>CancelURL : Required parameter

missing</long_message>

<severity_code>severityCode</severity_code>

</Error>

<error_code>10431</error_code>

<short_message>Item amount is invalid</short_message>

<long_message>Item amount is invalid</long_message>

</Error>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.8.1.4 XML Example Responses

2.8.1.4.1 Successful Transactions

Example XML Response for a set_express_checkout transaction

<datacash_reference>4000900012345671</datacash_reference>

<reason>ACCEPTED</reason>

<ack>Success</ack>

</PayPalTxn>

</Response>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example XML Response for a get_express_checkout_details transaction

<datacash_reference>4000900012345671</datacash_reference>

<reason>ACCEPTED</reason>

<ack>Success</ack>

<addressid>PayPal</addressid>

<addressstatus>Confirmed</addressstatus>

<street_address1>12 Boddingtons Road</street_address1>

<street_address2>Regeant's Park</street_address2>

<city>Wolverhampton</city>

<region>West Midlands</region>

<country>United Kingdom</country>

<country_code>GB</country_code>

<address_owner>Foobar Ltd</address_owner>

<address_status>Confirmed</address_status>

</BillingAddress>

<billing_agreement_accepted>1

</billing_agreement_accepted>

<custom>my_custom_data></custom>

<email>abc_11_1191417836_per@example.com</email>

<middlename>Arther</middlename>

<payerstatus>unverified</payerstatus>

<street_address1>1 Main Terrace</street_address1>

<street_address2>Highgate</street_address2>

<city>Wolverhampton</city>

<region>West Midlands</region>

<country>United Kingdom</country>

<country_code>GB</country_code>

<telephone_number>0121 231 3122</telephone_number>

</ShippingAddress>

</PayPalTxn>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

</Response>

Example XML Response for do_express_checkout_payment transaction

<datacash_reference>4000900012345671</datacash_reference>

<reason>ACCEPTED</reason>

<ack>Success</ack>

<billing_agreement_id>billing123</billing_agreement_id>

<paymentstatus>Completed</paymentstatus>

<paymenttype>instant</paymenttype>

<transactiontype>expresscheckout</transactiontype>

</PayPalTxn>

</Response>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example XML Response for a refund

<datacash_reference>4000900012345671</datacash_reference>

<reason>ACCEPTED</reason>

<ack>Success</ack>

</PayPalTxn>

</Response>

Example XML Response for a do_authorization

<datacash_reference>4000900012345671</datacash_reference>

<reason>ACCEPTED</reason>

<ack>Success</ack>

</PayPalTxn>

</Response>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example XML Response for a do_capture.which cancels any remaining

funds received against the payers account

<datacash_reference>4000900012345671</datacash_reference>

<reason>ACCEPTED</reason>

<ack>Success</ack>

<paymentstatus>Completed</paymentstatus>

<paymenttype>instant</paymenttype>

<transactiontype>express-checkout</transactiontype>

</PayPalTxn>

</Response>

Example XML Response for a do_void

<datacash_reference>4000900012345671</datacash_reference>

<reason>ACCEPTED</reason>

<ack>Success</ack>

</PayPalTxn>

</Response>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example XML Response for a create_billing_agreement

<datacash_reference>4000900012345671</datacash_reference>

<reason>ACCEPTED</reason>

<ack>Success</ack>

<billing_agreement_id>B-4C465615S44462100

</billing_agreement_id>

<correlationid>abc123correlationIDftw</correlationid>

</PayPalTxn>

</Response>

Example XML Response for an update_billing_agreement

<datacash_reference>4000900012345671</datacash_reference>

<reason>ACCEPTED</reason>

<ack>Success</ack>

<billing_agreement_custom>Part of our CHEAP09 promo

</billing_agreement_custom>

<billing_agreement_description>9.99 per month subscription

to FOO Magazine</billing_agreement_description>

<billing_agreement_id>B-4C465615S44462100

</billing_agreement_id>

<billing_agreement_status>Active</billing_agreement_status>

<correlationid>abc123correlationIDftw</correlationid>

</PayPalTxn>

</Response>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example XML Response for a do_reference_transaction

<datacash_reference>4000900012345671</datacash_reference>

<reason>ACCEPTED</reason>

<ack>Success</ack>

<authorizationid>HOFAOW8973H4FA</authorizationid>

<paymentstatus>Completed</paymentstatus>

<paymenttype>instant</paymenttype>

<transactionid>AUWEHRGLUH92374</transactionid>

<transactiontype>merchtpmt</transactiontype>

</PayPalTxn>

</Response>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.8.1.4.2 PayPal Warning and Errors

Example XML Response for an error

<datacash_reference>4000900012345671</datacash_reference>

<reason>PayPal: Error returned in response</reason>

<information>The transaction response from PayPal indicated that

an error has occurred - see the extended PayPal

information</information>

<ack>Failure</ack>

<error_code>81104</error_code>

<short_message>Missing Parameter</short_message>

<long_message>CancelURL : Required parameter

missing</long_message>

<severity_code>severityCode</severity_code>

</Error>

</Errors>

</PayPalTxn>

</Response>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.8.1.4.3 Invalid Transactions

When DataCash is sent a transaction, it will be validated before forwarding the

information to PayPal. If a transaction fails this validation, the response will not have a

PayPalTxn element. Examples are shown below.

A full list of error codes is available in the Developers Area. Additional examples - and

suggestions for how to prevent the errors re-occurring - are published in the Support

Centre.

Example XML Response for an invalid transaction

<datacash_reference>4000900012345671</datacash_reference>

<reason>PayPal: Not configured for service</reason>

<information>Merchant is not configured for the PayPal

service</information>

</Response>

Example XML Response for an invalid transaction

<datacash_reference>4000900012345671</datacash_reference>

<reason>PayPal: Invalid reference</reason>

<information>Referenced transactions is not a

PayPalTxn</information>

</Response>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.8.1.5 Re-Directing the Customer

This section describes how to re-direct your customer from your website to PayPal.

In order to complete this process, you must have submitted a set_express_checkout

transaction to DataCash, and received a successful response. This response will provide

you with a token (section 2.1.1.3):

Example Successful XML Response for set_express_checkout, highlighting

the token

<datacash_reference>…</datacash_reference>

<reason>ACCEPTED</reason>

</PayPalTxn>

</Response>

This token is used to construct the URL to which you will re-direct your customer, as

shown below:

Example URL for re-direct

https://www.paypal.com/cgi-bin/webscr?cmd=_express-checkout

&token=EC-4VL78907RS990801R/

https://www.sandbox.paypal/

When redirecting the customer’s browser to the PayPal login page, PayPal recommends

that you use the HTTPS response 302 “Object Moved” with the URL above as the value

of the Location header in the HTTPS response. Ensure that you use an SSL-enabled

server to prevent browser warnings about a mix of secure and insecure graphics.

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.8.1.6 Query Transaction for PayPal

Query transactions can be submitted against the DataCash reference of a PayPal

transaction to obtain information about that transaction.

2.8.1.6.1 Schema Elements For Request

o Request

 Authentication – section 2.2.1.1

 Transaction

 HistoricTxn – see section 2.6.2.3.2.1.

Elements of HistoricTxn

Element

Name

Description

Values / Limitations

method

The transaction type

query

R

reference

The reference of the

transaction to be queried

DataCash Reference of a

previous PayPal

transaction on the same

client.

R

Example XML Request for HistoricTxn complex elements

<method>query</method>

</HistoricTxn>

2.8.1.6.2 XML Example - PayPal Query Transaction

Example XML PayPal Query

</Authentication>

<method>query</method>

</HistoricTxn>

</Transaction>

</Request>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.8.1.6.3 Schema Elements for PayPal Query Response

Element Name:

QueryTxnResult

Position:

Response

The QueryTxnResult complex element contains the retrieved details for the transaction

reference provided in the request. The contents of the following elements all relate to

the original transaction being queried, and not the query transaction itself.

Elements of QueryTxnResult

Element Name

Description

PayPalTxn

Complex element containing details about the PayPal transaction

being queried

datacash_reference

DataCash reference

merchant_reference

Merchant reference

reason

DataCash response message.

status

DataCash response code

transaction_date

Date of processing by DPG

Elements of PayPalTxn

Element Name

Description

method

The method of the PayPal transaction being queried

status_update

Indicates whether the transaction status was updated as a

result of the query (see 2.8.1.6.5)

Captures

Complex element returned when the queried transaction was an

Authorization (method do_authorization), containing details of

any captures (method do_capture) that were associated with

that transaction

Elements of Captures

Element Name

Description

Capture

Complex element containing details of a single capture. An

element of this type will appear for each capture associated with

the authorization.

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Elements of Capture

Element Name

Description

datacash_reference

The DataCash reference of the capture transaction. This can

be used to query the capture transaction directly.

dc_response

The DataCash response code of the capture transaction.

2.8.1.6.4 XML Example - PayPal Query Response

Example XML Response for basic PayPal Query Txn

<method>do_express_checkout_payment</method>

</PayPalTxn>

<datacash_reference>4600900012345673</datacash_reference>

<merchant_reference>mref12345680</merchant_reference>

<reason>ACCEPTED</reason>

<transaction_date>2011-07-04 14:57:11</transaction_date>

</QueryTxnResult>

<reason>ACCEPTED</reason>

</Response>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example XML Response for PayPal Query Txn on an Authorization

<datacash_reference>4100900012345675</datacash_reference>

<dc_response>1</dc_response>

</Capture>

<datacash_reference>4900900012345676</datacash_reference>

<dc_response>1</dc_response>

</Capture>

</Captures>

<method>do_authorization</method>

</PayPalTxn>

<datacash_reference>4400900012345674</datacash_reference>

<merchant_reference>mref12345678</merchant_reference>

<reason>ACCEPTED</reason>

<transaction_date>2011-07-04 15:01:40</transaction_date>

</QueryTxnResult>

<reason>ACCEPTED</reason>

</Response>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.8.1.6.5 Status Updates

In the event that a PayPal transaction fails with a reason indicating that no response

was received from PayPal, if the transaction had method

do_express_checkout_payment, txn_refund, do_authorization or do_capture then

submitting a Query against that transaction will cause the payment gateway to attempt

to determine an updated status for the transaction by communicating with PayPal. In

the response to the Query the element status_update will indicate the outcome of this

attempt.

Example XML Response for PayPal Query Txn with status update

<method>txn_refund</method>

<status_update>Transaction status has been updated</status_update>

</PayPalTxn>

<datacash_reference>4100900012345675</datacash_reference>

<merchant_reference>mref12345677</merchant_reference>

<reason>ACCEPTED</reason>

<transaction_date>2011-07-04 15:06:12</transaction_date>

</QueryTxnResult>

<reason>ACCEPTED</reason>

</Response>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.8.1.7 Instant Payment Notification (IPN)

If subscribed to the PayPal service you can also be set up to receive Notification

Messages from DataCash alerting you to when a Transaction is updated. In addition,

this update will also be reflected in DataCash Reporting.

The Notification Message will be an XML document sent to a URL you have provided.

This URL should respond with an Acknowledgement of the Notification.

See below for schemas and examples

2.8.1.7.1 Schema of a Notification Message

Element Name:

Notify

Position:

Notification

Elements of Notify

Element Name

Description

datacash_reference

The DataCash reference of the update transaction

sequence_number

This corresponds to the number of times a Notification has

been sent for this update. This field will auto increment with

each attempt

PayPalTxn

This contains the transaction information

Elements of PayPalTxn

Element Name

Description

datacash_reference

The DataCash reference of the transaction that has been

updated

merchantreference

The reference sent in with the original transaction

txn_status

The current status of the transaction

raw_ipn

The original, unaltered IPN message from PayPal

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.8.1.7.2 Example of a Notification Message

Example XML Message for PayPal IPN Message

<datacash_reference>4000900001134560</datacash_reference>

<merchantreference>myref1234</merchantreference>

<txn_status>reversed</txn_status>

<raw_ipn><![CDATA[ original IPN msg ]]></raw_ipn>

</PayPalTxn>

<datacash_reference>4000900012345671</datacash_reference>

<sequence_number>1</sequence_number>

</Notify>

</Notification>

2.8.1.7.3 Schema of a Notification Acknowledgement

Element Name:

Acknowledge

Position:

Notification

Elements of Notify

Element Name

Description

datacash_reference

The DataCash reference of the update transaction from the

Notification. Contents of

Notification.Notify.datacash_reference

sequence_number

The sequence_number from the Notification being

acknowledged. Contents of

Notification.Notify.sequence_number

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.8.1.7.4 Example of a Notification Acknowledgement

Example XML Message for an Acknowledgement

<datacash_reference>4000900012345671</datacash_reference>

<sequence_number>1</sequence_number>

</Acknowledge>

</Notification>

2.8.2 Variable End of Day

This section describes the Variable End of Day service for the dynamic processing

model only. If you are using the Static processing model, no transactions need to be

sent to the DPG.

2.8.2.1 Schema Elements for Request

In this section, the fields that can be submitted when using the variable end of day

(dynamic) service will be presented, along with sample XML for those fields.

When presenting an eod transaction, the following schema elements should be

presented:

 Request

o Authentication – section 2.1.1.1

o Transaction

 TxnDetails – the merchant reference – section 2.8.2.1.1

 EoDTxn – the method eod – section 2.8.2.1.2

All elements are required, unless otherwise stated.

2.8.2.1.1 TxnDetails

There is one element to be presented in this parent element

Elements in TxnDetails

Element Name

Description

Values / Limitations

merchantreference

A unique reference

number for each

transaction

Minimum 6, maximum 30

alphanumeric characters. Must be

unique

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example XML for EoDTxn elements

</TxnDetails>

2.8.2.1.2 EoDTxn

There is one element to be presented in this parent element.

1Elements in EoDTxn

Element Name

Description

Values / Limitations

method

The transaction type

eod

Example XML for EoDTxn elements

</EoDTxn>

2.8.2.2 Example Requests

Example XML Request

</Authentication>

</TxnDetails>

</EoDTxn>

</Transaction>

</Request>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.8.2.3 Schema Elements for Response

Please refer to section 2.1.1.3. There are no additional elements which may be

returned in the XML response for this service.

2.8.2.4 Example Responses

Example XML Response for a successful transaction

<datacash_reference>4900200047685356</datacash_reference>

<reason>ACCEPTED</reason>

</Response>

Example XML Response for a rejected transaction

<datacash_reference>4000200047685351</datacash_reference>

<reason>VEoD: already received an EoD</reason>

</Response>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.8.3 RBS Gift Card

2.8.3.1 Summary of Service

The RBS Gift Card service provides the ability to perform a number of transaction types

against RBS Gift Cards:

 Balance Enquiries: To determine the remaining balance

 Redemptions: To perform an authorisation against the card

 Refunds: To refund an amount to the card

 txn_refunds: To refund an amount to the card based on a previously authorized

redemption.

2.8.3.2 Schema Elements for Request

Element Name:

RbsGiftCardTxn

Position:

Request.Transaction

Elements of RbsGiftCardTxn

Element Name

Description

Values / Limitations

Required

method

The method of the

transaction.

balance_enquiry

redeem

refund

txn_refund

R

Card

The card details of the

transaction to be

authenticated. This

element contains sub

elements. See

2.2.1.1.1 for more

information. This is not

used in the case of a

txn_refund.

See 2.2.1.1.1 for more

information

M

Reference

When performing a

txn_refund, this

element should be used

to indicate the

transaction that is

being refunded.

The value contained

should be the

datacash_reference of the

original RBS gift card

transaction to refund.

M

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.8.3.3 Balance Enquiry

The balance enquiry transaction is provided to allow the merchant to check the existing

balance of an RBS Gift Card prior to performing a redemption request.

An example balance enquiry transaction is illustrated below:

Example Balance Enquiry Request

<client>xxxxxxxx</client>

<password>xxxxxxxx</password>

</Authentication>

<capturemethod>ecomm</capturemethod>

</TxnDetails>

<method>balance_enquiry</method>

<Card>

<pan>xxxxxxxxxxxxxxxx</pan>

<accesscode>xxxxxxxx</accesscode>

</Card>

</RbsGiftCardTxn>

</Transaction>

</Request>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

An example response to a balance enquiry is shown below:

Example Balance Enquiry Response

<datacash_reference>4000900012345671</datacash_reference>

<reason>ACCEPTED</reason>

</RbsGiftCardTxn>

</Response>

2.8.3.4 Redemption

The redemption transaction allows the merchant to collect funds from the gift card. An

example redemption transaction is shown below:

Example Redemption Request

<client>xxxxxxxx</client>

<password>xxxxxxxx</password>

</Authentication>

<capturemethod>ecomm</capturemethod>

</TxnDetails>

<method>redeem</method>

<Card>

<pan>xxxxxxxxxxxxxxxx</pan>

<accesscode>xxxxxxxx</accesscode>

</Cv2Avs>

</Card>

</RbsGiftCardTxn>

</Transaction>

</Request>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

An example response to a redeem transaction where the card has sufficient funds to

complete the transaction is shown below:

Example Redemption Response where card has sufficient funds

<datacash_reference>4000900012345671</datacash_reference>

<reason>ACCEPTED</reason>

</RbsGiftCardTxn>

</Response>

The remaining balance is presented in the response XML as shown above.

Where the card contains insufficient funds, the response is slightly different. The

available funds on the Gift Card will be deducted and the XML response will contain a

negative balance. The negative balance will specify the difference between the

requested amount and the card balance i.e. the outstanding balance required to

complete the transaction.

The response below illustrates a negative balance being returned:

Example Redemption Response where card has insufficient funds

<datacash_reference>4000900012345671</datacash_reference>

<reason>ACCEPTED</reason>

</RbsGiftCardTxn>

</Response>

Where a negative balance is returned, the merchant must submit another transaction

request using another card (either Gift Card or Credit/Debit card) to secure the

outstanding balance.

See the developers guide for information on processing Credit / Debit card

transactions.

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.8.3.5 Refunds

The refund transaction allows the merchant to refund the gift card. An example refund

transaction is shown below:

Example Refund Request

<client>xxxxxxxx</client>

<password>xxxxxxxx</password>

</Authentication>

<capturemethod>ecomm</capturemethod>

</TxnDetails>

<method>refund</method>

<Card>

<pan>xxxxxxxxxxxxxxxx</pan>

<accesscode>xxxxxxxx</accesscode>

</Card>

</RbsGiftCardTxn>

</Transaction>

</Request>

An example response to a successful refund transaction is shown below:

Example Refund Response

<datacash_reference>4000900012345671</datacash_reference>

<reason>ACCEPTED</reason>

</RbsGiftCardTxn>

</Response>

Note: the response formatting is identical to that for redemption transactions.

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.8.3.6 Txn Refunds

The txn_refund transaction allows the merchant to refund the gift card with a

maximum amount equal to that contained within the original redemption transaction as

identified by the ‘reference’ provided in the XML.

Note that where multiple txn_refund transactions are submitted against the same

redemption, the sum of the refunded amounts must not exceed the originally

authorised amount.

An example txn_refund transaction is shown below:

Example txn_refund Request

<client>xxxxxxxx</client>

<password>xxxxxxxx</password>

</Authentication>

<capturemethod>ecomm</capturemethod>

</TxnDetails>

<method>txn_refund</method>

</RbsGiftCardTxn>

</Transaction>

</Request>

If the amount is not provided, the amount refunded will be that of the original

redemption transaction. Note that ‘currency’ is not permitted in a txn_refund.

An example response to a txn_refund is provided below:

Example txn_refund Response

<datacash_reference>4000900012345671</datacash_reference>

<reason>ACCEPTED</reason>

</RbsGiftCardTxn>

</Response>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

The ‘merchantreference’ returned in response to a txn_refund is the

‘datacash_reference’ of the original redemption transaction.

2.8.3.7 Unsuccessful Transactions

In the event of an unsuccessful transaction (where a valid response is received

indicating failure at RBS), the balance may be returned, and additional data provided in

the response message may be returned in the information field.

An example of an unsuccessful transaction can be seen below:

Example Response for a Unsuccessful Transaction

<datacash_reference>4000900012345672</datacash_reference>

<reason>DECLINED</reason>

</RbsGiftCardTxn>

<information>CARD EXPIRED</information>

</Response>

2.8.3.8 Invalid Transactions

In the event of a transaction being rejected by the DPG without going to RBS for

processing, the RbsGiftCardTxn block will not be returned. A suitable status code and

simple message will be returned, with additional details in the information field. This is

in-line with the existing DataCash response format.

For example:

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example Response for a Invalid Transaction

<datacash_reference>4000900012345672</datacash_reference>

<reason>Inappropriate card number</reason>

<information>The card provided is not an RBS Gift

Card</information>

</Response>

Such responses will be received if the XML submitted contains unexpected elements,

has missing elements or the data contained within those elements has failed to meet

the validation rules.

2.8.3.9 Failed Transactions

A failed transaction is one where an attempt to submit a request to RBS was made, but

a communication error has rendered the outcome either failed or unknown.

An example of a failed transaction is given below for completeness:

Example Response for a Failed Transaction

<datacash_reference>4000900012345672</datacash_reference>

<reason>BANK DID NOT REPLY</reason>

</Response>

2.8.3.10 Notes

2.8.3.10.1 Accesscode

This element is optional and if presented must be 8 digits in length. If provided, the

‘accesscode’ must match that held against the account otherwise the transaction will be

declined.

2.8.3.10.2 Capturemethod

This can be one of ‘ecomm’ or ‘cnp’ for RBS Gift Card transactions. If this is not

specified, the capturemethod will be set by determining the environment of a terminal

configured on your account which is capable of processing the card and currency

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

combination specified in the transaction.

Note that the ‘capturemethod’ is mandatory if the account is configured with multiple

merchant ID environments.

2.8.4 PrePay Technology (PPT)

2.8.4.1 Summary of Service

The PrePay Technology service (hereafter referred to as PPT) provides the ability to

perform a number of transaction types against PPT gift cards:

 Top Ups: To load the PPT gift card with funds

 Redemptions: To perform an authorization against the PPT gift card

 Refunds: To refund an amount to the PPT gift card

 Balance Enquiries: To determine the remaining balance on the PPT gift card

 Reversals: Reverse a previous top up, redemption or refund on the PPT gift card

 txn_refunds: To refund an amount to the card based on a previously authorized

redemption.

PPT transactions can be performed in ecommerce or cardholder not present

environments. Alternatively PPT cards can be swiped or keyed into a card terminal.

2.8.4.2 Schema Elements for Request

Element Name:

PPTCardTxn

Position:

Request.Transaction

Elements of PPTCardTxn

Element Name

Description

Values / Limitations

Required

method

The method of the transaction

top_up

redeem

refund

balance_enquiry

reversal

txn_refund

R

pan

The PPT card number. Element

used for “ecomm”, “cnp” and

“keyed” capturemethods.

The PPT card

number

M

A Pin number can optionally be

supplied when performing

“top-up”, “redeem” and

“balance_enquiry”

transactions.

4 digit pin number

O

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

reference

The datacash reference of the

related transaction.

This element is only valid for

“reversal” or “txn_refund”

methods.

Datacash reference

of the related

transaction

M

merchantreference

If subscribed to the merchant

reference cancellations service,

a “reversal” may be invoked

with this element instead of

reference

Merchant reference

of the related

transaction

O

card_details

For the “swiped”

capturemethod only, this

element is used instead of pan.

The track2

information from the

PPT gift card

M

Terminal

For PPT transactions using a

terminal (“keyed”, “swiped”

capturemethods), this element

should be present.

See section

2.7.1.1.3

M

2.8.4.3 Schema Elements for Response

Element Name:

PPTCardTxn

Position:

Response

Elements of PPTCardTxn

Element Name

Description

Values /

Limitations

Authcode

The authcode of the transaction, this element can also contain

messages from PPT e.g “INVALID PIN”.

card_activated

PPT may return information in their authorisation

response that indicates that a card has been

activated as a result of the transaction. This

element will only be included where card activation

has occurred.

“yes”

Balance

The balance remaining on the PPT gift card following the

transaction, returned with major and minor units (i.e 0.00).

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.8.4.4 Top Ups

Top up transactions are used to load funds onto the PPT gift card. An example of a

“swiped” top up request is shown below:

Example PPT Top Up Request

<client>xxxxxxxx</client>

<password>xxxxxxxx</password>

</Authentication>

<capturemethod>swiped</capturemethod>

</TxnDetails>

<terminal_capabilities ic_reader="true"

magnetic_stripe_reader="true"

manual_card_entry="true"/>

<features_capabilities pin_pad_available="true"/>

</Terminal>

<card_details

type="track2">xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx</card_det

ails>

</PPTCardTxn>

</Transaction>

</Request>

An example of a DataCash response to a top up request is shown below. Note that in

this case, this was the first use of the gift card and so the “card_activated” element is

present.

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example PPT Top Up Response

<reason>ACCEPTED</reason>

<datacash_reference>4000900012345671</datacash_reference>

<card_activated>yes</card_activated>

</PPTCardTxn>

</Response>

2.8.4.5 Redemption

Redeem transactions are used to authorise fund removal from the gift card. An

example of a “keyed” redemption request is shown below:

Example PPT Redemption Request

<client>xxxxxxxx</client>

<password>xxxxxxxx</password>

</Authentication>

<capturemethod>keyed</capturemethod>

</TxnDetails>

<terminal_capabilities ic_reader="true"

magnetic_stripe_reader="true" manual_card_entry="true"/>

<features_capabilities pin_pad_available="true"/>

</Terminal>

<method>redeem</method>

<pan>xxxxxxxxxxxxxxxx</pan>

</PPTCardTxn>

</Transaction>

</Request>

Note that the “pin” element is optional.

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

An example of a response to the above request is shown below:

Example PPT Redemption Response

<reason>ACCEPTED</reason>

<datacash_reference>4800900012345672</datacash_reference>

</PPTCardTxn>

</Response>

2.8.4.6 Refunds

Refund transactions are used to refund an amount to the gift card, where the refund

doesn’t relate to an existing redemption on that gift card. An example of an e-

commerce refund request is shown below:

Example PPT Refund Request

<client>xxxxxxxx</client>

<password>xxxxxxxx</password>

</Authentication>

<capturemethod>ecomm</capturemethod>

</TxnDetails>

<method>refund</method>

<pan>xxxxxxxxxxxxxxxx</pan>

</PPTCardTxn>

</Transaction>

</Request>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

An example response to the above transaction is shown below:

Example PPT Refund Response

<reason>ACCEPTED</reason>

<datacash_reference>4800900012345673</datacash_reference>

</PPTCardTxn>

</Response>

2.8.4.7 Balance Enquiries

Balance enquiries are used query the amount of funds on the gift card. An example of

an e-commerce balance enquiry request is shown below:

Example PPT Balance Enquiry Request

<client>xxxxxxxx</client>

<password>xxxxxxxx</password>

</Authentication>

<capturemethod>ecomm</capturemethod>

</TxnDetails>

<method>balance_enquiry</method>

<pan>xxxxxxxxxxxxxxxx</pan>

</PPTCardTxn>

</Transaction>

</Request>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

An example response to the above transaction is shown below:

Example PPT Balance Enquiry Response

<reason>ACCEPTED</reason>

<datacash_reference>4800900012345674</datacash_reference>

</PPTCardTxn>

</Response>

2.8.4.8 Reversals

Reversals can be used to reverse a previous top up, redemption or refund on the PPT

gift card, by using the datacash_reference (supplied in the response of the previous

transaction). An example of an e-commerce reversal request is shown below:

Example PPT Reversal Request

<client>xxxxxxxx</client>

<password>xxxxxxxx</password>

</Authentication>

<method>reversal</method>

</PPTCardTxn>

</Transaction>

</Request>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

An example response to the above transaction is shown below:

Example PPT Reversal Response

<reason reversal="success">ACCEPTED</reason>

<datacash_reference>4800900012345675</datacash_reference>

<information>Reversal ACCEPTED status=1

authcode=100000</information>

</PPTCardTxn>

</Response>

2.8.4.9 Txn_refunds

Txn_Refund transactions are used to refund an amount to the gift card, where the

refund relates to an existing redemption on that gift card. The refund may be for the

full amount of the transaction, or a partial amount (if the amount element is missing

then the full amount will be assumed).

An example of an e-commerce txn_refund request is shown below:

Example PPT Txn_Refund Request

<client>xxxxxxxx</client>

<password>xxxxxxxx</password>

</Authentication>

</TxnDetails>

<method>txn_refund</method>

</PPTCardTxn>

</Transaction>

</Request>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

An example response to the above transaction is shown below:

Example PPT Txn_Refund Response

<reason>ACCEPTED</reason>

<datacash_reference>4800900012345675</datacash_reference>

</PPTCardTxn>

</Response>

2.8.4.10 Unsuccessful Transactions

2.8.4.10.1 Declined

In the event of a decline by PPT, the balance may or may not be returned, for

example:

Example of a PPT Decline response

<reason>DECLINED</reason>

<datacash_reference>4800900012345672</datacash_reference>

<authcode>DECLINED</authcode>

</PPTCardTxn>

</Response>

2.8.4.10.2 Pin Mismatch

This scenario follows the same format as a Decline above, however the reason field

indicates why the transaction was declined, for example:

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example of a PPT PIN mismatch response

<reason>PIN MISMATCH</reason>

<datacash_reference>4800900012345672</datacash_reference>

<authcode>PIN MISMATCH 010000010000</authcode>

</PPTCardTxn>

</Response>

2.8.4.11 Invalid Transactions

In the event of a transaction being rejected by the DPG without going to PPT for

processing, the PPTCardTxn block will not be returned. A suitable status code and

simple message will be returned, with additional details in the information field. It

may not be possible to include currency information in such transactions. For example:

Example of a response to an Invalid PPT transaction

<datacash_reference>4000900012345672</datacash_reference>

<reason>PPT: Inappropriate Request Element</reason>

<information>Field LINEITEMDETAIL may not be included in a PPT

transaction</information>

</Response>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.8.4.12 Failed Transactions

A failed transaction will be one where an attempt to submit a request to PPT was made,

but a communication error has rendered the outcome either failed or unknown.

On behalf of a merchant, DataCash issue an automatic reversal in this case, and the

reversed element is used to indicate whether the reversal was successful. This will

only be applicable only to error 6 responses.

Elements of Response

Element

Name

Description

Values / Limitations

reversed

Indicates whether an automatic reversal

issued by DataCash in the event of a

communications failure was successful.

Y – The original

transaction was reversed

N – The original

transaction did not reach

the acquirer so was not

reversed

F – A reversal was

attempted but failed

In the event of a reversed flag of F, it is not possible for DataCash to know the status

of the transaction, and the merchant will have to investigate further with PPT. For

example:

Example of DataCash Response on PPT communications failure

<datacash_reference>4000900012345672</datacash_reference>

<reason>BANK DID NOT REPLY</reason>

<information>Reversal attempt FAILED</information>

</Response>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.8.5 Currency Conversion Service

2.8.5.1 Summary of Service

Transactions placed using the Currency Conversion Service can charge a bank card in

the currency of the account that the cardholder uses rather than the currency of the

merchant processing the transaction. The amount charged to the customer is

calculated using exchange rates provided by the merchant.

2.8.5.2 Schema Elements for Request

Element Name:

CurrencyConversionTxn

Position:

Request.Transaction.TxnDetails

Elements of CurrencyConversionTxn

Element Name

Description

Values / Limitations

Required

exchange_currency

The currency used

by the card

Valid ISO 4217

alphabetic currency

code

R

exchange_amount

The amount

provided for the

transaction in the

exchange currency.

R

exchange_rate

The exchange rate

provided for the

transaction

Must contain a decimal

point, and contain no

more than 5 decimal

places. The exchange

rate goes from base ->

exchange currency:

base_amount x

exchange_rate =

exchange_amount

R

Whenever the CurrencyConversionTxn block is present in an XML transaction, the

currency attribute of Request.Transaction.TxnDetails.amount is mandatory.

Note that Dynamic Currency Conversion (DCC) transactions can only be supplied in

bank card transactions where the transaction method is either “auth”, “pre”, or

“refund”. A “fulfil” after a DCC “pre” should not contain any DCC information.

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.8.5.3 Example XML Request

The following is an example authorisation. Note that the base amount and currency is

specified in the amount element.

For example:

Example of a Currency Conversion Service Authorisation Request

<client>xxxxxxxx</client>

<password>xxxxxxxx</password>

</Authentication>

<capturemethod>ecomm</capturemethod>

<exchange_currency>USD</exchange_currency>

<exchange_amount>200.00</exchange_amount>

<exchange_rate>2.0000</exchange_rate>

</CurrencyConversionTxn>

</TxnDetails>

<Card>

<pan>xxxxxxxxxxxxxxxx</pan>

</Card>

</CardTxn>

</Transaction>

</Request>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.8.5.4 Schema Elements for Response

Element Name:

CurrencyConversionTxn

Position:

Response

Elements of CurrencyConversionTxn

Element Name

Description

Values / Limitations

base_amount

The amount that the

merchant has

requested for the

transaction in their

currency

exchange_currency

The currency used

by the card

Valid ISO 4217

alphabetic currency

code

exchange_amount

The amount

provided for the

transaction in the

exchange currency

exchange_rate

The exchange rate

provided for the

transaction

Must contain a decimal

point, and contain no

more than 5 decimal

places

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.8.5.5 Example XML Response

The following is an example of a response following a successful authorisation.

For example:

Example of a Currency Conversion Service Authorisation Response

<base_amount currency=”GBP”>100.00</base_amount>

<exchange_currency>USD</exchange_currency>

<exchange_amount>200.00</exchange_amount>

<exchange_rate>2.0000</exchange_rate>

</CurrencyConversionTxn>

<card_scheme>VISA</card_scheme>

<country>United Kingdom</country>

</CardTxn>

<datacash_reference>4800903000000001</datacash_reference>

<reason>ACCEPTED</reason>

</Response>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.8.6 Fexco Dynamic Currency Conversion

2.8.6.1 Summary of service

This service allows merchants to take international payments via Fexco’s third party

Dynamic Currency Conversion (herin referred to as DCC) product.

Transactions placed using the DCC service can charge a bank card in the currency of

the account that the cardholder uses rather than the currency of the merchant

processing the txn. The amount changed to the customer is calculated using exchange

rates provided by Fexco to the merchant.

This service is deprecated in favour of the Currency Conversion Service (2.8.5).

2.8.6.2 Schema Elements for Request

Element Name:

FexcoDCC

Position:

Request.Transaction.TxnDetails

Elements of FexcoDCC

Element Name

Description

Values / Limitations

Required

BaseCurrency

The currency that

the merchant usually

trades in

Valid ISO 4217

alphabetic currency

code

R

BaseAmount

The amount that the

merchant has

requested for the

transaction

R

ExchangeRate

The exchange rate

provided by FEXCO

for the transaction

Must contain a decimal

point, and contain no

more than 5 decimal

places

R

Whenever the FexcoDCC block is present in an XML transaction, the currency attribute

of Request.Transaction.TxnDetails.amount is mandatory.

Note that Fexco DCC transactions can only be supplied in bank card transactions where

the transaction method is either “auth” or “pre”.

The Fexco DCC service is compatiable with both DataCash MPI and Third Party MPI 3-D

Secure transactions. In order to use the Fexco DCC service with these services, the

FexcoDCC element must only be supplied in the initial stage (Where the transaction

method is “auth” or “pre”).

In the case of Airlines transactions, the per-passenger ticket prices can be in either the

DCC (Post conversion) currency or the Base (Pre conversion) currency. No cross check

on the totalling of these values against the transaction amount will be made for DCC

transactions in the DPG.

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.8.6.3 Example Transaction

The following is an example authorisation. Note that the post conversion amount and

currency is specified in the amount element.

For example:

Example of a Fexco DCC Authorisation Request

<client>xxxxxxxx</client>

<password>xxxxxxxx</password>

</Authentication>

<capturemethod>ecomm</capturemethod>

</FexcoDCC>

</TxnDetails>

<Card>

<pan>xxxxxxxxxxxxxxxx</pan>

</Card>

</CardTxn>

</Transaction>

</Request>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.8.7 Bankcard Query Transactions

2.8.7.1 Service Overview

The Query Transaction service makes it possible to retrieve details of a previous

Bankcard transaction by sending a request to the DataCash Payment Gateway. In

addition to regular bankcard transactions, the service may be used to retrieve details

for Fuels, RBS Giftcard and PPT transactions.

No additional subscription is required by merchants to use this service.

See also:

 BatchInput Query Transactions – section 6.6.2.3

 HCC Query Transactions – section 2.2.8.4.2

 HPS Query Transactions – section 2.2.9

Additional uses for the query transaction are outlined in the FAQ:

https://datacash.custhelp.com/cgi-

bin/datacash.cfg/php/enduser/std_adp.php?p_faqid=1037/

2.8.7.2 Schema Elements For Request

 Request

o Authentication – section 2.2.1.1

o Transaction

 HistoricTxn – see section 2.6.2.3.2.1.

Elements of HistoricTxn

Element

Name

Description

Values / Limitations

method

The transaction type

query

R

reference

The reference of the

transaction to be

queried

DataCash or Merchant Reference of a

previous Bankcard transaction on the same

client.

If the Merchant Reference is used, only the

details for the most recent transaction with

that reference will be returned.

R

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Attributes for Elements of HistoricTxn

Attribute Name

Attribute of Element

Values / Limitations

type

reference

datacash (default)

merchant

O

Example XML Request for HistoricTxn complex elements

<method>query</method>

</HistoricTxn>

<method>query</method>

</HistoricTxn>

2.8.7.3 XML Example - Bankcard Query Transaction

Example XML Bankcard Query

</Authentication>

<method>query</method>

</HistoricTxn>

</Transaction>

</Request>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.8.7.4 Schema Elements for Bankcard Query Response

Element Name:

QueryTxnResult

Position:

Response

The QueryTxnResult complex element contains the retrieved details for the transaction

reference provided in the request. The contents of the following elements all relate to

the original transaction being queried, and not the query transaction itself.

Elements of QueryTxnResult

Element Name

Description

Card

Complex element containing details of the payment card used

ThreeDSecure

Complex element containing 3-D Secure details from the original

transaction – only present where the original transaction used 3-

D Secure

acquirer

Acquiring bank

authcode

Bank authorisation response

datacash_reference

DataCash reference

environment

Processing environment

fulfill_date

Date of fulfillment

merchant_reference

Merchant reference

reason

DataCash response message. For a ‘duplicate transaction’ reason

this will also contain the DataCash reference of the original,

which may then be queried.

sent

Sent status – indicates whether the transaction was sent for

settlement

status

DataCash response code

transaction_date

Date of processing by DPG

Elements of Card

Element Name

Description

expirydate

Expiry date

issuenumber

Issue number or start date if available

pan

Card number (masked)

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Elements of ThreeDSecure

Element Name

Description

eci

ECI

security_code

CAVV

transactionID

XID

Example XML Response for QueryTxnResult complex elements

<Card>

</Card>

<acquirer>natwest</acquirer>

<datacash_reference>4000900012345671</datacash_reference>

<environment>ecomm</environment>

<fulfill_date>2009-12-08 11:35:48</fulfill_date>

<merchant_reference>123401</merchant_reference>

<reason>ACCEPTED</reason>

<transaction_date>2009-12-08 11:35:48</transaction_date>

</QueryTxnResult>

<Card>

</Card>

<security_code>Q0FWVkNBVlZDQVZWQ0FWVkNBVlY=</security_code>

<transactionID>MDAwMDAwMDAwMDAwMTIzNDU2NzE=</transactionID>

</ThreeDSecure>

<acquirer>natwest</acquirer>

<datacash_reference>4000900012345671</datacash_reference>

<environment>ecomm</environment>

<fulfill_date>2009-12-08 11:56:53</fulfill_date>

<merchant_reference>4421000008</merchant_reference>

<reason>ACCEPTED</reason>

<transaction_date>2009-12-08 11:56:53</transaction_date>

</QueryTxnResult>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.8.7.5 XML Example - Bankcard Query Responses

Example XML Response for successful Query Txn

<Card>

</Card>

<security_code>Q0FWVkNBVlZDQVZWQ0FWVkNBVlY=</security_code>

<transactionID>MDAwMDAwMDAwMDAwMTIzNDU2NzE=</transactionID>

</ThreeDSecure>

<acquirer>natwest</acquirer>

<datacash_reference>4000900012345671</datacash_reference>

<environment>ecomm</environment>

<fulfill_date>2009-12-08 11:56:53</fulfill_date>

<merchant_reference>4421000008</merchant_reference>

<reason>ACCEPTED</reason>

<transaction_date>2009-12-08 11:56:53</transaction_date>

</QueryTxnResult>

<reason>ACCEPTED</reason>

</Response>

Example XML Response for unsuccessful Query Txn

<datacash_reference>4100900012345675</datacash_reference>

<information>The transaction you are querying

cannot be located</information>

<reason>Cannot locate transaction to query</reason>

</Response>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.8.8 vTID Configuration Transactions

2.8.8.1 Service Overview

The vTID Configuration service allows for the changing or generation of a new

password for a vTID by submitting a transaction to the DataCash Payment Gateway.

This service is constrained to transactions received from IP addresses specified in vTID

IP filtering for the vTID being configured.

No additional subscription is required by merchants to use this service.

2.8.8.2 Schema Elements For Request

 Request

o Authentication – section 2.1.1.2

o Transaction

 VtidConfigurationTxn – contains the transaction type/method, section

2.8.8.2.1

 Password – the new password, section 2.8.8.2.2

2.8.8.2.1 VtidConfigurationTxn

This element must be present with all transactions.

Element Name:

VtidConfigurationTxn

Position:

Request.Transaction.VtidConfigurationTxn

Elements of VtidConfigurationTxn

Element Name

Description

Values / Limitations

Password

See section 2.8.8.2.2

R

method

The transaction type

vtidconfiguration

R

2.8.8.2.2 Password

This element must be present with all transactions

Element Name:

Password

Position:

Request.Transaction.VtidConfigurationTxn.Password

Elements of Password

Element

Name

Description

Values / Limitations

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

new_password

The password to be

assigned to the

vTID.

May be blank in order to have the DataCash

Payment Gateway generate a vTID password.

Alternatively, a password may be specified

and must meet the following specifications.

 More than 8 characters

 Made up of a combination of at least 2

of lowercase, uppercase, numeric and

special characters.

 Dissimilar to the current password.

 Not too simplistic or repetitive.

 Not contain whole or partial words

from the dictionary.

R

Example XML Request for VtidConfigurationTxn with specified password

<method>vtidconfiguration</method>

<new_password>########</new_password>

</Password>

</VtidConfigurationTxn>

2.8.8.3 Example XML Requests

Example XML Request for VtidConfigurationTxn for password generation

</Authentication>

<method>vtidconfiguration</method>

<new_password/>

</Password>

</VtidConfigurationTxn>

</Transaction>

</Request>

2.8.8.4 Schema Elements for Response

In the XML Response, there will be one additional element. The standard elements are

outlined in section 2.1.1.3

Elements of Response

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Element Name

Description

new_password

Contains the specified or generated

password as acknowledgement that the

password has been modified.

Example XML Response for VtidConfigurationTxn

<datacash_reference>4000900012345671</datacash_reference>

<new_password>########</new_password>

<reason>ACCEPTED</reason>

</Response>

2.8.9 PreCall Transaction

2.8.9.1 Service Overview

The PreCall service analyses the input field (detailed below) and applys a set of rules to

this information in order to determine the payment methods that are available for this

particular transaction. The supported methods of payment are returned in the

response. The rules applied to the input are configurable. Contact DataCash for more

information regarding this service and to discuss the configuration of these rules.

2.8.9.2 Schema Elements for Request

2.8.9.2.1 Authentication

Element Name:

Authentication

Position:

Request

Elements of Authentication

Element

Name

Description

client

This is the vTID which has been configured for you by DataCash support.

password

This is the SHA1 hash, generated using the shared secret agreed with

DataCash support. The SHA1 hash is generated by concatenating your

vTID, client_reference and shared secret together and hashing the resultant

string using SHA1.

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.8.9.2.2 Txn Details

Element Name:

TxnDetails

Position:

Request.Transaction

Elements of TxnDetails

Element Name

Description

amount

This is the decimal amount of the transaction. The currency

attribute must be provided as a 3 letter currency code. (See

Example XML)

merchantreference

This is your unique reference for the transaction which can be up

to 30 characters.

2.8.9.2.3 PreCall Txn

Element Name:

PreCallTxn

Position:

Request.Transaction

Elements of PreCallTxn

Element

Name

Description

method

Currently, the only supported method is “precall”, and you should

populate this field with the latter value.

2.8.9.2.4 Client Data

Element Name:

ClientData

Position:

Request.Transaction.PreCallTxn

Elements of ClientData

Element Name

Description

client_reference

This your reference for the PreCall transaction which can be used

as part of the rule application process.

client_order_id

This is your reference of the customer order for which this

transaction is being submitted.

client_billing_id

This is your client billing id reference.

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

client_pos

This is the point of sale or office identifier for the location in which

the transaction is taking place.

client_country

The 2 letter country code in which the transaction is taking place.

client_site

The URI for the website from which the transaction originated. E.g.

www.example.com

2.8.9.2.5 Custom Client Fields

Element Name:

CustomClientFields

Position:

Request.Transaction.PreCallTxn.ClientData

This block can be used to provide additional / custom client data on agreement with

DataCash support.

Elements of CustomClientFields

Element Name

Description

reference_1

To be agreed with DataCash.

reference_2

To be agreed with DataCash.

reference_3

To be agreed with DataCash.

reference_4

To be agreed with DataCash.

2.8.9.2.6 Order Details

Element Name:

OrderDetails

Position:

Request.Transaction.PreCallTxn

Elements of OrderDetails

Element Name

Description

order_date_time

This is the date and time when the order took place. This

should be presented as an ISO8601 formatted timestamp. E.g.

2011-01-14T14:22:23+01:00

delivery_date_time

This is the date and time when the goods/service will be

delivered. If this transaction is related to the sale of Airline

tickets, this is the time of flight. This should be presented as an

ISO8601 formatted timestamp. E.g. E.g. 2011-01-

14T14:22:23+01:00

billing_country

This is the country in which the customer will be billed.

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

customer_logged_in

Indicates whether or not the customer is an existing account

holder, and was logged into this account at the time of the

transaction.

sales_channel

The channel through which this transaction took place. E.g.

ecommerce.

customer_ip_address

The IP address of the customer.

customer_language

The customers preferred language.

2.8.9.2.7 Airline Details

Element Name:

AirlineDetails

Position:

Request.Transaction.PreCallTxn

Elements of AirlineDetails

Element Name

Description

airline_country

This is the two letter country code of the country in which the

customer will be billed.

airline_booking_type

E.g. BOOK

customer_level

The customer loyalty level.

Legs

Contains up to 16 Leg elements representing each individual

Leg of a journey.

2.8.9.2.8 Legs

The Legs complex element can contain up to 16 Leg elements. Each Leg element

represents an individual leg of the overall journey. The Leg element is described

below:

Element Name:

Leg

Position:

Request.Transaction.PreCallTxn.AirlineDetails.Legs

Elements of Leg

Element Name

Description

depart_airport

This is the 3 letter IATA airport code for the departure airport.

depart_city

This is the 3 letter city code for the departure city.

depart_state

The departure state if applicable.

depart_country

This is the two letter country code for the departure country.

carrier

This is the 2 letter IATA airline code for the carrier.

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

arrival_airport

This is the 3 letter IATA airport code for the arrival/destination

airport.

arrival_city

This is the 3 letter city code for the arrival/destination city.

arrival_state

The arrival/destination state if applicable.

arrival_country

This is the two letter country code for the arrival/destination country.

Example XML Request for PreCallTxn

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

</Request>

Example XML Request for PreCall Txn

<password

type="SHA1">df855a23df855a23df855a23df855a23df855a23</password>

</Authentication>

</TxnDetails>

<method>precall</method>

<client_reference>00001239</client_reference>

<client_order_id>order-15-2011</client_order_id>

<client_billing_id>cust12358</client_billing_id>

<client_pos>FRALH010Z</client_pos>

<client_country>IT</client_country>

<client_site>agent.com</client_site>

<reference_1>xyz</reference_1>

<reference_2>xyz</reference_2>

<reference_3>xyz</reference_3>

<reference_4>xyz</reference_4>

</CustomClientFields>

</ClientData>

<order_date_time>2011-01-14T14:22:23+01:00</order_date_time>

<delivery_date_time>2011-03-

25T14:30:00+01:00</delivery_date_time>

<billing_country>DE</billing_country>

<customer_logged_in>true</customer_logged_in>

<sales_channel>ecommerce</sales_channel>

<customer_ip_address>112.118.128.253</customer_ip_address>

<customer_language>fr</customer_language>

</OrderDetails>

<airline_country>DE</airline_country>

<airline_booking_type>BOOK</airline_booking_type>

<customer_level>SEN</customer_level>

<Legs>

<Leg>

<depart_airport>JFK</depart_airport>

<depart_city>NYC</depart_city>

<depart_state>NY</depart_state>

<depart_country>US</depart_country>

<arrival_airport>HAM</arrival_airport>

<arrival_city>HH</arrival_city>

<arrival_state>HH</arrival_state>

<arrival_country>DE</arrival_country>

</Leg>

</Legs>

</AirlineDetails>

</PreCallTxn>

</Transaction>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.8.9.3 Example Request / Response XML

The following represents an example PreCall request and response.

Example XML Response for PreCallTxn

<client_reference>00001239</client_reference>

<client_order_id>order-15-2011</client_order_id>

<client_billing_id>cust12358</client_billing_id>

<reference_1>xyz</reference_1>

<reference_2>xyz</reference_2>

<reference_3>xyz</reference_3>

<reference_4>xyz</reference_4>

</CustomClientFields>

</ClientData>

<payment_method type="wallet" valid_thru="2011-01-

14T22:50:00+01:00" airline_fee_level="A001">PL</payment_method>

<payment_method type="creditCard" valid_thru="2011-01-

14T22:50:00+01:00" airline_fee_level="A002">CC</payment_method>

</PaymentMethods>

</PreCallTxn>

<datacash_reference>4600900012345673</datacash_reference>

<reason>ACCEPTED</reason>

</Response>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.9 CARD TOKENIZATION

An overview of the Card Tokenization Service is available on the website:

http://www.datacash.com/gettingproducts.php?id=Card-Tokenization/

2.9.1 Schema Elements for Request

In this section the required fields for each transaction type will be presented, along

with example XML for those fields. The XML is presented in italics for those fields that

are not required for all transaction types. If the transaction type is specified in the XML,

this is highlighted in the cases where other transaction types can be used in its place.

As not all transaction types use the same fields, each field will be labelled with the

following key:

 O - Optional

 R - Required, field must be presented

 X - Excluded, presenting this field will cause the transaction to fail

 M - Mandatory if Available, if the information is available, it should be presented

Please refer to the website for definitions of the transaction types and examples of

when you may wish to implement them.

Generating a Token – during Payment

When subscribed to this service, any transaction which results in payment taken being

taken from or refunded a card will automatically generate a token. There is no change

to the data is passed for these transactions if the Merchant is using the default shared

secret configured on their account.

If the Merchant is using sending a shared secret with the transaction (to be used

instead of the default configured on their account, one additional element is required to

supply this shared secret. For most payment types, this is passed within the Card,

section 2.9.1.2.

Generating a Token – without payment

When generating a token without payment a tokenize transaction is used. Existing

tokens may also be retokenized using a retokenize transaction. For both of these,

data is passed in these distinct places in the schema:

 Request

o Authentication – section 2.1.1.2

o Transaction

 TokenizeTxn – the type and authorisation code, section 2.9.1.1

 Card - this contains the card number or an existing token

– section 2.9.1.1

 TxnDetails - contains details of the transaction, section

2.2.1.1.3

Generating a Token – via query transaction

Tokens for card numbers which have existing transactions may be retrieved using the

query transation. This may be used to generate tokens for cards processed before Card

Tokenization was configured on the account, or to obtain existing tokens. There is no

change to the format of the request, see section 2.9.1

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Payments using Tokens

When using a Card Token to make a payment, much of the XML Request is the same as

if the card details where being presented. However, in place of the card number the

token is presented instead. The position of this element within the schema will

varydepending upon the transaction type in question – as documented in section

2.9.1.2.

2.9.1.1 TokenizeTxn

This element is required for tokenize and retokenize transactions.

Element Name:

TokenizeTxn

Position:

Request.Transaction

Elements of TokenizeTxn

Element Name

Description

Values/Limitations

Card

See section 2.9.1.2

R

method

The type of

Token generation

tokenize

retokenize

R

shared_secret

Overrides the

VTIDs shared

secret

a 20 character string containing digits

(0 to 9) or letters drawn from the

Standard English (upper case)

alphabet (A to Z)

O

Example XML for TokenizeTxn element

<method>tokenize</method>

</TokenizeTxn>

<method>retokenize</method>

<shared_secret>1234567890ABCDEFGHIJ</shared_secret>

</TokenizeTxn>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.9.1.2 pan

This element is not a Parent element, but a child element of several parents in the

schema. It is required for tokenize, retokenize and payments made using tokens.

Element Name:

pan

Position:

Request.Transaction.CardTxn.Card

Request.Transaction.DirectDebitTxn

Request.Transaction.FuelCardTxn.Card

Request.Transaction.RbsGiftCardTxn.Card

Request.Transaction.TokenizeTxn.CardTxn.Card

Request.Transaction.DirectcreditTxn

The pan element

Element Name

Description

Values/Limitations

Required for

pan

The card

number, or

token

If the value supplied is a

token, the attribute must

be set appropriately (see

below).

All transaction types

Attributes for pan

Attribute

Name

Values / Limitations

Required for

type

token – used to indicate a token is being

provided.

retokenize and

payments using tokens

hps_token – used to indicate a token is being

used for an HCC setup collecting CV2 and expiry

only

HCC setup

It should be noted that if the payment method you are using requires additional

elements within the parent element (e.g. expirydate), these should continue to be

presented as documented within the appropriate section of this Guide. No additional

elements are required for tokenize and retokenize.

Example XML for Card element, for a retokenize transaction

<Card>

</Card>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example XML for Card element, for a tokenize transaction

<Card>

</Card>

Example XML for Card complex elements for a payment using a token

<Card>

</Card>

Example XML for Card complex elements for a payment using a token,

where HCC is being used to collect the CV2 and expiry date

<Card>

3C12DE55292A13227E14D92C6E8D8F4843D21654</pan>

</Card>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.9.2 Example XML Requests

2.9.2.1 Tokenize

Example XML Request to tokenize a card, using the default shared

secret configured on the account

</Authentication>

<Card>

</Card>

<method>tokenize</method>

</TokenTxn>

</TxnDetails>

</Transaction>

</Request>

Example XML Request to tokenize a card, providing a new shared secret

with the transaction

</Authentication>

<Card>

<shared_secret>0123456789abcdeFGHIJ</shared_secret>

</Card>

<method>tokenize</method>

</TokenTxn>

</TxnDetails>

</Transaction>

</Request>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example XML Request to tokenize a swiped card, using the default

shared secret configured on the account

</Authentication>

<Card>

<card_details type='track2_data'>

NDQ0NDMzMzMyMjIyMTExMT0yODA5MjAxMDAMDAwMU...YfMA==</card_details>

</Card>

<method>tokenize</method>

</TokenTxn>

</TxnDetails>

</Transaction>

</Request>

2.9.2.2 Tokenization during Payment, default shared secret

Once Card Tokenization is configured on the Merchant account, the XML Requests for

payment are unchanged if the Merchant wishes to use the default shared secret

configured on the account.

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.9.2.3 Tokenization during Payment, providing shared secret

To be used if the Merchant wishes to provide a shared_secret with the payment

Example XML Request for Bank Card payment, providing a new shared

secret with the transaction

</Authentication>

<Card>

</Card>

<shared_secret>1234567890ABCDEFGHIJ</shared_secret>

</CardTxn>

</TxnDetails>

</Transaction>

</Request>

Example XML Request for Direct Credit cardaccountpayment, providing

a new shared secret with the transaction

</Authentication>

</TxnDetails>

<method>cardaccountpayment</method>

<shared_secret>1234567890ABCDEFGHIJ</shared_secret>

</DirectCreditTxn>

</Transaction>

</Request>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example XML Request for Bank Card payment via HCC, providing a new

shared secret with the transaction

</Authentication>

<card_details type="from_hps">4900203023045857

</card_details>

<shared_secret>1234567890ABCDEFGHIJ</shared_secret>

</CardTxn>

</TxnDetails>

</Transaction>

</Request>

2.9.2.4 Using Tokens for Payments

Example XML Request for Bank Card payment using a token

</Authentication>

<Card>

<pan

type="token">3C12DE55292A13227E14D92C6E8D8F4843D21654</pan>

</Card>

</CardTxn>

</TxnDetails>

</Transaction>

</Request>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example XML Request for Bank Card payment with 3-D Secure using a

token

</Authentication>

<Card>

<pan

type="token">3C12DE55292A13227E14D92C6E8D8F4843D21654</pan>

</Card>

</CardTxn>

...

</ThreeDSecure>

</TxnDetails>

</Transaction>

</Request>

Example XML Request for Direct Credit cardaccountpayment using a

token

</Authentication>

<method>cardaccountpayment</method>

<pan type="token">3C12DE55292A13227E14D92C6E8D8F4843D21654

</pan>

</DirectCreditTxn>

</TxnDetails>

</Transaction>

</Request>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example XML Request for Fuel Card payment using a token

</Authentication>

<capturemethod>keyed</capturemethod>

</TxnDetails>

<method>fuel_validate</method>

<terminal_capabilities ic_reader="true"

magnetic_stripe_reader="true" manual_card_entry="true"/>

<features_capabilities pin_pad_available="true"/>

</Terminal>

<ICC>

<term_type>22</term_type>

</ICC>

<Card>

<pan type="token">59307422C194A22332160C850F415A0164707908

</pan>

</Card>

</FuelCardTxn>

</Transaction>

</Request>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example XML Request for PPT using a token

</Authentication>

<capturemethod>keyed</capturemethod>

</TxnDetails>

<terminal_capabilities ic_reader="true"

magnetic_stripe_reader="true" manual_card_entry="true"/>

<features_capabilities pin_pad_available="true"/>

</Terminal>

<pan type=”token”> 781C5A1B53BBC9DEF17AF7334ADE0C9E31841EAC

</pan>

</PPTCardTxn>

</Transaction>

</Request>

2.9.3 Schema Elements for Response

When using the Card Tokenization service, there is one additional element that may

appear in the response for all transactions. This element will appear in different

positions within the schema depending upon the transaction type in question

Element Name:

token

Position:

Response

Response.CardTxn

Response.FuelCardTxn

Response.PPTCardTxn

Response.QueryTxn.CardTxn

Response.RbsGiftCardTxn

Response.TokenizeTxn

The token element

Element

Name

Position

Return with

token

Response

cardaccountpayment

Response.CardTxn

auth, pre, refund and erp

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Response.FuelCardTxn

Fuels transactions

Response.PPTCardTxn

PPT transactions

Response.QueryTxn.CardTxn

query

Response.RbsGiftCardTxn

RBS Giftcard transactions

Response.TokenizeTxn

tokenize and retokenize

Example XML Response Elements containing token field

...

</TokenizeTxn>

...

<token>FE554B87039DAFCB9D03F6AFBB502028B33AA7A1</token>

</CardTxn>

...

</RbsGiftCardTxn>

2.9.4 Example XML Responses

2.9.4.1 Tokenize and Retokenize

Example XML Response for tokenize or retokenize

<card_scheme>Mastercard</card_scheme>

<country>United Kingdom</country>

<issuer>National Westminster Bank Plc</issuer>

</TokenizeTxn>

<datacash_reference>4900203022056130</datacash_reference>

<reason>ACCEPTED</reason>

</Response>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.9.4.2 Tokenization During Payment

Example XML Responses to a successful Bank Card payment or refund

<card_scheme>Mastercard</card_scheme>

<country>Poland</country>

<token>FE554B87039DAFCB9D03F6AFBB502028B33AA7A1</token>

</CardTxn>

<datacash_reference>4400203020266707</datacash_reference>

<reason>ACCEPTED</reason>

</Response>

<cv2avs_status>NO DATA MATCHES</cv2avs_status>

</Cv2Avs>

<card_scheme>VISA</card_scheme>

</CardTxn>

<datacash_reference>4800203023045872</datacash_reference>

<reason>ACCEPTED</reason>

</Response>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example XML Response to a DECLINED Bank Card payment or refund

<authcode>DECLINED</authcode>

<card_scheme>Maestro</card_scheme>

<country>United Kingdom</country>

</CardTxn>

<datacash_reference>4400203020266707</datacash_reference>

<reason>DECLINED</reason>

</Response>

Example XML Response to a Bank Card Payment with 3-D Secure

<acs_url>https://testserver.datacash.com/acs</acs_url>

<pareq_message>eJxdUk1PwyAYvu9XEC9eTKFd.../</pareq_message>

</ThreeDSecure>

<card_scheme>VISA</card_scheme>

</CardTxn>

<datacash_reference>4700203022949886</datacash_reference>

<reason>3DS Payer Verification Required</reason>

</Response>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example XML Response to a Direct Credit cardaccountpayment transaction

<datacash_reference>4600203020658851</datacash_reference>

<reason>Accepted</reason>

</Response>

Example XML Response to a RBS Giftcard balance_enquiry transaction

</RbsGiftCardTxn>

<datacash_reference>4100203023047327</datacash_reference>

<reason>ACCEPTED</reason>

</Response>

Example XML Response to a PPT transaction

<authcode>CARD HAS NOT BEEN ACTIVATED</authcode>

<card_activated>no</card_activated>

</PPTCardTxn>

<datacash_reference>4800203023047201</datacash_reference>

<reason>DECLINED</reason>

</Response>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example XML Response to a Fuels Card transaction

<card_scheme>CHJones Fuel Card</card_scheme>

<issuer>Key Fuels Bunker+</issuer>

</FuelCardTxn>

<acquirer_message>AUTH CODE:075216</acquirer_message>

<acquirer_response_code>00</acquirer_response_code>

<datacash_reference>4800203023047017</datacash_reference>

<reason>ACCEPTED</reason>

<referral_telephone_number>MTIzNA==</referral_telephone_number>

</Response>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.9.4.3 Tokenization during Query

Example XML Responses to query transactions

<Card>

<card_category>Unknown</card_category>

<issuer>Unknown</issuer>

</Card>

<datacash_reference>4200203020699556</datacash_reference>

<environment>ecomm</environment>

<fulfill_date/>

<merchant_reference>...</merchant_reference>

<reason>ACCEPTED</reason>

<transaction_date>2011-11-16 13:41:18</transaction_date>

</QueryTxnResult>

<reason>ACCEPTED</reason>

</Response>

<Card>

<card_category>Unknown</card_category>

<issuer>Allocated to Switch</issuer>

<scheme>Maestro</scheme>

</Card>

<authcode>DECLINED</authcode>

<datacash_reference>4000203020277500</datacash_reference>

<environment>ecomm</environment>

<fulfill_date/>

<merchant_reference>...</merchant_reference>

<reason>DECLINED</reason>

<transaction_date>2012-02-01 16:55:19</transaction_date>

</QueryTxnResult>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

<reason>ACCEPTED</reason>

</Response>

2.10 SWITCH TO ISSUER TRANSACTIONS

2.10.1 Versioning

All Switch to Issuer transactions are version 2.

2.10.2 Standard transaction - response elements

When submitting a standard transaction through Switch to Issuer, five extra response

elements are provided by the DPG. These are:

Elements of Response

Element Name

Description

response_code

Contains the response code returned by

Switch to Issuer.

response_text

Contains the response message returned

by Switch to Issuer.

aiic

Acquiring Institution ID Code – 6 digits

stan

System Trace Audit Number – 6 digits

rrn

Retrieval Reference Number – 12 digits

Example XML:

Response

...

<datacash_reference>3900100821792328</datacash_reference>

...

<response_code>0</response_code>

<response_text>Approved or completed successfully</response_text>

</CardTxn>

...

</Response>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.10.3 Query transaction – response elements

When making a query transaction against Switch to Issuer, three new response

elements are provided by the DPG. These are:

Elements of Response

Element Name

Description

aiic

Acquiring Institution ID Code – 6 digits

stan

System Trace Audit Number – 6 digits

rrn

Retrieval Reference Number – 12 digits

Example XML:

Query Response

...

<datacash_reference>3900100821792328</datacash_reference>

...

</QueryTxnResult>

...

</Response>

2.10.4 Transactions including CSC data

For Switch to Issuer, CSC (CV2) data is to be supplied in an alternative structure,

under a CSC block (part of CardTxn).

As well as the CSC (CV2) number, a policy can optionally be supplied, or an

ExtendedPolicy (unlike non-Switch to Issuer transactions, CSC.ExtendedPolicy can only

contain a single element, csc_policy).

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example XML:

...

<Card>

<CSC>

</CSC>

</Card>

...

</CardTxn>

...

</Request>

...

<Card>

<CSC>

</CSC>

</Card>

...

</CardTxn>

...

</Request>

...

<Card>

<CSC>

<csc_policy notprovided='reject' notchecked='reject'

matched='accept' notmatched='reject' partialmatch='reject' />

</ExtendedPolicy>

</CSC>

</Card>

...

</CardTxn>

...

</Request>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.10.5 Transactions including AVS data

For Switch to Issuer, AVS data is to be supplied in an alternative structure, under an

AVS block (part of CardTxn).

As well as the address data, a policy can optionally be supplied, or an ExtendedPolicy

(unlike non-Switch to Issuer transactions, AVS.ExtendedPolicy can only contain the two

elements, postcode_policy and address_policy).

Example XML:

...

<Card>

<AVS>

<street_address1>1 High Street</street_address1>

<street_address2>Town</street_address2>

<street_address3>County</street_address3>

<street_address4>United Kingdom</street_address4>

</AVS>

</Card>

...

</CardTxn>

...

</Request>

...

<Card>

<AVS>

<street_address1>1 High Street</street_address1>

<street_address2>Town</street_address2>

<street_address3>County</street_address3>

<street_address4>United Kingdom</street_address4>

</AVS>

</Card>

...

</CardTxn>

...

</Request>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Back to Contents

...

<Card>

<AVS>

<street_address1>1 High Street</street_address1>

<street_address2>Town</street_address2>

<street_address3>County</street_address3>

<street_address4>United Kingdom</street_address4>

<postcode_policy notprovided='reject' notchecked='reject'

matched='accept' notmatched='reject' partialmatch='reject' />

<address_policy notprovided='reject' notchecked='reject'

matched='accept' notmatched='reject' partialmatch='reject' />

</ExtendedPolicy>

</AVS>

</Card>

...

</CardTxn>

...

</Request>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.11 LOCAL DIRECT DEBIT

2.11.1 Service Overview

In Germany the ELV system (Elektronisches Lastschriftverfahren - Direct Debit) is the

most popular method of payment among customers in an online environment. The ELV

process is a simple one and can be utilised by anyone who is in possession of a German

cheque account. This payment method allows the customer to authorise a merchant to

withdraw money directly from their bank account.

Schema Elements for Request

o Request

 Authentication – section 2.1.1.2

 Transaction

 LocalDDTxn – section 2.11.2

 TxnDetails – section 2.11.3

The following keys will be used for each transaction type:

 B – localdd_buy

 A – localdd_authorise

 C – localdd_capture

 L – localdd_cancel

 R – localdd_refund

Each field will be labelled with the following key:

 O – Optional.

 R – Required, field must be presented.

 X – Excluded, presenting this field will cause the transaction to fail.

2.11.2 LocalDDTxn

Element Name:

LocalDDTxn

Position(s)

Request.Transaction

Attributes of LocalDDTxn

Attribute

Name

Attribute of

Element

Values / Limitations

B

A

C

L

R

type

LocalDDTxn

Currently this should only be ‘elv’.

R

X

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Elements of LocalDDTxn

Element Name

Description

Values/

Limitations

B

A

C

L

R

billing_name

The name of the

account holder

Alphanumeric

R

X

method

Determines the

processing model to be

used

localdd_buy - for one

stage processing

localdd_authorise -

for two stage

processing

R

X

profile

The respective profile

controls which payment

and transaction

methods can be

selected.

Numeric

R

X

customer_ip

The customer’s IP

address.

Valid IP address

R

X

One of the following payment elements must be included. Please note, sortcode and

accountnumber are supplied as a pair.

Elements of LocalDDTxn

Attribute Name

Description

Values /

Limitations

sortcode

The sort code of the customer's bank

Six digits

accountnumber

The customer's account number

Eight digits

iban

An International Bank Account Number. Standard

for indentifying bank accounts across national

borders.

A valid IBAN

paymentreference

Merchant configurable data field typically used to

identify a customer uniquely within the system,

regardless of the amount of accounts that the

customer has.

A valid

Payment

Reference

When the method in use is localdd_buy one of the following elements is required.

Elements of LocalDDTxn

Attribute

Name

Description

Values /

Limitations

delaydays

The number of days on which the direct debit

must be actioned.

Numeric

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

debitdate

The date on which the direct debit must be

auctioned.

yyyy-mm-dd

Example XML for LocalDDTxn complex elements:

localdd_buy

<customer_ip>192.168.1.1</customer_ip>

<method>localdd_buy</method>

<billing_name>A Customer<method>

</LocalDDTxn>

localdd_authorise

<customer_ip>192.168.1.1</customer_ip>

<method>localdd_authorise</method>

<billing_name>A Customer<method>

</LocalDDTxn>

2.11.3 TxnDetails

Element Name:

TxnDetails

Position:

Request.Transaction

Elements of TxnDetails

Element Name

Description

Values/

Limitations

B

A

C

L

R

merchantreference

A unique reference

number for each

transaction

Min 6, max 30

alphanumeric

characters. Must be

unique.

R

X

amount

The value of the

transaction

R

O

Attributes for Elements of TxnDetails

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Attribute

Name

Attribute

of

Element

Values / Limitations

B

A

C

L

R

currency

amount

Currency is passed in the 3 character ISO

4217 Alphabetic format e.g. GBP, USD,

EUR.

R

X

Example XML for TxnDetails complex elements:

Transaction

<merchantreference>myreference123459988</merchantreference>

</TxnDetails>

Historic Transaction

</TxnDetails>

2.11.4 HistoricTxn

This element is the direct equivalent of the Card element (for transactions using card

details).

Element Name:

HistoricTxn

Position:

Request.Transaction

Elements of HistoricTxn

Element

Name

Description

Values / Limitations

C

L

R

reference

DataCash unique reference of

the original transaction

must be a valid

transaction

R

method

The transaction type

localdd_capture

localdd_cancel

localdd_refund

R

Example XML Request for HistoricTxn complex elements

<method>localdd_capture</method>

</HistoricTxn>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Successful localdd_authorise

<apg_reference_id>150968437</apg_reference_id>

<apg_response_code>100</apg_response_code>

<apg_response_desc>Transaction successfull</apg_response_desc>

<method>localdd_authorise</method>

</LocalDDTxn>

<datacash_reference>3300900010000208</datacash_reference>

<reason>The APG accepted the transaction</reason>

</Response>

Successful localdd_capture

<apg_payment_id>DD1354319267000</apg_payment_id>

<apg_reference_id>150968507</apg_reference_id>

<apg_response_code>100</apg_response_code>

<apg_response_desc>Transaction successfull</apg_response_desc>

<method>localdd_capture</method>

</LocalDDTxn>

<datacash_reference>3300900010000208</datacash_reference>

<reason>CAPTURED OK</reason>

</Response>

Unsuccessful localdd_buy

<method>localdd_buy</method>

</LocalDDTxn>

<datacash_reference>3900900010000210</datacash_reference>

<information>Field 'delaydays' or 'debitdate' are required for

localdd_buy txns</information>

<reason>Field not supported in APG transaction</reason>

</Response>

Unsuccessful localdd_capture

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Back to Contents

<apg_error_code>211</apg_error_code>

<apg_error_description>Modification.DPGReferenceId refers to

transaction that cannot be captured</apg_error_description>

<method>localdd_capture</method>

</LocalDDTxn>

<datacash_reference>3500900010000207</datacash_reference>

<reason>The APG rejected the transaction</reason>

</Response>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.12 ALTERNATIVE PAYMENT METHODS

The DataCash Payment Gateway has built in support for the following Alternative

Payment Methods:

 iDeal

 Sofort

 La Caixa

 Nordea

 Web Money

 MisterCash

 Alipay

 Giropay

If you are interested in using one or more of the supported alternative payment

methods, please contact DataCash support.

The following sections detail the request / response XML elements used to process

alternative payments using the DataCash Payment Gateway:

2.12.1 Common Request Elements

The following request elements are common across all of the alternative payment

methods listed above. Billing information is optional (O), whereas all other common

fields are required / mandatory (R).

Element Names:

IdealTxn

SofortTxn

LaCaixaTxn

NordeaTxn

WebMoneyTxn

MisterCashTxn

AlipayTxn

GiropayTxn

Position:

Request.Transaction

Elements of [PaymentMethod]Txn

Element Name

Description

Values/Limitations

method

The type of request.

A constant value of “payment” (this is

currently the only method supported)

R

language

The customer’s

language

IETF Language Tag

R

customer_email

The customer’s E-

Mail address.

64 Characters Maximum, must contain @ and .

R

customer_ip

The IPv4 address of

the customer.

nnn.nnn.nnn.nnn

R

title

The customer’s

title/honorific.

E.g. Mr, Mrs, Sir, Miss, Lord

R

first_name

The customer’s first

name.

Alphanumeric. Between 1 and 31 characters (2

to 31 if fraud screening to be carried out)

R

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

last_name

The customer’s last

name / surname.

Alphanumeric. Between 1 and 31 characters (2

to 31 if fraud screening to be carried out).

R

country

The customer’s

country. In the case

of an airlines

transaction, this

would usually be the

country of

departure.

(ISO 3166-1 Alpha-2)

R

billing_street1

The billing address

(1st line)

Alphanumeric

O

billing_street2

The billing address

(2nd line)

Alphanumeric

O

billing_city

The billing city

Alphanumeric

O

billing_postcode

The billing postal

code

Alphanumeric

O

billing_state_pro

vince

The billing state /

province

Alphanumeric

O

billing_country

The billing country.

Alphanumeric

O

2.12.2 iDeal Transactions

2.12.2.1 Payment Transactions

The following request elements are specific to iDeal payment transactions (in addition

to the common elements described above).

Element Names:

IdealTxn

Position:

Request.Transaction

Elements of IdealTxn

Element Name

Description

Values/Limitations

method

The type of request.

For payment transactions this must

be “payment”.

R

issuer_id

The issuer id

Alphanumeric

R

success_url

The success URL

(customer will be

redirected in the

event of a successful

payment)

Alphanumeric

R

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

failure_url

The failure URL

(customer will be

redirected in the

event of a failed

payment / error)

Alphanumeric

R

Example IdealTxn Payment Request:

</Authentication>

</TxnDetails>

<method>payment</method>

<customer_email>john@mail.com</customer_email>

<customer_ip>127.0.0.1</customer_ip>

<first_name>JOHN</first_name>

<last_name>KENT</last_name>

<billing_street1>Address Line 1</billing_street1>

<billing_city>CA</billing_city>

<billing_postcode>12345</billing_postcode>

<billing_country>DE</billing_country>

<issuer_id>2</issuer_id>

<success_url>http://success</success_url>

<failure_url>http://failure</failure_url>

</IdealTxn>

</Transaction>

</Request>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example IdealTxn Payment Response:

<redirect_param param_name="param1">value1</redirect_param>

<redirect_param param_name="param2">value2</redirect_param>

</RedirectParams>

<apg_ref>123456789</apg_ref>

<apg_status>REDIRECT</apg_status>

<content_type>application/x-www-form-urlencoded</content_type>

<display_message>Please wait</display_message>

<http_method>POST</http_method>

<redirect_url>http://redirecthost</redirect_url>

</IdealTxn>

<datacash_reference>4200903000000481</datacash_reference>

<reason>The APG accepted the transaction</reason>

</Response>

2.12.2.2 Txn Refund Transactions

iDeal supports multiple partial refunds up to 100% of the original refund amount. An

amount can be specified in the Request.Transaction.TxnDetails.amount element.

Element Names:

IdealTxn

Position:

Request.Transaction

Elements of IdealTxn

Element Name

Description

Values/Limitations

method

The type of request.

For txn refund transactions this must

be "txn_refund".

R

reference

The historic

reference of a

previously completed

IdealTxn payment.

Numeric

R

note

A description of the

transaction.

Alphanumeric

O

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example IdealTxn Txn Refund Request:

</Authentication>

</TxnDetails>

<method>txn_refund</method>

<note>Refund note</note>

</IdealTxn>

</Transaction>

</Request>

Example IdealTxn Txn Refund Response:

<apg_bank_ref>221236068</apg_bank_ref>

<apg_ref>84695</apg_ref>

<apg_status>REFUNDED</apg_status>

</IdealTxn>

<datacash_reference>4500900010000486</datacash_reference>

<reason>ACCEPTED</reason>

</Response>

2.12.2.3 Bank List Transactions

A list of banks supported by iDeal can be retrieved by sending a Bank List request to

the DPG.

Element Names:

IdealTxn

Position:

Request.Transaction

Elements of IdealTxn

Element Name

Description

Values/Limitations

method

The type of request.

For bank list transactions this must

be "idealbanklistitem"

R

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example IdealTxn Bank List Request:

</Authentication>

<method>idealbanklistitem</method>

</IdealTxn>

</Transaction>

</Request>

Example IdealTxn Bank List Response:

<Banks>

<issuer_id>1</issuer_id>

<name>iDeal Bank A</name>

</Bank>

<issuer_id>2</issuer_id>

<name>iDeal Bank B</name>

</Bank>

...

</Banks>

</IdealTxn>

<datacash_reference>4000900010000498</datacash_reference>

<reason>ACCEPTED</reason>

</Response>

2.12.3 Sofort Transactions

2.12.3.1 Payment Transactions

The following request elements are specific to Sofort payment transactions (in addition

to the common elements described above).

Element Names:

SofortTxn

Position:

Request.Transaction

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Elements of SofortTxn

Element Name

Description

Values/Limitations

method

The type of request

For payment transactions this must

be “payment”.

issuer_id

The issuer id

Alphanumeric

R

success_url

The success URL

(customer will be

redirected in the

event of a successful

payment)

Alphanumeric

R

failure_url

The failure URL

(customer will be

redirected in the

event of a failed

payment / error)

Alphanumeric

R

Example Sofort Payment Request:

</Authentication>

</TxnDetails>

<method>payment</method>

<customer_email>john@mail.com</customer_email>

<customer_ip>127.0.0.1</customer_ip>

<first_name>JOHN</first_name>

<last_name>KENT</last_name>

<billing_street1>Address Line 1</billing_street1>

<billing_city>CA</billing_city>

<billing_postcode>12345</billing_postcode>

<billing_country>DE</billing_country>

<success_url>http://success</success_url>

<failure_url>http://failure</failure_url>

</SofortTxn>

</Transaction>

</Request>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example Sofort Payment Response:

<redirect_param param_name="user_id">12345</redirect_param>

<redirect_param param_name="project_id">56789</redirect_param>

<redirect_param param_name="amount">119.76</redirect_param>

<redirect_param param_name="currency_id">GBP</redirect_param>

<redirect_param

param_name="reason_1">SU1234567890123</redirect_param>

<redirect_param param_name="reason_2">12345</redirect_param>

<redirect_param

param_name="user_variable_0">123456789</redirect_param>

<redirect_param

param_name="user_variable_1">X4M75U</redirect_param>

<redirect_param

param_name="user_variable_2">127.0.0.1</redirect_param>

<redirect_param

param_name="user_variable_4">https://epi.expercash.net/3rdPartyNotifica

tion/su_success.php?taid=123456789/</redirect_param>

<redirect_param

param_name="user_variable_5">https://epi.expercash.net/3rdPartyNotifica

tion/su_failure.php/</redirect_param>

<redirect_param

param_name="hash">0123456789ABCDEF0123456789ABCDEF01234567</redirect_pa

ram>

</RedirectParams>

<apg_ref>123456789</apg_ref>

<apg_status>REDIRECT</apg_status>

<content_type>application/x-www-form-urlencoded</content_type>

<http_method>GET</http_method>

<redirect_url>http://testdb:8180/dc-apg-

simulator/payment/</redirect_url>

</SofortTxn>

<datacash_reference>4600903000000479</datacash_reference>

<reason>The APG accepted the transaction</reason>

</Response>

2.12.3.2 Txn Refund Transactions

The following request elements are specific to Sofort txn refund transactions. Sofort

supports multiple partial refunds up to 100% of the original refund amount. An amount

can be specified in the Request.Transaction.TxnDetails.amount element.

Element Names:

SofortTxn

Position:

Request.Transaction

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Elements of IdealTxn

Element Name

Description

Values/Limitations

method

The type of request.

For txn refund transactions this must

be "txn_refund".

R

reference

The historic

reference of a

previously completed

SofortTxn payment.

Numeric

R

note

A description of the

transaction.

Alphanumeric

O

Example SofortTxn Txn Refund Request:

</Authentication>

</TxnDetails>

<method>txn_refund</method>

<note>Refund note</note>

</SofortTxn>

</Transaction>

</Request>

Example SofortTxn Txn Refund Response:

<apg_bank_ref>221260687</apg_bank_ref>

<apg_ref>84718</apg_ref>

<apg_status>REFUNDED</apg_status>

</SofortTxn>

<datacash_reference>4900900010000540</datacash_reference>

<reason>ACCEPTED</reason>

</Response>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.12.4 WebMoney Transactions

The following request elements are specific to WebMoney transactions (in addition to

the common elements described above).

Element Names:

WebMoneyTxn

Position:

Request.Transaction

Elements of WebMoneyTxn

Element Name

Description

Values/Limitations

success_url

The success URL

(customer will be

redirected in the

event of a successful

payment)

Alphanumeric

R

failure_url

The failure URL

(customer will be

redirected in the

event of a failed

payment / error)

Alphanumeric

R

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example WebMoneyTxn Request:

</Authentication>

</TxnDetails>

<method>payment</method>

<customer_email>john@mail.com</customer_email>

<customer_ip>127.0.0.1</customer_ip>

<first_name>JOHN</first_name>

<last_name>KENT</last_name>

<billing_street1>Address Line 1</billing_street1>

<billing_city>CA</billing_city>

<billing_postcode>12345</billing_postcode>

<billing_country>DE</billing_country>

<success_url>http://success</success_url>

<failure_url>http://failure</failure_url>

</WebMoneyTxn>

</Transaction>

</Request>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example WebMoneyTxn Response:

<redirect_param

param_name="LMI_PAYMENT_AMOUNT">119.76</redirect_param>

<redirect_param

param_name="LMI_PAYEE_PURSE">pursename</redirect_param>

<redirect_param param_name="LMI_PAYMENT_NO">payment

number</redirect_param>

<redirect_param param_name="LMI_SIM_MODE">sim

mode</redirect_param>

</RedirectParams>

<apg_ref>123456789</apg_ref>

<apg_status>REDIRECT</apg_status>

<content_type>application/x-www-form-urlencoded</content_type>

<display_message>Please wait while you are redirected to

WebMoney</display_message>

<http_method>GET</http_method>

<redirect_url>http://webmoneyurl</redirect_url>

</WebMoneyTxn>

<datacash_reference>4300903000000485</datacash_reference>

<reason>The APG accepted the transaction</reason>

</Response>

2.12.5 MisterCash Transactions

The following request elements are specific to MisterCash transactions (in addition to

the common elements described above).

Element Names:

MisterCashTxn

Position:

Request.Transaction

Elements of MisterCashTxn

Element Name

Description

Values/Limitations

success_url

The success URL

(customer will be

redirected in the

event of a successful

payment)

Alphanumeric

R

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

failure_url

The failure URL

(customer will be

redirected in the

event of a failed

payment / error)

Alphanumeric

R

Example MisterCashTxn Request:

</Authentication>

</TxnDetails>

<method>payment</method>

<customer_email>john@mail.com</customer_email>

<customer_ip>127.0.0.1</customer_ip>

<first_name>JOHN</first_name>

<last_name>KENT</last_name>

<billing_street1>Address Line 1</billing_street1>

<billing_city>CA</billing_city>

<billing_postcode>12345</billing_postcode>

<billing_country>DE</billing_country>

<success_url>http://success</success_url>

<failure_url>http://failure</failure_url>

</MisterCashTxn>

</Transaction>

</Request>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example MisterCashTxn Response:

<redirect_param

param_name="merchantID">123456789</redirect_param>

<redirect_param param_name="customerRef">X4M75U</redirect_param>

<redirect_param param_name="country">UK</redirect_param>

<redirect_param param_name="currency">GBP</redirect_param>

<redirect_param param_name="recieveCurrency">GBP</redirect_param>

<redirect_param param_name="email">john@mail.com</redirect_param>

<redirect_param param_name="service">MISTERCASH</redirect_param>

<redirect_param param_name="language">en</redirect_param>

</RedirectParams>

<apg_ref>123456789</apg_ref>

<apg_status>REDIRECT</apg_status>

<content_type>application/x-www-form-urlencoded</content_type>

<display_message>Please wait while you are redirected to the Envoy

OneClick site</display_message>

<http_method>GET</http_method>

<redirect_url>http://envoy</redirect_url>

</MisterCashTxn>

<datacash_reference>4800903000000483</datacash_reference>

<reason>The APG accepted the transaction</reason>

</Response>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.12.6 La Caixa Transactions

Only the common elements described above are applicable to La Caixa transactions.

Element Names:

LaCaixaTxn

Position:

Request.Transaction

Example LaCaixaTxn Request:

</Authentication>

</TxnDetails>

<method>payment</method>

<customer_email>john@mail.com</customer_email>

<customer_ip>127.0.0.1</customer_ip>

<first_name>JOHN</first_name>

<last_name>KENT</last_name>

<billing_street1>Address Line 1</billing_street1>

<billing_city>CA</billing_city>

<billing_postcode>12345</billing_postcode>

<billing_country>DE</billing_country>

</LaCaixaTxn>

</Transaction>

</Request>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example LaCaixaTxn Response:

<apg_account_name>Merchant account name</apg_account_name>

<apg_account_number>1234567890</apg_account_number>

<apg_bank>Bank of Bankeria</apg_bank>

<apg_branch>BranchName</apg_branch>

<apg_branch_address>123 Bank St, Banktown, Republic of

Bankeria</apg_branch_address>

<apg_iban>RB01 CBCO 1234 1234 1234 56</apg_iban>

<apg_ref>123456789</apg_ref>

<apg_status>PENDING</apg_status>

<apg_swift>CBCORB00XXX</apg_swift>

<display_message>Display message</display_message>

</LaCaixaTxn>

<datacash_reference>4400903000000475</datacash_reference>

<reason>The APG accepted the transaction</reason>

</Response>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.12.7 Nordea Transactions

Only the common elements described above are applicable to Nordea transactions.

Element Names:

NordeaTxn

Position:

Request.Transaction

Example NordeaTxn Request:

</Authentication>

</TxnDetails>

<method>payment</method>

<customer_email>john@mail.com</customer_email>

<customer_ip>127.0.0.1</customer_ip>

<first_name>JOHN</first_name>

<last_name>KENT</last_name>

<billing_street1>Address Line 1</billing_street1>

<billing_city>CA</billing_city>

<billing_postcode>12345</billing_postcode>

<billing_country>DE</billing_country>

</NordeaTxn>

</Transaction>

</Request>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

xample NordeaTxn Response:

<apg_account_name>Merchant account name</apg_account_name>

<apg_account_number>1234567890</apg_account_number>

<apg_bank>Bank of Bankeria</apg_bank>

<apg_branch>BranchName</apg_branch>

<apg_branch_address>123 Bank St, Banktown, Republic of

Bankeria</apg_branch_address>

<apg_iban>RB01 CBCO 1234 1234 1234 56</apg_iban>

<apg_ref>123456789</apg_ref>

<apg_status>PENDING</apg_status>

<apg_swift>CBCORB00XXX</apg_swift>

<display_message>Display message</display_message>

</NordeaTxn>

<datacash_reference>4900903000000473</datacash_reference>

<reason>The APG accepted the transaction</reason>

</Response>

2.12.8 Alipay Transactions

2.12.8.1 Purchase Transactions

The following request elements are specific to Alipay purchase transactions (in addition

to the common elements described above).

Element Name:

AlipayTxn

Position:

Request.Transaction

Elements of AlipayTxn

Element Name

Description

Values/Limitations

authorization_token

The secure token for

accessing express login

API.

Alphanumeric

O

buyer_id

The unique ID of the

buyer for this transaction.

Alphanumeric

O

settlement_currency

The 3 digit currency code

for the currency that will

be used to settle the

transaction.

Numeric

R

subject

The name of the goods.

Alphanumeric

R

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

supplier

The name of the supplier,

these details are agreed

between Alipay and the

merchant.

Alphanumeric

O

body

A detailed description of

the goods.

Alphanumeric

O

user_agent_header

This is a value indicating

the browser type and

operating system details

of the user. This

information can be

retrieved from

the HTTP_USER_AGENT

header.

Alphanumeric

O

description

Use this field to supply

descriptive text for the

transaction.

Alphanumeric

O

success_url

The success URL

(customer will be

redirected in the event of

a successful payment)

Alphanumeric

R

failure_url

The failure URL (customer

will be redirected in the

event of a failed payment

/ error)

Alphanumeric

R

billing_name

A descriptor for the billing

details.

Alphanumeric

O

2.12.8.2 Refund Transactions

The following request elements are specific to Alipay refund transactions.

Element Name:

AlipayTxn

Position:

Request.Transaction

Elements of AlipayTxn

Element Name

Description

Values/Limitations

method

The type of request.

Must be 'txn_refund'

R

reference

DataCash transaction

reference of the original

transaction

Must reference a valid, Alipay

purchase which has been

successfully completed

R

note

A description of the

transaction.

Alphanumeric

O

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Notes:

 An Alipay refund can only be submitted against a completed Alipay Purchase Transaction which has

had a Query Transaction completed against it returning a status code of "1".

 A successful Alipay refund will initially return a reason of "Sent for refund" with status code of "1832", it

is necessary to send a subsequent Query Transaction at a later time to complete the refund. This will

query Alipay to determine whether the refund was successfully processed. A successfully processed

refund will return a status of "Refunded" and a status code of "1".

 When sending a Query Transaction against an outstanding Alipay refund the "reference" used should

be that of the refund you are querying, and not the original purchase transaction.

 Alipay supports multiple partial refunds up to 100% of the original purchase amount, however it is

necessary to ensure that the previous refund was successfully processed by means of a Query

Transaction before attempting a subsequent refund.

The optional currency supplied in the "TxnDetails" block must match that of the original payment

transaction.

2.12.9 Giropay Transactions

2.12.9.1 Purchase Transactions

The following request elements are specific to Giropay purchase transactions (in

addition to the common elements described above).

Element Names:

GiropayTxn

Position:

Request.Transaction

Elements of MisterCashTxn

Element Name

Description

Values/Limitations

description

Use this field to supply

descriptive text for the

transaction.

Alphanumeric

O

user_agent_header

This is a value indicating

the browser type and

operating system details

of the user. This

information can be

retrieved from

the HTTP_USER_AGENT

header.

Alphanumeric

O

gender

The individual’s gender

M =male, F = Female

O

telephone1

Consumer’s Local Home

Telephone Number.

String (20);

US: The 7 digit home telephone

number must be supplied in this

field.

CA: The 7 digit home telephone

number must be supplied in this

field.

O

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

telephone_country_code

Country Code for

Telephone1. The country

code is the prefix to be

used when dialling to a

particular country from

another country.

value must not be prefixed with

a plus (+) e.g. 1 for United States.

O

telephone_area_code

Consumer's Telephone

Area Code. This is

the 3-digit area code for a

particular region.

Short;

US: 3 digit number (e.g. 619 for

California).

CA: 3 digit number (e.g. 867 for

Northwest Territories).

O

success_url

The success URL

(customer will be

redirected in the event of

a successful payment)

Alphanumeric

R

failure_url

The failure URL (customer

will be redirected in the

event of a failed payment

/ error)

Alphanumeric

R

billing_name

The name of the

account holder

Alphanumeric

O

sort_code

The sort code of the

customer's bank

Six digits

R

account_number

The customer's account

number

Eight digits

O

iban

An International Bank

Account Number.

Standard

for indentifying bank

accounts across national

borders.

A valid IBAN

O

payment_reference

Merchant configurable

data field typically used to

identify a customer

uniquely within the

system, regardless of the

amount of accounts that

the customer has.

A valid Payment Reference

O

Notes:

 A valid combination of billing details must be provided for Risk enabled merchants.See the note on

ExperCash in section 3.3.2.1.2 for more information.

 The account_number element is optional but must be specified in order to process refunds. If the

element is omitted an error will be returned when trying to refund the transaction.

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.12.9.2 Modification Transactions

The following request elements are specific to Giropay modification (cance/refund)

transactions.

Element Names:

GiropayTxn

Position:

Request.Transaction

Elements of MisterCashTxn

Element Name

Description

Values/Limitations

C

R

method

The type of request.

One of ‘cancel’ or

‘txn_refund’

R

reference

DataCash unique

reference of

the original transaction

Must be a valid

transaction

R

note

This is a description for

the transaction

Alphanumeric

O

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example GiropayTxn Purchase Request:

</Authentication>

</TxnDetails>

<method>payment / payout</method>

<user_agent_header>Mozilla/5.0 (Windows NT 6.1) AppleWebKit/536.5

(KHTML, like Gecko) Chrome/19.0.1084.52 Safari/536.5</user_agent_header>

<customer_email>john@mail.com</customer_email>

<customer_ip>127.0.0.1</customer_ip>

<first_name>JOHN</first_name>

<last_name>KENT</last_name>

<telephone_country_code>44</telephone_country_code>

<telephone_area_code>131</telephone_area_code>

<success_url>http://success</success_url>

<failure_url>http://failure</failure_url>

<billing_name>John Kent</billing_name>

<billing_street1>Address Line 1</billing_street1>

<billing_street2>Address Line 2</billing_street2>

<billing_city>CA</billing_city>

<billing_postcode>12345</billing_postcode>

<billing_country>DE</billing_country>

<billing_state_province>province</billing_state_province>

<sort_code>12345678</sort_code>

<account_number>1234567890</account_number>

</GiropayTxn>

</Request>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example GiropayTxn Purchase Response:

<redirect_param

param_name="redirectData">merchantID=123456789&customerRef=X4M75U&count

ry=UK&currency=GBP&recieveCurrency=GBP&email=john@mail.com&service=GIRO

PAY&language=en</redirect_param>

</RedirectParams>

<apg_ref>123456789</apg_ref>

<apg_status>REDIRECT</apg_status>

<content_type>application/x-www-form-urlencoded</content_type>

<display_message>Please wait while you are redirected to the

Giropay site</display_message>

<http_method>GET</http_method>

<redirect_url>http://envoy</redirect_url>

</GiropayTxn>

<datacash_reference>4800903000000483</datacash_reference>

<reason>The APG accepted the transaction</reason>

</Response>

Example GiropayTxn Modification Request:

</Authentication>

<method>cancel</method>

</GiropayTxn>

</Transaction>

</Request>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example GiropayTxn Modification Response:

<apg_bank_ref>00000000000004594228</apg_bank_ref>

<apg_ref>1002</apg_ref>

<apg_status>CANCELLED</apg_status>

</GiropayTxn>

<reason>CANCELLED OK</reason>

</Response>

2.12.10 Common Response Elements

The following response elements are common across all Alternative Payment Methods.

The transaction type specific response fields will be contained in the

[PaymentMethod]Txn complex element. For example, a response for a Sofort txn

would contain a “Response.SofortTxn” block. See the examples above for more detail.

Element Names:

[PaymentMethod]Txn

Position:

Response

Elements of [PaymentMethod]Txn

Element Name

Description

apg_ref

The apg reference for this transaction.

apg_status

The status of this transaction.

display_message

The recommended display message that should be displayed

to the customer.

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.12.11 Offline Bank Transfer (OBT) Response Elements

The following elements are specific to OBT payment methods:

 Nordea

 La Caixa

The response elements detailed below should be displayed to the customer to enable

them to complete the payment offline. The APG reference detailed above should also

be displayed.

Element Names:

[OBTPaymentMethod]Txn

Position:

Response

Elements of [PaymentMethod]Txn

Element Name

Description

apg_account_name

The merchant account name

apg_account_number

The account number with the APG (Alternative Payment

Gateway).

apg_bank

apg_branch

The name of the branch.

apg_branch_address

The address of the branch.

apg_iban

The International Bank Account Number (IBAN)

apg_swift

The SWIFT code for the bank.

2.12.12 Redirect Response Elements

The following response elements are specific to redirect payment types (where the

customer is redirected to a 3rd party processor in order to complete the payment).

Supported redirect payment types are:

 iDeal

 Sofort

 Web Money

 MisterCash

Element Names:

[RedirectPaymentMethod]Txn

Position:

Response

Elements of [RedirectPaymentMethod]Txn

Element Name

Description

redirect_url

This is a URL on the 3rd party payment processors website to

which the customer should be redirected.

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

http_method

This is the HTTP method that should be used to redirect the

customer (GET or POST). In the case of a POST redirect, you

might need to consider using JavaScript to automatically

submit a form (and providing a button in the case where the

customer has disabled / does not support JavaScript).

content_type

The content type that should be used.

RedirectParams

This complex element contains an arbitrary number of redirect

parameters. These parameters must be used when redirecting

the customer to the 3rd party payment processor.

2.12.12.1 Redirect Handling (Redirect Payment Types)

The XML response for a redirect type payment request will contain a

RedirectParameters complex element containing an arbitrary number of redirect

parameters. See the example snippet below:

Example of RedirectParams complex element:

<redirect_param param_name="customerRef">X4M75U</redirect_param>

<redirect_param param_name="country">UK</redirect_param>

<redirect_param param_name="currency">GBP</redirect_param>

<redirect_param param_name="recieveCurrency">GBP</redirect_param>

<redirect_param param_name="email">john@mail.com</redirect_param>

<redirect_param param_name="service">MISTERCASH</redirect_param>

<redirect_param param_name="language">en</redirect_param>

</RedirectParams>

...

<content_type>application/x-www-form-urlencoded</content_type>

<http_method>GET</http_method>

<redirect_url>http://envoy</redirect_url>

</MisterCashTxn>

...

</Response>

When redirecting the customer to the 3rd party payment processor URL (redirect_url),

you must extract the redirect parameters from the RedirectParams complex element

and include these in the redirect (paying attention to the content_type and

http_method). Note that the redirect parameters above are only an example.

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.12.13 Compatibility With HPS

The alternative payment methods described in the previous section can also be used in

conjunction with HPS (Hosted Payment Service). Some examples of requests /

responses are shown below. Note that the success_url and failure_url elements

described in the sections above are optional. In the case where no success_url or

failure_url is supplied, HPS will use the return_url instead.

For more information on HPS, please see the relevant section of this guide.

Example of HPS Setup Session Request for Sofort Txn:

</Authentication>

</TxnDetails>

<method>setup_full</method>

<page_set_id>99999</page_set_id>

<return_url>http://returnurl</return_url>

</HpsTxn>

<method>payment</method>

<customer_email>john@mail.com</customer_email>

<customer_ip>127.0.0.1</customer_ip>

<first_name>JOHN</first_name>

<last_name>KENT</last_name>

<billing_street1>Address Line 1</billing_street1>

<billing_city>CA</billing_city>

<billing_postcode>12345</billing_postcode>

<billing_country>DE</billing_country>

</SofortTxn>

</Transaction>

</Request>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example of HPS Setup Session Response for Sofort Txn:

<hps_url>http://localhost:8180/hps/</hps_url>

<session_id>ce0be36b-15c1-46e5-9f67-33ce39ad5dc7</session_id>

</HpsTxn>

<datacash_reference>4900903000000492</datacash_reference>

<reason>ACCEPTED</reason>

</Response>

Multiple Txn blocks can also be supplied in the context of an HPS Setup session. In this

scenario, when the customer is redirected to HPS, they will be given a choice of

payment methods. See the below request example below:

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example of HPS Setup Session Request with Multiple Txn Blocks:

</Authentication>

</TxnDetails>

<method>setup_full</method>

<page_set_id>99999</page_set_id>

<return_url>http://returnurl</return_url>

</HpsTxn>

<method>payment</method>

<customer_email>john@mail.com</customer_email>

<customer_ip>127.0.0.1</customer_ip>

<first_name>JOHN</first_name>

<last_name>KENT</last_name>

<billing_street1>Address Line 1</billing_street1>

<billing_city>CA</billing_city>

<billing_postcode>12345</billing_postcode>

<billing_country>DE</billing_country>

</SofortTxn>

<method>payment</method>

<customer_email>john@mail.com</customer_email>

<customer_ip>127.0.0.1</customer_ip>

<first_name>JOHN</first_name>

<last_name>KENT</last_name>

<billing_street1>Address Line 1</billing_street1>

<billing_city>CA</billing_city>

<billing_postcode>12345</billing_postcode>

<billing_country>DE</billing_country>

</MisterCashTxn>

</Transaction>

</Request>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.13 BIN LOOKUP SERVICE

This section of the documentation assumes the reader is familiar with the Card

Tokenization Service, which is discussed in section 2.9.

2.13.1 Service Overview

The BIN Lookup service allows a merchant to submit a pan or tokenized pan and get

the card BIN details in response.

2.13.2 XML Schema for Request

In the following section, the XML schema for the BINLookupTxn request is shown. Note

that in the Card element, either a pan, or tokenized pan can be submitted. When a

token is submitted, the attribute “type” must specified as “token”.

Elements of [BINLookup]Txn Request

Element Name

Description

Values/Limitations

Method

The type of request.

A constant value of “binlookup” (this

is currently the only method

supported)

R

Card

Contains the card

details / tokenized

card details

Parent element of pan element

R

Pan

Card number or

Tokenized Card

number

When submitting a tokenized pan, the

“type” attribute must be specified to

“token”.

R

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

<method>binlookup</method>

<Card>

OR

</Card>

</BINLookupTxn>

</TxnDetails>

</Transaction>

</Authentication>

</Request>

2.13.3 XML Schema for response

In the following section, the XML schema for the BINLookupTxn response is shown.

Note that the token element will only be returned if the VTID is a member of a VTID

Tokenization group and the token is associated with the same VID tokenization group.

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

<card_scheme>VISA</card_scheme>

<issuer>Unknown</issuer>

</BINLookupTxn>

<datacash_reference>1111111111111111</datacash_reference>

<reason>ACCEPTED</reason>

</Response>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.14 CHINA UNION PAY

2.14.1 Summary of Service

The China Union Pay service provides the ability to perform several transaction types

against the China Union Pay QuickPay system:

 Authorisation transactions

 Txn Refund transactions

 Cancel transactions

These transactions types will be represented by the letters A, T and C respectively in

the table below which maps out the potential fields.

Authorisation requests can be submitted in two different modes, datacash-managed or

merchant-managed. In merchant-manged mode, as with Txn Refund and Cancel

transactions, they are submitted directly to the DPG. In datacash-managed mode,

Authorisations are submitted to the DPG via the Hosted Payment Service (HPS).

Section 2.14.3 shows the format in which the HPS setup request must be submitted in

datacash-managed mode to begin an HPS session. Section 2.14.4 shows the format in

which authorisation commencement requests must be submitted in merchant-managed

mode. In the table below, letter A represents both of these authorisation requests.

2.14.2 Schema Elements for Request

Element Name:

ChinaUnionPayTxn

Position:

Request.Transaction

Elements of ChinaUnionPayTxn

Element Name

Description

Values / Limitations

Required

A

T

C

method

The method of the

transaction.

auth

cancel

txn_refund

R

reference

When performing a

txn_refund or

cancel, this element

should be used to

indicate the

transaction that is

being refunded or

cancelled respectively.

The value contained

should be the

datacash_reference of the

original CUP authorisation

transaction. This value

can be found by querying

the HPS Setup used to

initiate the authorisation

transaction. It should not

be confused with the

reference of the HPS

Setup transaction itself.

-

R

mer_abbr

The name of the

merchant submitting

the transaction.

Alphanumeric, up to 32

characters.

R

-

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

order_time

The time at which the

transaction takes

place.

The value should be in

Chinese Standard Time

(GMT+8) and formatted

in the following style:

yyyymmddHHMMSS

R

-

customer_ip

The IP address of the

customer.

Valid IP address, max

length 40.

R

-

commodity_url

The address of the

item being purchased.

Valid URL, max length

1024.

O

-

commodity_name

The name of the item

being purchased.

Alphanumeric, up to 256

characters.

O

-

commodity_quantity

The number of items

bought.

Numeric, up to 10 digits.

O

-

commodity_unit_price

The individual price of

each item.

Numeric, up to 12 digits.

O

-

commodity_discount

The discount value to

be applied.

Numeric, up to 10 digits.

O

-

transfer_fee

The transfer fee to

charge the customer.

Numeric, up to 12 digits.

O

-

customer_name

The name of the

customer if it is

known.

Alphanumeric, up to 20

characters.

O

-

default_pay_type

The default type of

payment.

Alphanumeric, up to 8

characters.

O

-

default_bank_number

The default bank

number to use.

Numeric, up to 11

characters.

O

-

version

The version number of

the transaction.

This field should take the

form, RO.RO.RO, so can

vary between 0.0.0 and

99.99.99.

O

-

mer_reserved

The merchants own

reference.

Text, up to 1024

characters. UTF-8

compatible.

O

-

2.14.3 Authorisation transactions

Transactions using the China Union Pay service are initiated in datacash-managed

mode with a Hosted Payment Service (HPS) transaction. This causes the authorisation

setup requests for this service to use the following format:

 Request

o Authentication (section 2.1.1.2)

o Transaction

 CardTxn (section)

 TxnDetails (section)

 HpsTxn (section)

 ChinaUnionPayTxn (section)

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

An example authorisation transaction is illustrated below:

Example China Union Pay HPS Setup Request

<password>xxxxxxxx</password>

<client>xxxxxxxx</client>

</Authentication>

</CardTxn>

<capturemethod>ecomm</capturemethod>

</TxnDetails>

<page_set_id>1</page_set_id>

<return_url>http://www.merchant.com/paymentmade</return_url>

<method>setup_full</method>

</HpsTxn>

<mer_abbr>abc</mer_abbr>

<commodity_unit_price>100</commodity_unit_price>

<order_time>20120203185332</order_time>

<customer_name>Geoff Jefferson</customer_name>

<commodity_quantity>10</commodity_quantity>

<customer_ip>127.0.0.1</customer_ip>

<commodity_url>http://www.merchant.com/item6103</commodity_url>

<commodity_name>Face paint</commodity_name>

<commodity_discount>0</commodity_discount>

<default_bank_number>1234</default_bank_number>

<mer_reserved>merchref_12345</mer_reserved>

<transfer_fee>0</transfer_fee>

<default_pay_type>12</default_pay_type>

</ChinaUnionPayTxn>

</Transaction>

</Request>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

An example response to a setup transaction is shown below:

Example China Union Pay HPS Setup Response

<?xml version="1.0" encoding="UTF-8"?>

<hps_url>https://dpg.example.com:8180/hps/</hps_url>

<session_id>6f69e357-24b1-492d-ac21-898c83f25e5d</session_id>

</HpsTxn>

<datacash_reference>4000900012345671</datacash_reference>

<reason>ACCEPTED</reason>

</Response>

2.14.3.1

2.14.4 Authorisation commencement transactions

Merchant-managed China Union Pay authorisation transactions do not require a setup

transaction. Instead they send an authorisation commencement transaction. These

have the format

 Request

o Authentication (section 2.1.1.2)

o Transaction

 TxnDetails (section)

 ChinaUnionPayTxn (section)

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

An example authorisation commencement transaction is shown below

Example China Union Pay Authorisation Commencement Request

<password>xxxxxxxx</password>

<client>xxxxxxxx</client>

</Authentication>

<capturemethod>ecomm</capturemethod>

</TxnDetails>

<mer_abbr>abc</mer_abbr>

<commodity_unit_price>100</commodity_unit_price>

<order_time>20120203185332</order_time>

<customer_name>Geoff Jefferson</customer_name>

<commodity_quantity>10</commodity_quantity>

<customer_ip>127.0.0.1</customer_ip>

<commodity_url>http://www.merchant.com/item6103</commodity_url>

<commodity_name>Face paint</commodity_name>

<commodity_discount>0</commodity_discount>

<default_bank_number>1234</default_bank_number>

<mer_reserved>merchref_12345</mer_reserved>

<transfer_fee>0</transfer_fee>

<default_pay_type>12</default_pay_type>

</ChinaUnionPayTxn>

</Transaction>

</Request>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.14.5 Txn Refund and Cancel transactions

The txn_refund transaction allows the merchant to refund the authorisation transaction

with a maximum amount equal to that contained within the original transaction as

identified by the ‘reference’ provided in the XML. The cancel transaction uses much the

same process but cannot be supplied with an amount value; either the whole

transaction is cancelled, or it is not cancelled at all.

Note that where multiple txn_refund transactions are submitted against the same

redemption, the sum of the refunded amounts must not exceed the originally

authorised amount.

An example txn_refund transaction is shown below:

Example Txn Refund Request

<client>xxxxxxxx</client>

<password>xxxxxxxx</password>

</Authentication>

</TxnDetails>

<method>txn_refund</method>

</ChinaUnionPayTxn>

</Transaction>

</Request>

If the amount is not provided, the amount refunded will be that of the original

redemption transaction. Note that ‘currency’ is not permitted in a txn_refund.

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

An example cancel transaction is shown below:

Example Cancel Request

<client>xxxxxxxx</client>

<password>xxxxxxxx</password>

</Authentication>

<method>cancel </method>

</ChinaUnionPayTxn>

</Transaction>

</Request>

As can be seen, the transaction is similar to that of a txn_refund but does not include

the TxnDetails block as no amount is necessary. Both transactions receive their

responses in the same format though.

An example response to a txn_refund/cancel is provided below:

Example Txn Refund Response

<?xml version="1.0" encoding="UTF-8"?>

<datacash_reference>4000900012345671</datacash_reference>

<reason>ACCEPTED</reason>

</ChinaUnionPayTxn>

</Response>

The ‘qid’ returned in response is the China Union Pay serial number of the submitted

transaction. In the instance above, for example, the ‘qid’ shown is the serial number of

the txn_refund transaction.

2.14.6 Unsuccessful, Invalid or Failed Transactions

In the event of a transaction being rejected by the DPG without going to China Union

Pay for processing or the transaction receiving an error code from China Union Pay, the

ChinaUnionPayTxn block will not be returned. A suitable status code and message will be

returned, with additional details in the information field. This is in-line with the existing

DataCash response format.

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

For example:

Example Response for a Invalid Transaction

<?xml version="1.0" encoding="UTF-8"?>

<datacash_reference>4000900012345672</datacash_reference>

<reason>China Union Pay: Invalid Order Number</reason>

<information>Specified transaction has not completed!</information>

</Response>

Such responses will be received if the XML submitted contains unexpected elements,

has missing elements or the data contained within those elements has failed to meet

the validation rules.

2.14.7 Query Transactions

It is possible to query any of the China Union Pay transactions using a standard query

transaction supplying the DataCash reference within a HistoricTxn block. This would

look like the following example:

Example XML Batch Query

</Authentication>

<method>query</method>

</HistoricTxn>

</Transaction>

</Request>

2.14.7.1 Query Transaction Responses

As can be seen in the following examples, the query transaction returns the standard

block outlining the details submitted as part of the original cancel, and also includes

details of the China Union Pay confirmation which was performed upon it. All details of

the transactions sent to China Union Pay are contained within the ChinaUnionPayTxn

block.

If the query transaction has communicated with China Union Pay while verifying the

status of the transaction, an InquiryResponse block will be included in the response.

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

This block can contain the following elements:

Elements of InquiryResponse

Element Name

Description

Values / Limitations

status

The status of the inquiry sent to

China Union Pay.

successful

error

info

A message detailing the response

received from CUP pertaining to

the original transaction.

Message indicating the

status of the transaction

according to China Union

Pay.

transaction_updated

Whether the transaction has just

been updated by performing this

query.

true

false

2.14.7.2 Query of HPS Setup Transaction Submitting CUP Authorisation

The following example is the response to a query transaction on an HPS Setup

transaction which has submitted an authorisation to China Union Pay.

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example Response for a Query Transaction

<?xml version="1.0" encoding="UTF-8"?>

<info>China Union Pay have indicated that the transaction was

successful</info>

<status>successful</status>

<transaction_updated>true</transaction_updated>

</InquiryResponse>

<acquirer_code>28180826</acquirer_code>

<cup_reserved>{orderAmount=10000&orderCurrency=826}</cup_reserved>

<customer_ip>127.0.0.1</customer_ip>

<mer_abbr>dtest1</mer_abbr>

<order_amount>10000</order_amount>

<order_currency>826</order_currency>

<order_number>3300900010000128</order_number>

<order_time>2012-02-06 18:16:18</order_time>

<resp_code>00</resp_code>

<resp_time>20120206181605</resp_time>

<settle_amount>10000</settle_amount>

<settle_currency>826</settle_currency>

<settle_date>0206</settle_date>

<trace_number>732087</trace_number>

<trace_time>0206181618</trace_time>

<trans_timeout>300000</trans_timeout>

<trans_type>1</trans_type>

</ChinaUnionPayTxn>

<datacash_reference>3300900010000128</datacash_reference>

<dc_response>1</dc_response>

<reason>ACCEPTED</reason>

</Attempt>

</AuthAttempts>

<datacash_reference>3300900010000128</datacash_reference>

</HpsTxn>

<datacash_reference>3500900010000127</datacash_reference>

<information>You have queried a Full-HPS China Union Pay transaction, where the

payment was successfully collected</information>

<reason>ACCEPTED</reason>

</Response>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.14.7.3 Query of Txn Refund/Cancel Transactions

The following example is the response to a query transaction for a cancel transaction

performed for China Union Pay:

Example Response for a Query Transaction

<?xml version="1.0" encoding="UTF-8"?>

<info>China Union Pay have indicated that the transaction was

successful</info>

<status>successful</status>

<transaction_updated>true</transaction_updated>

</InquiryResponse>

<acquirer_code>28180826</acquirer_code>

<cup_reserved>{orderAmount=10000&orderCurrency=826}</cup_reserved>

<customer_ip>127.0.0.1</customer_ip>

<mer_abbr>dtest1</mer_abbr>

<method>cancel</method>

<order_amount>10000</order_amount>

<order_currency>826</order_currency>

<order_number>3500900010000113</order_number>

<order_time>2012-02-04 00:48:02</order_time>

<orig_qid>201202040042077318332</orig_qid>

<resp_code>00</resp_code>

<resp_time>20120204004715</resp_time>

<settle_amount>10000</settle_amount>

<settle_currency>826</settle_currency>

<settle_date>0203</settle_date>

<trace_number>731835</trace_number>

<trace_time>0204004802</trace_time>

<trans_timeout>300000</trans_timeout>

<trans_type>31</trans_type>

</ChinaUnionPayTxn>

</QueryTxnResult>

<datacash_reference>3500900010000113</datacash_reference>

<reason>ACCEPTED</reason>

</Response>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.15 PAYPASS ONLINE

2.15.1 Summary of Service

The PayPass service allows merchants to integrate with the MasterCard PayPass OnLine

wallet system.

There are three separate methods of sending transactions to PayPass now in place.

 HCC (section 2.15.2)

 Full HPS (section 2.15.3)

 Direct (section 2.15.4)

Sending queries and authorisations for each of these methods is covered in the

following sections:

 Queries (2.15.5)

 Authorisations (2.15.6)

2.15.2 Shipping Address Suppression

The optional element suppress_shipping_address allows for the capture of the shipping

address within the PayPass wallet to be suppressed should the capture/storage of the

Consumer’s shipping address occur on the Merchant’s site. The new parameter can be

used in the setup transactions for HCC, Full HPS and Direct.

If the new parameter = TRUE, then the address will be suppressed and shipping details

will NOT be returned from PayPass. If the new parameter = FALSE then the shipping

address will not be suppressed and shipping details WILL be returned from PayPass

Default: If the parameter is not sent within the PayPass request, then the shipping

address details will be returned from PayPass by default.

2.15.3 HCC

The merchant initiates an HCC session, once their customer reaches the checkout stage

of the payment cycle, by submitting a transaction to DataCash. The response to this

transaction gives the merchant the URL of the HCC session to redirect their customer

to. When the customer arrives on the HCC page, a setup_paypass_online_session

transaction is sent to inform PayPass that a customer wishes to pay using PayPass. The

customer is then redirected onwards to PayPass. On the PayPass site, the customer will

choose which wallet details to use before being redirected back to HCC. A

get_customer_details transaction is then sent by HCC to retrieve the details, chosen by

the customer, from PayPass. The merchant can then query these details before sending

in the authorisation request.

2.15.3.1 Schema Elements for HCC Setup Request

o Request

 Authentication – section 2.1.1.2

 Transaction

 TxnDetails – section 2.15.2.1.1

 HpsTxn – section 2.15.2.1.2

 PayPassOnLineTxn – section 2.15.2.1.3

Each field will be labelled with the following key:

 O – Optional.

 R – Required, field must be presented.

 X – Excluded, presenting this field will cause the transaction to fail.

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.15.3.1.1 TxnDetails

Element Name:

TxnDetails

Position:

Request.Transaction

Elements of TxnDetails

Element Name

Description

Values /

Limitations

Require

d?

merchantreference

A unique reference number to

distinguish each transaction

Min 6, max 30

alphanumeric

characters. Must

be unique

R

amount

The value of the transaction

R

capturemethod

Indicates how the transaction was

accepted at the POS

ecomm

R

Attributes for Elements of TxnDetails

Attribute

Name

Attribute

of Element

Values / Limitations

Required?

currency

amount

Currency is passed in the 3

character ISO 4217 Alphabetic

format (Default is GBP)

O

2.15.3.1.2 HpsTxn

This element must be present for all setup transactions. It should not be presented for

other transaction types.

Element Name:

HpsTxn

Position:

Request.Transaction

Elements of HpsTxn

Element

Name

Description

Values / Limitations

Required

method

The action that is being requested

Must have the value

“setup_paypass_online”

R

page_set_id

An ID number that signifies the

“page set” that should be used

when presenting the data capture

screen to the customer.

An integer value of a page

set that has already been

configured.

R

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

return_url

A URL from the customer’s

website. If this value is supplied,

then when the data capture

process has been completed, the

customer will be redirected to this

URL instead of the default URL

configured within HCC.

Max size 2083.

R

expiry_url

A URL from the customer’s

website. If this value is specified,

the customer will be redirected to

this URL instead of the default

expiry URL configured within HCC

on attempting to visit an expired

session.

Max size 208.

O

cvv_only

If this element is given the value

1, it signifies that this will be a

CVV Only card capture. This

means that either a pre-

registered card or tokenized card

number are being used. The

merchant must be subscribed to

the HCC CVV Only service for this

type of card capture.

A value of 1 means true. A

value of 0 means false.

O

2.15.3.1.3 PayPassOnlineTxn

This element is optional for setup transactions.

Element Name:

PayPassOnLineTxn

Position:

Request.Transaction

Elements of TxnDetails

Element Name

Description

Values / Limitations

Required

suppress_shipping

_address

Determines whether a

customer will be prevented

from selecting a shipping

address within the PayPass

wallet. If this parameter is

not present the customer

will be able to select a

shipping address within the

PayPass wallet.

“TRUE” or ”FALSE”, but

case insensitive

O

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.15.3.1.4 Example HCC Setup Transaction

An example transaction is illustrated below:

Example PayPass HCC Setup Request

<client>xxxxxxxx</client>

<password>xxxxxxxx</password>

</Authentication>

<capturemethod>ecomm</capturemethod>

</TxnDetails>

<method>setup_paypass_online</method>

<page_set_id>1</page_set_id>

<return_url>https://www.merchantexample.com/customer_return</return_url>

</HpsTxn>

<suppress_shipping_address>FALSE</suppress_shipping_address>

</PayPassOnlineTxn>

</Transaction>

</Request>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

An example response to this setup transaction is shown below:

Example PayPass HCC Setup Response

<hps_url>https://dpg.example.com:8180/hps/</hps_url>

<session_id>6f69e357-24b1-492d-ac21-898c83f25e5d</session_id>

</HpsTxn>

<datacash_reference>4800903000000001</datacash_reference>

<reason>ACCEPTED</reason>

</Response>

2.15.4 Full HPS

To use the Full HPS integration, the merchant submits a setup request in a similar style

as used by the HCC integration. The merchant will then receive a response containing

the HPS URL to use for their customer redirect. Once the customer arrives on the HPS

page, the setup_paypass_online_session transaction is sent to PayPass and the

customer redirected to select their card details from PayPass. When PayPass redirect

the customer back to HPS, a get_customer_details transaction is then sent to retrieve

the details selected by the customer. The authorisation transaction for the request will

then be automatically submitted based on the details received. The outcome of the

authorisation will then be sent back sent back to the merchant so that a confirmation

page can be displayed to the customer.

2.15.4.1 Schema Elements for Full HPS Setup Request

o Request

 Authentication – section 2.1.1.2

 Transaction

 TxnDetails – section 2.15.2.1.1

 PayPassOnLineTxn – section 2.15.3.1.1

 HpsTxn – section 2.15.3.1.2

Each field will be labelled with the following key:

 O – Optional.

 R – Required, field must be presented.

 X – Excluded, presenting this field will cause the transaction to fail.

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.15.4.1.1 PayPassOnLineTxn

This element must be present for all setup transactions. It should not be presented for

other transaction types.

Element Name:

PayPassOnLineTxn

Position:

Request.Transaction

Elements of HpsTxn

Element Name

Description

Values / Limitations

Required

method

The action that is being

requested

Must have the value

“setup_paypass_online_

session”

R

suppress_shipping_

address

Determines whether a

customer will be prevented

from selecting a shipping

address within the PayPass

wallet. If this parameter is

not present the customer will

be able to select a shipping

address within the PayPass

wallet.

“TRUE” or ”FALSE”, but

case insensitive

O

2.15.4.1.2 HpsTxn

This element must be present for all setup transactions. It should not be presented for

other transaction types.

Element Name:

HpsTxn

Position:

Request.Transaction

Elements of HpsTxn

Element Name

Description

Values / Limitations

Required

method

The action that is being requested

Must have the

value “setup_full”

R

page_set_id

An ID number that signifies the “page set”

that should be used when presenting the

data capture screen to the customer.

An integer value of

a page set that has

already been

configured.

R

return_url

A URL from the customer’s website. If this

value is supplied, then when the data

capture process has been completed, the

customer will be redirected to this URL

instead of the default URL configured

within HCC.

Max size 2083.

R

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

expiry_url

A URL from the customer’s website. If this

value is specified, the customer will be

redirected to this URL instead of the

default expiry URL configured within HCC

on attempting to visit an expired session.

Max size 208.

O

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.15.4.1.3 Example Full HPS Setup Transaction

An example transaction is illustrated below:

Example PayPass Full HPS Setup Request

<client>xxxxxxxx</client>

<password>xxxxxxxx</password>

</Authentication>

<capturemethod>ecomm</capturemethod>

</TxnDetails>

<method>setup_paypass_online_session</method>

<suppress_shipping_address>FALSE</suppress_shipping_address>

</PayPassOnLineTxn>

<method>setup_full</method>

<page_set_id>1</page_set_id>

<return_url>https://www.merchantexample.com/customer_return</return_url>

</HpsTxn>

</Transaction>

</Request>

An example response to this setup transaction is shown below:

Example PayPass Full HPS Setup Response

<hps_url>https://dpg.example.com:8180/hps/</hps_url>

<session_id>6f69e357-24b1-492d-ac21-898c83f25e5d</session_id>

</HpsTxn>

<datacash_reference>4800903000000001</datacash_reference>

<reason>ACCEPTED</reason>

</Response>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.15.5 Direct

The third integration option is for the merchant to directly send transactions to the DPG

and to keep the customer on their own site. In this scenario, the merchant starts by

submitting a setup_paypass_online_session transaction to the DPG to get the

information necessary to redirect the customer to PayPass. The customer will then be

handed over to PayPass to select card details, addresses to use, etc before being sent

back to the merchant’s site. The merchant can then submit a get_customer_details

transaction to fetch the details chosen by the customer. Using this information, the

merchant can then send in an authorisation request.

2.15.5.1 Schema Elements for Setup PayPass Online Session Request

o Request

 Authentication – section 2.1.1.2

 Transaction

 TxnDetails – section 2.15.2.1.1

 PayPassOnLineTxn – section 2.15.4.1.1

Each field will be labelled with the following key:

 O – Optional.

 R – Required, field must be presented.

 X – Excluded, presenting this field will cause the transaction to fail.

2.15.5.1.1 PayPassOnLineTxn

This element must be present for all setup transactions. It should not be presented for

other transaction types.

Element Name:

PayPassOnLineTxn

Position:

Request.Transaction

Elements of HpsTxn

Element Name

Description

Values / Limitations

Required

method

The action that is being

requested

Must have the value

“setup_paypass_online_

session”

R

paypass_callback_url

The address of the

merchant website

submitting the request.

Must be a valid URL.

R

suppress_shipping_ad

dress

Determines whether a

customer will be

prevented from selecting a

shipping address within

the PayPass wallet. If this

parameter is not present

the customer will be able

to select a shipping

address within the

PayPass wallet.

“TRUE” or ”FALSE”, but

case insensitive

O

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.15.5.1.2 Example Setup PayPass Online Session Transaction

An example transaction is illustrated below:

Example PayPass Setup PayPass Online Session Request

<client>xxxxxxxx</client>

<password>xxxxxxxx</password>

</Authentication>

<capturemethod>ecomm</capturemethod>

</TxnDetails>

<method>setup_paypass_online_session</method>

<paypass_callback_url>http://www.merch.com/paypass</paypass_callback_url>

<suppress_shipping_address>FALSE</suppress_shipping_address>

</PayPassOnLineTxn>

</Transaction>

</Request>

An example response to this setup transaction is shown below:

Example PayPass Setup PayPass Online Session Response

<paypass_redirect_url>https://sandbox.paypass.com/online/Checkout/Authorize?oaut

h_token=1234567890abcdef1234567890abcdef&acceptable_cards=visa,maestro,jcb,m

aster&checkout_identifier=123425334234235234</paypass_redirect_url>

<paypass_request_token>1234567890abcdef1234567890abcdef</paypass_request_token>

</PayPassOnLineTxn>

<datacash_reference>4800903000000001</datacash_reference>

<reason>ACCEPTED</reason>

</Response>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.15.5.2 Schema Elements for Get Customer Details Request

o Request

 Authentication – section 2.1.1.2

 Transaction

 TxnDetails – section 2.15.2.1.1

 PayPassOnLineTxn – section 2.15.4.2.1

Each field will be labelled with the following key:

 O – Optional.

 R – Required, field must be presented.

 X – Excluded, presenting this field will cause the transaction to fail.

2.15.5.2.1 PayPassOnLineTxn

This element must be present for all setup transactions. It should not be presented for

other transaction types.

Element Name:

PayPassOnLineTxn

Position:

Request.Transaction

Elements of HpsTxn

Element Name

Description

Values / Limitations

Required

method

The action that is being

requested

Must have the value

“get_customer_details”

R

reference

The reference to the

setup_paypass_online_session

transaction.

Must be a valid 16 digit

DataCash reference.

R

paypass_resource

_url

The checkout resource URL

returned by PayPass when the

customer is redirected back to

the merchant site from PayPass.

Must be a valid URL.

R

paypass_verifier

Verifier code returned by

PayPass when the customer

completes choosing their details.

Must be a valid verifier

code.

R

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.15.5.2.2 Example Get Customer Details Transaction

An example transaction is illustrated below. If the suppress_shipping_adddress

parameter was used with the value “true” in the setup transaction, the shipping

address will not appear.

Example PayPass Get Customer Details Request

<client>xxxxxxxx</client>

<password>xxxxxxxx</password>

</Authentication>

<method>get_customer_details</method>

<paypass_resource_url>http://www.merch.com/details</paypass_resource_url>

<paypass_verifier>1234567890abcdef</paypass_verifier>

</PayPassOnLineTxn>

</Transaction>

</Request>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

An example response to this transaction is shown below:

Example PayPass Get Customer Details Response

<City>Purchase</City>

<Country>United States</Country>

<Line1>2000 Purchase St</Line1>

</ShippingAddress>

<Card>

<City>Buffalo</City>

<Country>United States</Country>

<Line1>123 Bison Ln</Line1>

</BillingAddress>

</Card>

<EmailAddress>joe.test@email.com</EmailAddress>

</Contact>

</PayPassOnLineTxn>

<datacash_reference>4600903000000002</datacash_reference>

<reason>ACCEPTED</reason>

</Response>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.15.6 Query Transactions

It is possible to query a PayPass transaction using a standard query transaction

supplying the DataCash reference within a HistoricTxn block. This would look like the

following example:

Example PayPass Query Request

<client>xxxxxxxx</client>

<password>xxxxxxxx</password

</Authentication>

<method>query</method>

</HistoricTxn>

</Transaction>

</Request>

2.15.6.1 Example Response

The following example response is based on the merchant querying a transaction

shortly after the customer has selected or entered their details on the PayPass site, and

the DPG has retrieved them. It is these retrieved details that the transaction is

displaying as the card, contact and shipping information. If the

suppress_shipping_adddress parameter was used with the value “true” in the setup

transaction, the shipping address will not appear.

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example PayPass Query Response

<paypass_redirect_url>http://paypass.mastercard.com/login</paypass_redirect_url>

<paypass_request_token>aXHfwEYfwehHF23re23</paypass_request_token>

<datacash_reference>4900900023456780</datacash_reference>

<reason>ACCEPTED</reason>

</SetupPayPassOnLine>

<Card>

</Card>

</Contact>

<City>Arlington</City>

<Country>United States</Country>

<Line1>11 Any Street</Line1>

</ShippingAddress>

<datacash_reference>4900900023456781</datacash_reference>

<reason>ACCEPTED</reason>

</GetCustomerDetails>

</PayPassOnLineTxn>

</QueryTxnResult>

<reason>ACCEPTED</reason>

</Response>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.15.7 Authorisation Transactions

Authorisation transactions for PayPass are handled much the same as standard

authorisation requests. The primary difference is that a reference to a successful

PayPass setup transaction must be included in the authorisation request.

2.15.7.1 Schema Elements for Authorisation Request

PayPass authorisation transactions require the following sections and elements:

o Request

 Authentication – section 2.1.1.2

 Transaction

 TxnDetails – section 1.1.1.1.2

 CardTxn – section 2.15.6.1.1

2.15.7.1.1 CardTxn

Element Name:

Card

Position:

Request.Transaction.CardTxn

Elements of CardTxn

Element Name

Description

Values / Limitations

card_details

Specifies the

DataCash reference of

a successful HCC

session setup.

Required. Must be a 16-digit DataCash

reference.

method

The transaction type

auth

pre

Attributes for Elements of CardTxn

Attribute

Name

Attribute of

Element

Values / Limitations

type

card_details

Specifies the nature of the supplied DataCash

reference. For a PayPass transaction, it must have the

value “from_paypass_online”.

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.15.7.1.1.1 Example Request

The following example request demonstrates a basic PayPass authorisation request:

Example PayPass Authorisation Request

<password>xxxxxxxx</password>

<client>xxxxxxxx</client>

</Authentication>

<capturemethod>ecomm</capturemethod>

</TxnDetails>

<card_details type="from_paypass_online">4000900012345671</card_details>

</CardTxn>

</Transaction>

</Request>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.15.7.1.1.2 Example Response

Example PayPass Authorisation Response

<card_scheme>VISA</card_scheme>

<country>United Kingdom</country>

</CardTxn>

<datacash_reference>4200903000000001</datacash_reference>

<reason>ACCEPTED</reason>

</Response>

2.16 BOLETO BANCARIO

2.16.1 Summary of Service

The Boleto Bancario service enables Redecard merchants to process Boleto Bancario

transactions, a type of alternative payment method involving offline payments. In order

to support Boletos we integrate into a third party provider called MaxiPago.

There are two separate methods for sending Boleto Bancario transactions:

 Full HPS – section 2.16.2

 Direct – section 2.16.3

Sending queries and authorisations for each of these methods is covered in the

following sections:

 Queries – section 2.16.4

 Authorisations – sections 2.16.2.1.3 and 2.16.3.1.2

2.16.2 Full HPS

To use the Full HPS integration, the merchant submits a setup request. The merchant

will then receive a response containing the HPS URL to use for their customer redirect.

The authorisation transaction for the request will then be automatically submitted

based on the details received. The outcome of the authorisation will then be sent back

to the merchant so that a confirmation page can be displayed to the customer.

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.16.2.1 Schema Elements for Full HPS Setup Request

o Request

 Authentication – section 2.1.1.2

 Transaction

 TxnDetails – section 2.16.2.1.1

 BoletoBancarioTxn – section 2.16.2.1.2

 HpsTxn – section 2.16.2.1.3

Each field will be labelled with the following key:

 O – Optional.

 R – Required, field must be presented.

 X – Excluded, presenting this field will cause the transaction to fail.

2.16.2.1.1 TxnDetails

Element Name:

TxnDetails

Position:

Request.Transaction

Elements of TxnDetails

Element Name

Description

Values /

Limitations

Required

merchantreference

A unique reference number to

distinguish each transaction

Min 6, max 30

alphanumeric

characters. Must

be unique.

R

amount

The value of the transaction

R

Attributes for Elements of TxnDetails

Attribute

Name

Attribute

of Element

Values / Limitations

Required

currency

amount

Currency is passed in the 3 character ISO

4217 Alphabetic format (Only BRL is

accepted)

O

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.16.2.1.2 BoletoBancarioTxn

This element must be present for all the Boleto Bancario transactions.

Element Name:

BoletoBancarioTxn

Position:

Request.Transaction

Elements of BoletoBancarioTxn

Element Name

Description

Values / Limitations

Required

method

The action that is being

requeste

Must have the value

“payment”

R

expiry_date

The date that the boleto

expires. Payment may have

additional fees after expiry

date.

Must be in the format

YYYY-MM-DD

R

instructions

General instructions for the

specific transaction

Maximum length of 350

characters

R

first_name

The customer’s name

R

last_name

The customer’s surnam

R

billing_street

The customer’s billing street

O

billing_street2

Additional information for

customer’s billing address

O

billing_city

The customer’s billing street

O

billing_state_prov

ince

The customer’s billing state

province

O

billing_postcode

The customer’s billing

postcode

O

billing_country

The customer’s billing

country

O

customer_email

The customer’s email address

O

customer_phone

The customer’s phone numer

O

processor_id

A unique ID set by merchant

from Account Maintenance. It

is overridden by the value

submitted in the request.

3 digitis numerical. Valid

values :

11 = Itau

12 = Bradesco OR a test

transaction

13 = Banco do Brasil

14 = HSBC

15 = Santander

16 = Caixa

O

customer_ip

The customer’s IP address

Needs to be a valid IP

address

O

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

interest_per_day

Additional amount of interest

that must be paid for every

day after expiration date.

Needs to be in

percentage format

O

overdue_fine

Overall fine that must be

paid for transactions due

after the expiration day.

Needs to be in

percentage format

O

2.16.2.1.3 HpsTxn

This element must be present for all setup transactions. It should not be presented for

other transaction types.

Element Name:

HpsTxn

Position:

Request.Transaction

Elements of HpsTxn

Element Name

Description

Values / Limitations

Required

method

The action that is being requested

Must have the value

“setup_full”

R

page_set_id

An ID number that signifies the “page

set” that should be used when presenting

the data capture screen to the customer.

An integer value of a

page set that has

already been

configured.

R

return_url

A URL from the customer’s website. If

supplied, the customer will be redirected

to this URL instead of the default URL

configured within HCC when the data

capture process is completed.

Max size 2083.

R

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.16.2.1.4 Example Full HPS Setup Transaction

An example transaction is illustrated below:

Example Boleto Bancario Full HPS Setup Request

<client>xxxxxxxx</client>

<password>xxxxxxxx</password>

</Authentication>

<merchantreference>boletobancario123</merchantreference>

</TxnDetails>

<method>setup_full</method>

<page_set_id>50</page_set_id>

<return_url>https://www.merchant-website.com/done</return_url>

</HpsTxn>

<method>payment</method>

<expiry_date>2013-12-01</expiry_date>

<instructions>Faça o que fizer, não dê esse cara todo o dinheiro.

</instructions>

<first_name>John</first_name>

<last_name>Doe</last_name>

</BoletoBancarioTxn>

</Transaction>

</Request>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

An example response to this setup transaction is shown below:

Example Boleto Bancario Full HPS Setup Response

<hps_url>https://dpg.example.com:8180/hps/</hps_url>

<session_id>6f69e357-24b1-492d-ac21-898c83f25e5d</session_id>

</HpsTxn>

<datacash_reference>4800903000000001</datacash_reference>

<merchantreference>boletobancario123</merchantreference>

<reason>ACCEPTED</reason>

</Response>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.16.3 Direct

The merchant may choose to to directly send transactions to the DPG and keep the

customer on their own site. In this scenario, the merchant starts by submitting a

payment transaction to the DPG and then DPG redirects that request to the MaxiPago.

Schema Elements for Boleto Bancario “payment” request:

o Request

 Authentication – section 2.1.1.2

 Transaction

 TxnDetails – section 2.16.3.1.1

 BoletoBancarioTxn – section 2.16.3.1.2

Each field will be labelled with the following key:

 O – Optional.

 R – Required, field must be presented.

 X – Excluded, presenting this field will cause the transaction to fail.

2.16.3.1.1 TxnDetails

Element Name:

TxnDetails

Position:

Request.Transaction

Elements of TxnDetails

Element Name

Description

Values /

Limitations

Require

d?

merchantreference

Unique reference number to

distinguish each transaction

Min 6, max 30

alphanumeric

characters. Must

be unique

R

amount

The value of the transaction

R

capturemethod

Indicates how the transaction was

accepted at the POS

ecomm

R

Attributes for Elements of TxnDetails

Attribute

Name

Attribute

of Element

Values / Limitations

Required?

currency

amount

Currency is passed in the 3

character ISO 4217 Alphabetic

format (Only BRL is accepted)

O

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.16.3.1.2 BoletoBancarioTxn

This element must be present for all payment transactions. It should not be presented

for other transaction types.

Element Name:

BoletoBancarioTxn

Position:

Request.Transaction

Elements of BoletoBancarioTxn

Element Name

Description

Values / Limitations

Required

method

The action that is being

requested

Must have the value

“payment”

R

expiry_date

The date that the boleto

expires. Payment may have

additional fees after expiry

date.

Must be in the format

YYYY-MM-DD

R

instructions

General instructions for the

specific transaction

Maximum length of 350

characters

R

first_name

The customer’s name

R

last_name

The customer’s surname

R

billing_street

The customer’s billing street

O

billing_street2

Additional information for

customer’s billing address

O

billing_city

The customer’s billing street

O

billing_state_prov

ince

The customer’s billing state

province

O

billing_postcode

The customer’s billing

postcode

O

billing_country

The customer’s billing

country

O

customer_email

The customer’s email address

O

customer_phone

The customer’s phone numer

O

processor_id

A unique ID set by merchant

from the Account

Maintenance. It is overridden

by the value submitted in the

request.

3 digitis numerical. Valid

values :

11 = Itau

12 = Bradesco OR a test

transaction

13 = Banco do Brasil

14 = HSBC

15 = Santander

16 = Caixa

O

customer_ip

The customer’s IP address

Needs to be a valid IP

address

O

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

interest_per_day

Additional amount needs to

be paid for every day after

the expiration day

Needs to be in

percentage format

O

overdue_fine

Overall fine needs to be paid

for transactions paid after

the expiration day.

Needs to be in

percentage format

O

2.16.3.1.3 Example Boleto Bancario payment Transaction

An example transaction is illustrated below:

Example Boleto Bancario Payment Request

<?xml version="1.0" encoding="UTF-8"?>

</Authentication>

<merchantreference>Boleto1234</merchantreference>

<capturemethod>ecomm</capturemethod>

</TxnDetails>

<hps_setup_ref>4900900023456600</hps_setup_ref>

<method>payment</method>

<expiry_date>2013-12-01</expiry_date>

<instructions>Faça o que fizer, não dê esse cara todo o

dinheiro.</instructions>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

<first_name>John</first_name>

<last_name>Doe</last_name>

<billing_street1>123 Example Street</billing_street1>

<billing_street2>Apt. 123</billing_street2>

<billing_city>Blahtown</billing_city>

<billing_state_province>PA</billing_state_province>

<billing_postcode>24000-123</billing_postcode>

<billing_country>BR</billing_country>

<customer_telephone>123456789099</customer_telephone>

<customer_email>dude@example.com</customer_email>

<processor_id>12</processor_id>

<customer_ip>127.0.0.1</customer_ip>

<interest_per_day>0.1</interest_per_day>

<overdue_fine>5.00</overdue_fine>

</BoletoTxn>

</Transaction>

</Request>

2.16.3.1.4 Example Boleto Bancario payment Response

An example response to this payment transaction is shown below:

<?xml version="2.0" encoding="UTF-8"?>

<method>payment</method>

<expiry_date>2013-12-01</expiry_date>

<instructions>Faça o que fizer, não dê esse cara todo o

dinheiro.</instructions>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

<first_name>John</first_name>

<last_name>Doe</last_name>

<billing_street1>123 Example Street</billing_street1>

<billing_street2>Apt. 123</billing_street2>

<billing_city>Blahtown</billing_city>

<billing_state_province>PA</billing_state_province>

<billing_postcode>24000-123</billing_postcode>

<billing_country>BR</billing_country>

<customer_telephone>123456789099</customer_telephone>

<customer_email>dude@example.com</customer_email>

<processor_id>12</processor_id>

<customer_ip>127.0.0.1</customer_ip>

<interest_per_day>0.1</interest_per_day>

<overdue_fine>5.00</overdue_fine>

<boleto_url>http://example.com/something</boleto_url>

<order_id>eb7b1eaf-eb6a-49fc-bf94-e175485d3bfa</order_id>

<transaction_id>4568123581487</transaction_id>

<payment_status>pending</payment_status>

</BoletoTxn>

<datacash_reference>4900900023456781</datacash_reference>

<merchantreference>Boleto1234</merchantreference>

<reason>ACCEPTED</reason>

</Response>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.16.4 Query Boleto Bancario Transactions

It is possible to query a Boleto Bancario transaction using a standard query transaction

supplying the DataCash reference within a HistoricTxn block.

An example query request is shown below:

Example Boleto Bancario Query Request

<client>xxxxxxxx</client>

<password>xxxxxxxx</password

</Authentication>

<method>query</method>

</HistoricTxn>

</Transaction>

</Request>

2.16.4.1 Example Response – Pending Payment

The following example response is based on the merchant querying a transaction

shortly after submitting the request and before MaxiPago provides the payment

notification for the transaction.

Example Boleto Bancario Query Response – Pending Payment

<method>payment</method>

<expiry_date>2013-12-01</expiry_date>

<instructions>Faça o que fizer, não dê esse cara todo o

dinheiro.</instructions>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

<first_name>John</first_name>

<last_name>Doe</last_name>

<billing_street1>123 Example Street</billing_street1>

<billing_street2>Apt. 123</billing_street2>

<billing_city>Blahtown</billing_city>

<billing_state_province>PA</billing_state_province>

<billing_postcode>24000-123</billing_postcode>

<billing_country>BR</billing_country>

<customer_telephone>123456789099</customer_telephone>

<customer_email>dude@example.com</customer_email>

<processor_id>12</processor_id>

<customer_ip>127.0.0.1</customer_ip>

<interest_per_day>0.1</interest_per_day>

<overdue_fine>5.00</overdue_fine>

<boleto_url>http://example.com/something</boleto_url>

<order_id>eb7b1eaf-eb6a-49fc-bf94-e175485d3bfa</order_id>

<transaction_id>4568123581487</transaction_id>

<payment_status>pending</payment_status>

</BoletoTxn>

<datacash_reference>4800903000000001</datacash_reference>

<merchantreference>boletobancario123</merchantreference>

<reason>Payment pending</reason>

</QueryTxnResult>

<reason>ACCEPTED</reason>

</Response

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

2.16.4.2 Example Response – Payment Received

The following example response is based on the merchant querying a transaction after

submitting the request and after MaxiPago provides the payment notification for the

transaction.

An example transaction is illustrated below:

Example Boleto Bancario Query Response – Payment Received

<method>payment</method>

<expiry_date>2013-12-01</expiry_date>

<instructions>Faça o que fizer, não dê esse cara todo o

dinheiro.</instructions>

<first_name>John</first_name>

<last_name>Doe</last_name>

<billing_street1>123 Example Street</billing_street1>

<billing_street2>Apt. 123</billing_street2>

<billing_city>Blahtown</billing_city>

<billing_state_province>PA</billing_state_province>

<billing_postcode>24000-123</billing_postcode>

<billing_country>BR</billing_country>

<customer_telephone>123456789099</customer_telephone>

<customer_email>dude@example.com</customer_email>

<processor_id>12</processor_id>

<customer_ip>127.0.0.1</customer_ip>

<interest_per_day>0.1</interest_per_day>

<overdue_fine>5.00</overdue_fine>

<boleto_url>http://example.com/something</boleto_url>

<order_id>eb7b1eaf-eb6a-49fc-bf94-e175485d3bfa</order_id>

<transaction_id>4568123581487</transaction_id>

<boleto_bank_code>001</boleto_bank_code>

<transaction_id>73341232091557</transaction_id>

<payment_date>2013-12-01</payment_date>

<payment_amount>130.00</payment_amount>

<payment_status>OVERPAID</payment_status>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

</BoletoTxn>

<datacash_reference>4800903000000001</datacash_reference>

<merchantreference>boletobancario123</merchantreference>

<reason>ACCEPTED</reason>

</QueryTxnResult>

<reason>ACCEPTED</reason>

</Response>

The payment_status element of such a transaction where payment has been received

can have values of "UNDERPAID", "PAID", or "OVERPAID", depending on the overdue

fees indicated in the original payment transaction.

2.16.5 Query HPS Boleto Bancario Transactions

It is possible to query a Boleto Bancario transaction sent via HPS using a standard

query transaction supplying the DataCash reference within a HistoricTxn block.

This would look like the following example:

Example Boleto Bancario Query HPS Request

<client>xxxxxxxx</client>

<password>xxxxxxxx</password

</Authentication>

<method>query</method>

</HistoricTxn>

</Transaction>

</Request>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

The following example response is based on the merchant querying a transaction after

submitting the request and after MaxiPago provides the payment notification for the

transaction.

Example HPS Boleto Bancario Query Response – Overpaid

<method>payment</method>

<expiry_date>2013-12-01</expiry_date>

<instructions>Faça o que fizer, não dê esse cara todo o

dinheiro.</instructions>

<first_name>John</first_name>

<last_name>Doe</last_name>

<billing_street1>123 Example Street</billing_street1>

<billing_street2>Apt. 123</billing_street2>

<billing_city>Blahtown</billing_city>

<billing_state_province>PA</billing_state_province>

<billing_postcode>24000-123</billing_postcode>

<billing_country>BR</billing_country>

<customer_telephone>123456789099</customer_telephone>

<customer_email>dude@example.com</customer_email>

<processor_id>12</processor_id>

<customer_ip>127.0.0.1</customer_ip>

<interest_per_day>0.1</interest_per_day>

<overdue_fine>5.00</overdue_fine>

<boleto_url>http://example.com/something</boleto_url>

<order_id>eb7b1eaf-eb6a-49fc-bf94-e175485d3bfa</order_id>

<transaction_id>4568123581487</transaction_id>

<boleto_bank_code>001</boleto_bank_code>

<transaction_id>73341232091557</transaction_id>

<payment_date>2013-12-01</payment_date>

<payment_amount>130.00</payment_amount>

<payment_status>OVERPAID</payment_status>

</BoletoTxn>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

<datacash_reference>4800903000000002</datacash_reference>

</HpsTxn>

<datacash_reference>4800903000000001</datacash_reference>

<merchantreference>boletobancario123</merchantreference>

<information>You have queried a Full-HPS transaction, where the payment was

successfully collected</information>

<reason>ACCEPTED</reason>

</QueryTxnResult>

<reason>ACCEPTED</reason>

</Response>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

3. APG – ALTERNATIVE PAYMENT GATEWAY

3.1 INTRODUCTION TO APG

This section of the DataCash Developers Guide describes the Alternative Payment

Gateway, which provides non card purchase and payout method processing (including

Risk Screening) functionality.

The APG section of the document includes detailed descriptions of the process flow

involved in the various Services provided by the APG.

3.1.1 Glossary

Abbreviation /

Term

Description

APG

Alternative Payment Gateway

SOAP

Simple Object Access Protocol

WSDL

Web Service Definition Language

RSG

Risk Services Gateway

Processor

A generic reference to an electronic wallet provider / processing

institution. The term “payment method” is also sometimes used

interchangeably with the term “processor” in the APG.

See Appendix 7 for a list of all the Processors that the APG provides

access to.

Back to Contents

3.2 APG OVERVIEW

The APG exposes two interfaces that facilitate transaction flow: the SOAP Web Service

and the Redirect Solution. A successful integration will involve using one or both of

these.

The APG supports the UTF-8 Unicode encoding standard internally, but please note that

not all purchase and payout methods support this standard.

3.2.1 APG SOAP Web Service

The APG Web Service is a standard SOAP web service to be called directly from the

merchant’s server.

The APG web service is RPC-based (Remote Procedure Call), which allows clients to

make the synchronous invocation of DataCash’s gateway seem like a local procedure

call.

The web service integration offers several benefits:

 Service oriented standards based architecture;

 SOAP 1.1 and 1.2 based data encoding encapsulates transportation protocols;

 WSDL descriptor file allows easier integration and client side validation;

 The RPC-based interface allows developers to generate a web service client

without having to manually encode and decode XML data.

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

This web service offers 7 methods:

 Purchase - see section 3.3.2

 Payout – see section 3.3.3

 TransactionQuery – see section 3.3.4.1

 TransactionQueryByTransactionId – see section 3.3.4.2

 RetrieveSettlementValue – see section 3.3.5

 GetInformation – see section 3.3.6

 Modification – see section 3.3.7.1

Web Service locations:

Live URL

https://DPG-CPT.datacash.com/Service/Production.wsdl

Staging URL

https://DPG-CPT.staging.datacash.com/Service/Staging.wsdl

3.2.2 APG Redirect Solution

Certain Processors’ transactions make use of this interface. DataCash will provide the

necessary information that needs to be sent to the Processor. When processing has

been completed, the Processor will then redirect the end user to the redirect solution

for the final step of the transaction.

Note that the Redirect Solution of the APG provides an interface between the APG and

Processors, so Merchants do not need to integrate into the Redirect Solution (as they

do into the Web Service).

Refer to the Transaction Flow descriptions (section 1) for more information.

3.2.3 Security

To keep the merchant information safe between the merchant and the DataCash

Gateway, the following methods of security are in place:

 Communication Encryption.

 Digital certificates.

 Merchant Account.

In order to have a secure communication channel between the merchant site and the

APG, use SSL version 3, with 1028-bit encryption.

For merchants integrating using Java, it is recommended that you install the client

certification. Note: Java users can read more at

http://www.oracle.com/technetwork/java/api-141528.html

DataCash will also supply the merchant with their account details: an Account Name,

Company ID and PIN, which must be sent to the APG on a transactional basis in order

to process successfully.

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

3.2.4 Transaction Flow

The flow of a transaction from a merchant’s perspective may differ depending on

whether the payment method requires a redirect, partial redirect or no redirect.

3.2.4.1 Non-Redirect Flow (Figure 1 - Purchase)

1. The client enters their purchase details on the merchant’s site.

2. The merchant sends the relevant information to the APG using the

Purchasemethod of the APG Web Service (see 0)

3. If the merchant is enabled for Risk, APG sends the transaction to RSG for

screening – if the transaction is rejected by RSG, there is no further processing

of the transaction so continue at step 6; if the transaction is not rejected by

RSG, continue at the next step.

4. APG processes the transaction.

5. If the merchant is enabled for Risk, APG sends the bank result to RSG.

6. APG responds to the Purchase method request with the transaction’s result

details.

7. The result details must be analyzed and an appropriate message be displayed to

the client on the merchant’s site.

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

The following Processors use the non-redirect flow for Purchase transactions:

 AM – Amazon

 CL – Click2Pay

 EL – eCheck

 EV – ExperCash (ELV)

 NT – Neteller

 O3 – Offline Bank Transfer

 UK – Ukash

(Refer to Appendix 7 for descriptions of the various Processors.)

Figure 1

Merchant Server Alternative Payment

Gateway

(APG Web Service)

Processing

Institution

Request

Response

If validation checks are passed, the transaction is sent to processing institution.

Processing Result

Consumer

Consumer goes to merchant’s site and elects

their payment option, filling the necessary

information

Merchant to analyze response and display

appropriate message to consumer

Risk Services

Gateway

(RSG)

Merchant Risk

Enabled?

APG send transaction to RSG for screening

YES

RSG Result (Approved/Review/Rejected)

NO

RSG Rejected

YES

NO

Response

Merchant Risk

Enabled?

YES

NO

APG sends bank result to Risk System

RSG sends response to APG

3.2.4.2 Non-Redirect Flow (Figure 2 - Payout)

The client enters their payout details on the merchant’s site.

The merchant sends the relevant information to the APG using the Payout method of

the APG Web Service (see 0)

APG validates the payout request. If the transaction is rejected, there is no further

processing of the transaction so continue at step 5; if the transaction is not rejected,

continue at the next step.

APG processes the transaction.

APG responds to the Payout method request with the transaction’s result details.

The result details must be analyzed and an appropriate message be displayed to the

client on the merchant’s site.

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

The following Processors use the non-redirect flow for Payout transactions:

 BU – ClickandBuy

 CL – Click2Pay

 EP – EntroPay

 IN – InstaDebit

 MB – MoneyBookers

 NT – Neteller

 OC – Envoy OneClick

 UK – Ukash

(Refer to Appendix 7 for descriptions of the various Processors.)

Figure 2

Merchant Server Alternative Payment

Gateway

(APG Web Service)

Processing

Institution

Request

Response

If validation checks are passed, the transaction

is sent to processing institution.

Processing Result

Consumer

Consumer goes to merchant’s site and elects

their payout option, filling the necessary

information

Merchant to analyze response and display

appropriate message to consumer

Validate

Payout Failed?

YES

NO

Response

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

3.2.4.3 Redirect Flow (Figure 3)

1. The client enters their purchase details on the merchant’s site.

2. The merchant sends the relevant information to the APG using the Purchase

method of the APG Web Service (see 0).

3. If the merchant is enabled for Risk, APG sends the transaction to RSG for

screening – if the transaction is rejected by RSG, there is no further processing

of the transaction and APG responds to merchant; if the transaction is not

rejected by RSG, continue at the next step.

4. APG responds to the Purchase method request by returning the relevant set of

redirect parameters.

5. Merchant needs to transform the redirect parameters into form variables and

then redirect client to the Processor.

6. Client enters necessary information at the Processor’s site and confirms

transaction.

7. Processor will redirect the client to the Redirect Solution of the APG.

8. If the merchant is enabled for Risk, APG sends the bank result to RSG.

9. APG sends transaction result details notification to merchant’s URL via a server-

side post as detailed in Section 3.4.

10. The merchant acknowledges receipt of transaction result notification.

11. The result details must be analyzed by the merchant.

12. APG redirects the client to the merchant’s success or failure page depending on

the result.

Note: Steps 9-10 happens simultaneously with step 12.

The following Processors use the redirect flow:

 A7 – AliPay

 BU – ClickAndBuy

 EN – eNETS

 EV – ExperCash (GiroPay and Sofort)

 I3 – iDeal

 IN – InstaDebit

 MB – Moneybookers

 NS – NPS

 OC – OneClick

 PF – PaysafeCard

 P5 - POLi

 W3 – WebMoney

(Refer to Appendix 7 for descriptions of the various Processors.)

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Figure 3

Merchant Server Alternative Payment

Gateway (APG)

Web Service

Risk Services

Gateway

(RSG)

Processing

Institution

Request

APG redirects consumer to Merchant success/failure URL based on result

DPG-CPT sends final result

notification server-side to

Merchant Event URL

Merchant send receipt

confirmation of Notification

Consumer

Consumer goes to merchant’s site and elects

their payment option, filling the necessary

information

Appropriate message displayed to consumer

If validation checks are passed, then

transaction is sent to Redirect Solution

Redirect Solution prepares redirect parameters

that will be returned to merchant

Response

Merchant to transform the redirect parameters

into form variables, display appropriate

message to consumer informing they being

redirected to financial institution

Merchant redirects consumer to processing institution, passing along the form variables as supplied in the APG response

Consumer logs in and confirms transaction @Processing

Institution. Consumer then gets redirected to APG Redirect

Solution

APG Redirect Solution

Redirect interacts with APG Web Service

Dependent on payment method, transaction maybe sent to

processing institution for further processing

Merchant to analyze result and credit

consumer’s a/c based on successful result

APG sends bank result to RSG

Merchant Risk

Enabled? RSG sends response to APG

YES

Merchant Risk

Enabled?

APG send transaction to RSG for screening

RSG Result (Approved/Review/Rejected)

RSG Rejected

YES

NO

Response

Dependent on payment method, transaction maybe be sent to

processing institution for initialization

Processing Result

3.2.4.4 PARTIAL-Redirect Flow (Figure 4)

1. The client requests certain information (to be used for submitting a transaction)

from the merchant.

2. The merchant requests the information from APG. APG gathers the requested

information, and returns it to the merchant, who in turn provides it to the client.

3. The client enters the necessary information at the financial institution’s site and

confirms the transaction.

4. Financial institution will notify the Processor of the processed transaction.

5. The Processor notifies APG of the processed transaction.

6. APG receives this notification of the successful processed transaction.

7. APG sends transaction result details notification to merchant’s URL via a server-

side post.

The following payment methods / processors use the partial-redirect flow:

 BT – Direct Bank Transfer

(Refer to Appendix 7 for descriptions of the various payment methods / processors.)

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Figure 4

Consumer Merchant Server Alternative Payment Gateway

(APG) Processing Institution Financial Institution

Client commits transaction on the financial institution's web site

Financial institution notifies the processing institution of the processed transaction

Processing institution notifies the APG of the processed transaction

APG notifies the merchant of the processed transaction

Merchant notifies client of the processed transaction

Information request

The merchant requests the information

APG returns the requested information

The merchant returns the requested information

Back to Contents

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

3.3 APG SOAP WEB SERVICE

In order to call one of the web methods available in the web service, the following

needs to happen:

 Specify the DataCash URL specified in section 3.2.1 as the web reference

 Create the proxy class

 Instantiate the proxy class

 Pass along the parameters to the specific web method

All the Web Service’s Web Methods are discussed in detail in the following sections.

3.3.1 Shared XML Request and Response elements

There are certain XML complex structures in the Requests and Responses that are

common to more than one of the APG Web Methods – these elements are covered in

this section. Others are only used for a particular Web Methods – these elements will

be covered within the documentation for those Web Methods.

3.3.1.1 Shared Request Structures

3.3.1.1.1 AccountDetails

This is a set of the merchant’s authentication details which is required in order to

access the APG.

Element Name

AccountDetails

Type

AccountItem

Position

Purchase.purchaseDetails

Payout.payoutDetails

TransactionQuery

RetrieveSettlementValue

InformationRequest

Modification

Children

Yes

Attributes

No

Elements of AccountDetails

Element

Name

Description

Data type /

Limitations

Required /

Payment Method

Specific details

AccountName

The DataCash Account Name is the

unique gateway-supplied identifier

for the Merchant (applicable for all

Merchants).

String (20)

Mandatory for all

Payment Methods

and Risk

AccountPIN

The DataCash Account PIN is the

unique Gateway supplied password

for the Merchant.

String (50)

Mandatory for all

Payment Methods

CompanyId

The DataCash Company Id is the

unique Gateway supplied identifier

for the Merchant.

String (20)

Mandatory for all

Payment Methods

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example XML for AccountDetails complex elements

<AccountName>TestAccount</AccountName>

<AccountPIN>TestPIN</AccountPIN>

</AccountDetails>

3.3.1.1.2 AmountDetails

Element Name

AmountDetails

Type

AmountItem

Position

Purchase.purchaseDetails.BillingDetails

Purchase.purchaseDetails.ShippingDetails

Payout.payoutDetails.BillingDetails

RetrieveSettlementValue

Modification

Children

Yes

Attributes

No

Elements of AmountDetails

Element

Name

Description

Data type / Limitations

Required /

Payment Method

Specific details

Amount

This is the transaction

amount.

Int

This value must be sent as

cents (e.g. US $100.01 =

10001).

Mandatory for all

Payment Methods

and Risk

Exponent

This is the transaction

currency exponent.

Please refer to

Appendix 10.

Short

Mandatory for all

Payment Methods

and Risk

CurrencyCode

This is the transaction

currency.

Short

This value must be sent as

the numeric ISO currency

code (Please reference

Appendix 10).

Mandatory for all

Payment Methods

and Risk

Example XML for AmountDetails complex elements

</AmountDetails>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

3.3.1.1.3 SaleAmountDetails

Element Name

SaleAmountDetails

Type

AmountItem

Position

Purchase.purchaseDetails.BillingDetails

Children

Yes

Attributes

No

Elements of SaleAmountDetails

Element

Name

Description

Data type / Limitations

Required /

Payment Method

Specific details

Amount

This is the transaction

item sale amount.

Int

This value must be sent as

cents (e.g. US $100.01 =

10001).

# Optional for

OC.

N/A for all other

Payment Methods

Exponent

This is the transaction

item sale currency

exponent. Please refer

to Appendix 10.

Short

# Optional for

OC.

N/A for all other

Payment Methods

CurrencyCode

This is the transaction

item sale currency.

Short

This value must be sent as

the numeric ISO currency

code (Please reference

Appendix 10).

# Optional for

OC.

N/A for all other

Payment Methods

# SaleAmount can be used if the merchant requires the APG to do a currency

conversion from the Sale Amount to the merchant currency.

Example XML for AmountDetails complex elements

</SaleAmountDetails>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

3.3.1.2 Shared Response structures

3.3.1.2.1 Error

The result of an error encountered during processing will be displayed here.

Element Name:

Error

Position

Response.Event.Purchase

Response.Event.Payout

Response.Event.Settlement

Response.Event.Information

Response.Event.Modification

Children

Yes

Attributes

No

Elements of Error

Element Name

Description

Data type /

Limitations

Code

This is a return code which indicates the

rejection reason, if applicable.

String (10)

Description

This is a text field used to give a short

description of Code.

String (255)

Example XML for Error complex elements

<Error>

<Description>PurchaseDetails.AccountDetails.AccountPIN value

invalid</Description>

</Error>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

3.3.1.2.2 Event

Top-level container for the type of event that this Response refers to. This element

applies to all transaction types.

Element Name:

Event

Position

Response

Children

Yes

Attributes

No

Elements of Event

Element Name

Description

Data type /

Limitations

Directly below the Event element will be one of the following complex XML structures:

 Payout – see section 3.3.3.2

 Purchase – see section 3.3.2.3.4

 Settlement – see section 3.3.5.3.1

 Information – see section 3.3.6.3.6

 Modification – see section 3.3.7.1

3.3.1.2.3 Response

The complete XML structure that will be returned to the Merchant during a transaction.

Element Name:

Response

Position

Top-level

Children

Yes

Attributes

Yes

Attributes involved in the Response element

Attribute

Name

Located in

which Element

Description

Data type /

Limitations

version

Response

Version of the APG response

complex structure.

String

AccountName

Response

This is the account name that the

merchant holds with the processor.

String (50)

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Elements of Response

Element

Name

Description

Data type /

Limitations

Event

Top-level container for the type of event that this

Response refers to. This element appears in this position

for all transaction types.

n/a

Example XML for Response complex elements

<Event>

...other complex structures here, e.g. <Purchase...> etc.

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

3.3.2 Purchase

A call to the Purchase web method of the APG Web Service is the first step in the

lifecycle of a transaction.

Validation will occur during the call to the web method - see Appendix 6 for a list of

possible validation errors.

The result of this request will determine if the transaction has completed processing, or

whether the merchant should continue to process the transaction (by redirecting to the

Processor, and passing along the redirect parameters returned by the response to the

Purchase request).

A transaction that adheres to the partial-redirect flow is an exception to the standard

Purchase web method arrangement, since the merchant will never call the Purchase

web method in this scenario.

The Purchase web method accepts two parameters: purchaseDetails of type

PurchaseItem, and methodDetails of type PaymentMethodItem. The two types are

custom complex structures. For more information on the composition of these

structures, please refer to the WSDL which can be downloaded from the URLs specified

in section 3.2.1.

3.3.2.1 Schema Elements for Purchase Request

In this section, the fields that can be presented with Purchase transaction Requests will

be presented along with example XML for those fields.

To submit Processor transaction information for a Purchase transaction, one should use

the relevant PaymentMethodItem within the Purchase schema element:

 Purchase

o PurchaseDetails – see section 3.3.2.1.1

 AccountDetails – see section 3.3.1.1.1

 BillingDetails – see section 3.3.2.1.3

 AddressDetails – see section 3.3.2.1.2

 AmountDetails – see section 3.3.1.1.2

 SaleAmountDetails – see section 3.3.1.1.3

 PersonalDetails – see section 3.3.2.1.8

 ShippingDetails – see section 3.3.2.1.4

 AddressDetails – see section 3.3.2.1.2

 AmountDetails – see section 3.3.1.1.2

 RiskDetails – see section 3.3.2.1.5

 LineItems – see section 3.3.2.1.6

 CustomMerchantDetails – see section 3.3.2.1.7

o MethodDetails – see section 3.3.2.1.27

 One of the following:

 AliPayItem – section 3.3.2.1.26

 AmazonItem – section 3.3.2.1.21

 Click2PayItem – section 3.3.2.1.11

 ClickAndBuyItem – section 3.3.2.1.14

 ElectronicCheckItem – section 3.3.2.1.20

 eNetsItem – section 3.3.2.1.16

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

 ExperCashItem – section 3.3.2.1.19

 iDealItem – section 3.3.2.1.22

 InstaDebitItem – section 3.3.2.1.18

 MoneybookersItem – section 3.3.2.1.12

 NetellerItem – section 3.3.2.1.10

 NPSItem – section 3.3.2.1.9

 OBTItem – section 3.3.2.1.25

 OneClickItem – section 3.3.2.1.17

 PaySafeCardItem – section 3.3.2.1.13

 PoliItem - section 3.3.2.1.26

 UKashItem – section 3.3.2.1.15

 WebMoneyItem – section 3.3.2.1.24

The “Required / Payment Method Specific” column lists the following details:

 Mandatory - This means that field cannot be empty.

 Recommended - The data is highly recommended. The fields are not mandated

by APG since not all processors mandate them. Please note that if these fields

are not supplied and the transaction is processed through a processor which

does mandate them, the transaction will be rejected.

 Optional – The data is not required for processing but should be supplied if

available.

 Not Applicable – The data is not applicable for this payment method and will be

discarded if supplied.

If no data is available for Recommended or Optional fields, the field can simply be left

out completely. Under no circumstances is the word ‘NULL’ to be used as a default

value for blank fields; merchants should rather leave the field blank.

NOTE: If the value sent for a field should exceed the maximum length then the

transaction may be rejected by the risk system or risk screening may be

bypassed.

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

SOAP XML Purchase Request document:

<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xmlns:xsd="http://www.w3.org/2001/XMLSchema"

xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">

<soap:Body>

<TransactionId>string</TransactionId>

<Description>string</Description>

<TransactionDateTime>string</TransactionDateTime>

<WebBrowserSessionId>string</WebBrowserSessionId>

<SuccessURL>string</SuccessURL>

<FailureURL>string</FailureURL>

<UserIP>string</UserIP>

<UserAgentHeader>string</UserAgentHeader>

<UserAcceptHeader>string</UserAcceptHeader>

<CustomerReference>string</CustomerReference>

<AccountName>string</AccountName>

<AccountPIN>string</AccountPIN>

<CompanyId>string</CompanyId>

</AccountDetails>

<FirstName>string</FirstName>

<LastName>string</LastName>

<Telephone1>string</Telephone1>

<Telephone1_CountryCode>short</Telephone1_CountryCode>

<Telephone1_AreaCode>short</Telephone1_AreaCode>

<Telephone2>string</Telephone2>

<Telephone2_CountryCode>short</Telephone2_CountryCode>

<Telephone2_AreaCode>short</Telephone2_AreaCode>

<DateOfBirth>dateTime</DateOfBirth>

<Email>string</Email>

<IDNumber>string</IDNumber>

<TypeOfID>NONE or PASSPORT or PERSONAL_ID or IDENTITY_CARD or

DRIVERS_LICENSE or TRAVEL_DOCUMENT or RESIDENCE_PERMIT or

IDENTITY_CERTIFICATE_NUMBER or

REGISTRO_FEDERAL_DE_CONTRIBUYENTES or

CREDENTIAL_DE_ELECTOR</TypeOfID>

<CPF_CNPJ>string</CPF_CNPJ>

<Nationality>string</Nationality>

</PersonalDetails>

<Name>string</Name>

<StreetLine1>string</StreetLine1>

<StreetLine2>string</StreetLine2>

<City>string</City>

<PostalCode>string</PostalCode>

<StateProvince>string</StateProvince>

<Country>string</Country>

</AddressDetails>

<Exponent>short</Exponent>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

<CurrencyCode>short</CurrencyCode>

</AmountDetails>

<Exponent>short</Exponent>

<CurrencyCode>short</CurrencyCode>

</SaleAmountDetails>

</BillingDetails>

<Name>string</Name>

<StreetLine1>string</StreetLine1>

<StreetLine2>string</StreetLine2>

<City>string</City>

<PostalCode>string</PostalCode>

<StateProvince>string</StateProvince>

<Country>string</Country>

</AddressDetails>

<Exponent>short</Exponent>

<CurrencyCode>short</CurrencyCode>

</AmountDetails>

</ShippingDetails>

<MerchantId>short</MerchantId>

<AccountName>string</AccountName>

<AccountPassword>string</AccountPassword>

<AccountNumber>string</AccountNumber>

<UserId>string</UserId>

<UserMachineId>string</UserMachineId>

<UserProfile1>string</UserProfile1>

<UserProfile2>string</UserProfile2>

<UserProfile3>string</UserProfile3>

</RiskDetails>

<Language>string</Language>

</purchaseDetails>

</Purchase>

</soap:Body>

</soap:Envelope>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

3.3.2.1.1 PurchaseDetails

This is a set of fields and structures required for a transaction.

Element Name

PurchaseDetails

Type

PurchaseItem

Position

Purchase

Children

Yes

Attributes

No

Elements of PurchaseDetails

Element Name

Description

Data type /

Limitations

Required /

Payment Method

Specific details

TransactionId

The TransactionId

is a unique

identifier

generated by the

integrating

(Merchant)

system. Usually

this is the

integrating

system’s internal

payment order

reference

number.

String (16);

We

Recommend

this value be

be prefixed

with the

CompanyId

plus an

underscore e.g.

ABC_1234567

(where the

CompanyId is a

value that will

be supplied by

DataCash).

All

Mandatory

Description

Use this field to

supply descriptive

text for the

transaction.

String (255)

UK

Optional

TransactionDateTime

The Merchant’s

time stamp of the

transaction.

String (19);

Format “yyyy-

mm-dd

hh:mm:ss”

EN

Mandatory

EV

Mandatory

Risk

Mandatory

UK

Mandatory

UserAgentHeader

This is a value

indicating the

browser type and

operating system

details of the

user. This

information can

be retrieved from

the

HTTP_USER_AGE

NT header.

String (255)

All

Recommended

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

UserAcceptHeader

This is a value

that contains the

MIME types that a

browser can

accept. This

information can

be retrieved from

the HTTP_ACCEPT

header.

String (255)

All

Not Applicable

SuccessURL

This is the URL to

which the

merchant’s

consumer will be

redirected to after

a successful

transaction.

String (255)

BU

Mandatory

EN

Mandatory

EV

Mandatory:

for Giropay

and Sofort

only

I3

Mandatory

IN

Mandatory

MB

Mandatory

NS

Mandatory

OC

Mandatory

PF

Mandatory

P5

Mandatory

W3

Mandatory

FailureURL

This is the URL to

which the

merchant’s

consumer will be

redirected to after

an unsuccessful

transaction.

String (255)

BU

Mandatory

EN

Mandatory

EV

Mandatory:

for Giropay

and Sofort

only

I3

Mandatory

IN

Mandatory

MB

Mandatory

NS

Mandatory

OC

Mandatory

PF

Mandatory

P5

Mandatory

W3

Mandatory

Language

This field contains

the language in

which the client’s

user experience

will take place.

Please refer to

Appendix 13 for

supported

languages.

If no language is

supplied, the

value defaults to

“en” (English).

String (20)

All

Recommended

Risk

Not applicable

UserIP

Consumer's IP

String (26);

CL

Mandatory

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

address.

(Format:

255.255.255.255

)

EL

Mandatory

EV

Mandatory

P5

Mandatory

Risk

Recommended

CustomerReference

This is the generic

identifier of a

customer.

String(70)

EV

Optional

IN

Mandatory

O3

Mandatory

OC

Mandatory for

InstantBank

Purchase

AccountDetails

This is a set of

the merchant’s

authentication

details which is

required in order

to access the

APG.

See section

3.3.1.1.1

All

Mandatory

PersonalDetails

This is a set of

consumer specific

details that are

required by the

Processors.

See section

3.3.2.1.8

All

Mandatory

EV

Recommended

see

PersonalDetails.Fir

stName

x

PersonalDetails.Las

tName

x

BillingDetails

This is a set of

the consumer’s

billing details that

are required by

the Processors.

See section

3.3.2.1.3

All

Mandatory

ShippingDetails

This is a set of

consumer’s

shipping details

that are required

by the Processors.

See section

3.3.2.1.4

AM

Mandatory

NS

Mandatory

RiskDetails

This is a set of

specific details

that are required

by the Processors.

See section

3.3.2.1.5

All

If Risk is

enabled on

the merchant

this element is

mandatory

CustomMerchantDetails

Optional structure

allowing

Merchants to pass

custom fields and

values.

See section

3.3.2.1.7

All

Optional

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

LineItems

Merchants can

provide detail on

the purchased

items. The items

are passed as

Line Items.

See Section

3.3.2.1.6

AM

Mandatory

Example XML for PurchaseDetails with all complex elements

<TransactionId>string</TransactionId>

<Description>string</Description>

<TransactionDateTime>string</TransactionDateTime>

<WebBrowserSessionId>string</WebBrowserSessionId>

<SuccessURL>string</SuccessURL>

<FailureURL>string</FailureURL>

<UserIP>string</UserIP>

<UserAgentHeader>string</UserAgentHeader>

<UserAcceptHeader>string</UserAcceptHeader>

<Language>string</Language>

<AccountName>TestAccount</AccountName>

<AccountPIN>TestPIN</AccountPIN>

</AccountDetails>

<FirstName>Jerry</FirstName>

<LastName>Anderson</LastName>

<Telephone1_CountryCode>44</Telephone1_CountryCode>

<Telephone1_AreaCode>105</Telephone1_AreaCode>

<Telephone2_CountryCode/>

<Telephone2_AreaCode/>

<Email>customer@email.com</Email>

<TypeOfID>PASSPORT</TypeOfID>

<SSN/>

<CPF_CNPJ/>

</PersonalDetails>

<StreetLine1>404 Mulberry Court</StreetLine1>

<StreetLine2>78 Praed Street</StreetLine2>

<City>London</City>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

</AddressDetails>

</AmountDetails>

</SaleAmountDetails>

</BillingDetails>

<StreetLine1>404 Mulberry Court</StreetLine1>

<StreetLine2>78 Praed Street</StreetLine2>

<City>London</City>

</AddressDetails>

</AmountDetails>

</ShippingDetails>

<AccountName>TestAccount</AccountName>

<AccountPassword>TestPwd</AccountPassword>

<UserMachineId>DESKTOP13579</UserMachineId>

<UserProfile1>is_vip_customer</UserProfile1>

<UserProfile2>is_promotion</UserProfile2>

<UserProfile3>is_good_customer</UserProfile3>

</RiskDetails>

<FieldName>PaymentId</FieldName>

</CustomDetail>

</CustomMerchantDetails>

</purchaseDetails>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

3.3.2.1.2 AddressDetails

Element Name

AddressDetails

Type

AddressItem

Position

Purchase.purchaseDetails.BillingDetails

Purchase.purchaseDetails.ShippingDetails

Payout.payoutDetails.BillingDetails

Children

Yes

Attributes

No

Elements of AddressDetails

Element Name

Description

Data type /

Limitations

Payment Applicable

Requirements

StreetLine1

Consumer’s

address line1

String (60)

BU

Mandatory

EP

Optional

EV

Optional (refer to note

below)

IN

Optional

MB

Optional

NS

Mandatory

O3

Optional

OC

Optional – However is

mandatory for some of

the OC products.

Risk

Mandatory

StreetLine2

Consumer’s

address line2

String (60)

BU

Optional

EV

Optional (refer to note

below)

NS

Recommended

O3

Optional

OC

Optional – However is

mandatory for some of

the OC products.

Risk

Recommended

City

Consumer’s

city

String (60)

Only alpha characters

(A – Z) and spaces are

allowed in this field.

BU

Optional

EP

Optional

EV

Optional (refer to note

below)

IN

Optional

MB

Optional

NS

Mandatory

O3

Optional

OC

Optional – However is

mandatory for some of

the OC products.

Risk

Mandatory

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

PostalCode

Consumer’s

Postal

code/zip.

String (10)

China

China does

not make use

of a zip code,

but does

make use of

a postal code

e.g.

Shanghai

postal code

= 200336.

Please send

through the

postal code

in this field.

US

Digit number

e.g. 77088

CA

Alphanumeric

characters

e.g. V3M3W5

BU

Optional

EP

Optional

EV

Optional (refer to note

below)

IN

Optional

MB

Optional

NS

Mandatory

O3

Optional

OC

Optional – However is

mandatory for some

of the OC products.

Risk

Mandatory

StateProvince

Consumer’s

State/Province

String (25)

Please reference

Appendix 8. For

countries listed in

Appendix 8, please

send the value listed in

the Code Column. For

any other country,

please send the full

state name up to the

max length specified.

CL

Mandatory

EP

Optional

IN

Mandatory

MB

Optional

NS

Mandatory

O3

Optional

OC

Optional – However is

mandatory for some

of the OC products.

Risk

Recommended

Country

Consumer’s

Country

String (60)

This is a 2-character

code that needs to be

supplied. Please

reference Appendix 9.

BU

Mandatory

CL

Mandatory

OC

Mandatory

EP

Optional

EV

Optional (refer to note

below)

IN

Optional

MB

Optional

NS

Mandatory

NT

Optional

O3

Mandatory

OC

Optional – However is

mandatory for some

of the OC products.

Risk

Mandatory

ExperCash Note: When submitting an ExperCash (ELV) transaction, either of the

below combinations of customer data may be sent to APG or nothing at all.

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Field

Combo

1

Combo

2

Combo

3

Combo

4

Combo

5

Combo

6

PersonalDetails.FirstName

x

PersonalDetails.LastName

x

StreetLine1

x

StreetLine2

x

City

x

PostalCode

x

Country

x

If only partial data is supplied, then the transaction will be rejected.

The above fields are only applicable for ELV (Buy and Authorise). For GiroPay and

Sofort, these can be left out completely or sent through with blank values. In the case

where Risk is enabled, these values must be sent through.

Example XML for AddressDetails complex elements

<StreetLine1>404 Mulberry Court</StreetLine1>

<StreetLine2>78 Praed Street</StreetLine2>

<City>London</City>

</AddressDetails>

3.3.2.1.3 BillingDetails

This is a set of the consumer’s billing details that are required by the Processors.

Element Name

BillingDetails

Type

BillingItem

Position

Purchase.purchaseDetails

Payout.payoutDetails

Children

Yes

Attributes

No

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Elements of BillingDetails

Element Name

Description

Purchase /

Payout

Data type /

Limitations

Payment Applicable

Requirements

Name

This is

descriptor for

the billing

details.

*NB: This

element

should

contain the

bank

account

owner’s

name. It is

used for

debiting the

account.

Incorrect

information

could cause

chargebacks

and for

larger

amounts,

there may

be checks

for the

owner

matching

the account

number.

Purchase,

Payout

String (50)

EV

Mandatory:

Only for ELV

(Buy and

Authorise)

EL

Mandatory

O3

Optional

OC

Optional

Risk

Recommended

AddressDetails

These are

line items of

the address.

Purchase,

Payout

See section 3.3.2.1.2

AmountDetails

This is a set

of billing

amount

details.

Purchase,

Payout

See section 3.3.1.1.2

SaleAmountDetails

This is a set

of sale

amount

details.

Purchase

See section 3.3.1.1.3

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example XML for BillingDetails complex elements

<Name>JohnDoe</Name>

<StreetLine1>404 Mulberry Court</StreetLine1>

<StreetLine2>78 Praed Street</StreetLine2>

<City>London</City>

</AddressDetails>

</AmountDetails>

</SaleAmountDetails>

</BillingDetails>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

3.3.2.1.4 ShippingDetails

This is a set of the consumer’s shipping details that are required by the Processors.

Element Name

ShippingDetails

Type

ShippingItem

Position

Purchase.purchaseDetails

Children

Yes

Attributes

No

Elements of ShippingDetails

Element Name

Description

Data type /

Limitations

Required / Payment Method

Specific details

Name

This is

descriptor for

the shipping

details.

String (50)

NS

Optional

O3

Optional

Risk

Optional

AddressDetails

These are line

items of the

address.

See section 3.3.2.1.2

AmountDetails

This is a set

of billing

amount

details.

See section 3.3.1.1.2

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example XML for ShippingDetails complex elements

<StreetLine1>404 Mulberry Court</StreetLine1>

<StreetLine2>78 Praed Street</StreetLine2>

<City>London</City>

</AddressDetails>

</AmountDetails>

</ShippingDetails>

3.3.2.1.5 RiskDetails

This is a set of specific details that are required by for Risk Screening.

Element Name

RiskDetails

Type

RiskItem

Position

Purchase.purchaseDetails

Children

Yes

Attributes

No

Elements of RiskDetails

Element Name

Description

Data type /

Limitations

Required / Payment

Method Specific

details

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

MerchantId

This is a unique gateway

supplied risk identifier for

merchants who require risk

screening.

Short

Risk

#Optional

AccountName

This is the associated

account name that goes with

the MerchantId supplied by

DataCash.

String (30)

Risk

#Optional

AccountPassword

This is the associated

account password that goes

with the MerchantId supplied

by DataCash.

String (50)

Risk

#Optional

AccountNumber

A unique account number at

the Merchant associated with

individual that is transacting.

String (30)

Risk

Mandatory

UserId

This is a Merchant

configurable data field

typically used to identify a

customer uniquely within the

system, regardless of the

amount of accounts that the

customer has.

String (36)

Risk

Optional

UserMachineId

This is an ID used to identify

the computer (actual

hardware) uniquely within

the system regardless of the

amount of customers or

accounts that’s using the

computer.

Examples of the User

Machine ID are Motherboard

ID, Hard drive ID, CPU ID,

etc.

String (25)

Risk

Optional

UserProfile1

This is a customizable field

that may be used by the

merchant to supplement

fraud screening processes

according to a risk

classification set by the

merchant (e.g. VIP flag,

indication whether the

transaction is part of a

promotion, a confidence

level around the identity of

the customer, etc).

String (20)

Risk

Optional

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

UserProfile2

This is a customizable field

that may be used by the

merchant to supplement

fraud screening processes

according to a risk

classification set by the

merchant.

String (20)

Risk

Optional

UserProfile3

This is a customizable field

that may be used by the

merchant to supplement

fraud screening processes

according to a risk

classification set by the

merchant.

String (20)

Risk

Optional

LineItems

Retail merchants can provide

detail on the purchaced

items. The items are passed

as Line Items.

See Section

3.3.2.1.6

Risk

Mandatory for

Retail Risk

Screening

# The Risk Authentication Fields (MerchantId, AccountName and AccountPassword) are

by default setup on the APG Merchant Profile. However the default can be overridden.

To override the default, values for all the authentication fields (MerchantId,

AccountName and AccountPassword) are required on the RiskDetails element of the

payment request.

Example XML for RiskDetails complex elements

<AccountName>TestAccount</AccountName>

<AccountPassword>TestPwd</AccountPassword>

<UserMachineId>DESKTOP13579</UserMachineId>

<UserProfile1>is_vip_customer</UserProfile1>

<UserProfile2>is_promotion</UserProfile2>

<UserProfile3>is_good_customer</UserProfile3>

</RiskDetails>

3.3.2.1.6 Line Item

This is a set of specific details that are required by either the Risk Line Item or the

Purchase Detail Line Item.

Element Name

LineItem

Type

LineItem

Position

Purchase.purchaseDetails.RiskDetails.LineItems

Purchase.purchaseDetails.LineItems

Children

Yes

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Attributes

No

3.3.2.1.6.1 Position: Purchase.purchaseDetails.RiskDetails.LineItems

Elements of a LineItem Structure

Element Name

Description

Data type /

Limitations

Required / Payment

Method Specific

details

LineItemId

Unique line item ID

Int

ALL

Optional

ProductCode

Line item product code

String(50)

ALL

Optional

ProductDescription

Line item description

String(50)

ALL

Optional

ProductCategory

Type of item as classified

by the merchant

String(50)

ALL

Optional

ProductRisk

Indication of how

susceptible to product is

to fraud.

Possible values:

High

Medium

Low

String(50)

ALL

Optional

OrderQuantity

Number of items ordered

Int

ALL

Optional

UnitPrice

The amount of the

transaction in the smallest

unit of the currency

Int

ALL

Optional

Example XML for LineItem complex elements

<ProductCode>Sample</ProductCode>

<ProductDescription>Sample Description</ProductDescription>

</LineItem>

3.3.2.1.6.2 Position: Purchase.purchaseDetails.LineItems

Elements of a LineItem Structure

Element Name

Description

Data type /

Limitations

Required / Payment

Method Specific details

LineItemId

Unique line item ID

Int

AM

Mandatory

ProductCode

Line item product code

String(50)

Risk

#Mandatory

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

ProductDescription

Line item description

String(50)

AM

Mandatory

ProductCategory

Type of item as

classified by the

merchant

String(50)

Risk

#Mandatory

ProductRisk

Indication of how

susceptible to product is

to fraud.

Possible values:

High

Medium

Low

String(50)

AM

Mandatory

OrderQuantity

Number of items

ordered

Int

Risk

#Mandatory

UnitPrice

The amount of the

transaction in the

smallest unit of the

currency

Int

AM

Mandatory

# – Line Items are only Mandatory for Retail Risk Screening if the merchant is set up

to do risk.

Example XML for LineItem complex elements

<ProductCode>Sample</ProductCode>

<ProductDescription>Sample Description</ProductDescription>

</LineItem>

3.3.2.1.7 CustomMerchantDetails

This is a set of specific details that are required by a CustomDetail Item.

Element

Name

CustomDetail

Type

CustomDetail

Position

Purchase.purchaseDetails.CustomMerchantDetails

Payout.payoutDetails.CustomMerchantDetails

Children

Yes

Attributes

No

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Elements of CustomDetail

Element

Name

Description

Data type /

Limitations

Required / Payment Method

Specific details

FieldValue

Custom field name

String(20)

All

Optional

FieldName

Value associated

with the custom field

String(100)

All

Optional

Example XML for CustomDetail complex elements

<FieldName>PaymentId</FieldName>

</CustomDetail>

</CustomMerchantDetails>

Example XML Result for CustomDetail complex elements

</CustomMerchantDetails>

3.3.2.1.8 PersonalDetails

This is a set of consumer specific details that are required by the Processors.

Element Name

PersonalDetails

Type

PersonalItem

Position

Purchase.purchaseDetails

Payout.payoutDetails

Children

Yes

Attributes

No

Elements of Personal Details

Element Name

Description

Data type /

Limitations

Required / Payment

Method Specific details

FirstName

Consumer's First Name.

String (32)

BU

Recommended

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

It must be at

least 2

characters

long.

EV

Optional - refer

to note under

PersonalDetails.Fir

stName

x

PersonalDetails.Las

tName

x

IN

Optional

MB

Recommended

NS

Mandatory

NT

Optional

O3

Mandatory

OC

Optional

Risk

Recommended:

The combined

length of the

FirstName and

LastName fields

may not exceed 31

characters

LastName

Consumer's Last Name.

String (32)

It must be at

least 2

characters

long.

BU

Recommended

EP

Optional

EV

Optional - refer

to note under

3.3.2.1.1

IN

Optional

MB

Recommended

NS

Mandatory

NT

Optional

O3

Mandatory

OC

Optional

Risk

Recommended:

The combined

length of the

FirstName and

LastName fields

may not exceed 31

characters

Telephone1_Country

Code

Consumer's Telephone

Country Code for Telephone1.

The country code is the prefix

to be used when dialling to a

particular country from

another country.

Short. This

value must

not be

prefixed with

a plus (+)

e.g. 1 for

United

States.

BU

Optional

EP

Optional

EV

Optional

NS

Mandatory

O3

Optional

Risk

Recommended

Telephone1_AreaCod

e

Consumer's Telephone Area

Code for Telephone1. This is

the 3-digit area code for a

particular region.

Short; US: 3

digit number

(e.g. 619 for

California).

CA: 3 digit

BU

Optional

EV

Optional

IN

Optional

NS

Mandatory

O3

Optional

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

number (e.g.

867 for

Northwest

Territories).

Risk

Recommended

Telephone1

Consumer’s Local Home

Telephone Number.

String (20);

US: The 7

digit home

telephone

number

must be

supplied in

this field.

CA: The 7

digit home

telephone

number

must be

supplied in

this field.

BU

Optional

EP

Optional

EV

Optional

IN

Optional

NS

Mandatory

O3

Optional

Risk

Recommended

Telephone2_Country

Code

Consumer's Telephone

Country Code for Telephone2.

The country code is the prefix

to be used when dialling to a

particular country from

another country.

Short; This

value must

not be

prefixed with

a plus (+)

e.g. 1 for

United

States.

NS

Mandatory

O3

Optional

Risk

Optional

Telephone2_AreaCod

e

Consumer's Telephone Area

Code for Telephone2. This is

the 3-digit area code for a

particular region.

Short; US: 3

digit number

(e.g. 619 for

California).

CA: 3 digit

number (e.g.

867 for

Northwest

Territories).

NS

Mandatory

O3

Optional

Risk

Optional

Telephone2

Consumer’s Secondary

Telephone Number

String (20)

NS

Mandatory

O3

Optional

Risk

Optional

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

DateOfBirth

Consumer's date of birth.

String (10);

Format

“yyyy-mm-

dd”. If a

value is

supplied, it

must be a

valid date

larger than

“1899-12-

31”.

BU

Optional

EL

Optional

EP

Not applicable

IN

Optional

O3

Optional

Risk

Recommended

Nationality

Consumer's nationality.

String (3)

BU

Optional

O3

Optional

Risk

Optional

Email

Consumer's Email Address.

String (64);

The email

address

must contain

an @ and a

dot (.)

BU

Recommended

EN

Recommended

EP

Mandatory

EV

Optional

NS

Mandatory

NT

Optional

O3

Mandatory

OC

Mandatory

Risk

Recommended

IDNumber

The ID number required

differs by country. Please see

Appendix 11 for the list of

countries and required ids.

String (40)

EP

Optional for

Payouts

Risk

Recommended

TypeOfID

This field indicates the type of

ID sent through in the

IDNumber field. The

associated numeric code for

the ID Type must be sent

through e.g. If the consumer

chose to enter in his passport

registry number, then the

value “1” must be submitted.

If the IDNumber is not

supplied, this field should be

left blank. Appendix 12 lists

the possible ID Types and

their numeric codes.

Enum

Risk

Recommended

SSN

If the consumer’s country

code is US (United States),

the last 4 digits of the Social

Security Number (SSN) must

be provided, else if the

consumer’s country code is CA

(Canada), then the full 9 digit

Social Insurance Number

(SIN) must be provided in this

field.

String (9)

Risk

Recommended

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

CPF_CNPJ

This is required for Brazilian

transactions.

 CPF – Brazilian individual

taxpayer ID number.

 CNPJ – ID Number of

Brazilian companies.

String (20)

All

Not Applicable

Gender

Consumer’s Gender (M =

male, F = Female)

String(1)

EV

Recommended

Example XML for PersonalDetails with all complex elements

<FirstName>Jerry</FirstName>

<LastName>Anderson</LastName>

<Telephone1_CountryCode>44</Telephone1_CountryCode>

<Telephone1_AreaCode>105</Telephone1_AreaCode>

<Telephone2_CountryCode/>

<Telephone2_AreaCode/>

<Email>customer@email.com</Email>

<TypeOfID>PASSPORT</TypeOfID>

<SSN/>

<CPF_CNPJ/>

</PersonalDetails>

3.3.2.1.9 NPSItem

These are the fields or structures contained within the NPSItem structure.

Element Name

NPSItem

Type

NPSItem

Position

Purchase.methodDetails

Children

No

Attributes

No

Structure is to be sent blank.

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example XML for NPSItem elements (note that it is to be sent blank, as

shown in this small portion of the Purchase request)

</purchaseDetails>

</Purchase>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

3.3.2.1.10 NetellerItem

These are the fields or structures contained within the NetellerItem structure.

Element Name

NetellerItem

Type

NetellerItem

Position

Purchase.methodDetails

Children

Yes

Attributes

No

Elements of NetellerItem

Element Name

Description

Data type /

Limitations

Required /

Payment

Method Specific

details

AccountNumber

Consumer’s

NETELLER Account

ID

String (50)

NT

Mandatory

AccountPIN

Consumer’s secure

ID that was

assigned, when

they registered with

NETELLER.

String (50)

NT

Mandatory

PaymentInstrumentNumber

This field contains

an additional

account number

relating to the

client’s account at

the financial

institution (it is the

consumer’s last 4

digits of the bank

account registered

with NETELLER.)

This needs to be

provided if you

would like to make

use of NETELLER’s

instaCASH option.

String (50)

This is only available

for consumers with a

US or Canadian

bank account and

the transaction

currency (i.e.

CurrencyCode) must

be 840 or 124

NT

Optional

Example XML for NetellerItem complex elements

<AccountNumber>TestAccount</AccountNumber>

<AccountPIN>TestPIN</AccountPIN>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

3.3.2.1.11 Click2PayItem

These are the fields or structures contained within the Click2PayItem structure.

Element Name

Click2PayItem

Type

Click2PayItem

Position

Purchase.methodDetails

Children

Yes

Attributes

No

Elements of Click2PayItem

Element Name

Description

Data type /

Limitations

Required / Payment

Method Specific

details

AccountNumber

Consumer’s Click2Pay User Name

(in the form of an email address).

String (50)

CL

Mandatory

AccountPIN

Consumer’s Click2Pay Personal

Account Number (PAN) that was

assigned, when they registered

with Click2Pay.

String (50)

CL

Mandatory

Example XML for Click2PayDetails complex elements

<AccountNumber>test.account@gmail.com</AccountNumber>

<AccountPIN>TestPIN</AccountPIN>

3.3.2.1.12 MoneybookersItem

These are the fields or structures contained within the MoneybookersItem structure.

Element Name

MoneybookersItem

Type

MoneybookersItem

Position

Purchase.methodDetails

Children

Yes

Attributes

No

Elements of MoneybookersItem

Element Name

Description

Data type /

Limitations

Required / Payment

Method Specific

details

AccountNumber

Consumer’s MoneyBookers

User Name (in the form of

an email address).

String (50)

MB

Mandatory

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

PaymentMethodType

Payment method for

Moneybookers. For more

information, please refer to

Appendix 16.

Enum

MB

Optional

Example XML for MoneybookersItem complex elements

<AccountNumber>test.account@gmail.com</AccountNumber>

3.3.2.1.13 PaySafeCardItem

These are the fields or structures contained within the PaySafeCardItem structure.

Element Name

PaySafeCardItem

Type

PaySafeCardItem

Position

Purchase.methodDetails

Children

No

Attributes

No

Structure is to be sent blank.

Example XML for PaySafeCardItem elements (note that it is to be sent

blank, as shown in this small portion of the Purchase request)

</purchaseDetails>

</Purchase>

3.3.2.1.14 ClickAndBuyItem

These are the fields or structures contained within the ClickAndBuyItem structure.

Element Name

ClickAndBuyItem

Type

ClickAndBuyItem

Position

Purchase.methodDetails

Children

Yes

Attributes

No

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Elements of ClickAndBuyItem

Element Name

Description

Data type /

Limitations

Required / Payment Method

Specific details

AccountNumber

Consumer’s

ClickAndBuy

account

number.

String (50)

BU

Optional

Create Recurring

States

whether to do

a recurring

purchase

transaction

boolean

BU

Optional

Example XML for ClickAndBuyItem complex elements

<CreateRecurring>false</CreateRecurring>

3.3.2.1.15 UKashItem

These are the fields or structures contained within the UKashItem structure.

Element Name

UKashItem

Type

UKashItem

Position

Purchase.methodDetails

Children

Yes

Attributes

No

Elements of UKashItem

Element Name

Description

Data type /

Limitations

Required / Payment

Method Specific

details

AccountNumber

Consumer’s Ukash Voucher or

Account number.

String (19)

UK

Mandatory

AccountPIN

Consumer’s Ukash Account

number PIN.

String (4)

UK

Optional. This is

mandatory if the

AccountNumber

is 16 digits long.

AccountValue

Ukash voucher or account

value.

Int

UK

Mandatory

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

TypeOfRedemption

This identifies the type of

purchase transaction. Example:

If the consumer wants to make

a cash withdrawal then the

value “CASH_WITHDRAWAL”

must be passed. Refer to

Appendix 15.

Enum

UK

Mandatory

AmountReference

This is the id returned from the

‘RetrieveSettlementValue’ web

method.

String (50)

UK

Optional

Example XML for UKashItem complex elements

<TypeOfRedemption>CASH_WITHDRAWAL</TypeOfRedemption>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

3.3.2.1.16 eNetsItem

These are the fields or structures contained within the eNetsItem structure.

Element Name

eNetsItem

Type

eNetsItem

Position

Purchase.methodDetails

Children

No

Attributes

No

Structure is to be sent blank.

Example XML for eNetsItem complex elements (note that it is to be sent

blank, as shown in this small portion of the Purchase request)

</purchaseDetails>

</Purchase>

3.3.2.1.17 OneClickItem

These are the fields or structures contained within the OneClickItem structure.

Element Name

OneClickItem

Type

OneClickItem

Position

Purchase.methodDetails

Children

Yes

Attributes

No

Elements of OneClickItem

Element Name

Description

Data type /

Limitations

Required / Payment

Method Specific

details

AccountNumber

N/A

String (50)

OC

N/A

ServiceType

This indicates the type of

banking service available from

Envoy OneClick. Refer to

Appendix 17.

Enum

OC

Mandatory

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example XML for OneClickItem complex elements

<ServiceType>IDEAL</ServiceType>

3.3.2.1.18 InstaDebitItem

These are the fields or structures contained within the InstaDebitItem structure.

Element Name

InstaDebitItem

Type

InstaDebitItem

Position

Purchase.methodDetails

Children

No

Attributes

No

Structure is to be sent blank.

Example XML for InstaDebitItem elements (note that it is to be sent blank, as

shown in this small portion of the Purchase request)

</purchaseDetails>

</Purchase>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

3.3.2.1.19 ExperCashItem

These are the fields or structures contained within the ExperCashItem structure.

Element Name

ExperCashItem

Type

ExperCashItem

Position

Purchase.methodDetails

Children

Yes

Attributes

No

Elements of ExperCashItem

Element Name

Description

Data type

/

Limitations

Required / Payment

Method Specific details

SortCode

This is the Customer's

bank sort code.

String (8)

EV

ELV:

Mandatory. Either

the Combination of

(SortCode and

AccountNumber), or

IBAN or

PaymentReference

must be supplied,

but not all values can

be empty.

GiroPay:

SortCode is

mandatory.

Sofort: None of these

fields are required.

AccountNumber

This is the Customer's

bank account number

String (10)

EV

IBAN

This is the International

Bank Account Number.

Standard for

indentifying bank

accounts across

national borders..

String (34)

EV

PaymentReference

This is a Merchant

configurable data field

typically used to

identify a customer

uniquelywithin the

system, regardless of

the amount of accounts

that the customer has.

String (15)

EV

TypeOfAction

This field indicates the

type of purchase Action

that the ExperCash

gateway needs to

perform. Please refer to

Appendix 19 for a list

of Actions that can be

performed.

Enum

EV

Mandatory

DelayDays

This is the number of

days on which the

direct debit must be

actioned. This only

applies to ‘BUY’ type

transactions.

Short

EV

Mandatory. If

TypeOfAction is

'BUY', then either

DelayDays or

DebitDate is

mandatory, but both

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

DebitDate

This is the date on

which the direct debit

must be actioned.

Format “yyyy-mm-dd”.

String (10)

EV

values must not be

supplied.

Profile

The respective profile

controls which payment

and transaction

methods can be

selected.

Int

EV

Mandatory

Example XML for ExperCashItem complex elements

3.3.2.1.20 ElectronicCheckItem

These are the fields or structures contained within the ElectronicCheckItem structure.

Element Name

ElectronicCheckItem

Type

ElectronicCheckItem

Position

Purchase.methodDetails

Children

Yes

Attributes

No

Elements of ElectronicCheckItem

Element Name

Description

Data type /

Limitations

Required /

Payment Method

Specific details

FinancialAccount

Number

Customer's bank routing

number

String (8)

EL

Mandatory

AccountNumber

This is the Customer's bank

account number

String (8)

EL

Mandatory

AccountType

This is the type of the

Customer’s account. Please

refer to Appendix 21 for a list

of eCheck account types

Enum

EL

Mandatory

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

TypeOfAction

This is the type of the

transaction. Please refer to

Appendix 22 for a list of

eCheck action types

Enum

EL

Mandatory

Recurring

This is to indicate that the

transaction will be recurring

Booelan

EL

Optional

StartDate

Start date for recurring

transactions. Date format is

‘DD/MM/YYYY’.

Date

EL

For recurring

transactions

it is

Mandatory.

For non

recurring

transactions

it is Optional.

EndDate

End date for recurring

transactions. Date format is

‘DD/MM/YYYY’.

Date

EL

Optional

Frequency

Recurrence pattern for the

date on which clients will be

billed every month. The

frequency pattern uses a

subset of a standard CRON

expression, comprising 3

fields separated by a white

space. Please refer to

Appendix 20 for frequency

pattern fields.

String(12)

EL

For recurring

transactions

it is

Mandatory.

For non

recurring

transactions

it is Optional.

Example XML for ElectronicCheckItem complex elements

<AccountType>CONSUMER_SAVING</AccountType>

<TypeOfAction>AUTH_AND_CAPTURE</TypeOfAction>

3.3.2.1.21 AmazonItem

These are the fields or structures contained within the AmazonItem structure.

Element Name

AmazonItem

Type

AmazonItem

Position

Purchase.methodDetails

Children

Yes

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Attributes

No

Elements of AmazonItem

Element Name

Description

Data type

/

Limitations

Required / Payment

Method Specific details

AmazonContractID

Amazon

ContractID

String

(255)

AM

Mandatory

Example XML for AmazonItem complex elements

<AmazonContractID>amzn1.contract.1.1.1.8a34d7a8db9a4e8be2b25d9e2e67fff1</

AmazonContractID>

3.3.2.1.22 iDealItem

These are the fields or structures contained within the iDealItem structure.

Element Name

iDealItem

Type

iDealItem

Position

Purchase.methodDetails

Children

Yes

Attributes

No

Elements of iDealItem

Element Name

Description

Data type /

Limitations

Required / Payment

Method Specific details

IssuerId

IssuerId the consumer

has selected from the

drop down on the

merchant site.

Int

I3

Mandatory

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example XML for iDealItem complex

elements

</methodDetails>

3.3.2.1.23 iDealBankListItem

These are the fields or structures contained within the iDealItem structure.

Element Name

iDealBankListItem

Type

iDealBankListItem

Position

GetInformation.methodDetails

Children

Yes

Attributes

No

Elements of iDealItem

Element Name

Description

Data type /

Limitations

Required / Payment

Method Specific details

None

-

Example XML for iDealBankListItem complex element

3.3.2.1.24 WebMoney

These are the fields or structures contained within the WebMoney structure.

Element Name

WebMoneyItem

Type

WebMoneyItem

Position

Purchase.methodDetails

Children

Yes

Attributes

No

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Elements of WebMoneyItem

Element Name

Description

Data type /

Limitations

Required / Payment

Method Specific details

None

-

Example XML for WebMoneyItem complex elements

</methodDetails>

3.3.2.1.25 OBTItem

These are the fields or structures contained within the OBTItem structure.

Element Name

OBTItem

Type

OBTItem

Position

Purchase.methodDetails

Children

Yes

Attributes

No

Elements of OBTItem

Element

Name

Description

Data type /

Limitations

Required / Payment

Method Specific details

ServiceType

This indicates the type of

banking service available.

Refer to Appendix 27.

Enum

O3

Mandatory

Example XML for OBTItem complex elements

<ServiceType>LA_CAIXA</ServiceType>

</methodDetails>

3.3.2.1.26 AliPayItem

These are the fields or structures contained within the AliPayItem structure.

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Element Name

AliPayItem

Type

AliPayItem

Position

Purchase.methodDetails

Children

Yes

Attributes

No

Elements of AliPayItem

Element Name

Description

Data type /

Limitations

Required / Payment

Method Specific

details

AuthorizationToken

The secure token from

accessing express login API

Mandatory for express login

String

A7

Optional

Body

A detailed description of the

goods

String (400)

A7

Optional

BuyerId

The unique ID of the buyer

of this trade

Mandatory for express login

String (16)

A7

Optional

SettlementCurrency

The Settlement curreny

code. Please refer to

Appendix 10.

Short

A7

Mandatory

Subject

The name of the goods

String(256)

A7

Mandatory

Supplier

The name of supplier

String(64)

A7

Optional

Example XML for Politem complex elements

<Subject>Test Subject</Subject>

</methodDetails>

3.3.2.1.27 methodDetails (PaymentMethodItem)

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

This is a parent structure from which all the individual specific payment methods are

inherited.

Element Name

methodDetails

Type

PaymentMethodItem

Position

Purchase

Children

Yes

Attributes

Yes

Elements of methodDetails

Element Name

Description

Data type /

Limitations

Required / Payment Method

Specific details

Please refer to the following sections for details relevant to each individual payment

method:

 A7 See section 3.3.2.1.26

 AM See section 3.3.2.1.21

 BU See section 3.3.2.1.14

 CL See section 3.3.2.1.11

 EL See section 3.3.2.1.20

 EN See section 3.3.2.1.16

 EV See section 3.3.2.1.19

 I3 See section 3.3.2.1.22

 IN See section 3.3.2.1.18

 MB See section 3.3.2.1.12

 NS See section 3.3.2.1.9

 NT See section 3.3.2.1.10

 O3 See section 3.3.2.1.25

 OC See section 3.3.2.1.17

 PF See section 3.3.2.1.13

 P5 See section 3.3.2.1.26

 UK See section 3.3.2.1.15

 W3 See section 3.3.2.1.24

Attributes of methodDetails

Element Name

Description

Data type /

Limitations

Required / Payment Method

Specific details

xsi:type

This indicates the

individual payment

method involved in

this transaction.

Refer to Appendix 7

for the Payment

Method Type options.

Enum

ALL

Mandatory

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example XML for methodDetails complex elements (no individual payment

method structure involved e.g. eNets)

Example XML for methodDetails complex elements (individual payment

method structure involved e.g. Ukash)

<TypeOfRedemption>CASH_WITHDRAWAL</TypeOfRedemption>

</methodDetails>

3.3.2.2 Examples of XML for Purchase Requests

3.3.2.2.1 Ukash input values

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xmlns:xsd="http://www.w3.org/2001/XMLSchema">

<soap:Body>

<AccountName>TestAccount</AccountName>

<AccountPIN>TestPIN</AccountPIN>

</AccountDetails>

<StreetLine1>Koningenplein 113</StreetLine1>

<City>Amsterdam</City>

</AddressDetails>

</AmountDetails>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

</BillingDetails>

<FieldName>PaymentId</FieldName>

</CustomDetail>

</CustomMerchantDetails>

</purchaseDetails>

<AccountNumber>633718009 xxxxxx 5236</AccountNumber>

<TypeOfRedemption>CASH_WITHDRAWAL</TypeOfRedemption>

</methodDetails>

</Purchase>

</soap:Body>

</soap:Envelope>

3.3.2.2.2 ClickAndBuy input values

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xmlns:xsd="http://www.w3.org/2001/XMLSchema">

<soap:Body>

<SuccessURL>MerchantSuccessURL</SuccessURL>

<FailureURL>MerchantFailureURL</FailureURL>

<AccountName>TestAccount</AccountName>

<AccountPIN>TestPIN</AccountPIN>

</AccountDetails>

<FirstName>Bridgette</FirstName>

<LastName>Robins</LastName>

<Telephone1_CountryCode>44</Telephone1_CountryCode>

<Telephone1_AreaCode>20</Telephone1_AreaCode>

<Telephone2_CountryCode>0</Telephone2_CountryCode>

<Telephone2_AreaCode>0</Telephone2_AreaCode>

<Email>customer@email.com</Email>

<TypeOfID>PASSPORT</TypeOfID>

</PersonalDetails>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

<StreetLine1>51 Rocky Road</StreetLine1>

<City>London</City>

</AddressDetails>

</AmountDetails>

</BillingDetails>

<AccountName>TestRiskAccount</AccountName>

<AccountPassword>TestRiskPwd</AccountPassword>

<AccountNumber>TestRiskAccountNum</AccountNumber>

</RiskDetails>

<FieldName>PaymentId</FieldName>

</CustomDetail>

</CustomMerchantDetails>

</purchaseDetails>

<CreateRecurring>false</CreateRecurring>

</methodDetails>

</Purchase>

</soap:Body>

</soap:Envelope>

3.3.2.2.3 Click2Pay input values

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xmlns:xsd="http://www.w3.org/2001/XMLSchema">

<soap:Body>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

<SuccessURL>MerchantSuccessURL</SuccessURL>

<FailureURL>MerchantFailureURL</FailureURL>

<AccountName>TestAccount</AccountName>

<AccountPIN>TestPIN</AccountPIN>

</AccountDetails>

<FirstName>Jerry</FirstName>

<LastName>Anderson</LastName>

<Telephone1_CountryCode>44</Telephone1_CountryCode>

<Telephone1_AreaCode>105</Telephone1_AreaCode>

<Telephone2_CountryCode>0</Telephone2_CountryCode>

<Telephone2_AreaCode>0</Telephone2_AreaCode>

<Email>customer@email.com</Email>

<TypeOfID>PASSPORT</TypeOfID>

</PersonalDetails>

<StreetLine1>123 Roman Street</StreetLine1>

<City>London</City>

</AddressDetails>

</AmountDetails>

</BillingDetails>

<AccountName>TestRiskAccount</AccountName>

<AccountPassword>TestRiskPwd</AccountPassword>

<AccountNumber>TestRiskAccountNum</AccountNumber>

</RiskDetails>

<FieldName>PaymentId</FieldName>

</CustomDetail>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

</CustomMerchantDetails>

</purchaseDetails>

<AccountNumber>test.account@gmail.com</AccountNumber>

<AccountPIN>TestMethodPIN</AccountPIN>

</methodDetails>

</Purchase>

</soap:Body>

</soap:Envelope>

3.3.2.2.4 Neteller input values

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xmlns:xsd="http://www.w3.org/2001/XMLSchema">

<soap:Body>

<SuccessURL>MerchantSuccessURL</SuccessURL>

<FailureURL>MerchantFailureURL</FailureURL>

<AccountName>TestAccount</AccountName>

<AccountPIN>TestPIN</AccountPIN>

</AccountDetails>

<FirstName>Caylin</FirstName>

<LastName>Williams</LastName>

<Telephone1_CountryCode>44</Telephone1_CountryCode>

<Telephone1_AreaCode>105</Telephone1_AreaCode>

<Telephone2_CountryCode>0</Telephone2_CountryCode>

<Telephone2_AreaCode>0</Telephone2_AreaCode>

<Email>customer@email.com</Email>

<TypeOfID>PASSPORT</TypeOfID>

</PersonalDetails>

<StreetLine1>78 Praed Street</StreetLine1>

<City>London</City>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

</AddressDetails>

</AmountDetails>

</BillingDetails>

<AccountName>TestRiskAccount</AccountName>

<AccountPassword>TestRiskPwd</AccountPassword>

<AccountNumber>TestRiskAccountNum</AccountNumber>

</RiskDetails>

<FieldName>PaymentId</FieldName>

</CustomDetail>

</CustomMerchantDetails>

</purchaseDetails>

<AccountNumber>TestMethodAccount</AccountNumber>

<AccountPIN>TestMethodPIN</AccountPIN>

</methodDetails>

</Purchase>

</soap:Body>

</soap:Envelope>

3.3.2.2.5 MoneyBookers input values

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xmlns:xsd="http://www.w3.org/2001/XMLSchema">

<soap:Body>

<SuccessURL>MerchantSuccessURL</SuccessURL>

<FailureURL>MerchantFailureURL</FailureURL>

<AccountName>TestAccount</AccountName>

<AccountPIN>TestPIN</AccountPIN>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

</AccountDetails>

<LastName>Bakkers</LastName>

<Telephone1_CountryCode>31</Telephone1_CountryCode>

<Telephone1_AreaCode>20</Telephone1_AreaCode>

<Telephone2_CountryCode>0</Telephone2_CountryCode>

<Telephone2_AreaCode>0</Telephone2_AreaCode>

<Email>customer@email.com</Email>

<TypeOfID>PASSPORT</TypeOfID>

</PersonalDetails>

<StreetLine1>Koningenplein 113</StreetLine1>

<City>Amsterdam</City>

</AddressDetails>

</AmountDetails>

</BillingDetails>

<AccountName>TestRiskAccount</AccountName>

<AccountPassword>TestRiskPwd</AccountPassword>

<AccountNumber>TestRiskAccountNum</AccountNumber>

</RiskDetails>

<FieldName>PaymentId</FieldName>

</CustomDetail>

</CustomMerchantDetails>

</purchaseDetails>

<AccountNumber>test.account@gmail.com</AccountNumber>

</methodDetails>

</Purchase>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

</soap:Body>

</soap:Envelope>

3.3.2.2.6 PaySafeCard input values

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xmlns:xsd="http://www.w3.org/2001/XMLSchema">

<soap:Body>

<SuccessURL>MerchantSuccessURL</SuccessURL>

<FailureURL>MerchantFailureURL</FailureURL>

<AccountName>TestAccount</AccountName>

<AccountPIN>TestPIN</AccountPIN>

</AccountDetails>

<FirstName>Joost</FirstName>

<Telephone1_CountryCode>31</Telephone1_CountryCode>

<Telephone1_AreaCode>30</Telephone1_AreaCode>

<Telephone2_CountryCode>0</Telephone2_CountryCode>

<Telephone2_AreaCode>0</Telephone2_AreaCode>

<Email>customer@email.com</Email>

<TypeOfID>PASSPORT</TypeOfID>

</PersonalDetails>

<StreetLine1>Kerkstraat 78</StreetLine1>

<City>Nieuwegein</City>

</AddressDetails>

</AmountDetails>

</BillingDetails>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

<AccountName>TestRiskAccount</AccountName>

<AccountPassword>TestRiskPwd</AccountPassword>

<AccountNumber>TestRiskAccountNum</AccountNumber>

</RiskDetails>

<FieldName>PaymentId</FieldName>

</CustomDetail>

</CustomMerchantDetails>

</purchaseDetails>

</Purchase>

</soap:Body>

</soap:Envelope>

3.3.2.2.7 NPS input values

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xmlns:xsd="http://www.w3.org/2001/XMLSchema">

<soap:Body>

<SuccessURL>MerchantSuccessURL</SuccessURL>

<FailureURL>MerchantFailureURL</FailureURL>

<AccountName>TestAccount</AccountName>

<AccountPIN>TestPIN</AccountPIN>

</AccountDetails>

<FirstName>William</FirstName>

<LastName>Dickson</LastName>

<Telephone1_CountryCode>1</Telephone1_CountryCode>

<Telephone1_AreaCode>205</Telephone1_AreaCode>

<Telephone2_CountryCode>2</Telephone2_CountryCode>

<Telephone2_AreaCode>305</Telephone2_AreaCode>

<Email>customer@email.com</Email>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

<TypeOfID>PASSPORT</TypeOfID>

</PersonalDetails>

<StreetLine1>51 Rocky Road</StreetLine1>

<City>San Diego</City>

</AddressDetails>

</AmountDetails>

</BillingDetails>

<Name>Holiday House</Name>

<StreetLine1>Greenway Terraces</StreetLine1>

<StreetLine2>210 Bayside Road</StreetLine2>

</AddressDetails>

</AmountDetails>

</ShippingDetails>

<AccountName>TestRiskAccount</AccountName>

<AccountPassword>TestRiskPwd</AccountPassword>

<AccountNumber>TestRiskAccountNum</AccountNumber>

</RiskDetails>

<FieldName>PaymentId</FieldName>

</CustomDetail>

</CustomMerchantDetails>

</purchaseDetails>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

</Purchase>

</soap:Body>

</soap:Envelope>

3.3.2.2.8 eNETS input values

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

mlns:xsd="http://www.w3.org/2001/XMLSchema">

<soap:Body>

<SuccessURL>MerchantSuccessURL</SuccessURL>

<FailureURL>MerchantFailureURL</FailureURL>

<AccountName>TestAccount</AccountName>

<AccountPIN>TestPIN</AccountPIN>

</AccountDetails>

<FirstName>Betty</FirstName>

<LastName>Kheng Sing Peh</LastName>

<Telephone1_CountryCode>65</Telephone1_CountryCode>

<Telephone1_AreaCode>6</Telephone1_AreaCode>

<Telephone2_CountryCode>0</Telephone2_CountryCode>

<Telephone2_AreaCode>0</Telephone2_AreaCode>

<Email>customer@email.com</Email>

<TypeOfID>PASSPORT</TypeOfID>

</PersonalDetails>

<StreetLine1>1094 Lower Delta Road</StreetLine1>

<StreetLine2>#07-01 Motorway Building</StreetLine2>

<City>Singapore</City>

</AddressDetails>

</AmountDetails>

</BillingDetails>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

<StreetLine1>Waterview Park</StreetLine1>

<StreetLine2>Century City</StreetLine2>

</AddressDetails>

</AmountDetails>

</ShippingDetails>

<AccountName>TestRiskAccount</AccountName>

<AccountPassword>TestRiskPwd</AccountPassword>

<AccountNumber>TestRiskAccountNum</AccountNumber>

</RiskDetails>

<FieldName>PaymentId</FieldName>

</CustomDetail>

</CustomMerchantDetails>

</purchaseDetails>

</Purchase>

</soap:Body>

</soap:Envelope>

3.3.2.2.9 OneClick input values

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

mlns:xsd="http://www.w3.org/2001/XMLSchema">

<soap:Body>

<SuccessURL>MerchantSuccessURL</SuccessURL>

<FailureURL>MerchantFailureURL</FailureURL>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

<AccountName>TestAccount</AccountName>

<AccountPIN>TestPIN</AccountPIN>

</AccountDetails>

<FirstName>Betty</FirstName>

<LastName>Kheng Sing Peh</LastName>

<Telephone1_CountryCode>65</Telephone1_CountryCode>

<Telephone1_AreaCode>6</Telephone1_AreaCode>

<Telephone2_CountryCode>0</Telephone2_CountryCode>

<Telephone2_AreaCode>0</Telephone2_AreaCode>

<Email>customer@email.com</Email>

<TypeOfID>PASSPORT</TypeOfID>

</PersonalDetails>

<StreetLine1>1094 Lower Delta Road</StreetLine1>

<StreetLine2>#07-01 Motorway Building</StreetLine2>

<City>Singapore</City>

</AddressDetails>

</AmountDetails>

</BillingDetails>

<StreetLine1>Waterview Park</StreetLine1>

<StreetLine2>Century City</StreetLine2>

</AddressDetails>

</AmountDetails>

</ShippingDetails>

<AccountName>TestRiskAccount</AccountName>

<AccountPassword>TestRiskPwd</AccountPassword>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

<AccountNumber>TestRiskAccountNum</AccountNumber>

</RiskDetails>

<FieldName>PaymentId</FieldName>

</CustomDetail>

</CustomMerchantDetails>

</purchaseDetails>

<ServiceType>IDEAL</ServiceType>

</methodDetails>

</Purchase>

</soap:Body>

</soap:Envelope>

3.3.2.2.10 iDeal input values

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xmlns:xsd="http://www.w3.org/2001/XMLSchema">

<soap:Body>

<SuccessURL>MerchantSuccessURL</SuccessURL>

<FailureURL>MerchantFailureURL</FailureURL>

<AccountName>TestAccount</AccountName>

<AccountPIN>TestPIN</AccountPIN>

</AccountDetails>

<FirstName>Wolfgang</FirstName>

<LastName>Middendorp</LastName>

<Telephone1_CountryCode>49</Telephone1_CountryCode>

<Telephone1_AreaCode>10</Telephone1_AreaCode>

<Email>customer@email.com</Email>

</PersonalDetails>

<StreetLine1>Berliner Straße 213</StreetLine1>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

<City>Berlin</City>

</AddressDetails>

</AmountDetails>

</BillingDetails>

<AccountName>TestRiskAccount</AccountName>

<AccountPassword>TestRiskPwd</AccountPassword>

<AccountNumber>TestRiskAccountNum</AccountNumber>

</RiskDetails>

<FieldName>PaymentId</FieldName>

</CustomDetail>

</CustomMerchantDetails>

</purchaseDetails>

</methodDetails>

</Purchase>

</soap:Body>

</soap:Envelope>

3.3.2.2.11 InstaDebit input values

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xmlns:xsd="http://www.w3.org/2001/XMLSchema">

<soap:Body>

<AccountName>TestAccount</AccountName>

<AccountPIN>TestPIN</AccountPIN>

</AccountDetails>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

<FirstName>Wolfgang</FirstName>

<LastName>Middendorp</LastName>

<Telephone1_CountryCode>49</Telephone1_CountryCode>

<Telephone1_AreaCode>10</Telephone1_AreaCode>

<Email>customer@email.com</Email>

<SSN/>

</PersonalDetails>

<Name>Wolfgang Middendorp</Name>

<StreetLine1>Berliner Straße 213</StreetLine1>

<City>Berlin</City>

</AddressDetails>

</AmountDetails>

</BillingDetails>

<AccountName>TestRiskAccount</AccountName>

<AccountPassword>TestRiskPwd</AccountPassword>

<AccountNumber>TestRiskAccountNum</AccountNumber>

</RiskDetails>

<FieldName>PaymentId</FieldName>

</CustomDetail>

</CustomMerchantDetails>

</purchaseDetails>

</Purchase>

</soap:Body>

</soap:Envelope>

3.3.2.2.12 ExperCash input values

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xmlns:xsd="http://www.w3.org/2001/XMLSchema">

<soap:Body>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

<AccountName>TestAccount</AccountName>

<AccountPIN>TestPIN</AccountPIN>

</AccountDetails>

<FirstName>Wolfgang</FirstName>

<LastName>Middendorp</LastName>

<Telephone1_CountryCode>49</Telephone1_CountryCode>

<Telephone1_AreaCode>10</Telephone1_AreaCode>

<Email>customer@email.com</Email>

</PersonalDetails>

<StreetLine1>Berliner Straße 213</StreetLine1>

<City>Berlin</City>

</AddressDetails>

</AmountDetails>

</BillingDetails>

<AccountName>TestRiskAccount</AccountName>

<AccountPassword>TestRiskPwd</AccountPassword>

<AccountNumber>TestRiskAccountNum</AccountNumber>

</RiskDetails>

<FieldName>PaymentId</FieldName>

</CustomDetail>

</CustomMerchantDetails>

</purchaseDetails>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

</methodDetails>

</Purchase>

</soap:Body>

</soap:Envelope>

3.3.2.2.13 ElectronicCheck input values

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xmlns:xsd="http://www.w3.org/2001/XMLSchema">

<soap:Body>

<TransactionId>T10_LENFRUCVQVQ1</TransactionId>

<SuccessURL>MerchantSuccessURL</SuccessURL>

<FailureURL>MerchantFailureURL</FailureURL>

<AccountName>TestAccount</AccountName>

<AccountPIN>TestPIN</AccountPIN>

</AccountDetails>

<FirstName>Candy</FirstName>

<LastName>Daniels</LastName>

<Telephone1_CountryCode>1</Telephone1_CountryCode>

<Telephone1_AreaCode>212</Telephone1_AreaCode>

<Telephone2_CountryCode>0</Telephone2_CountryCode>

<Telephone2_AreaCode>0</Telephone2_AreaCode>

<Email>Candy.daniels@hotmail.com</Email>

</PersonalDetails>

<StreetLine1>88 High Street</StreetLine1>

<StreetLine2>Faulty Towers</StreetLine2>

</AddressDetails>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

</AmountDetails>

</BillingDetails>

<FieldName>PaymentId</FieldName>

</CustomDetail>

</CustomMerchantDetails>

</purchaseDetails>

<AccountType>COMMERCIAL_CHECK</AccountType>

<TypeofAction>AUTH_AND_CAPTURE</TypeofAction>

</methodDetails>

</Purchase>

</soap:Body>

</soap:Envelope>

3.3.2.2.14 Amazon input values

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xmlns:xsd="http://www.w3.org/2001/XMLSchema">

<soap:Body>

<SuccessURL>MerchantSuccessURL</SuccessURL>

<FailureURL>MerchantFailureURL</FailureURL>

<AccountName>Test_DataCash</AccountName>

<AccountPIN>xxxxxxxxxxx</AccountPIN>

</AccountDetails>

<FirstName>Wolfgang</FirstName>

<LastName>Middendorp</LastName>

<Telephone1_CountryCode>49</Telephone1_CountryCode>

<Telephone1_AreaCode>10</Telephone1_AreaCode>

<Telephone2_CountryCode>0</Telephone2_CountryCode>

<Telephone2_AreaCode>0</Telephone2_AreaCode>

<Email>test@hotmail.com</Email>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

</PersonalDetails>

<StreetLine1>Berliner Straße 213</StreetLine1>

<City>Berlin</City>

</AddressDetails>

</AmountDetails>

</BillingDetails>

<StreetLine1>Blue Moon Terraces</StreetLine1>

<StreetLine2>254 Paddington Road</StreetLine2>

<City>London</City>

</AddressDetails>

</AmountDetails>

</ShippingDetails>

<AccountName>GamingTest</AccountName>

<AccountPassword>password123</AccountPassword>

<AccountNumber>danger</AccountNumber>

</RiskDetails>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

</LineItem>

</LineItems>

</purchaseDetails>

<AmazonContractID>amzn1.contract.1.1.1.8a34d7a8db9a4e8be2b25d9e2e67fff1

</AmazonContractID>

</methodDetails>

</Purchase>

</soap:Body>

</soap:Envelope>

3.3.2.2.15 WebMoney input values

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xmlns:xsd="http://www.w3.org/2001/XMLSchema">

<soap:Body>

<SuccessURL>MerchantSuccessURL</SuccessURL>

<FailureURL>MerchantFailureURL</FailureURL>

<AccountName>Test_DataCash</AccountName>

<AccountPIN>xxxxxxxxxxx</AccountPIN>

</AccountDetails>

<FirstName>Jerry</FirstName>

<LastName>Anderson</LastName>

<Telephone1_CountryCode>44</Telephone1_CountryCode>

<Telephone1_AreaCode>105</Telephone1_AreaCode>

<Telephone2_CountryCode>0</Telephone2_CountryCode>

<Telephone2_AreaCode>0</Telephone2_AreaCode>

<Email>candice_williams@hotmail.com</Email>

<TypeOfID>PASSPORT</TypeOfID>

</PersonalDetails>

<Name>David Williams</Name>

<StreetLine1>123 Roman Street</StreetLine1>

<City>London</City>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

</AddressDetails>

</AmountDetails>

</BillingDetails>

<AccountNumber>danger</AccountNumber>

</RiskDetails>

</purchaseDetails>

</Purchase>

</soap:Body>

</soap:Envelope>

3.3.2.2.16 Offline Bank Transfer input values

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

mlns:xsd="http://www.w3.org/2001/XMLSchema">

<soap:Body>

<SuccessURL>MerchantSuccessURL</SuccessURL>

<FailureURL>MerchantFailureURL</FailureURL>

<AccountName>TestAccount</AccountName>

<AccountPIN>TestPIN</AccountPIN>

</AccountDetails>

<FirstName>Betty</FirstName>

<LastName>Kheng Sing Peh</LastName>

<Telephone1_CountryCode>65</Telephone1_CountryCode>

<Telephone1_AreaCode>6</Telephone1_AreaCode>

<Telephone2_CountryCode>0</Telephone2_CountryCode>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

<Telephone2_AreaCode>0</Telephone2_AreaCode>

<Email>customer@email.com</Email>

<TypeOfID>PASSPORT</TypeOfID>

</PersonalDetails>

<StreetLine1>1094 Lower Delta Road</StreetLine1>

<StreetLine2>#07-01 Motorway Building</StreetLine2>

<City>Singapore</City>

</AddressDetails>

</AmountDetails>

</BillingDetails>

<StreetLine1>Waterview Park</StreetLine1>

<StreetLine2>Century City</StreetLine2>

</AddressDetails>

</AmountDetails>

</ShippingDetails>

<FieldName>PaymentId</FieldName>

</CustomDetail>

</CustomMerchantDetails>

</purchaseDetails>

<ServiceType>LA_CAXIA</ServiceType>

</methodDetails>

</Purchase>

</soap:Body>

</soap:Envelope>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

3.3.2.2.17 POLi Input Values

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xmlns:xsd="http://www.w3.org/2001/XMLSchema">

<soap:Body>

<SuccessURL>MerchantSuccessURL</SuccessURL>

<FailureURL>MerchantFailureURL</FailureURL>

<AccountName>TestAccount</AccountName>

<AccountPIN>TestPIN</AccountPIN>

</AccountDetails>

</AmountDetails>

</BillingDetails>

</purchaseDetails>

</methodDetails>

</Purchase>

</soap:Body>

</soap:Envelope>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

3.3.2.2.18 AliPay Input Values

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xmlns:xsd="http://www.w3.org/2001/XMLSchema">

<soap:Body>

<SuccessURL>MerchantSuccessURL</SuccessURL>

<FailureURL>MerchantFailureURL</FailureURL>

<AccountName>TestAccount</AccountName>

<AccountPIN>TestPIN</AccountPIN>

</AccountDetails>

</AmountDetails>

</BillingDetails>

</purchaseDetails>

<Subject>Test Subject</Subject>

</methodDetails>

</Purchase>

</soap:Body>

</soap:Envelope>

3.3.2.3 Schema elements for Purchase Response

In this section, the fields that can be presented with Purchase transaction Responses

will be presented along with example XML for those fields.

The top-level XML element is the Response element. This will be followed by the Event

element, with the Purchase method’s response details inside that, in the Purchase

complex structure.

Note that various responses will result in various XML formats being returned -

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

the following list contains some of the response fields, but you should refer to the

XML samples below and in Section 3.3.2.5 for further information.

 Response – see section 3.3.1.2.3

o Event – see section 3.3.1.2.2

 Purchase – see section 3.3.2.3.4

 PaymentMethod – see section 3.3.2.1.27

o PaymentMethod – specific fields

 Error – see section 3.3.1.2.1

 RiskResult – see section 3.3.2.3.1

3.3.2.3.1 RiskResult

The result of Risk Screening will be displayed here.

Element Name:

RiskResult

Position

Response.Event.Purchase

Children

Yes

Attributes

No

Elements of RiskResult

Element Name

Description

Data type /

Limitations

StatusCode

This returns the Risk Status Code.

Short

StatusDescription

This is a text field used to give a short

description of the Risk Status Code.

String (255)

Example XML for RiskResult complex elements

</RiskResult>

3.3.2.3.2 Redirect transaction specific elements

A variety of elements will appear in various positions, to serve different functions

during a redirect transaction. Please refer to the individual “Position” descriptions in the

following sections, for more information on all the Redirect details.

Redirect transaction responses are characterized with “REDIRECT” in the Status field.

These Purchase Payment Methods are categorized as Redirect payment methods:

 A7

 BU

 EN

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

 EV (Giropay & Sofort)

 I3

 IN

 MB

 NS

 OC

 PF

 P5

 W3

For all non-redirect transactions except O3, these fields are not applicable. O3 makes

use of the RecommendedDisplayMessage only.

Element name:

RecommendedDisplayMessage

Position

Response.Event.Purchase.PaymentMethod

See section

3.3.2.3.3

Element name

RedirectURL

Position

Response.Event.Purchase

See section

3.3.2.3.4

Element name

PopupBrowser

Position

Response.Event.Purchase

See section

3.3.2.3.4

Element name

RedirectParameters

Position

Response.Event.Purchase

See section

3.3.2.3.4

Element name

RedirectParameter

Position

Response.Event.Purchase.RedirectParameters

See section

3.3.2.3.4

3.3.2.3.3 PaymentMethod

The details involved in the specific Payment Method of this transaction are displayed

here. The top-level element “PaymentMethod” will contain the payment method for the

transaction, while the sub elements will contain the rest of the details.

Element Name:

PaymentMethod

Position

Response.Event.Purchase

Children

Yes

Attributes

Yes

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Attributes involved in the PaymentMethod element

Attribute Name

Located in which Element

Description

Data type /

Limitations

name

PaymentMethod

Indicates the

Payment Method

(Processor) involved

in this transaction.

Refer to Appendix 7

for the possible

values.

String

isLeftToRight

RecommendedDisplayMessage

Indicates the

direction of the

language used in the

recommended display

message.

Boolean

ONLY relevant

to Redirect

transactions.

Elements of PaymentMethod

Element Name

Description

Data type /

Limitations

ReferenceId

This is a value returned by the

processor to uniquely identify the

transaction.

String (50)

NOT relevant to

Redirect

transactions.

ResponseCode

This is a return code, which gets

returned by the processor.

String (10)

NOT relevant to

Redirect

transactions.

ResponseDescription

This is a text field used to give a

short text description of the

response code from the processor.

String (255)

NOT relevant to

Redirect

transactions.

RecommendedDisplayMessage

This field contains the recommended

display message that can be

displayed to the consumer.

The RecommendedDisplayMessage

will be returned in the language

which was passed through in

Language field of original

transaction.

This is dependent on whether the

language is supported by APG. If the

language is not supported, the

message will default to English.

String (1000)

ONLY relevant

to Redirect

transactions.

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

AmountReference

This is a value returned by the

Ukash processor to uniquely identify

the settlement amount transaction.

String (50)

ONLY relevant

to Retrieve

Settlement

Values

transactions

(See section

3.3.5)

Payment-method specific

elements

Note: More fields could be returned here, this is

dependent on the payment method. Refer to the XML

Samples for details (see section 3.3.2.5)

CustomMerchantDetails

The merchant custom fields and values are returned in

the element.

The custom fields and values will be returned as follows:

<FieldName>FieldValue</FieldValue>

Examples of XML for PaymentMethod complex elements (These examples

are specifically for a successfully completed PaySafeCard transaction, with

the payment method specific details displayed in italics. Example 1 is the

redirect XML returned to the Merchant during the initial phase of the

transaction, while Example 2 is the final result XML at the end of the

transaction.)

1:

<RecommendedDisplayMessage isRightToLeft="False">Please wait while

you are being redirected to the PaySafeCard

website.</RecommendedDisplayMessage>

</PaymentMethod>

2:

<ResponseDescription>Consumed</ResponseDescription>

</SerialNumber>

</SerialNumbers>

</PaymentMethod>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

3.3.2.3.4 Purchase Response

The results of a Purchase transaction will be returned in this complex structure. Note

that the details depend on the Payment Method involved – this is a very dynamic

complex structure that can take on a variety of shapes, depending on the scenario.

Element Name:

Purchase

Position

Response.Event

Children

Yes

Attributes

Yes

Attributes involved in the Purchase element

Attribute Name

Located in which

Element

Description

Data type /

Limitations

DPGReferenceId

Purchase

The DPGReferenceId is a unique

APG transaction identifier which is

generated by the APG for each

merchant transaction.

Long

TransactionId

Purchase

This will return the original

TransactionId that the Merchant

sent through. This is for

informational purposes only.

String (16)

CurrencyCode

Amount

This is the transaction currency.

Please refer to Appendix 10.

Short

Exponent

Amount

This is the transaction currency

exponent. Please refer to

Appendix 10.

Short

CurrencyCode

SaleAmount

This is the transaction currency.

Please refer to Appendix 10.

Short

Exponent

SaleAmount

This is the transaction currency

exponent. Please refer to

Appendix 10.

Short

Method

RedirectParameters

Indicates how the redirect

parameters should be sent to the

Processor. See section 3.3.2.5.

String

“GET” or

“POST”

contentType

RedirectParameters

Indicates how the redirect

parameters should be sent to the

Processor. See section 3.3.2.5.

String

Name

RedirectParameter

“Name” field of the specific

Redirect parameter name-value

pair.

String

Value

RedirectParameter

“Value” field of the specific

Redirect parameter name-value

pair.

String

Elements of Purchase

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Element Name

Description

Data type /

Limitations

Purchase

Top-level XML element indicating a Purchase

transaction - the DPGReferenceId and TransactionId

for the transaction are also returned as attributes of

this field – refer to the Attributes table above for more

information.)

PaymentMethod

See section 3.3.2.3.3

Status

This is the response, which

indicates if the transaction was

accepted, or not at the processor.

See Appendix 6 for possible

response messages.

String (20)

Error

See section 3.3.1.2.1. This element will appear in the

Purchase XML if the Status = “ERROR”.

Amount

This field contains the amount

taken from the client’s account at

the financial institution. The field

type is a numeric value in cents.

(The currency and exponent for

the amount are also returned as

attributes of this field – refer to the

Attributes table above for more

information.)

Applicable to all Payment Types

Int

SaleAmount

This field contains the amount

credited to the merchant account

in the currency provided within the

SaleAmount field in the merchant

request. If no SaleAmount values

were provided within the merchant

request, the amount returned will

be provided in the currency of the

Amount field within the merchant

request.

Currently available for the

following Payment Methods:

OC

Int

RiskResult

See section 3.3.2.3.1

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

RecommendedClientMessage

This field contains the

recommended client message that

can be displayed to the consumer.

A list of these messages will be

detailed in the Product Document.

In certain instances, the exact

nature of the error will be hidden

from the consumer e.g. error

relating to merchant account

details. The true nature of the

error can always be found in the

ResponseDescription or Error

Description response fields.

Note: The

RecommendedClientMessage field

might contain end-of-line

characters. Merchants should

design their front-end systems in

such a way that the end-of-line

characters are correctly displayed

to end-users.

For example, if an HTML page is

used as the display method in the

front-end system, the merchant

must replace the end-of-line

characters in the

RecommendedClientMessage field

with the appropriate <BR> tags,

otherwise the HTML front-end will

not display the appropriate line

breaks correctly.

Alternatively, the contents of the

RecommendedClientMessage can

be included in <PRE> tags.

The RecommendedClientMessage

will be returned in the language

which was passed through in

Language field of original

transaction. This is dependent on

whether the language is supported

by APG. If the language is not

supported, the message will

default to English.

String (1000)

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

RecommendedDisplayMessage

This field contains the

recommended display message

that can be displayed to the

consumer.

The RecommendedDisplayMessage

will be returned in the language

which was passed through in

Language field of original

transaction.

This is dependent on whether the

language is supported by APG. If

the language is not supported, the

message will default to English.

Currently available for the

following Payment Methods:

 BU

 EN

 EV (Only for Giropay and

Sofort)

 I3

 IN

 MB

 NS

 O3

 OC

 PF

 W3

String (1000)

RedirectURL

URL to which the merchant needs

to redirect the consumer.

This value might also contain

redirect parameters. In this

scenario, the RedirectParameters

element would typically not contain

any RedirectParameter child

elements.

String (1000)

ONLY relevant

to Redirect

transactions

PopupBrowser

Merchant needs to popup a new

browser depending on the value in

this field.

‘true’ – Popup a new browser and

then redirect to the website

specified in the RedirectURL field

in the popup browser.

‘false’ – Redirect to the website

specified in the RedirectURL in the

current browser session.

Boolean

ONLY relevant

to Redirect

transactions

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

RedirectParameters

A collection of RedirectParameters,

which represent all the information

necessary to successfully redirect

the consumer to the RedirectURL.

(The method and contentType are

also returned as attributes of this

field – refer to the Attributes table

above for more information.)

RedirectParameter

(see below)

ONLY relevant

to Redirect

transactions

RedirectParameter

This Element contains information

in its Attributes, which the

merchant needs to transform into

form variables and post them to

the RedirectURL (please refer to

the Attributes table above for more

information).

If the RedirectURL element

already contains the necessary

values, then the

RedirectParameters element

would typically not contain any

RedirectParameter child

elements.

String name-value

pairs (contained

as Attributes)

ONLY relevant

to Redirect

transactions

Examples of XML for Purchase complex elements

Please refer to section 3.3.2.5 for examples per Payment Method.

3.3.2.4 Interpreting the Purchase Responses

There are various types of possible responses that can be returned from the APG to the

Merchant. These include:

 Successful transaction

 Unsuccessful transaction

 Redirect transaction

 Event notification

Refer to section 2.1.1.3 for examples.

The APG can return multiple responses per transaction, and as a result the merchant

needs to analyze these and perform the appropriate action. Appendix 6 details the

various responses. The Status field will indicate the status of the transaction. The

merchant should only credit the consumer’s account when the Status=AUTHORISED, in

all other cases the merchant should not credit the consumer’s account.

In the case whereby the Status = REDIRECT, then the following needs to happen:

 Merchant to transform the RedirectParameter attributes into form variables

 Use the RedirectURL as the action of the form

 Display the suggested RecommendedDisplayMessage to the consumer

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

 Depending on the redirect the form variables needs to be posted or otherwise

the Query string parameters need to be appended to the url before the

consumer is redirected.

Here is an example of the Redirect response and parameters that the APG returns to

the merchant:

Example of Redirect Response

<Event>

<RecommendedDisplayMessage isRightToLeft="False">Please wait

while you are being redirected to the Envoy OneClick

website.</RecommendedDisplayMessage>

</PaymentMethod>

<Status>REDIRECT</Status>

</RedirectURL>

<PopupBrowser>false</PopupBrowser>

<RedirectParameters method="POST" contentType="application/x-

www-form-urlencoded">

<RedirectParameter name="customerRef"

value="A99_090909141714"/>

</RedirectParameters>

</RiskResult>

</Purchase>

</Event>

</Response>

Below is an example of a form the merchant needs to post to the Processor, following

from the Response XML example above. The redirect can be done by creating a form

and then using java script to submit it.

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

<form method=”post” Action=” https://test.envoytransfers.com ”

enctype="application/x-www-form-urlencoded">

</form>

The consumer will then authenticate themselves on the Processor’s website, and then

they will be redirected to the APG Redirect Solution. At this stage the transaction will

be processed further in the APG, or be passed onto the processor.

Once processing has completed, the APG will send a notification of the transaction

result to the merchant’s Event_URL. On signing-up to the APG system, the merchant

would have provided DataCash with the Event_URL. Merchant should expect to receive

all out-of-process event notifications at this URL. Refer to section 3.3.2.5 for examples

of event notifications (any of the responses, excluding Redirect responses, can be sent

as event notifications).

3.3.2.5 Examples of XML for Purchase Responses

3.3.2.5.1 Ukash Return values

3.3.2.5.1.1 AUTHORISED

<Event>

<ResponseDescription>Accepted</ResponseDescription>

</PaymentMethod>

<Status>AUTHORISED</Status>

<![CDATA[Transaction Approved ]]>

</Message>

</RiskResult>

<RecommendedClientMessage><![CDATA[Your transaction has been

processed successfully.]]></RecommendedClientMessage>

</Purchase>

</Event>

</Response>

3.3.2.5.1.2 REFUSED

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

<Event>

<ResponseDescription>Declined</ResponseDescription>

</PaymentMethod>

<Status>REFUSED</Status>

</RiskResult>

<RecommendedClientMessage><![CDATA[Your request could not be

completed. Please contact merchant customer service for more

information.]]></RecommendedClientMessage>

</Purchase>

</Event>

</Response>

3.3.2.5.1.3 ERROR

<Event>

<ResponseDescription>Failed</ResponseDescription>

</PaymentMethod>

<Status>ERROR</Status>

<Error>

<Description>Invalid Login and/or BrandID</Description>

</Error>

</RiskResult>

<RecommendedClientMessage><![CDATA[Your request could not be

completed. Please contact merchant customer service for more

information.]]></RecommendedClientMessage>

</Purchase>

</Event>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

</Response>

3.3.2.5.2 Click2Pay return values

3.3.2.5.2.1 AUTHORISED

<Event>

<ResponseDescription>Transaction is

Acknowledged</ResponseDescription>

<PaymentType>FUNDS</PaymentType>

</PaymentMethod>

<Status>AUTHORISED</Status>

</RiskResult>

<RecommendedClientMessage><![CDATA[Your transaction has been

processed successfully.]]></RecommendedClientMessage>

</Purchase>

</Event>

</Response>

3.3.2.5.2.2 REFUSED

<Event>

<ResponseDescription>You have provided invalid CLICK2PAY user

data or the account is not active. Please check and try again.

If the problem persists, please contact our helpdesk at

service@click2pay.com.</ResponseDescription>

</PaymentMethod>

<Status>REFUSED</Status>

</RiskResult>

<RecommendedClientMessage><![CDATA[Your request could not be

completed. Please contact merchant customer service for more

information.]]></RecommendedClientMessage>

</Purchase>

</Event>

</Response>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

3.3.2.5.2.3 ERROR

<Event>

<ResponseDescription>The supplied CLICK2PAY UserName is wrong.

Please check and try again. If the problem should still exist,

please contact our customer service at

service@click2pay.com.</ResponseDescription>

</PaymentMethod>

<Status>ERROR</Status>

<Error>

<Code/>

</Error>

</RiskResult>

<RecommendedClientMessage><![CDATA[Your request could not be

completed. Please contact merchant customer service for more

information.]]></RecommendedClientMessage>

</Purchase>

</Event>

</Response>

3.3.2.5.3 ClickAndBuy return values

3.3.2.5.3.1 AUTHORISED

<Event>

<ResponseDescription>success</ResponseDescription>

</PaymentMethod>

<Status>AUTHORISED</Status>

</RiskResult>

<RecommendedClientMessage><![CDATA[Your transaction has been

processed successfully.]]></RecommendedClientMessage>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

</Purchase>

</Event>

</Response>

3.3.2.5.3.2 PENDING

<Event>

<ResponseCode>CREATED/PAYMENT_PENDING/BOOKED_OUT/BOOKED_OUT</ResponseCode>

<ResponseDescription>Transaction Pending</ResponseDescription>

</PaymentMethod>

<Status>PENDING</Status>

</RiskResult>

<RecommendedClientMessage><![CDATA[Your transaction has been

processed successfully.]]></RecommendedClientMessage>

</Purchase>

</Event>

</Response>

3.3.2.5.3.3 ERROR

<Event>

<ResponseCode>EXPIRED/ABORTED</ResponseCode>

<ResponseDescription>Transaction

Unsuccessful</ResponseDescription> <CreationDateTime>2000-01-

20 12:00:00</CreationDateTime>

</PaymentMethod>

<Status>ERROR</Status>

</RiskResult>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

<RecommendedClientMessage><![CDATA[Your transaction has been

processed successfully.]]></RecommendedClientMessage>

</Purchase>

</Event>

</Response>

3.3.2.5.3.4 REFUSED

<Event>

<ResponseCode>DECLINED</ResponseCode>

<ResponseDescription>Transaction Refused</ResponseDescription>

</PaymentMethod>

<Status>REFUSED</Status>

</RiskResult>

<RecommendedClientMessage><![CDATA[Your transaction has been

processed successfully.]]></RecommendedClientMessage>

</Purchase>

</Event>

</Response>

3.3.2.5.3.5 CANCELLED

<Event>

<ResponseCode>CANCELLED</ResponseCode>

<ResponseDescription>Transaction

Cancelled</ResponseDescription> <CreationDateTime>2000-01-20

12:00:00</CreationDateTime>

</PaymentMethod>

<Status>CANCELLED</Status>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

</RiskResult>

<RecommendedClientMessage><![CDATA[Your transaction has been

processed successfully.]]></RecommendedClientMessage>

</Purchase>

</Event>

</Response>

3.3.2.5.3.6 REFUNDED

<Event>

<ResponseCode>REFUNDED</ResponseCode>

<ResponseDescription>Transaction Refunded</ResponseDescription>

</PaymentMethod>

<Status>REFUNDED</Status>

</RiskResult>

<RecommendedClientMessage><![CDATA[Your transaction has been

processed successfully.]]></RecommendedClientMessage>

</Purchase>

</Event>

</Response>

3.3.2.5.3.7 REDIRECT

<Event>

<RecommendedDisplayMessage isRightToLeft="False">Please wait

while you are being redirected to the ClickAndBuy

website.</RecommendedDisplayMessage>

</PaymentMethod>

<Status>REDIRECT</Status>

<RedirectURL><![CDATA[https://checkout.clickandbuy.com/checkout?

tx=8824001&s=399275BC6DBBEE60&h=9EE5252B5B23E902443771

F301E2C6D26E48709F]]></RedirectURL>

<PopupBrowser>false</PopupBrowser>

<RedirectParameters method="GET" contentType="application/x-www-

form-urlencoded">

</RedirectParameters>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

</RiskResult>

</Purchase>

</Event>

</Response>

3.3.2.5.4 Neteller return values

3.3.2.5.4.1 AUTHORISED

<Event>

<Email>customer@email.com</Email>

</PaymentMethod>

<Status>AUTHORISED</Status>

</RiskResult>

<RecommendedClientMessage><![CDATA[Your transaction has been

processed successfully.]]></RecommendedClientMessage>

</Purchase>

</Event>

</Response>

3.3.2.5.4.2 ERROR

<Event>

</PaymentMethod>

<Status>ERROR</Status>

<Error>

<Description>The Account ID or Secure ID you entered is not

valid. Please enter your correct account

information.</Description>

</Error>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

</RiskResult>

<RecommendedClientMessage><![CDATA[Your request could not be

completed. Please contact merchant customer service for more

information.]]></RecommendedClientMessage>

</Purchase>

</Event>

</Response>

3.3.2.5.5 MoneyBookers return values

3.3.2.5.5.1 AUTHORISED

<Event>

<Email>test.account@gmail.com</Email>

<AccountNumber>TestMethodAccount</AccountNumber>

</PaymentMethod>

<Status>AUTHORISED</Status>

</RiskResult>

<RecommendedClientMessage><![CDATA[Uw transactie is

geslaagd.]]></RecommendedClientMessage>

</Purchase>

</Event>

</Response>

3.3.2.5.5.2 CANCELLED

<Event>

</PaymentMethod>

<Status>CANCELLED</Status>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

</RiskResult>

<RecommendedClientMessage><![CDATA[Uw transactie is op uw verzoek

geannuleerd. Neem a.u.b. contact op met de verkoopklantenservice

voor nadere informatie.]]></RecommendedClientMessage>

</Purchase>

</Event>

</Response>

3.3.2.5.5.3 REDIRECT

<Event>

<RecommendedDisplayMessage isRightToLeft="False">Even geduld

graag. U wordt doorgeleid naar de MoneyBookers

website.</RecommendedDisplayMessage>

</PaymentMethod>

<Status>REDIRECT</Status>

<RedirectURL><![CDATA[https://www.moneybookers.com/app/payment.pl?

sid=fcce7ddb4f5a162b429e2ed0a206132]]></RedirectURL>

<PopupBrowser>false</PopupBrowser>

<RedirectParameters method="GET" contentType="application/x-www-

form-urlencoded"/>

</RiskResult>

</Purchase>

</Event>

</Response>

3.3.2.5.5.4 PENDING

<Event>

<Email>test.account@gmail.com</Email>

<AccountNumber>TestMethodAccount</AccountNumber>

</PaymentMethod>

<Status>PENDING</Status>

</RiskResult>

<RecommendedClientMessage><![CDATA[Your request could not entirely

be completed. Please check your account later for an updated

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

status. You may also contact merchant customer service for more

information.]]></RecommendedClientMessage>

</Purchase>

</Event>

</Response>

3.3.2.5.6 PaySafeCard return values

3.3.2.5.6.1 AUTHORISED

<Event>

<ResponseDescription>Consumed</ResponseDescription>

</SerialNumber>

</SerialNumbers>

</PaymentMethod>

<Status>AUTHORISED</Status>

</RiskResult>

<RecommendedClientMessage><![CDATA[Uw transactie is

geslaagd.]]></RecommendedClientMessage>

</Purchase>

</Event>

</Response>

3.3.2.5.6.2 REFUSED

<Event>

<ResponseDescription>Closed</ResponseDescription>

</PaymentMethod>

<Status>REFUSED</Status>

</RiskResult>

<RecommendedClientMessage><![CDATA[Uw verzoek kan niet afgehandeld

worden. Neem a.u.b. contact op met de verkoopklantenservice voor

nadere informatie.]]></RecommendedClientMessage>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

</Purchase>

</Event>

</Response>

3.3.2.5.6.3 REDIRECT

<Event>

<RecommendedDisplayMessage isRightToLeft="False">Even geduld

graag. U wordt doorgeleid naar de PaySafeCard

website.</RecommendedDisplayMessage>

</PaymentMethod>

<Status>REDIRECT</Status>

<RedirectURL><![CDATA[https://customer.test.at.paysafecard.com/psc

customer/GetCustomerPanelServlet?cid=0&

currency=EUR&

mid=MerchAccount&

mtid=A99_091104101009&

amount=3.50&

language=nl]]></RedirectURL>

<PopupBrowser>false</PopupBrowser>

<RedirectParameters method="GET" contentType="application/x-www-

form-urlencoded"/>

</RiskResult>

</Purchase>

</Event>

</Response>

3.3.2.5.7 NPS return values

3.3.2.5.7.1 AUTHORISED

<Event>

</PaymentMethod>

<Status>AUTHORISED</Status>

</RiskResult>

<RecommendedClientMessage><![CDATA[Your transaction has been

processed successfully.]]></RecommendedClientMessage>

</Purchase>

</Event>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

</Response>

3.3.2.5.7.2 REDIRECT

<Event>

<RecommendedDisplayMessage isRightToLeft="False">Please wait

while you are being redirected to NPS website. You will be

given opportunity to choose your Chinese banking

institution</RecommendedDisplayMessage>

</PaymentMethod>

<Status>REDIRECT</Status>

<RedirectURL><![CDATA[https://payment.nps.cn/ReceiveMerchantAction

.do]]></RedirectURL>

<PopupBrowser>false</PopupBrowser>

<RedirectParameters method="GET" contentType="application/x-www-

form-urlencoded">

<RedirectParameter name="OrderMessage"

value="12345645838A13F803F93333137D03C603B1331DC7B6452313910388

F5C8039493640345438A03F833F91333037D53C613B1331D93B6C7231391E28

823C85394C7641345C78A86F847F94733077D37C6A3B1F21DF2B64623079176

88D2C8469456646745E28A36F807F94733E27D46C616B1471D16B6362316913

78886C8E2943664F645D68AF2F8E4F9F633477D96C666B1961D36B616234791

9688F6C8E694F2642545568A46F896F92733567D36C647B1841D16B6E623469

1C68856C827943764F245E48A05F835F9E233167D37C607B1871DC7B61323C7

91758896C8C694C6649645168AD6F802F94433967D36C6B6B1371DF6B6E623C

791538813C802942564F645368AB6F897F90233257DF6C616B1461D02B6C223

0291358816C8E69402644445968A56F876F9F633C27D02C654B1E41DC2B6022

355913588C7C8239403640345938A13F8C7F92333037D63C683B1131D23B673

232391738883C81394C7647545968AC6F8C6F99633167DD6C6E2B1441D96B63

623B6913788F6C8E69404647645C68AF6F826F91633C67DE2C636B1F61DD6B6

C7238491F688C6C8969446641645978A02F884F9F633577D37C656B1C71D74B

6272356915688E6C8779416649745028A45F856F92733277D16C636B1561D37

B602232391138803C8029424641645978A37F896F94633567D02C625B1F61D1

6B64623C2910288E4C8569477640245958AF6F827F9B633C27D02C6E4B1951D

C2B6022355913588C7C8139403640345238A83F8C7F92333037D63C683B1131

D23B673232391738883C81394C7647545968AC6F8C6F99633167DD6C6E2B144

1D96B63623B6913788F6C8E69404647645C68AF6F826F91633C67DE2C636B1F

61DD6B6C7234591138803C8F59403649345038A43F803F93333137D03C653B1

131D33B69323C7910388C7C8239403640345938AD2F803F94333D27D03C633B

1"/>

<RedirectParameter name="digest"

value="123A456B830273A80B52DDC0B"/>

</RedirectParameters>

</RiskResult>

</Purchase>

</Event>

</Response>

3.3.2.5.8 eNETS return values

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

3.3.2.5.8.1 AUTHORISED

<Event>

<ResponseDescription>Success</ResponseDescription>

<BANK_ID>7123</BANK_ID>

<BANK_Ref_Code>181234563</BANK_Ref_Code>

<BANK_Remarks>No Remarks</BANK_Remarks>

<BANK_Status>00000</BANK_Status>

<BANK_Currency_Code>702</BANK_Currency_Code>

<BANK_Exchange_Rate>1.0</BANK_Exchange_Rate>

<BANK_Transaction_Amount>100</BANK_Transaction_Amount>

<BANK_Time_Zone>+08:00</BANK_Time_Zone>

<BANK_Txn_Date>06/08/2008</BANK_Txn_Date>

<BANK_Txn_Time>00:47:29</BANK_Txn_Time>

<NETSTransactionDateTime>06/08/2008

00:48:57</NETSTransactionDateTime>

</PaymentMethod>

<Status>SUCCESS</Status>

</RiskResult>

<RecommendedClientMessage>><![CDATA[Your transaction has been

processed successfully.]]></RecommendedClientMessage>

</Purchase>

</Event>

</Response>

3.3.2.5.8.2 REDIRECT

<Event>

<RecommendedDisplayMessage isRightToLeft="False">Please wait

while you are being redirected to the eNETS

website.</RecommendedDisplayMessage>

</PaymentMethod>

<Status>REDIRECT</Status>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

<RedirectURL><![CDATA[https://test.enets.sg/enets2/PaymentListener

.do]]></RedirectURL>

<RedirectParameters method="POST" contentType="application/x-www-

form-urlencoded">

<RedirectParameter name="message"

value="sdojfawfsCRUdJTiBQR1AgTUVTU0FHRS0tLS0tDQpWZXJzaW9uOiBTZW

N1cmVCbGFja2JveCA1IChQR1BCbGFja2JveCkNCg0Kd2NCT0E5SE1VYTd5Z0UwS

kVBUUF1bU9ORGdzS05KbVE3TkI1ZEt6M2ZCb001TVhtbDFUVXVjRnJZRm1KdFlB

SQ0KNWE0QzdJOXNIWXlRQk1xZWVjejRCWlVFa0FFL0JzSkJSNUxuWld0NGtUc1d

ZQmRPNFY5Nlo2VGViTUwrUnRUdQ0KNVZIbmF0bzdtZlNxQkt4UkdrVkNETHNRek

FmTkcwUFNxL3pJaGxTZjBnODJIMjZCaWZ3M0RBM2RnVVNPSEFNRQ0KQVBvUnM2e

XE2bVpnNFhjWTAzWWQ5eVJtaW1EK0UvWW5JREphODVGNnhibXlEcEt3Qk51c3Zh

eEE4TnpabXFhWA0KQWxhd2tuemtxdnZZTWZmb1FYZ09JSGJid1IxeUthVXZ5Uld

RWVp4V2xnTzFYOFNEUzllbk9kNHNaOHY2SWwrNg0KSHk0VnRoczBRWnc4OFZ4R0

tMZnZwaG1PMExqVVFYQTZHRGR2eGRReUNFWkUwc0ovQWVVUUtSbXZUc1QzQ2JpO

Q0KRzNhT3lRQm0yTU0wVit0d2JYWUJDQjBpbzE0NUlmZk5BQUxpRnZ6c0VFTVV3

eFVCQ3ZsYWJYMUZiaGozUm1qRg0KU2l3Sk5GaWwrWE94YkdGNkxPMUFaR3R5YjZ

MMHMvRURLM2swQTZnMGhzVlRrK0w0R3duVUN5TnVqdGI1Snd2aA0KazV5UWpIUW

xtVVhldFgyem1WQ2pZS3NTeE5GOVQ4UndmcWFqYTRCL2ZDVldMWVFRWExRMWYxT

jUxdTVzb0p1Yw0KU3ErRHZ5VzR4cDFwNFRGa0xpd2svVGg0NFZ1WmhmbFAyU3pZ

Q1hCZ2VKclE4dmNJa0tZdE4zMlNseEJJYmsraQ0KOUptSDRhajg3QS93WHVEaEI

2WDVMSUNFbnFRS2hPMXZ6YnBySXAzdGFjMU9WOGsvV210VWRtdHg0bHdoY3JOTw

0KcytLLzBTUVc1T0xPUWhYektxQ245V0Rjd2lUNVRTYlI3QWxicGxCQ0JzdjMzN

nluM1hyQmtZS1Z4TWhkUmZsRg0KeDQyeU9GNFI5Y1g2QzhmUHVaVnBNOTkyMnFH

Sm80REpoeEU0SnZrRW9VUGdFcFFjOXJQUXpGSjFnNnk3cXptaQ0Kd2lDVHZ6Tit

RcGJCTU5yREhCMCtoeDdFU0xNTzhlNStHSFNaVEE1QkhMTXM1OXhVMitoL0o3Vz

dCRTVlemlLLw0KRmtNUXhqVTQyVE1RWUU4Q0ZVYU13WXhVL2dkMzVaaFB3R3ZDe

lZVUHdEOGt3U0srNkQ2RXluQnpsbkJFWXd0Rw0KSW5QRFQyVmVtZXRQWXpDcURz

Q2NnV0JSYTJ0amNWYjhMUDVkcnp1Vkt1eW9CMWtXVjRlUlF6UVZpSlYwMDE5cA0

KVmpBUlZFaVp1SktYQ2xtUFNzbnhadmtycjMxcWo2bm5oUWI0a3NjZ3VxWWs1Sk

ZTSnUwRmJSaXV1T09SeElzSQ0KTUlQMEFpWkd0R0dtVmtudG1oM3B2eUtHeXJOV

2FlOXVHNkpGUHZqSk1IQ1FlSzJuSC8ydFVpSUJWSndDYzBDTg0KOWdXZXExQlE4

aGsyRXVOblB4c3pSdjFWUmpiN1ZQdU91dmNDVGFkM2Jwd2VSVnVicWl0R0tjVVB

SK1JBcnQ2dQ0KNDhiaXZsSTQ2RE1VVTg1ZncxZWN4b1FVNFY2WnFXbjQ2OEhBMj

dDdE40ZWEyMWFpOU9RV0Q2enN0bkVEallKaQ0KL0NxcndKUndoMW1QdXdrcDZtW

VZRL1puZDAxM2g2MGlWUjdQKzJmVmhkTFdrTlloZG9YTnVRRjFXUkU2R2M2cw0K

bGJWQzJyOEZqK1VHUHpkMnhXcXd5Y2VZNzRFZWh5S2IveFI0K2tTdWlJOG1SOVV

zczc4QlN0dmVvbFNZcmlHUA0KRkRCZHJ1ZXJnM2hKWEpjYTNwUzlJNkNpandtOD

JHc2lMd2xOa1hrMEJLVmlvdFgxak4vOHN1TEpSbnplUVVHLw0KdFVDZw0KPVR6M

mkNCi0tLS0tRU5EIFBHUCBNRVNTQUdFLS0tLS0="/>

</RedirectParameters>

</RiskResult>

</Purchase>

</Event>

</Response>

3.3.2.5.8.3 ERROR

<Event>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

<ResponseDescription>Failure</ResponseDescription>

<BANK_ID>7123</BANK_ID>

<BANK_Ref_Code/>

<BANK_Remarks>Bank Remarks</BANK_Remarks>

<BANK_Status>20001</BANK_Status>

<BANK_Currency_Code/>

<BANK_Exchange_Rate>1</BANK_Exchange_Rate>

<BANK_Transaction_Amount>0</BANK_Transaction_Amount>

<BANK_Time_Zone/>

<BANK_Txn_Date>03/04/2009</BANK_Txn_Date>

<BANK_Txn_Time>19:47:29</BANK_Txn_Time>

</PaymentMethod>

<Status>ERROR</Status>

<Error>

</Error>

</RiskResult>

<RecommendedClientMessage><![CDATA[Your request could not be

completed. Please contact merchant customer service for more

information.]]></RecommendedClientMessage>

</Purchase>

</Event>

</Response>

3.3.2.5.8.4 CANCELLED

<Event>

<ResponseDescription>Cancel</ResponseDescription>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

<BANK_ID/>

<BANK_Ref_Code/>

<BANK_Remarks/>

<BANK_Status/>

<BANK_Currency_Code/>

<BANK_Exchange_Rate/>

<BANK_Transaction_Amount>0</BANK_Transaction_Amount>

<BANK_Time_Zone/>

<BANK_Txn_Date/>

<BANK_Txn_Time/>

</PaymentMethod>

<Status>CANCELLED</Status>

</RiskResult>

<RecommendedClientMessage><![CDATA[Your transaction has been

cancelled as per your request. Please contact merchant customer

service for more information.]]></RecommendedClientMessage>

</Purchase>

</Event>

</Response>

3.3.2.5.9 OneClick return values

3.3.2.5.9.1 AUTHORISED

<Event>

<ResponseDescription>Success</ResponseDescription>

<uniqueReference>ASLUS1234561</uniqueReference>

<bankInformation>Henrik Hamberger JSUE12349</bankInformation>

</PaymentMethod>

<Status>AUTHORISED</Status>

</RiskResult>

<RecommendedClientMessage>string</RecommendedClientMessage>

</Purchase>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

</Event>

</Response>

3.3.2.5.9.2 CANCELLED

<Event>

<ResponseCode>CANCELLED</ResponseCode>

<ResponseDescription>CANCELLED</ResponseDescription>

<email>test.account@gmail.com</email>

</PaymentMethod>

<Status>CANCELLED</Status>

</RiskResult>

<RecommendedClientMessage><![CDATA[Uw transactie is op uw verzoek

geannuleerd. Neem a.u.b. contact op met de verkoopklantenservice

voor nadere informatie.]]></RecommendedClientMessage>

</Purchase>

</Event>

</Response>

3.3.2.5.9.3 PENDING

<Event>

<email>test.account@gmail.com</email>

</PaymentMethod>

<Status>PENDING</Status>

</RiskResult>

<RecommendedClientMessage><![CDATA[Uw verzoek kan niet helemaal

afgerond worden. Raadpleeg uw account voor de laatste informatie.

U kunt ook contact opnemen met de verkoopklantenservice voor

nadere informatie.]]></RecommendedClientMessage>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

</Purchase>

</Event>

</Response>

3.3.2.5.9.4 REFUSED

<Event>

<ResponseCode>FAILURE</ResponseCode>

<ResponseDescription>FAILURE</ResponseDescription>

<email>test.account@gmail.com</email>

</PaymentMethod>

<Status>REFUSED</Status>

</RiskResult>

<RecommendedClientMessage><![CDATA[Uw verzoek kan niet afgehandeld

worden. Neem a.u.b. contact op met de verkoopklantenservice voor

nadere informatie.]]></RecommendedClientMessage>

</Purchase>

</Event>

</Response>

3.3.2.5.9.5 REDIRECT

<Event>

<RecommendedDisplayMessage isRightToLeft="False">Even geduld

graag. U wordt doorgeleid naar de Envoy OneClick

website.</RecommendedDisplayMessage>

</PaymentMethod>

<Status>REDIRECT</Status>

</RedirectURL>

<PopupBrowser>false</PopupBrowser>

<RedirectParameters method="POST" contentType="application/x-www-

form-urlencoded">

<RedirectParameter name="customerRef"

value="A99_090403141723"/>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

</RedirectParameters>

</RiskResult>

</Purchase>

</Event>

</Response>

3.3.2.5.9.6 ERROR

<Event>

<ResponseCode>ERROR</ResponseCode>

<ResponseDescription>Om technische redenen kan de bank uw

betaling op dit moment niet verwerken. Probeert u het

alstublieft later nog eens.</ResponseDescription>

<email>test.account@gmail.com</email>

</PaymentMethod>

<Status>ERROR</Status>

<StatusDescription><![CDATA[Transaction

Approved]]></StatusDescription>

</RiskResult>

<RecommendedClientMessage><![CDATA[Uw verzoek kan niet afgehandeld

worden. Neem a.u.b. contact op met de verkoopklantenservice voor

nadere informatie.]]></RecommendedClientMessage>

</Purchase>

</Event>

</Response>

3.3.2.5.10 InstaDebit return values

3.3.2.5.10.1 AUTHORISED

<Event>

<ResponseDescription>Success</ResponseDescription>

<user_id>test.user</user_id>

<txn_type>T</txn_type>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

<merchant_user_id>34563DSFSDF</merchant_user_id>

<txn_fee>0.10</txn_fee>

</PaymentMethod>

<Status>AUTHORISED</Status>

<StatusDescription><![CDATA[Transaction

Approved]]></StatusDescription>

</RiskResult>

<RecommendedClientMessage><![CDATA[Your transaction has been

processed successfully..]]></RecommendedClientMessage>

</Purchase>

</Event>

</Response>

3.3.2.5.10.2 ERROR

<Event>

</PaymentMethod>

<Status>ERROR</Status>

<Error>

<Description>The InstaDebit notification is

invalid</Description>

</Error>

<StatusDescription><![CDATA[Transaction

Approved]]></StatusDescription>

</RiskResult>

<RecommendedClientMessage><![CDATA[Your request could not be

completed. Please contact merchant customer service for more

information.]]></RecommendedClientMessage>

</Purchase>

</Event>

</Response>

3.3.2.5.10.3 REDIRECT

<Event>

<RecommendedDisplayMessage isRightToLeft="False">Even geduld

graag. U wordt doorgeleid naar de InstaDebit

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

website</RecommendedDisplayMessage>

</PaymentMethod>

<Status>REDIRECT</Status>

<RedirectURL>https://staging.instadebit.com/instadebit/merGatew

ay.do </RedirectURL>

<PopupBrowser>false</PopupBrowser>

<RedirectParameters method="POST" contentType="application/x-www-

form-urlencoded">

<RedirectParameter name="merchant_txn_num"

value="A99_45723456249"/>

<RedirectParameter name="addr_1" value="Unit 11, Forest Edge

Villa"/>

<RedirectParameter name="return_url" value="https://dpg-

cpt.datacash.com/Notification/RedirectHandlers/InstaDebit.aspx"

/>

</RedirectParameters>

<StatusDescription><![CDATA[Transaction

Approved]]></StatusDescription>

</RiskResult>

</Purchase>

</Event>

</Response>

3.3.2.5.10.4 REFUSED

<Event>

<ResponseDescription>Transaction is terminated. The transaction

is declined (generic error).</ResponseDescription>

<user_id>test.user</user_id>

<txn_type>T</txn_type>

<merchant_user_id>34DSFSDF</merchant_user_id>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

<txn_fee>0.10</txn_fee>

</PaymentMethod>

<Status>REFUSED</Status>

<StatusDescription><![CDATA[Transaction Approved

]]></StatusDescription>

</RiskResult>

<RecommendedClientMessage><![CDATA[Uw verzoek kan niet afgehandeld

worden. Neem a.u.b. contact op met de verkoopklantenservice voor

nadere informatie.]]></RecommendedClientMessage>

</Purchase>

</Event>

</Response>

3.3.2.5.10.5 CANCELLED

<Event>

<ResponseDescription>The transaction is cancelled by the

customer</ResponseDescription>

<user_id>test.user</user_id>

<txn_type>T</txn_type>

<merchant_user_id>34DSFSDF</merchant_user_id>

<txn_fee>0.10</txn_fee>

</PaymentMethod>

<Status>CANCELLED</Status>

<StatusDescription><![CDATA[Transaction Approved

]]></StatusDescription>

</RiskResult>

<RecommendedClientMessage><![CDATA[Uw transactie is op uw verzoek

geannuleerd. Neem a.u.b. contact op met de verkoopklantenservice

voor nadere informatie.]]></RecommendedClientMessage>

</Purchase>

</Event>

</Response>

3.3.2.5.11 ExperCash return values

3.3.2.5.11.1 AUTHORISED

<Event>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

<ResponseDescription>Transaction

successfull</ResponseDescription>

</PaymentMethod>

<Status>AUTHORISED</Status>

</RiskResult>

<RecommendedClientMessage><![CDATA[Your transaction has been

processed successfully..]]></RecommendedClientMessage>

</Purchase>

</Event>

</Response>

3.3.2.5.11.2 PENDING

<Event>

<ResponseDescription>Transaction

successfull</ResponseDescription>

</PaymentMethod>

<Status>PENDING</Status>

</RiskResult>

<RecommendedClientMessage><![CDATA[Your request could not entirely

be completed. Please check your account later for an updated

status. You may also contact merchant customer service for more

information. ]]></RecommendedClientMessage>

</Purchase>

</Event>

</Response>

3.3.2.5.11.3 ERROR

<Event>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

</PaymentMethod>

<Status>ERROR</Status>

<Error>

<Description>Either SortCode and AccountNumber OR IBAN OR

PaymentReference must be supplied - no other combinations

permitted.</Description>

</Error>

</RiskResult>

<RecommendedClientMessage><![CDATA[Your request could not be

completed. Please contact merchant customer service for more

information. ]]></RecommendedClientMessage>

</Purchase>

</Event>

</Response>

3.3.2.5.11.4 REFUSED

<Event>

<ResponseDescription>REJECTED: possibly wrong bank account

number or bank code</ResponseDescription>

</PaymentMethod>

<Status>REFUSED</Status>

</RiskResult>

<RecommendedClientMessage><![CDATA[Your request could not be

completed. Please contact merchant customer service for more

information.]]></RecommendedClientMessage>

</Purchase>

</Event>

</Response>

3.3.2.5.11.5 REDIRECT (SOFORT)

<Event>

</PaymentMethod>

<Status>REDIRECT</Status>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

<RedirectURL><![CDATA[https://www.sofortueberweisung.de/payment/start]]

></RedirectURL>

<RedirectParameters method="POST" contentType="application/x-www-

form-urlencoded">

<RedirectParameter name="hash"

value="f1a51d213fe82b90037d6708035f46704cf6d353"/>

</RedirectParameters>

<StatusDescription><![CDATA[Transaction

Approved]]></StatusDescription>

</RiskResult>

</Purchase>

</Event>

</Response>

3.3.2.5.11.6 REDIRECT (GIROPAY)

<Event>

</PaymentMethod>

<Status>REDIRECT</Status>

<RedirectURL><![CDATA[https://giropaytest1.fiducia.de/ShopSystem/bank/B

ankEntry]]></RedirectURL>

<RedirectParameters method="POST" contentType="application/x-www-

form-urlencoded">

<RedirectParameter name="redirectData"><![CDATA[operatorId=002&

merchantId=MerchantAccount&

txId=F000007SOJ&

merchantTxId=56749466&

customerBankBLZ=44441111&

shopEndSuccessURL=https%3A%2F%2Fdpg-

cpt.datacash.com%2FNotification%2FRedirectHandlers%2FExperCash.aspx%3Ftai

d%3D56749466&

shopEndFailureURL=https%3A%2F%2Fdpg-

cpt.datacash.com%2FNotification%2FRedirectHandlers%2FExperCash.aspx%3Fabo

rted%3Dtrue&

beneficiaryName1=easyDebit&

beneficiaryName2=&

beneficiaryAcctNo=1234567890&

beneficiaryBankBLZ=44441111&

amount=5240&

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

currency=EUR&

paymentPurposeLine1=GP0808502474000&

paymentPurposeLine2=GIROPAY0028993390F000007SOJ&

operatorSignature=kZ7X72%2F88h9pJGx%2BulrJ7gX%2FjEwBOmC8HZlF%2FiG%2FJYXWt

W2fLRel2biJ1vkqB6%2FhPJfJVyTkoiGkcqdTy3lVWttJTvFQYe0YkurrAoOQA2k6wseVI6Ko

f2EaEy%2F7ofRVN6MziZrx6WJFjbQ8Bz3B%2FFJrFHrlhAmvFekN1SwyZy0%3D]]></Redire

ctParameter>

</RedirectParameters>

</RiskResult>

</Purchase>

</Event>

</Response>

3.3.2.5.12 iDeal return values

3.3.2.5.12.1 AUTHORISED

<Event>

<ResponseDescription>Transaction

successfull</ResponseDescription>

</PaymentMethod>

<Status>AUTHORISED</Status>

</RiskResult>

<RecommendedClientMessage><![CDATA[Your transaction has been

processed successfully..]]></RecommendedClientMessage>

</Purchase>

</Event>

</Response>

3.3.2.5.12.2 PENDING

<Event>

<ResponseDescription>Transaction

successfull</ResponseDescription>

</PaymentMethod>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

<Status>PENDING</Status>

</RiskResult>

<RecommendedClientMessage><![CDATA[Your request could not entirely

be completed. Please check your account later for an updated

status. You may also contact merchant customer service for more

information. ]]></RecommendedClientMessage>

</Purchase>

</Event>

</Response>

3.3.2.5.12.3 ERROR

<Event>

</PaymentMethod>

<Status>ERROR</Status>

<Error>

<Description>iDealItem.Issuer_Id is invalid.</Description>

</Error>

</RiskResult>

<RecommendedClientMessage><![CDATA[Your request could not be

completed. Please contact merchant customer service for more

information. ]]></RecommendedClientMessage>

</Purchase>

</Event>

</Response>

3.3.2.5.12.4 REFUSED

<Event>

<ResponseDescription>REJECTED: possibly wrong bank account

number or bank code</ResponseDescription>

</PaymentMethod>

<Status>REFUSED</Status>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

</RiskResult>

<RecommendedClientMessage><![CDATA[Your request could not be

completed. Please contact merchant customer service for more

information.]]></RecommendedClientMessage>

</Purchase>

</Event>

</Response>

3.3.2.5.12.5 REDIRECT

<Event>

<RecommendedDisplayMessage isRightToLeft="False">Please wait

while you are being redirected to the iDeal

website.</RecommendedDisplayMessage>

</PaymentMethod>

<Status>REDIRECT</Status>

</RiskResult>

</Purchase>

</Event>

</Response>

3.3.2.5.13 ElectronicCheck return values

3.3.2.5.13.1 AUTHORISED

<Event>

<ResponseDescription>Approved</ResponseDescription>

</PaymentMethod>

<Status>AUTHORISED</Status>

</RiskResult>

<RecommendedClientMessage><![CDATA[Your transaction has been

processed successfully.]]></RecommendedClientMessage>

</Purchase>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

</Event>

</Response>

3.3.2.5.13.2 SENT FOR CAPTURE

<Event>

<ResponseDescription>Approved</ResponseDescription>

</PaymentMethod>

<Status>SENT_FOR_CAPTURE</Status>

</RiskResult>

<RecommendedClientMessage>><![CDATA[Your transaction has been

processed successfully.]]></RecommendedClientMessage>

</Purchase>

</Event>

</Response>

3.3.2.5.13.3 CAPTURED (Recurring transaction)

<Event>

<ResponseCode>Deposit</ResponseCode>

<ResponseDescription>The funds have been captured

successfully.</ResponseDescription>

<OriginalTransactionId>T10_GUSWFMVR2PNW</OriginalTransactionId>

</PaymentMethod>

<Status>CAPTURED</Status>

</RiskResult>

<RecommendedClientMessage>><![CDATA[Your transaction has been

processed successfully.]]></RecommendedClientMessage>

</Purchase>

</Event>

</Response>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

3.3.2.5.13.4 CAPTURED (Non-recurring transaction)

<Event>

<ResponseCode>Deposit</ResponseCode>

<ResponseDescription>The funds have been captured

successfully.</ResponseDescription>

<Recurring>False</Recurring>

</PaymentMethod>

<Status>CAPTURED</Status>

</RiskResult>

<RecommendedClientMessage><![CDATA[Your transaction has been

processed successfully.]]></RecommendedClientMessage>

</Purchase>

</Event>

</Response>

3.3.2.5.13.5 ERROR

<Event>

<ResponseDescription>Bad Account Number

Data</ResponseDescription>

</PaymentMethod>

<Status>ERROR</Status>

</RiskResult>

<RecommendedClientMessage><![CDATA[Your request could not be

completed. Please contact merchant customer service for more

information.]]></RecommendedClientMessage>

</Purchase>

</Event>

</Response>

3.3.2.5.13.6 REFUSED (Recurring transaction)

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

<Event>

<ResponseCode>REJECT</ResponseCode>

<ResponseDescription>Failed a front-end

edit</ResponseDescription>

<OriginalTransactionId>T10_GUSWFMVR2PNW</OriginalTransactionId>

</PaymentMethod>

<Status>REFUSED</Status>

</RiskResult>

<RecommendedClientMessage><![CDATA[Your request could not be

completed. Please contact merchant customer service for more

information.]]></RecommendedClientMessage>

</Purchase>

</Event>

</Response>

3.3.2.5.13.7 REFUSED (Non-recurring transaction)

<Event>

<ResponseCode>REJECT</ResponseCode>

<ResponseDescription>Failed a front-end

edit</ResponseDescription>

<Recurring>False</Recurring>

</PaymentMethod>

<Status>REFUSED</Status>

</RiskResult>

<RecommendedClientMessage><![CDATA[Your request could not be

completed. Please contact merchant customer service for more

information.]]></RecommendedClientMessage>

</Purchase>

</Event>

</Response>

3.3.2.5.13.8 REFUNDED (Recurring transaction)

<Event>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

<ResponseDescription>No account/unable to locate

account</ResponseDescription>

<OriginalTransactionId>T10_GUSWFMVR2PNW</OriginalTransactionId>

</PaymentMethod>

<Status>REFUNDED</Status>

</RiskResult>

<RecommendedClientMessage><![CDATA[Your transaction has been

refunded. Please contact merchant customer service for more

information.]]></RecommendedClientMessage>

</Purchase>

</Event>

</Response>

3.3.2.5.13.9 REFUNDED (Non-recurring transaction)

<Event>

<ResponseDescription>No account/unable to locate

account</ResponseDescription>

<Recurring>False</Recurring>

</PaymentMethod>

<Status>REFUNDED</Status>

</RiskResult>

<RecommendedClientMessage><![CDATA[Your transaction has been

refunded. Please contact merchant customer service for more

information.]]></RecommendedClientMessage>

</Purchase>

</Event>

</Response>

3.3.2.5.13.10 CHARGEBACK (Recurring transaction)

<Event>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

<ResponseDescription>Fraudulent Transaction: Card Not Present

Environment</ResponseDescription>

<OriginalTransactionId>T10_GUSWFMVR2PNW</OriginalTransactionId>

</PaymentMethod>

<Status>CHARGED_BACK</Status>

</RiskResult>

<RecommendedClientMessage><![CDATA[Your transaction has been

charged back. Please contact merchant customer service for more

information.]]></RecommendedClientMessage>

</Purchase>

</Event>

</Response>

3.3.2.5.13.11 CHARGEBACK (Non-recurring transaction)

<Event>

<ResponseDescription>Fraudulent Transaction: Card Not Present

Environment</ResponseDescription>

<Recurring>False</Recurring>

</PaymentMethod>

<Status>CHARGED_BACK</Status>

</RiskResult>

<RecommendedClientMessage><![CDATA[Your transaction has been

charged back. Please contact merchant customer service for more

information.]]></RecommendedClientMessage>

</Purchase>

</Event>

</Response>

3.3.2.5.14 Amazon return values

3.3.2.5.14.1 PENDING

<Event>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

</PaymentMethod>

<Status>PENDING</Status>

</RiskResult>

<RecommendedClientMessage><![CDATA[Your request could not entirely

be completed. Please check your account later for an updated status. You

may also contact merchant customer service for more

information.]]></RecommendedClientMessage>

</Purchase>

</Event>

</Response>

3.3.2.5.14.2 AUTHORISED

<Event>

<ResponseCode>ReadyToShip</ResponseCode>

</PaymentMethod>

<Status>AUTHORISED</Status>

</RiskResult>

<RecommendedClientMessage><![CDATA[Your transaction has been

processed successfully.]]></RecommendedClientMessage>

</Purchase>

</Event>

</Response>

3.3.2.5.14.3 SENT_FOR_CAPTURE

<Event>

<Modification DPGReferenceId="32604"

TransactionId="T10_110404083030">

</PaymentMethod>

<Status>SENT_FOR_CAPTURE</Status>

</Modification>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

</Event>

</Response>

3.3.2.5.14.4 SENT_FOR_CANCEL

<Event>

<Modification DPGReferenceId="32604"

TransactionId="T10_110404083030">

</PaymentMethod>

<Status>SENT_FOR_CANCEL</Status>

</Modification>

</Event>

</Response>

3.3.2.5.14.5 SENT_FOR_REFUND

<Event>

<Modification DPGReferenceId="32604"

TransactionId="T10_110404083030">

</PaymentMethod>

<Status>SENT_FOR_REFUND</Status>

</Modification>

</Event>

</Response>

3.3.2.5.14.6 CAPTURED

<Event>

<ResponseCode>OrderFulfilled</ResponseCode>

</PaymentMethod>

<Status>CAPTURED</Status>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

</RiskResult>

</Purchase>

</Event>

</Response>

3.3.2.5.14.7 CANCELLED

<Event>

<ResponseCode>OrderFulfilled</ResponseCode>

</PaymentMethod>

<Status>CANCELLED</Status>

</RiskResult>

</Purchase>

</Event>

</Response>

3.3.2.5.14.8 REFUNDED

<Event>

<ResponseCode>OrderFulfilled</ResponseCode>

</PaymentMethod>

<Status>REFUNDED</Status>

</RiskResult>

</Purchase>

</Event>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

</Response>

3.3.2.5.14.9 ERROR

<Event>

<ResponseCode>InvalidParameterValue</ResponseCode>

<ResponseDescription>Contract with id 1111 does not

exist.</ResponseDescription>

</PaymentMethod>

<Status>ERROR</Status>

</RiskResult>

<RecommendedClientMessage><![CDATA[Your request could not be

completed. Please contact merchant customer service for more

information.]]></RecommendedClientMessage>

</Purchase>

</Event>

</Response>

3.3.2.5.15 WebMoney Return Values

3.3.2.5.15.1 Redirect Purchase Response

<Event>

<RecommendedDisplayMessage

isRightToLeft="False">string</RecommendedDisplayMessage>

</PaymentMethod>

<Status>string</Status>

<RedirectURL>string</RedirectURL>

</RedirectParameters>

<StatusCode>string</StatusCode>

<StatusDescription>string</StatusDescription>

</RiskResult>

</Purchase>

</Event>

</Response>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

3.3.2.5.15.2 Successful Purchase Response

<Event>

<ReferenceId>string</ReferenceId>

<ResponseCode>string</ResponseCode>

<ResponseDescription>string</ResponseDescription>

<TimeStamp>string</TimeStamp>

<LMI_PAYEE_PURSE></LMI_PAYEE_PURSE>

<LMI_SYS_INVS_NO></LMI_SYS_INVS_NO>

<LMI_SYS_TRANS_NO></LMI_SYS_TRANS_NO>

<LMI_PAYER_PURSE></LMI_PAYER_PURSE>

<LMI_PAYER_WM></LMI_PAYER_WM>

<LMI_SYS_TRANS_DATE></LMI_SYS_TRANS_DATE>

</PaymentMethod>

<Status>string</Status>

<StatusCode>string</StatusCode>

<StatusDescription>string</StatusDescription>

</RiskResult>

<RecommendedClientMessage>string</RecommendedClientMessage>

</Purchase>

</Event>

</Response>

3.3.2.5.15.3 UnSuccessful Purchase Response

<Event>

; <ResponseCode>string</ResponseCode>

<ResponseDescription>string</ResponseDescription>

<LMI_PAYEE_PURSE></LMI_PAYEE_PURSE>

<LMI_SYS_INVS_NO></LMI_SYS_INVS_NO>

<LMI_SYS_TRANS_NO></LMI_SYS_TRANS_NO>

<LMI_PAYER_PURSE></LMI_PAYER_PURSE>

<LMI_PAYER_WM></LMI_PAYER_WM>

<LMI_SYS_TRANS_DATE></LMI_SYS_TRANS_DATE>

</PaymentMethod>

<Status>string</Status>

<Error>

<Code>string</Code>

<Description>string</Description>

</Error>

<StatusCode>string</StatusCode>

<StatusDescription>string</StatusDescription>

</RiskResult>

<RecommendedClientMessage>string</RecommendedClientMessage>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

</Purchase>

</Event>

</Response>

3.3.2.5.16 Offline Bank Transfer return values

3.3.2.5.16.1 AUTHORISED

<Event>

<ResponseDescription>Success</ResponseDescription>

<Email>john.doe@amnesia.co.za</Email>

<CustomerReference>435NSDVON252J3</CustomerReference>

<bankName>Barclays London</bankName>

<countryCode>string</countryCode>

<transferType>BANKIN</transferType>

<refererType>BANKIN</refererType>

</PaymentMethod>

<Status>AUTHORISED</Status>

<RecommendedClientMessage>Your transaction has been processed

successfully.</RecommendedClientMessage>

</Purchase>

</Event>

</Response>

3.3.2.5.16.2 MARKED FOR REFUND

<Event>

<ResponseDescription>Incorrect amount

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

deposited</ResponseDescription>

<Email>john.doe@amnesia.co.za</Email>

<CustomerReference>435NSDVON252J3</CustomerReference>

<bankName>Barclays London</bankName>

<countryCode>string</countryCode>

<transferType>BANKIN</transferType>

<refererType>BANKIN</refererType>

</PaymentMethod>

<Status>MARKED_FOR_REFUND</Status>

<RecommendedClientMessage><![CDATA[Your transaction has been marked

for refund. ]]></RecommendedClientMessage>

</Purchase>

</Event>

</Response>

3.3.2.5.16.3 MARKED FOR REFUND (Exception)

<Event>

<ResponseDescription>Duplicate deposit of correct

amount</ResponseDescription>

<Email>john.doe@amnesia.co.za</Email>

<CustomerReference>435NSDVON252J3</CustomerReference>

<bankName>Barclays London</bankName>

<countryCode>string</countryCode>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

<transferType>BANKIN</transferType>

<refererType>BANKIN</refererType>

</PaymentMethod>

<Status>MARKED_FOR_REFUND</Status>

<RecommendedClientMessage><![CDATA[Your transaction has been marked

for refund. ]]></RecommendedClientMessage>

</Purchase>

</Event>

</Response>

3.3.2.5.16.4 PENDING

<Event>

<ResponseCode>SUCCESS</ResponseCode>

<ResponseDescription>Bank Transfer Details

retrieved</ResponseDescription>

<bank>Werther Bank AG</bank>

</BankDetails>

</BankTransferDetails>

</PaymentMethod>

<Status>PENDING</Status>

<strong>1.</strong>&

nbsp;You can transfer funds from your personal bank account to the

account shown by using any of your banks fund transfer facilities e.g.

online banking, telephone banking or in person over-the-counter.</p>

<p>

<strong>2.</strong>&

nbsp;<b>Important: Quote your reference number when you do your transfer.

<font color="red">Inclusion of your reference with your deposit is

crucial to ensure your payment is processed timeously and is required in

order for your account balance to be updated at the merchant.</font>

</b>

</p>

<p>

<strong>3.</strong>&

nbsp;Once you have made your transfer, because of the local clearing

cycle, there will be a short delay before the funds are received at the

collecting bank. Usually this is in the order of a few days but depends

on the banking territory concerned.</p>

<p>

<strong>4.</strong>&

nbsp;It is recommended that all receipts and references are retained as

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

proof of payment for any future queries you might

have.</p>]]></RecommendedDisplayMessage>

</Purchase>

</Event>

</Response>

3.3.2.5.17 POLi return values

3.3.2.5.17.1 AUTHORISED

<Event>

<ResponseCode>Completed</ResponseCode>

<PaymentId>2JC+4IQqDA7HRHztqsBLoKVpVso+mJJJ</PaymentId>

<BankReceiptDateTime>2011-12-21

11:04:26</BankReceiptDateTime>

<CountryName>Australia</CountryName>

<CurrencyName>Australian Dollar</CurrencyName>

<EstablishedDateTime>2011-12-21

11:01:25</EstablishedDateTime>

<FinancialInstitutionCode>iBankAU01</FinancialInstitutionCode>

<FinancialInstitutionName>iBank AU

01</FinancialInstitutionName>

<MerchantEstablishedDateTime>2011-12-21

02:01:15</MerchantEstablishedDateTime>

</PaymentMethod>

<Status>AUTHORISED</Status>

</RiskResult>

<RecommendedClientMessage><![CDATA[Your transaction has been

processed successfully.]]></RecommendedClientMessage>

</Purchase>

</Event>

</Response>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

3.3.2.5.17.2 CANCELLED

<Event>

<ResponseCode>Cancelled</ResponseCode>

<PaymentId>1rwqaj4xDpFDIwDYQfTjCBehblM71yw1</PaymentId>

<CountryName>Australia</CountryName>

<CurrencyName>Australian Dollar</CurrencyName>

<EstablishedDateTime>2011-12-21

11:09:28</EstablishedDateTime>

<FinancialInstitutionCode>iBankAU01</FinancialInstitutionCode>

<FinancialInstitutionName>iBank AU

01</FinancialInstitutionName>

<MerchantEstablishedDateTime>2011-12-21

02:09:19</MerchantEstablishedDateTime>

</PaymentMethod>

<Status>CANCELLED</Status>

</RiskResult>

<RecommendedClientMessage><![CDATA[Your transaction has been

cancelled as per your request. Please contact merchant customer service

for more information.]]></RecommendedClientMessage>

</Purchase>

</Event>

</Response>

3.3.2.5.17.3 ERROR

<Event>

<ResponseCode>ReceiptUnverified</ResponseCode>

<PaymentId>rDf3pZb5pqmCHpGPZqUDstR9QocVdtA8</PaymentId>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

<CountryName>Australia</CountryName>

<CurrencyName>Australian Dollar</CurrencyName>

<EstablishedDateTime>2011-12-21

11:05:46</EstablishedDateTime>

<FinancialInstitutionCode>iBankAU01</FinancialInstitutionCode>

<FinancialInstitutionName>iBank AU

01</FinancialInstitutionName>

<MerchantEstablishedDateTime>2011-12-21

02:05:39</MerchantEstablishedDateTime>

</PaymentMethod>

<Status>ERROR</Status>

</RiskResult>

<RecommendedClientMessage><![CDATA[Your request could not be

completed. Please contact merchant customer service for more

information.]]></RecommendedClientMessage>

</Purchase>

</Event>

</Response>

3.3.2.5.18 POLi return values

3.3.2.5.18.1 AUTHORISED

<Event>

<ResponseCode>TRADE_FINISHED</ResponseCode>

<ResponseDescription>Transaction

successful</ResponseDescription>

</PaymentMethod>

<Status>AUTHORISED</Status>

</RiskResult>

<RecommendedClientMessage><![CDATA[Your transaction has been

processed successfully.]]></RecommendedClientMessage>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

</Purchase>

</Event>

</Response>

3.3.2.5.18.2 REDIRECTED

<Event>

</PaymentMethod>

<Status>REDIRECT</Status>

<RedirectURL><![CDATA[https://www.alipay.com/cooperate/gateway.do]]></RedirectU

RL>

<PopupBrowser>false</PopupBrowser>

<RedirectParameters method="POST" contentType="application/x-www-form-

urlencoded">

<RedirectParameter name="sign"

value="da1ecc0446519ef6add4b7f2cb975583"/>

</RedirectParameters>

</RiskResult>

</Purchase>

</Event>

</Response>

3.3.2.5.18.3 PENDING

<Event>

<ResponseCode>WAIT_BUYER_PAY</ResponseCode>

<ResponseDescription>Transaction Pending</ResponseDescription>

</PaymentMethod>

<Status>PENDING</Status>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

</RiskResult>

<RecommendedClientMessage><![CDATA[Your request could not entirely

be completed. Please check your account later for an updated status. You

may also contact merchant customer service for more

information.]]></RecommendedClientMessage>

</Purchase>

</Event>

</Response>

3.3.2.5.18.4 SENT FOR REFUND

<Event>

<Modification DPGReferenceId="141300"

TransactionId="T10_120315141257">

<ResponseDescription>Send for Refund</ResponseDescription>

</PaymentMethod>

<Status>SENT_FOR_REFUND</Status>

</Modification>

</Event>

</Response>

3.3.2.5.18.5 REFUNDED

<Event>

<ResponseCode>Refunded</ResponseCode>

<ResponseDescription>Refunded</ResponseDescription>

<Remark>Test Subject</Remark>

</PaymentMethod>

<Status>REFUNDED</Status>

</RiskResult>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

</Purchase>

</Event>

</Response>

3.3.2.5.18.6 ERROR

<Event>

</PaymentMethod>

<Status>ERROR</Status>

<Error>

<Description>PurchaseDetails.BillingDetails.AmountDetails.CurrencyCode

value invalid</Description>

</Error>

</RiskResult>

<RecommendedClientMessage><![CDATA[Your request could not be completed.

Please contact merchant customer service for more

information.]]></RecommendedClientMessage>

</Purchase>

</Event>

</Response>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

3.3.3 Payout

A call to the Payout web method of the APG Web Service is the first step in the lifecycle

of a payout transaction.

Validation will occur during the call to the web method - see Appendix 6 for a list of

possible validation errors.

The result of this request will determine if the transaction has completed processing.

The Payout web method accepts two parameters: payoutDetails of type PayoutItem,

and methodDetails of type PaymentMethodItem. The two types are custom complex

structures. For more information on the composition of these structures, please refer to

the WSDL which can be downloaded from the URLs specified in section 3.2.1.

3.3.3.1 Schema Elements for Payout Request

In this section, the fields that can be presented with Payout transaction Requests will

be presented along with example XML for those fields.

To submit Processor transaction information for a Payout transaction, one should use

the relevant PaymentMethodItem within the Payout schema element:

 Payout

o PayoutDetails – see section 3.3.3.1.1

 AccountDetails – see section 3.3.1.1.1

 PersonalDetails – see section 3.3.2.1.8

 BillingDetails – see section 3.3.2.1.3

 AddressDetails – see section 3.3.2.1.2

 AmountDetails – see section 3.3.1.1.2

o MethodDetails – see section 3.3.3.1.2

 One of the following:

 Click2PayItem – section 3.3.3.1.40

 ClickandBuyItem – section 3.3.3.1.8

 EntroPayItem – section 3.3.3.1.9

 InstaDebitItem – section 3.3.3.1.6

 MoneybookersItem – section 3.3.3.1.5

 NetellerItem – section 3.3.3.1.3

 OneClickItem – section 3.3.3.1.7

 Ukash – section 3.3.2.1.15

The “Required / Payment Method Specific” column lists the following details:

 Mandatory - This means that field cannot be empty.

 Recommended - The data is highly recommended. The fields are not mandated

by APG since not all processors mandate them. Please note that if these fields

are not supplied and the transaction is processed through a processor which

does mandate them, the transaction will be rejected.

 Optional – The data is not required for processing but should be supplied if

available.

 Not Applicable – The data is not applicable for this payment method and will be

discarded if supplied.

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

If no data is available for Recommended or Optional fields, the field can simply be left

out completely. Under no circumstances is the word ‘NULL’ to be used as a default

value for blank fields; merchants should rather leave the field blank.

NOTE: If the value sent for a field should exceed the maximum length then the

transaction may be rejected.

SOAP XML Payout Request document:

<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xmlns:xsd="http://www.w3.org/2001/XMLSchema"

xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">

<soap:Body>

<TransactionId>string</TransactionId>

<Description>string</Description>

<TransactionDateTime>string</TransactionDateTime>

<UserIP>string</UserIP>

<Language>string</Language>

<UserAgentHeader>string</UserAgentHeader>

<CustomerReference>string</CustomerReference>

<AccountName>string</AccountName>

<AccountPIN>string</AccountPIN>

<CompanyId>string</CompanyId>

</AccountDetails>

<FirstName>string</FirstName>

<LastName>string</LastName>

<Telephone1>string</Telephone1>

<Telephone1_CountryCode>short</Telephone1_CountryCode>

<Telephone1_AreaCode>short</Telephone1_AreaCode>

<DateOfBirth>dateTime</DateOfBirth>

<Email>string</Email>

<IDNumber>string</IDNumber>

<TypeOfID>NONE or PASSPORT or PERSONAL_ID or IDENTITY_CARD or

DRIVERS_LICENSE or TRAVEL_DOCUMENT or RESIDENCE_PERMIT or

IDENTITY_CERTIFICATE_NUMBER or

REGISTRO_FEDERAL_DE_CONTRIBUYENTES or

CREDENTIAL_DE_ELECTOR</TypeOfID>

<CPF_CNPJ>string</CPF_CNPJ>

<Nationality>string</Nationality>

</PersonalDetails>

<Name>string</Name>

<StreetLine1>string</StreetLine1>

<StreetLine2>string</StreetLine2>

<City>string</City>

<PostalCode>string</PostalCode>

<StateProvince>string</StateProvince>

<Country>string</Country>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

</AddressDetails>

<Exponent>short</Exponent>

<CurrencyCode>short</CurrencyCode>

</AmountDetails>

</BillingDetails>

</payoutDetails>

</Payout>

</soap:Body>

</soap:Envelope>

3.3.3.1.1 PayoutDetails

This is a set of fields and structures required for a transaction.

Element Name

PayoutDetails

Type

PayoutItem

Position

Payout

Children

Yes

Attributes

No

Elements of PayoutDetails

Element Name

Description

Data type /

Limitations

Required /

Payment

Method

Specific

details

TransactionId

The TransactionId is

a unique identifier

generated by the

integrating

(Merchant) system.

Usually this is the

integrating system’s

internal payment

order reference

number.

String (16);

We Recommend

this value be be

prefixed with the

CompanyId plus

an underscore e.g.

ABC_1234567

(where the

CompanyId is a

value that will be

supplied by

DataCash).

Mandatory for

all Payment

methods

Description

Use this field to

supply descriptive

text for the

transaction.

String (255)

BU

Optional

CL

Optional

EP

Optional

IN

Optional

MB

Optional

NT

Optional

OC

Optional

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

TransactionDateTime

The Merchant’s time

stamp of the

transaction.

String (19);

Format “yyyy-

mm-dd

hh:mm:ss”

BU

Optional

CL

Optional

IN

Optional

MB

Optional

NT

Optional

OC

Optional

UK

Mandatory

UserAgentHeader

This is a value

indicating the

browser type and

operating system

details of the user.

This information can

be retrieved from

the

HTTP_USER_AGENT

header.

String (255)

CL

Optional

IN

Optional

MB

Mandatory

NT

Optional

Language

This field contains

the language in

which the client’s

user experience will

take place. Please

refer to Appendix 13

for supported

languages. This

includes the

following Payment

method’s pages: MB

If no language is

supplied, the value

defaults to “en”

(English).

String (20)

CL

Optional

EP

Optional

IN

Optional

MB

Recommen

ded

NT

Optional

UserIP

Consumer's IP

address.

String (26);

(Format:

255.255.255.255)

CL

Mandatory

IN

Optional

MB

Optional

NT

Optional

CustomerReference

This is the generic

identifier of a

customer.

String(70)

CL

Optional

IN

Mandatory

MB

Optional

NT

Optional

AccountDetails

This is a set of the

merchant’s

authentication

details which is

required in order to

access the APG.

See section 3.3.1.1.1

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

PersonalDetails

This is a set of

consumer specific

details that are

required by the

Processors.

See section 3.3.2.1.8

BillingDetails

This is a set of the

consumer’s billing

details that are

required by the

Processors.

See section 3.3.2.1.3

CustomMerchantDetails

Optional structure

allowing Merchants

to pass custom

fields and values.

See section 3.3.2.1.7

Example XML for PayoutDetails complex elements

<TransactionId>string</TransactionId>

<Description>string</Description>

<TransactionDateTime>string</TransactionDateTime>

<UserIP>string</UserIP>

<UserAgentHeader>string</UserAgentHeader>

<Language>string</Language>

<CustomerReference>string</CustomerReference>

<AccountName>TestAccount</AccountName>

<AccountPIN>TestPIN</AccountPIN>

</AccountDetails>

<FirstName>Jerry</FirstName>

<LastName>Anderson</LastName>

<Telephone1_CountryCode>44</Telephone1_CountryCode>

<Telephone1_AreaCode>105</Telephone1_AreaCode>

<Email>customer@email.com</Email>

<TypeOfID>PASSPORT</TypeOfID>

<SSN/>

<CPF_CNPJ/>

</PersonalDetails>

<StreetLine1>404 Mulberry Court</StreetLine1>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

<StreetLine2>78 Praed Street</StreetLine2>

<City>London</City>

</AddressDetails>

</AmountDetails>

</BillingDetails>

<FieldName>PaymentId</FieldName>

</CustomDetail>

</CustomMerchantDetails>

</payoutDetails>

3.3.3.1.2 methodDetails (PaymentMethodItem)

This is a parent structure from which all the individual specific payout methods are

inherited.

Element Name

methodDetails

Type

PaymentMethodItem

Position

Payout

Children

Yes

Attributes

Yes

Elements of methodDetails

Please refer to the following sections for details relevant to each individual payout

method:

 BU – ClickandBuy see section 3.3.3.1.8

 CL – Click2Pay see section 3.3.3.1.4

 EP – EntroPay see section 3.3.3.1.9

 IN – InstaDebit see section 3.3.3.1.6

 MB – MoneyBookers see section 3.3.3.1.5

 NT – Neteller see section 3.3.3.1.3

 OC – Envoy OneClick see section 3.3.3.1.7

 UK – Ukash see section 3.3.2.1.15

Attributes of methodDetails

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Element Name

Description

Data type /

Limitations

Required / Payout

Method Specific details

xsi:type

This indicates the individual

payout method involved in

this transaction. Refer to

Appendix 7 for the Payout

Method Type options.

Enum

Mandatory for all

Payment methods

Example XML for methodDetails complex elements (individual payout

method structure involved e.g. Click2Pay)

<AccountNumber>string</AccountNumber>

<AccountPIN>string</AccountPIN>

</methodDetails>

3.3.3.1.3 NetellerItem

These are the fields or structures contained within the NetellerItem structure.

Element Name

NetellerItem

Type

NetellerItem

Position

Payout.methodDetails

Children

Yes

Attributes

No

Elements of NetellerItem

Element Name

Description

Data type /

Limitations

Required / Payment Method

Specific details

AccountNumber

Consumer’s NETELLER

Account ID

String (50)

NT

Mandatory

Example XML for NetellerItem complex elements

<AccountNumber>TestAccount</AccountNumber>

3.3.3.1.4 Click2PayItem

These are the fields or structures contained within the Click2PayItem structure.

Element Name

Click2PayItem

Type

Click2PayItem

Position

Payout.methodDetails

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Children

Yes

Attributes

No

Elements of Click2PayItem

Element Name

Description

Data type /

Limitations

Required / Payment

Method Specific

details

AccountNumber

Consumer’s Click2Pay User Name

(in the form of an email address).

String (50)

CL

Mandatory

AccountPIN

Consumer’s Click2Pay Personal

Account Number (PAN) that was

assigned, when they registered

with Click2Pay.

String (50)

CL

Optional

Example XML for Click2PayDetails complex elements

<AccountNumber>test.account@gmail.com</AccountNumber>

<AccountPIN>TestPIN</AccountPIN>

3.3.3.1.5 MoneybookersItem

These are the fields or structures contained within the MoneybookersItem structure.

Element Name

MoneybookersItem

Type

MoneybookersItem

Position

Payout.methodDetails

Children

Yes

Attributes

No

Elements of MoneybookersItem

Element Name

Description

Data type /

Limitations

Required / Payout

Method Specific

details

AccountNumber

Consumer’s MoneyBookers

User Name (in the form of

an email address).

String (50)

MB

Mandatory

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

PaymentMethodType

Payment method for

Moneybookers. For more

information, please refer to

Appendix 16.

Enum

MB

Optional

Example XML for MoneybookersItem complex elements

<AccountNumber>test.account@gmail.com</AccountNumber>

3.3.3.1.6 InstaDebitItem

These are the fields or structures contained within the InstaDebitItem structure.

Element Name

InstaDebitItem

Type

InstaDebitItem

Position

Payout.methodDetails

Children

Yes

Attributes

No

Elements of InstaDebitItem

Element Name

Description

Data type /

Limitations

Required / Payment Method

Specific details

AccountNumber

Consumer’s

InstaDebit User ID.

String (30)

IN

Mandatory

Example XML for InstaDebitItem complex elements

<AccountNumber>DEMO+CUSTOMER+PL6CDYYL</AccountNumber>

3.3.3.1.7 OneClickItem

These are the fields or structures contained within the OneClickItem structure.

Element Name

OneClickItem

Type

OneClickItem

Position

Payout.methodDetails

Children

Yes

Attributes

No

Elements of OneClickItem

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Element Name

Description

Data type /

Limitations

Required / Payment

Method Specific

details

AccountNumber

Consumer’s OneClick account

number (in the form of an

email address or account

number).

String (50)

OC

Mandatory

ServiceType

This indicates the type of

banking service available from

Envoy OneClick. Refer to

Appendix 17.

Enum

OC

Mandatory

UseSaleCurrency

This is to indicate that the

sales currency code and

exponent must be used.

Boolean

OC

Optional

Example XML for OneClickItem complex elements

<AccountNumber>test.account@gmail.com</AccountNumber>

<ServiceType>EWIRE</ServiceType>

3.3.3.1.8 ClickAndBuyItem

These are the fields or structures contained within the ClickAndBuyItem structure.

Element Name

ClickAndBuyItem

Type

ClickAndBuyItem

Position

Payout.methodDetails

Children

Yes

Attributes

No

Elements of ClickAndBuyItem

Element Name

Description

Data type /

Limitations

Required / Payment

Method Specific details

AccountNumber

Consumer’s

ClickAndBuy

account number or

account email.

String (50)

BU

Optional

CreateRecurring

This is not used by

Payouts

Boolean

BU

Optional

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example XML for ClickAndBuyItem complex elements

3.3.3.1.9 EntroPayItem

These are the fields or structures contained within the EntroPayItem structure.

Element Name

EntroPayItem

Type

EntroPayItem

Position

Payout.methodDetails

Children

Yes

Attributes

No

Elements of EntroPayItem

Element Name

Description

Data type /

Limitations

Required / Payment

Method Specific details

AccountReference

Entropay Account

Reference

String (7)

EP

Optional

CardNumber

Entropay

CardNumber

String (24)

EP

Optional

Email

Entropay Email

String (255)

EP

Optional

ClaimCode

Entropay

ClaimCode

String (15)

EP

Optional

PaymentType

This indicates

which security

details will be used

for this transaction.

Refer to Appendix

28.

Enum

EP

Mandatory

EntroPay Note: When submitting an EntroPay (EP) transaction, the below

combinations are allowed per the PaymentType for the EntroPayItem.

Field

Combo 1

Combo 2

Combo 3

PaymentType

EMAIL

CARD_NUMBER

ACCOUNT_REFERENCE

AccountReference

x

CardNumber

x

Email

x

ClaimCode

x

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example XML for EntroPayItem complex elements

<Email>testcustomer@datacash.co.za</Email>

<PaymentType>EMAIL</PaymentType>

</methodDetails>

3.3.3.2 Examples of XML for Payout Requests

3.3.3.2.1 Neteller input values

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xmlns:xsd="http://www.w3.org/2001/XMLSchema">

<soap:Body>

<AccountName>TestAccount</AccountName>

<AccountPIN>TestPIN</AccountPIN>

</AccountDetails>

<FirstName>Caylin</FirstName>

<LastName>Williams</LastName>

<Telephone1_CountryCode>44</Telephone1_CountryCode>

<Telephone1_AreaCode>105</Telephone1_AreaCode>

<Email>customer@email.com</Email>

<TypeOfID>PASSPORT</TypeOfID>

</PersonalDetails>

<StreetLine1>78 Praed Street</StreetLine1>

<City>London</City>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

</AddressDetails>

</AmountDetails>

</BillingDetails>

</payoutDetails>

<AccountNumber>TestMethodAccount</AccountNumber>

</methodDetails>

</Payout>

</soap:Body>

</soap:Envelope>

3.3.3.2.2 Click2Pay input values

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xmlns:xsd="http://www.w3.org/2001/XMLSchema">

<soap:Body>

<AccountName>TestAccount</AccountName>

<AccountPIN>TestPIN</AccountPIN>

</AccountDetails>

<FirstName>Jerry</FirstName>

<LastName>Anderson</LastName>

<Telephone1_CountryCode>44</Telephone1_CountryCode>

<Telephone1_AreaCode>105</Telephone1_AreaCode>

<Email>customer@email.com</Email>

<TypeOfID>PASSPORT</TypeOfID>

</PersonalDetails>

<StreetLine1>123 Roman Street</StreetLine1>

<City>London</City>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

</AddressDetails>

</AmountDetails>

</BillingDetails>

</payoutDetails>

<AccountNumber>test.account@gmail.com</AccountNumber>

<AccountPIN>TestMethodPIN</AccountPIN>

</methodDetails>

</Payout>

</soap:Body>

</soap:Envelope>

3.3.3.2.3 MoneyBookers input values

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xmlns:xsd="http://www.w3.org/2001/XMLSchema">

<soap:Body>

<AccountName>TestAccount</AccountName>

<AccountPIN>TestPIN</AccountPIN>

</AccountDetails>

<LastName>Bakkers</LastName>

<Telephone1_CountryCode>31</Telephone1_CountryCode>

<Telephone1_AreaCode>20</Telephone1_AreaCode>

<Email>customer@email.com</Email>

<TypeOfID>PASSPORT</TypeOfID>

</PersonalDetails>

<StreetLine1>Koningenplein 113</StreetLine1>

<City>Amsterdam</City>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

</AddressDetails>

</AmountDetails>

</BillingDetails>

</payoutDetails>

<AccountNumber>test.account@gmail.com</AccountNumber>

</methodDetails>

</Payout>

</soap:Body>

</soap:Envelope>

3.3.3.2.4 InstaDebit input values

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xmlns:xsd="http://www.w3.org/2001/XMLSchema">

<soap:Body>

<AccountName>TestAccount</AccountName>

<AccountPIN>TestPIN</AccountPIN>

</AccountDetails>

<FirstName>Wolfgang</FirstName>

<LastName>Middendorp</LastName>

<Telephone1_CountryCode>49</Telephone1_CountryCode>

<Telephone1_AreaCode>10</Telephone1_AreaCode>

<Email>customer@email.com</Email>

<SSN/>

</PersonalDetails>

<Name>Wolfgang Middendorp</Name>

<StreetLine1>Berliner Straße 213</StreetLine1>

<City>Berlin</City>

</AddressDetails>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

</AmountDetails>

</BillingDetails>

</payoutDetails>

<AccountNumber>DEMO+CUSTOMER+PL6CDYYL</AccountNumber>

</methodDetails>

</Payout>

</soap:Body>

</soap:Envelope>

3.3.3.2.5 Envoy OneClick input values

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xmlns:xsd="http://www.w3.org/2001/XMLSchema">

<soap:Body>

<AccountName>TestAccount</AccountName>

<AccountPIN>TestPin</AccountPIN>

</AccountDetails>

<LastName>CUSTOMER</LastName>

<Telephone1_CountryCode>0</Telephone1_CountryCode>

<Telephone1_AreaCode>0</Telephone1_AreaCode>

<Telephone2_CountryCode>0</Telephone2_CountryCode>

<Telephone2_AreaCode>0</Telephone2_AreaCode>

<Email>consumer@email.com</Email>

</PersonalDetails>

<Name>Demo Customer</Name>

<StreetLine1>Descartes House</StreetLine1>

<StreetLine2>Centre-du- Québec-Sud</StreetLine2>

<City>Quebec City</City>

</AddressDetails>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

</AmountDetails>

</BillingDetails>

</payoutDetails>

<ServiceType>EWIRE</ServiceType>

<AccountNumber>consumer@email.com</AccountNumber>

</methodDetails>

</Payout>

</soap:Body>

</soap:Envelope>

3.3.3.2.6 ClickAndBuy input values

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xmlns:xsd="http://www.w3.org/2001/XMLSchema">

<soap:Body>

<AccountName>TestAccount</AccountName>

<AccountPIN>TestPin</AccountPIN>

</AccountDetails>

<FirstName>Bridgette</FirstName>

<LastName>Robins</LastName>

<Telephone1_CountryCode>44</Telephone1_CountryCode>

<Telephone1_AreaCode>20</Telephone1_AreaCode>

<Telephone2_CountryCode>0</Telephone2_CountryCode>

<Telephone2_AreaCode>0</Telephone2_AreaCode>

<Email>consumer@email.com</Email>

</PersonalDetails>

<StreetLine1>51 Rocky Road</StreetLine1>

<City>London</City>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

</AddressDetails>

</AmountDetails>

</BillingDetails>

</payoutDetails>

</methodDetails>

</Payout>

</soap:Body>

</soap:Envelope>

3.3.3.2.7 EntroPay input values

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xmlns:xsd="http://www.w3.org/2001/XMLSchema">

<soap:Body>

<AccountName>TestAccount</AccountName>

<AccountPIN>TestPIN</AccountPIN>

</AccountDetails>

<FirstName>Wolfgang</FirstName>

<LastName>Middendorp</LastName>

<Telephone1_CountryCode>49</Telephone1_CountryCode>

<Telephone1_AreaCode>10</Telephone1_AreaCode>

<Email>customer@email.com</Email>

<SSN/>

</PersonalDetails>

<Name>Wolfgang Middendorp</Name>

<StreetLine1>Berliner Straße 213</StreetLine1>

<City>Berlin</City>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

</AddressDetails>

</AmountDetails>

</BillingDetails>

</payoutDetails>

<Email>testcustomer@datacash.co.za</Email>

<PaymentType>EMAIL</PaymentType>

</methodDetails>

</Payout>

</soap:Body>

</soap:Envelope>

3.3.3.2.8 Ukash input values

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xmlns:xsd="http://www.w3.org/2001/XMLSchema">

<soap:Body>

<AccountName>TestAccount</AccountName>

<AccountPIN>TestPIN</AccountPIN>

</AccountDetails>

</AddressDetails>

</AmountDetails>

</BillingDetails>

</payoutDetails>

<TypeOfRedemption>ISSUE_VOUCHER</TypeOfRedemption>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

</methodDetails>

</Purchase>

</soap:Body>

</soap:Envelope>

3.3.3.3 Schema elements for Payout Response

In this section, the fields that can be presented with Payout transaction Responses will

be presented along with example XML for those fields.

The top-level XML element is the Response element. This will be followed by the Event

element, with the Payout method’s response details inside that, in the Payout complex

structure.

Note that various responses will result in various XML formats being returned -

the following list contains some of the response fields, but you should refer to the

XML samples below and in section 3.3.2.5 for further information.

 Response – see section 3.3.1.2.3

o Event – see section 3.3.1.2.2

 Payout – see section 3.3.3.3.2

 PaymentMethod – see section 3.3.3.3.1

o PaymentMethod – specific fields

 Error – see section 3.3.1.2.1

3.3.3.3.1 PaymentMethod

The details involved in the specific Payment Method of this transaction are displayed

here. The top-level element “PaymentMethod” will contain the payment method for the

transaction, while the sub elements will contain the rest of the details.

Element Name:

PaymentMethod

Position

Response.Event.Payout

Children

Yes

Attributes

Yes

Attributes involved in the PaymentMethod element

Attribute Name

Located in which Element

Description

Data type / Limitations

Please refer to section 3.3.2.3.3

Elements of PaymentMethod

Element Name

Description

Data type /

Limitations

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Please refer to section 3.3.2.3.3

Example of XML for PaymentMethod complex elements (The example is

specifically for a successfully completed Neteller transaction)

</PaymentMethod>

3.3.3.3.2 Payout

The results of a Payout transaction will be returned in this complex structure. Note that

the details depend on the Payment Method involved – this is a very dynamic complex

structure that can take on a variety of shapes, depending on the scenario.

Element Name:

Payout

Position

Response.Event

Children

Yes

Attributes

Yes

Attributes involved in the Payout element

Attribute Name

Located in

which

Element

Description

Data type /

Limitations

DPGReferenceId

Payout

The DPGReferenceId is a unique APG

transaction identifier which is generated

by the APG for each merchant

transaction.

Long

TransactionId

Payout

This will return the original TransactionId

that the Merchant sent through. This is

for informational purposes only.

String (16)

CurrencyCode

Amount

This is the transaction currency. Please

refer to Appendix 10.

Short

Exponent

Amount

This is the transaction currency

exponent. Please refer to Appendix 10.

Short

Elements of Payout

Element Name

Description

Data type /

Limitations

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Payout

Top-level XML element indicating a Payout transaction

- the DPGReferenceId and TransactionId for the

transaction are also returned as attributes of this field

– refer to the Attributes table above for more

information.)

PaymentMethod

See section 3.3.2.3.3

Status

This is the response, which

indicates if the transaction was

accepted, or not at the processor.

See Appendix 6 for possible

response messages.

String (20)

Error

See section 3.3.1.2.1. This element will appear in the

Payout XML if the Status = “ERROR”.

Amount

This field contains the amount

payed to the client’s account at the

financial institution. The field type

is a numeric value in cents.

(The currency and exponent for

the amount are also returned as

attributes of this field – refer to the

Attributes table above for more

information.)

Currently available for the

following Payout Methods:

 BU

 CL

 EP

 IN

 MB

 NT

 OC

 UK

Int

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

RecommendedClientMessage

This field contains the

recommended client message that

can be displayed to the consumer.

A list of these messages will be

detailed in the Product Document.

In certain instances, the exact

nature of the error will be hidden

from the consumer e.g. error

relating to merchant account

details. The true nature of the

error can always be found in the

ResponseDescription or Error

Description response fields.

Note: The

RecommendedClientMessage field

might contain end-of-line

characters. Merchants should

design their front-end systems in

such a way that the end-of-line

characters are correctly displayed

to end-users.

For example, if an HTML page is

used as the display method in the

front-end system, the merchant

must replace the end-of-line

characters in the

RecommendedClientMessage field

with the appropriate <BR> tags,

otherwise the HTML front-end will

not display the appropriate line

breaks correctly.

Alternatively, the contents of the

RecommendedClientMessage can

be included in <PRE> tags.

The RecommendedClientMessage

will be returned in the language

which was passed through in

Language field of original

transaction. This is dependent on

whether the language is supported

by APG. If the language is not

supported, the message will

default to English.

String (1000)

Examples of XML for Payout complex elements

Please refer to section 3.3.2.5 for examples per Payment Method.

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

3.3.3.4 Interpreting the Payout Responses

There are various types of possible responses that can be returned from the APG to the

Merchant. These include:

 Successful transaction

 Unsuccessful transaction

 Event notification

Refer to section 3.3.2.5 for examples.

The APG can return multiple responses per transaction, and as a result the merchant

needs to analyze these and perform the appropriate action. Appendix 6 details the

various responses. The Status field will indicate the status of the transaction. The

merchant should only credit the consumer’s account when the Status=AUTHORISED, in

all other cases the merchant should not credit the consumer’s account.

3.3.3.5 Examples of XML for Payout Responses

3.3.3.5.1 Neteller return values

3.3.3.5.1.1 AUTHORISED

<Event>

</PaymentMethod>

<Status>AUTHORISED</Status>

<RecommendedClientMessage><![CDATA[Your transaction has been

processed successfully.]]></RecommendedClientMessage>

</Payout>

</Event>

</Response>

3.3.3.5.1.2 ERROR

<Event>

</PaymentMethod>

<Status>ERROR</Status>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

<Error>

<Description>The Account ID or Secure ID you entered is not

valid. Please enter your correct account

information.</Description>

</Error>

<RecommendedClientMessage><![CDATA[Your request could not be

completed. Please contact merchant customer service for more

information.]]></RecommendedClientMessage>

</Payout>

</Event>

</Response>

3.3.3.5.2 Click2Buy return values

3.3.3.5.2.1 AUTHORISED

<Event>

<ResponseCode>SUCCESS</ResponseCode>

</PaymentMethod>

<Status>AUTHORISED</Status>

<RecommendedClientMessage><![CDATA[Your transaction has been

processed successfully.]]></RecommendedClientMessage>

</Payout>

</Event>

</Response>

3.3.3.5.2.2 PENDING

<Event>

<ResponseCode>CREATED/IN_PROGRESS</ResponseCode>

<ResponseDescription>pending</ResponseDescription>

</PaymentMethod>

<Status>PENDING</Status>

<RecommendedClientMessage><![CDATA[Your request could not be

completed. Please contact merchant customer service for more

information.]]></RecommendedClientMessage>

</Payout>

</Event>

</Response>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

3.3.3.5.2.3 REFUSED

<Event>

<ResponseCode>DECLINED</ResponseCode>

<ResponseDescription>declined</ResponseDescription>

</PaymentMethod>

<Status>REFUSED</Status>

<RecommendedClientMessage><![CDATA[Your request could not be

completed. Please contact merchant customer service for more

information.]]></RecommendedClientMessage>

</Payout>

</Event>

</Response>

3.3.3.5.2.4 CANCELLED

<Event>

<ResponseCode>CANCELLED</ResponseCode>

<ResponseDescription>cancelled</ResponseDescription>

</PaymentMethod>

<Status>CANCELLED</Status>

<RecommendedClientMessage><![CDATA[Your request could not be

completed. Please contact merchant customer service for more

information.]]></RecommendedClientMessage>

</Payout>

</Event>

</Response>

3.3.3.5.2.5 ERROR

<Event>

<ResponseCode>EXPIRED/ABORTED</ResponseCode>

<ResponseDescription>error</ResponseDescription>

</PaymentMethod>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

<Status>ERROR</Status>

<RecommendedClientMessage><![CDATA[Your request could not be

completed. Please contact merchant customer service for more

information.]]></RecommendedClientMessage>

</Payout>

</Event>

</Response>

3.3.3.5.3 Click2Pay return values

3.3.3.5.3.1 AUTHORISED

<Event>

<ResponseDescription>Transaction is

Acknowledged</ResponseDescription>

<PaymentType>FUNDS</PaymentType>

</PaymentMethod>

<Status>AUTHORISED</Status>

<RecommendedClientMessage><![CDATA[Your transaction has been

processed successfully.]]></RecommendedClientMessage>

</Payout>

</Event>

</Response>

3.3.3.5.3.2 REFUSED

<Event>

<ResponseDescription>You have provided invalid CLICK2PAY user

data or the account is not active. Please check and try again.

If the problem persists, please contact our helpdesk at

service@click2pay.com.</ResponseDescription>

</PaymentMethod>

<Status>REFUSED</Status>

<RecommendedClientMessage><![CDATA[Your request could not be

completed. Please contact merchant customer service for more

information.]]></RecommendedClientMessage>

</Payout>

</Event>

</Response>

3.3.3.5.3.3 ERROR

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

<Event>

<ResponseDescription>The supplied CLICK2PAY UserName is wrong.

Please check and try again. If the problem should still exist,

please contact our customer service at

service@click2pay.com.</ResponseDescription>

</PaymentMethod>

<Status>ERROR</Status>

<Error>

<Code/>

</Error>

<RecommendedClientMessage><![CDATA[Your request could not be

completed. Please contact merchant customer service for more

information.]]></RecommendedClientMessage>

</Payout>

</Event>

</Response>

3.3.3.5.4 MoneyBookers return values

3.3.3.5.4.1 AUTHORISE

<Event>

<ResponseDescription>processed</ResponseDescription>

</PaymentMethod>

<Status>AUTHORISED</Status>

<RecommendedClientMessage><![CDATA[Uw transactie is

geslaagd.]]></RecommendedClientMessage>

</Payout>

</Event>

</Response>

3.3.3.5.4.2 PENDING

<Event>

<ResponseDescription>scheduled</ResponseDescription>

</PaymentMethod>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

<Status>PENDING</Status>

<RecommendedClientMessage><![CDATA[Your request could not entirely

be completed. Please check your account later for an updated

status. You may also contact merchant customer service for more

information.]]></RecommendedClientMessage>

</Payout>

</Event>

</Response>

3.3.3.5.4.3 ERROR

<Event>

</PaymentMethod>

<Status>ERROR</Status>

<Error>

<Description>AccountNumber must be supplied</Description>

</Error>

<RecommendedClientMessage><![CDATA[Your request could not be

completed. Please contact merchant customer service for more

information.]]></RecommendedClientMessage>

</Payout>

</Event>

</Response>

3.3.3.5.5 MoneyBookers return values

3.3.3.5.5.1 AUTHORISE

<Event>

<ResponseDescription>processed</ResponseDescription>

</PaymentMethod>

<Status>AUTHORISED</Status>

<RecommendedClientMessage><![CDATA[Uw transactie is

geslaagd.]]></RecommendedClientMessage>

</Payout>

</Event>

</Response>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

3.3.3.5.5.2 PENDING

<Event>

<ResponseDescription>scheduled</ResponseDescription>

</PaymentMethod>

<Status>PENDING</Status>

<RecommendedClientMessage><![CDATA[Your request could not entirely

be completed. Please check your account later for an updated

status. You may also contact merchant customer service for more

information.]]></RecommendedClientMessage>

</Payout>

</Event>

</Response>

3.3.3.5.5.3 ERROR

<Event>

</PaymentMethod>

<Status>ERROR</Status>

<Error>

<Description>AccountNumber must be supplied</Description>

</Error>

<RecommendedClientMessage><![CDATA[Your request could not be

completed. Please contact merchant customer service for more

information.]]></RecommendedClientMessage>

</Payout>

</Event>

</Response>

3.3.3.5.6 InstaDebit return values

3.3.3.5.6.1 AUTHORISED

<Event>

<ResponseDescription>Success</ResponseDescription>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

<txn_fee>0.00</txn_fee>

</PaymentMethod>

<Status>AUTHORISED</Status>

<RecommendedClientMessage><![CDATA[Your transaction has been

processed successfully..]]></RecommendedClientMessage>

</Payout>

</Event>

</Response>

3.3.3.5.6.2 ERROR

<Event>

</PaymentMethod>

<Status>ERROR</Status>

<Error>

<Description>The InstaDebit notification is

invalid</Description>

3.3.3.5.6.3 REFUSED

<Event>

<ResponseDescription>Declined</ResponseDescription>

</PaymentMethod>

<Status>REFUSED</Status>

<RecommendedClientMessage><![CDATA[Your request could not be

completed. Please contact merchant customer service for more

information.]]></RecommendedClientMessage>

</Payout>

</Event>

</Response>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

3.3.4 Transaction Querying

The TransactionQuery call to the APG Web Service is used to determine the current

status of a transaction which was previously submitted. The result from the request will

determine if the transaction has completed processing or not.

The APG exposes two web methods that allows the querying of transactions.

1. TransactionQuery – Allows transaction querying by “DPGReferenceId”.

2. TransactionQueryByTransactionId – Allows transaction querying by

“TransactionId”, “TransactionType”, “PaymentMethod”

3.3.4.1 TransactionQuery

The TransactionQuery web method accepts two parameters: accountDetails of type

AccountItem, and “DPGReferenceId” of type Long. The AccountItem type is a custom

complex structure. For more information on the composition of this structure, please

refer to the WSDL which can be downloaded from the URLs specified in section 3.2.1.

3.3.4.1.1 Schema Elements for TransactionQuery Request

In this section, the fields that can be presented with TransactionQuery transaction

Requests will be presented along with example XML for those fields.

 TransactionQuery

o Account Details – see section 3.3.1.1.1

o DPGReferenceID

SOAP XML TransactionQuery Request document:

<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xmlns:xsd="http://www.w3.org/2001/XMLSchema"

xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">

<soap:Body>

<AccountName>string</AccountName>

<AccountPIN>string</AccountPIN>

<CompanyId>string</CompanyId>

</accountDetails>

</TransactionQuery>

</soap:Body>

</soap:Envelope>

3.3.4.1.2 TransactionQuery Structure

Element Name

TransactionQuery

Type

TransactionQuery

Position

Soap:Body

Children

Yes

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Attributes

Yes

Elements of TransactionQuery

Element Name

Description

Data type / Limitations

accountDetails

This is a set of the

merchant’s

authentication details

which is required in

order to access the

APG.

AccountItem – see section 3.3.1.1.1

DPGReferenceID

The DPGReferenceId is

a unique APG

transaction identifier

which is generated by

the APG for each

merchant transaction.

This identifier is

returned in the

response to a Purchase

or Payout transaction.

Long

This value is mandatory at all times.

See the next section for an XML example.

3.3.4.1.3 Example of XML for TransactionQuery Requests

<soap12:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xmlns:xsd="http://www.w3.org/2001/XMLSchema"

xmlns:soap12="http://www.w3.org/2003/05/soap-envelope">

<soap12:Body>

<AccountName>TestAccount</AccountName>

<AccountPIN>TestPIN</AccountPIN>

</accountDetails>

</TransactionQuery>

</soap12:Body>

</soap12:Envelope>

3.3.4.2 TransactionQueryByTransactionId

The TransactionQueryByTransactionId web method accepts four parameters:

accountDetails of type AccountItem, “TransactionId” of type string, “TransactionType”

of type enum, and “PaymentMethod” of type string. The AccountItem type is a custom

complex structure. For more information on the composition of this structure, please

refer to the WSDL which can be downloaded from the URLs specified in section 3.2.1

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

3.3.4.2.1 Schema Elements for TransactionQueryByTransactionId Request

In this section, the fields that can be presented with TransactionQueryByTransactionId

transaction Requests will be presented along with example XML for those fields.

 TransactionQueryByTransactionId

o Account Details – see section 3.3.1.1.1

o TransactionId

o PaymentMethod

o TransactionType

SOAP XML TransactionQueryByTransactionId Request document:

<soap12:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xmlns:xsd="http://www.w3.org/2001/XMLSchema"

xmlns:soap12="http://www.w3.org/2003/05/soap-envelope">

<soap12:Body>

<TransactionQueryByTransactionId xmlns="http://DPG-

CPT.datacash.com/">

<AccountName>TestAccount</AccountName>

<AccountPIN>TestPIN</AccountPIN>

</accountDetails>

<TransactionType>PURCHASE</TransactionType>

</TransactionQueryByTransactionId>

</soap12:Body>

</soap12:Envelope>

3.3.4.2.2 TransactionQueryByTransactionId Structure

Element Name

TransactionQueryByTransactionId

Type

TransactionQueryByTransactionId

Position

Soap:Body

Children

Yes

Attributes

Yes

Elements of TransactionQuery

Element Name

Description

Data type / Limitations

accountDetails

This is a set of the

merchant’s

authentication details

which is required in

order to access the

APG.

AccountItem – see section 3.3.1.1.1

Mandatory

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

TransactionID

The TransactionId is a

unique identifier

generated by the

integrating (Merchant)

system. Usually this is

the integrating

system’s internal

payment order

reference number.

String (16)

Mandatory

PaymentMethod

The payment method

of the transaction.

String (3)

Mandatory

TransactionType

This is a indicator as to

what they of

transaction should be

searched for.

Possible Values:

 PURCHASE

 PAYOUT

String Enum

Mandatory

See the next section for an XML example.

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

3.3.4.2.3 Example of XML for TransactionQuery Request

<soap12:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xmlns:xsd="http://www.w3.org/2001/XMLSchema"

xmlns:soap12="http://www.w3.org/2003/05/soap-envelope">

<soap12:Body>

<TransactionQueryByTransactionId xmlns="http://DPG-

CPT.datacash.com/">

<AccountName>TestAccount</AccountName>

<AccountPIN>TestPIN</AccountPIN>

</accountDetails>

<TransactionType>PURCHASE</TransactionType>

</TransactionQueryByTransactionId>

</soap12:Body>

</soap12:Envelope>

3.3.4.3 Schema Elements and Example XML for TransactionQuery and

TransactionQueryByTransactionId Response

The Response that is generated for a TransactionQuery and

TransactionQueryByTransactionId Request is similar to the Response that is generated

for a Purchase or Payout transaction.

See section 3.3.2.4 for details of the Purchase (and TransactionQuery)

Response structure.

See section 3.3.2.5 for examples of these Responses.

See section 3.3.3.2 for details of the Payout (and TransactionQuery)

Response structure.

See section 3.3.3.5 for examples of these Responses.

The following is a list of possible results that can be returned by the TransactionQuery

or TransactionQueryByTransactionId web method’s Status fields:

 AUTHORISED

 CANCELLED

 PENDING

 UNKNOWN

 ERROR

 NOTFOUND

 FRAUD_REJECTED

 REFUNDED

 REFUSED

 SENT_FOR_CAPTURE

 SENT_FOR_REFUND

 CAPTURED

 CHARGED_BACK

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

3.3.5 RetrieveSettlementValue

The RetrieveSettlementValue call to the APG Web Service is used to retrieve the

settlement amount when the currency of the merchant account and the voucher/user

account is different. This service is only available for the following payment method:

 UK

The RetrieveSettlementValue web method accepts six parameters: “TransactionId” of

type string, “PaymentMethod” of type string, “AccountNumber” of type string,

“Language” of type string, AccountDetails of type AccountItem and AmountDetails of

type AmountItem. The AccountItem and AmountItem types are custom complex

structures. For more information on the composition of this structure, please refer to

the WSDL which can be downloaded from the URLs specified in section 3.2.1.

3.3.5.1 Schema Elements for RetrieveSettlementValue Request

In this section, the fields that can be presented with RetrieveSettlementValue

transaction Requests will be presented along with example XML for those fields.

 RetrieveSettlementValue

o TransactionID

o PaymentMethod

o AccountNumber

o Language

o AccountDetails – section 3.3.1.1.1

o AmountDetails – section 3.3.1.1.2

SOAP XML RetrieveSettlementValue Request document:

<soap12:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xmlns:xsd="http://www.w3.org/2001/XMLSchema"

xmlns:soap12="http://www.w3.org/2003/05/soap-envelope">

<soap12:Body>

<TransactionId>string</TransactionId>

<PaymentMethod>string</PaymentMethod>

<AccountNumber>string</AccountNumber>

<Language>string</Language>

<AccountName>string</AccountName>

<AccountPIN>string</AccountPIN>

<CompanyId>string</CompanyId>

</AccountDetails>

<Exponent>short</Exponent>

<CurrencyCode>short</CurrencyCode>

</AmountDetails>

</RetrieveSettlementValue>

</soap12:Body>

</soap12:Envelope>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

3.3.5.1.1 RetrieveSettlementValue

Element Name

RetrieveSettlementValue

Type

RetrieveSettlementValue

Position

Soap:Body

Children

Yes

Attributes

Yes

Elements of RetrieveSettlementValue

Element Name

Description

Data type / Limitations

Required

TransactionID

The TransactionId is a

unique identifier generated

by the integrating

(Merchant) system.

Usually this is the

integrating system’s

internal payment order

reference number.

String (16)

This value must be

prefixed with the

CompanyId plus an

underscore e.g.

ABC_1234567 (where the

CompanyId is a value that

will be supplied by

DataCash).

Mandatory

PaymentMethod

The payment method of

the transaction.

String (3)

Mandatory

AccountNumber

Digits 7-9 of the

consumer’s Voucher or

Account number.

String (3)

Mandatory

Language

This field contains the

language in which the

client’s user experience

will take place.

String (20)

Mandatory

AccountDetails

This is a set of the

merchant’s authentication

details which is required in

order to access the APG.

AccountItem – see section

3.3.1.1.1

Mandatory

AmountDetails

This is a set of amount

details.

AmountItem – see section

3.3.1.1.2.

Mandatory

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

3.3.5.2 Example of XML for RetrieveSettlementValue Requests

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"

xmlns:xsi="http://www.w3.org/2xxxxxxxxxxxxxxxx/XMLSchema-instance"

xmlns:xsd="http://www.w3.org/2xxxxxxxxxxxxxxxx/XMLSchema">

<soap:Body>

<AccountNumber>AccountNum</AccountNumber>

<AccountName>TestAccount</AccountName>

<AccountPIN>TestPIN</AccountPIN>

</AccountDetails>

</AmountDetails>

</RetrieveSettlementValue>

</soap:Body>

</soap:Envelope>

3.3.5.3 Schema Elements for RetrieveSettlementValue Response

The following is a list of possible results that can be returned by the

RetrieveSettlementValue web method in the Status field:

 INFORMATION_SUPPLIED

 ERROR

3.3.5.3.1 Settlement

The results of a RetrieveSettlementValue transaction will be returned in this complex

structure.

Element Name:

Settlement

Position

Response.Event

Children

Yes

Attributes

Yes

Attributes involved in the Settlement element

Attribute Name

Located in which

Element

Description

Data type /

Limitations

TransactionId

Settlement

This will return the original

TransactionId that the Merchant

sent through. This is for

informational purposes only.

String (16)

CurrencyCode

Amount

This is the transaction currency.

Please refer to Appendix 10.

Short

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Exponent

Amount

This is the transaction currency

exponent. Please refer to Appendix

10.

Short

name

PaymentMethod

This string value will be equal to “UK”

Elements of Settlement

Element Name

Description

Data type / Limitations

Settlement

Top-level XML element indicating a

RetrieveSettlementValue transaction. The

TransactionId for the transaction is also returned as

an attribute of this field – refer to the Attributes table

above for more information.)

PaymentMethod

See section 3.3.3.3.1.

The name for the payment method is also returned as

an attribute of this field – refer to the Attributes table

above for more information.)

Note: This complex structure will contain the

AmountReference field for this

RetrieveSettlementValue transaction. This is a value

returned by the Ukash processor to uniquely identify

the settlement amount transaction.

Status

This is the response to the

RetrieveSettlementValue

transaction.

String (20)

These are the possible

values:

 INFORMATION_SUPPLIED

 ERROR

Error

See section 3.3.1.2.1. This element will appear in the

Settlement XML if the Status = “ERROR”.

Amount

This field contains the

amount taken from the

client’s account at the

financial institution. The

field type is a numeric

value in cents.

(The currency and

exponent for the amount

are also returned as

attributes of this field –

refer to the Attributes

table above for more

information.)

Int

RecommendedClientMessage

See section 3.3.2.3.4 for more information.

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example of XML for Settlement complex elements

<ResponseDescription>Settlement Amount

Retrieved</ResponseDescription>

</PaymentMethod>

<Status>INFORMATION_SUPPLIED</Status>

<RecommendedClientMessage><![CDATA[Your transaction has been

processed successfully.]]></RecommendedClientMessage>

</Settlement>

3.3.5.4 Example XML for RetrieveSettlementValue Response

3.3.5.4.1 Successful transaction

<Event>

<ResponseDescription>Settlement Amount

Retrieved</ResponseDescription>

</PaymentMethod>

<Status>INFORMATION_SUPPLIED</Status>

<RecommendedClientMessage><![CDATA[Your transaction has been

processed successfully.]]></RecommendedClientMessage>

</Settlement>

</Event>

</Response>

3.3.5.4.2 Unsuccessful transaction

<Event>

<ResponseDescription>Failed</ResponseDescription>

</PaymentMethod>

<Status>ERROR</Status>

<Error>

<Description>Required Currency Conversion not

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

supported</Description>

</Error>

<RecommendedClientMessage><![CDATA[Your request could not be

completed. Please contact merchant customer service for more

information.]]></RecommendedClientMessage>

</Settlement>

</Event>

</Response>

3.3.6 GetInformation

The GetInformation call to the APG Web Service retrieves information that can be used

for the processing of a transaction. This service is only available for the following

payment methods

 AM

 BT

 EV

 I3

 MB

The GetInformation web method accepts 2 parameters: accountDetails of type

AccountItem and methodDetails of type PaymentMethodItem. The AccountItem and

PaymentMethodItem types are custom complex structures. For more information on

the composition of this structure, please refer to the WSDL which can be downloaded

from the URLs specified in section 3.2.1.

3.3.6.1 Schema Elements for GetInformation Request

In this section, the fields that can be presented with GetInformation transaction

Requests will be presented along with example XML for those fields.

 InformationRequest – see section 3.3.6.1.4

o AccountDetails – see section 3.3.1.1.1

o MethodDetails – see section 3.3.2.1.27

 DBTItem – see section 3.3.6.1.1

 ExperCashChargeBackItem – see section 3.3.6.1.2

 iDealBankListItem – see section 3.3.2.1.23

 MoneybookerItem – see section 3.3.2.1.12

SOAP XML GetInformation Request document:

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xmlns:xsd="http://www.w3.org/2001/XMLSchema">

<soap:Body>

<AccountName>string</AccountName>

<AccountPIN>string</AccountPIN>

<CompanyId>string</CompanyId>

</accountDetails>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

<ServiceType> COUNTRY_LIST or

BANK_TRANSFER_DETAILS</ServiceType>

<Language>string</Language>

<AccountNumber>string</AccountNumber>

<Country>string</Country>

<CurrencyCode>string</CurrencyCode>

<FirstName>string</FirstName>

<LastName>string</LastName>

</methodDetails>

</InformationRequest>

</soap:Body>

</soap:Envelope>

3.3.6.1.1 DBTItem

These are the fields or structures contained within the DBTItem structure.

Element Name

DBTItem

Type

DBTItem

Position

InformationRequest.methodDetails

Children

Yes

Attributes

No

Elements of DBTItem

Element Name

Description

Data type /

Limitations

Required / Payment Method

Specific details

ServiceType

This indicates the

type of

transaction

request for DBT.

Refer to Appendix

18.

Enum

BT

Mandatory

Language

This is the ISO

language code of

the consumer.

Refer to Appendix

13.

String (20)

BT

Mandatory

AccountNumber

Unique Account

number assigned

by the Merchant

to identify a

customer’s

account. If a

unique number or

username is not

used, insert the

Customer’s email

address into this

field.

String (50)

BT

Optional.

Mandatory if ServiceType =

“BANK_TRANSFER_DETAILS”.

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Country

This is the

country code of

the consumer.

Refer to Appendix

9.

String (60)

BT

Optional.

Mandatory if ServiceType =

“BANK_TRANSFER_DETAILS”.

CurrencyCode

This is the ISO

currency code of

the account of

the consumer.

Refer to Appendix

10.

Short

BT

Optional.

Mandatory if ServiceType =

“BANK_TRANSFER_DETAILS”.

FirstName

The first name of

the merchant’s

customer

String (100)

BT

Optional.

Mandatory if ServiceType =

“BANK_TRANSFER_DETAILS”.

LastName

The last name of

the merchant’s

customer

String (100)

BT

Optional.

Mandatory if ServiceType =

“BANK_TRANSFER_DETAILS”.

Example XML for DBTItem complex elements

<ServiceType>COUNTRY_LIST</ServiceType>

<AccountNumber>TestMethodAccount</AccountNumber>

<LastName>Jackson</LastName>

3.3.6.1.2 ExperCashChargeBackItem

These are the fields or structures contained within the ExperCashChargeBackItem

structure.

Elements of ExperCashChargebackItem

Element

Name

Description

Data

type/Limitations

Required / Payment

Method Specific

details

StartDate

This indicates the start date

and time to retrieve the

chargeback

String

EV

Optional

Element Name

ExperCashChargeBackItem

Type

ExperCashChargeBackItem

Position

GetInformation.methodDetails

Children

Yes

Attributes

No

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

EndDate

This indicates the end date and

time to retrieve the

chargeback.

String

EV

Optional

Example XML for ExperCashChargebackItem complex elements

3.3.6.1.3 AmazonItem

These are the fields or structures contained within the AmazonItem structure.

Element Name

AmazonItem

Type

AmazonItem

Position

InformationRequest.methodDetails

Children

Yes

Attributes

No

Elements of AmazonItem

Element

Name

Description

Data

type/Limitations

Required / Payment

Method Specific

details

AmazonCont

ractID

The Amazon Contract ID

String

AM

Mandatory

Example XML for ExperCashChargebackItem complex elements

amzn1.contract.1.1.1.8a34d7a8db9a4e8be2b25d9e2e67fff1</AmazonContractID

>

3.3.6.1.4 InformationRequest

Element Name

InformationRequest

Type

InformationRequest

Position

Soap:Body

Children

Yes

Attributes

Yes

Elements of InformationRequest

Element Name

Description

Data type / Limitations

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

accountDetails

This is a set of the

merchant’s authentication

details which is required in

order to access the APG.

AccountItem – see section 3.3.1.1.1

methodDetails

This is a parent structure

from which all the

individual specific payment

methods are inherited.

For the

InformationRequest

structure, only the

DBTItem and

ExperCashChargeBackItem

are involved.

PaymentMethodItem – see section

3.3.3.3.1.

For details of the DBTItem, see section

3.3.6.1.1.

For details of the

ExperCashChargeBackItem, see section

3.3.6.1.2

3.3.6.2 Examples of XML for GetInformation Requests

3.3.6.2.1 “Bank Transfer Details” input values

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xmlns:xsd="http://www.w3.org/2001/XMLSchema">

<soap:Body>

<AccountName>TestAccount</AccountName>

<AccountPIN>TestPIN</AccountPIN>

</accountDetails>

<ServiceType>BANK_TRANSFER_DETAILS</ServiceType>

<AccountNumber>TestMethodAccount</AccountNumber>

</methodDetails>

</GetInformation >

</soap:Body>

</soap:Envelope>

3.3.6.2.2 “Country List” input values

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xmlns:xsd="http://www.w3.org/2001/XMLSchema">

<soap:Body>

<AccountName>TestAccount</AccountName>

<AccountPIN>TestPIN</AccountPIN>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

</accountDetails>

<ServiceType>COUNTRY_LIST</ServiceType>

</methodDetails>

</GetInformation>

</soap:Body>

</soap:Envelope>

3.3.6.2.3 “Chargeback” input values

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xmlns:xsd="http://www.w3.org/2001/XMLSchema">

<soap:Body>

<AccountName>TestAccount</AccountName>

<AccountPIN>TestPIN</AccountPIN>

</accountDetails>

</methodDetails>

</GetInformation>

</soap:Body>

</soap:Envelope>

3.3.6.2.4 MoneyBookers input values

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xmlns:xsd="http://www.w3.org/2001/XMLSchema">

<soap:Body>

<AccountName>TestAccount</AccountName>

<AccountPIN>TestPIN</AccountPIN>

</accountDetails>

<AccountNumber>test@email.com</AccountNumber>

</methodDetails>

</GetInformation>

</soap:Body>

</soap:Envelope>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

3.3.6.2.5 Amazon Contract input values

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xmlns:xsd="http://www.w3.org/2001/XMLSchema">

<soap:Body>

<AccountName>TestAccount</AccountName>

<AccountPIN>TestPIN</AccountPIN>

</accountDetails>

amzn1.contract.1.1.1.8a34d7a8db9a4e8be2b25d9e2e67fff1AmazonContractID>

</methodDetails>

</GetInformation>

</soap:Body>

</soap:Envelope>

3.3.6.2.6 iDeal Bank List input values

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xmlns:xsd="http://www.w3.org/2001/XMLSchema">

<soap:Body>

<AccountName>TestAccount</AccountName>

<AccountPIN>TestPIN</AccountPIN>

</accountDetails>

</methodDetails>

</GetInformation>

</soap:Body>

</soap:Envelope>

3.3.6.3 Schema Elements and Example XML for GetInformation Response

The following is a list of possible results that can be returned by the GetInformation

web method in the Status field:

 INFORMATION_SUPPLIED

 ERROR

3.3.6.3.1 Country

Element Name:

Country

Position

Response.Event.Information.PaymentMethod.Countries

Children

Yes

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Attributes

No

Elements of Country

Element Name

Description

Data type / Limitations

Code

This is the ISO code of the country.

String (2)

Name

This is the name of the country.

String (30)

Example of XML for Country complex elements

<Name>Netherlands</Name>

</Country>

3.3.6.3.2 Backcharge

Element Name:

backcharge

Position

Response.Event.Information.PaymentMethod.backcharge

Children

Yes

Attributes

No

Elements of backcharge

Element Name

Description

Data type / Limitations

epi_payment_id

PaymentID of the

chargeback.

String (15)

epi_backcharge_date

Date of the chargeback

DateTime

epi_backcharge_type

Always “DD” for direct

debit

String(2)

epi_backcharge_reason

Reason for chargeback

Integer

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Example of XML for Backcharge complex elements

<epi_payment_id>DD0328222535000</epi_payment_id>

<epi_backcharge_date>20031021</epi_backcharge_date>

<epi_backcharge_type>DD</epi_backcharge_type>

<epi_backcharge_reason>100</epi_backcharge_reason>

</backcharge>

3.3.6.3.3 PurchaseContract

Element Name:

PurchaseContract

Position

Response.Event.Information.PaymentMethod.PurchaseContract

Children

Yes

Attributes

No

Elements of PurchaseContract

Element Name

Description

Data type / Limitations

Id

PurchaseContractId

String (255)

ExpirationTimeStamp

Expiration Time of

PurchaseContract

DateTime

MerchantId

AWS MerchantId

String

MarketplaceId

AWS MarketplaceId

String

State

PurchaseContract State

String

Destinations

Delivery Destinations

Array of Destination

Elements. See section

3.3.6.3.3.1

ShippingAddress->Name

Shipping Name

String

ShippingAddress->

AddressLineOne

Shipping Address Line One

String

ShippingAddress->

AddressLineTwo

Shipping Address Line Two

String

ShippingAddress-> City

Shipping Address City

String

ShippingAddress-> PostalCode

Shipping Address Postal

Code

String

ShippingAddress->

CountryCode

Shipping Address Country

Code

String

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

ShippingAddress->

PhoneNumber

Shipping Addresss Phone

Number

String

3.3.6.3.3.1 Destination

Element Name:

Destination

Position

Response.Event.Information.PaymentMethod.PurchaseContract.

Destination

Children

Yes

Attributes

No

Elements of Destination

Element Name

Description

Data type / Limitations

DestinationName

Delivery Destinations

String

DestinationType

Delivery Destinations

String

PhysicalDestinationAttributes

Delivery Destinations

ShippingAddress see

section 3.3.6.3.3.2

3.3.6.3.3.2 ShippingAddress

Element Name:

Destination

Position

Response.Event.Information.PaymentMethod.PurchaseContract.

Destination.PhysicalDestinationAttributes.ShippingAddress

Children

Yes

Attributes

No

Elements of Destination

Element Name

Description

Data type / Limitations

Name

Shipping Name

String

AddressLineOne

Shipping Address Line One

String

AddressLineTwo

Shipping Address Line Two

String

City

Shipping Address City

String

PostalCode

Shipping Address Postal

Code

String

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

CountryCode

Shipping Address Country

Code

String

PhoneNumber

Shipping Addresss Phone

Number

String

Example of XML for PurchaseContract complex elements

<Id xmlns="http://payments.amazon.com/checkout/v2/2010-08-

31/">amzn1.contract.1.1.1.a90ea1f23f87f4d395213ce3f5c340ce</Id>

<ExpirationTimeStamp

xmlns="http://payments.amazon.com/checkout/v2/2010-08-31/">2011-04-

04T17:07:14.285Z</ExpirationTimeStamp>

<MerchantId xmlns="http://payments.amazon.com/checkout/v2/2010-

08-31/">A98E8GW3O4IUZ</MerchantId>

<MarketplaceId

xmlns="http://payments.amazon.com/checkout/v2/2010-08-

31/">A1V3LO6WH786V3</MarketplaceId>

<State xmlns="http://payments.amazon.com/checkout/v2/2010-08-

31/">ACTIVE</State>

<Destinations

xmlns="http://payments.amazon.com/checkout/v2/2010-08-31/">

<DestinationName>#default</DestinationName>

<DestinationType>PHYSICAL</DestinationType>

<Name>Ajmuddien Hoosain</Name>

<AddressLineOne>FLAT, HABIB HOUSE 9

13</AddressLineOne>

<AddressLineTwo>FULHAM HIGH STREET</AddressLineTwo>

<City>LONDON</City>

</ShippingAddress>

</PhysicalDestinationAttributes>

</Destination>

</Destinations>

</PurchaseContract>

3.3.6.3.4 iDeal Bank List

Element Name:

banks

Position

Response.Event.Information.PaymentMethod.banks

Children

Yes

Attributes

Yes

Elements of Bank

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Element

Name

Description

Data type /

Limitations

bank

Complex Element holding the individual bank

details.

Complex Element

issuer_id

Banks unique Issuer Id.

int

name

Bank name

String(30)

Attributes of Bank

Element Name

Description

Data type /

Limitations

listType

Indicator for where the bank should be

displayed on the merchant web site.

Values which can be returned:

 short

 long

String (20)

Example of XML for Country complex elements

<banks>

<issuer_id>121</issuer_id>

<name>Test Issuer</name>

</bank>

<issuer_id>151</issuer_id>

<name>Test Issuer 2</name>

</bank>

<issuer_id>171</issuer_id>

<name>Test Issuer 3</name>

</bank>

</banks>

3.3.6.3.5 PaymentMethod

Please note that not all the elements in this complex structure are always returned –

please see the XML examples for a further explanation.

Element Name:

PaymentMethod

Position

Response.Event.Information

Children

Yes

Attributes

Yes

Attributes involved in the PaymentMethod element

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Attribute Name

Located in which

Element

Description

Data type / Limitations

name

PaymentMethod

This string value will be equal to “AM”,

“BT”, “EV”, “I3” or “MB”

Elements of PaymentMethod

Element Name

Description

Data type /

Limitations

ResponseCode

This is a return code, which gets returned by

the processor.

String (10)

ResponseDescription

This is a text field used to give a short text

description of the response code from the

processor.

String

(255)

BankName

This is the bank name of the account.

String (50)

AccountHoldingBranch

This is the branch where the account was

registered.

String (50)

GiroNumber

Additional information pertaining to the bank

account.

String (50)

BranchCode

The code of the branch.

String (20)

BankCode

The code of the bank where the account was

registered.

String (20)

BSB

Additional information pertaining to the bank

account.

String (20)

AccountNumber

The number of the bank account.

String (20)

AccountName

The name of the bank account.

String (35)

CheckDigit

The check digit of the account number

Short

Sortcode

Additional information pertaining to the bank

account.

String (15)

IBAN

Additional information pertaining to the bank

account.

String (35)

SwiftBIC

Additional information pertaining to the bank

account.

String (15)

DBTVAN

VAN model: The customer’s Direct Bank

Transfer reference number (Virtual Account

Number)

Merchant Reference model: beneficiary

reference including Merchant Reference

prefix.

String(30)

timestamp

Time of the reply (only if there is an error)

DateTime

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

taid

TransactionID (only if there is an error)

String(20)

Countries

A list of country details, each one contained in a country

complex structure – see section 3.3.6.3.1

Backcharges

A list of backcharges, each one contained in a backcharge

complex structure – see section 3.3.6.3.2

PurchaseContract

Amazon PurchaseContract – see section 3.3.6.3.3

For examples of XML for PaymentMethod complex elements, see section

3.3.6.4

3.3.6.3.6 Information

Please note that not all the elements in this complex structure are always returned –

please see the XML examples for a further explanation.

Element Name:

Information

Position

Response.Event

Children

Yes

Attributes

Yes

Attributes involved in the Information element

Attribute Name

Located in

which Element

Description

Data

type

InformationId

Information

This is an ID to identify the information

request and response. This field will comprise

of the CompanyId and the current date and

time, e.g. “A99_090204143312093”.

String

(19)

Elements of Information

Element Name

Description

Data type / Limitations

PaymentMethod

See section 3.3.6.3.5

Status

This is the response to

the GetInformation

transaction.

String (20)

These are the possible

values:

 INFORMATION_SUPPLIED

 ERROR

RecommendedClientMessage

See section 3.3.2.3.4 for more information.

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Error

See section 3.3.1.2.1. This element will appear in the

Information XML if the Status = “ERROR”.

Example of XML for Information complex elements

See the samples in section 3.3.6

3.3.6.4 Examples of XML for GetInformation Responses

3.3.6.4.1 “Bank Transfer Details” response values

<Event>

<ResponseDescription>Bank Transfer Details

Retrieved</ResponseDescription>

<AccountHoldingBranch>Amsterdam</AccountHoldingBranch>

<BSB/>

<AccountName>TestAccountName</AccountName>

</PaymentMethod>

<Status>INFORMATION_SUPPLIED</Status>

<RecommendedClientMessage><![CDATA[Requested information has been

provided.]]></RecommendedClientMessage>

</Information>

</Event>

</Response>

3.3.6.4.2 “Country List” response values

<Event>

<ResponseDescription>Countries Retrieved</ResponseDescription>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

<Name>Netherlands</Name>

</Country>

</Countries>

</PaymentMethod>

<Status>INFORMATION_SUPPLIED</Status>

<RecommendedClientMessage><![CDATA[Requested information has been

provided.]]></RecommendedClientMessage>

</Information>

</Event>

</Response>

3.3.6.4.3 “BackCharge” response values

<Event>

<ResponseCode>Success</ResponseCode>

<ResponseDescription>Success</ResponseDescription>

<epi_payment_id>DD0328222535000</epi_payment_id>

<epi_backcharge_date>20031021</epi_backcharge_date>

<epi_backcharge_type>DD</epi_backcharge_type>

<epi_backcharge_reason>100</epi_backcharge_reason>

</BackCharges>

</PaymentMethod>

<Status>INFORMATION_SUPPLIED</Status>

<RecommendedClientMessage>string</RecommendedClientMessage>

</Information>

</Event>

</Response>

3.3.6.4.4 Unsuccessful response values

<Event>

</PaymentMethod>

<Status>ERROR</Status>

<Error>

<Description>AccountDetails must be supplied</Description>

</Error>

<RecommendedClientMessage><![CDATA[Your request could not be

completed. Please contact the merchant's customer service for

more information.]]></RecommendedClientMessage>

</Information>

</Event>

</Response>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

3.3.6.4.5 “PurchaseContract” response values

<Event>

<Id xmlns="http://payments.amazon.com/checkout/v2/2010-08-

31/">amzn1.contract.1.1.1.a90ea1f23f87f4d395213ce3f5c340ce</Id>

<ExpirationTimeStamp

xmlns="http://payments.amazon.com/checkout/v2/2010-08-31/">2011-04-

04T17:07:14.285Z</ExpirationTimeStamp>

<MerchantId

xmlns="http://payments.amazon.com/checkout/v2/2010-08-

31/">A98E8GW3O4IUZ</MerchantId>

<MarketplaceId

xmlns="http://payments.amazon.com/checkout/v2/2010-08-

31/">A1V3LO6WH786V3</MarketplaceId>

<State xmlns="http://payments.amazon.com/checkout/v2/2010-08-

31/">ACTIVE</State>

<Destinations

xmlns="http://payments.amazon.com/checkout/v2/2010-08-31/">

<DestinationName>#default</DestinationName>

<DestinationType>PHYSICAL</DestinationType>

<Name>Ajmuddien Hoosain</Name>

<AddressLineOne>FLAT, HABIB HOUSE 9

13</AddressLineOne>

<AddressLineTwo>FULHAM HIGH STREET</AddressLineTwo>

<City>LONDON</City>

</ShippingAddress>

</PhysicalDestinationAttributes>

</Destination>

</Destinations>

</PurchaseContract>

</PaymentMethod>

<Status>INFORMATION_SUPPLIED</Status>

<RecommendedClientMessage><![CDATA[Your transaction has been

processed successfully.]]></RecommendedClientMessage>

</Information>

</Event>

</Response>

3.3.6.4.6 MoneyBooker response values

<Event>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

<ResponseDescription>Customer Information

retrieved</ResponseDescription>

<LOCKLEVEL>NOT_LOCKED</LOCKLEVEL>

</PaymentMethod>

<Status>INFORMATION_SUPPLIED</Status>

<RecommendedClientMessage><![CDATA[Requested information has been

provided.]]></RecommendedClientMessage>

</Information>

</Event>

</Response>

3.3.6.4.7 iDeal Bank List response values

<Event>

<ResponseDescription>Transaction

Successful</ResponseDescription>

<banks>

<issuer_id>121</issuer_id>

<name>Test Issuer</name>

</bank>

<issuer_id>151</issuer_id>

<name>Test Issuer 2</name>

</bank>

<issuer_id>171</issuer_id>

<name>Test Issuer 3</name>

</bank>

</banks>

</PaymentMethod>

<Status>INFORMATION_SUPPLIED</Status>

<RecommendedClientMessage><![CDATA[Requested information has been

provided.]]></RecommendedClientMessage>

</Information>

</Event>

</Response>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

3.3.7 Modification

The Modification call to the APG Web Service is used to issue an instruction to update

the status of a Purchase transaction which was already submitted to the APG. This

service is only available for the following payment methods:

 A7

 AM

 EL

 EV

 I3

 W3

 BU

The following actions can be performed on a Modification transaction:

 CANCEL

 CAPTURE

 REFUND

For more information on these actions, please refer to Appendix 19.

The Modification web method accepts five parameters namely; accountDetails of type

AccountItem, DPGReferenceId of type Long, Type of Action of type ActionType,

amountDetails of type AmountItem and Note of type String. The AccountItem and

AmountItem types are custom complex structures, and the ActionType type is a

custom simple structure. For more information on the composition of these structures,

please refer to the WSDL which can be downloaded from the URLs specified in section

3.2.1.

3.3.7.1 Schema Elements for Modification Request

In this section, the fields that can be presented with Modification transaction Requests

will be presented along with example XML for those fields.

 Modification

o AccountDetails – section 3.3.1.1.1

o DPGReferenceID

o TypeOfAction

o AmountDetails

SOAP XML Modification Request document:

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xmlns:xsd="http://www.w3.org/2001/XMLSchema">

<soap:Body>

<AccountName>string</AccountName>

<AccountPIN>string</AccountPIN>

<CompanyId>string</CompanyId>

</accountDetails>

<typeOfAction>CANCEL or CAPTURE or REFUND</typeOfAction>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

<Exponent>short</Exponent>

<CurrencyCode>short</CurrencyCode>

</amountDetails>

</Modification>

</soap:Body>

</soap:Envelope>

3.3.7.1.1 Modification

Element Name

Modification

Type

Modification

Position

Soap:Body

Children

Yes

Attributes

Yes

Elements of Modification

Element Name

Description

Data type / Limitations

accountDetails

This is a set of the merchant’s

authentication details which is

required in order to access the

APG.

AccountItem – see section

3.3.1.1.1

DPGReferenceId

The DPGReferenceId is a unique

APG transaction identifier which

is generated by the APG for

each merchant transaction. This

identifier is returned in the

response to a Purchase or

Payout transaction.

Long

This value is mandatory at all times.

typeOfAction

This field indicates the type of

Action that the Modification web

method needs to perform.

Please reference Appendix 19.

Enum

This value is mandatory at all times.

Supported Action Types:

 CANCEL

 CAPTURE

 REFUND

amountDetails

This is a set of amount details.

AmountItem – see section 3.3.1.1.2

Optional if action is Refund.

Amount cannot be higher than

original purchase amount. Currency

must be the same as original

purchase currency. If AmountDetails

details structure is sent to APG, then

all its fields must be populated with

valid values.

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

Note

This is a description for the

transaction

String (255)

Optional

See the next section for an XML example.

3.3.7.2 Example of XML for Modification Requests

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xmlns:xsd="http://www.w3.org/2001/XMLSchema">

<soap:Body>

<AccountName>TestAccount</AccountName>

<AccountPIN>TestPIN</AccountPIN>

</accountDetails>

<typeOfAction>CANCEL</typeOfAction>

</amountDetails>

</Modification>

</soap:Body>

</soap:Envelope>

3.3.7.3 Schema Elements and Example XML for Modification Response

The Response that is generated for a Modification Request is similar to the Response

that is generated for a Purchase transaction.

See section 3.3.2.3.4 for details of the Purchase (and Modification)

Response structure.

See section 3.3.2.5 for examples of these Responses.

The following is a list of possible results that can be returned by the Modification web

method in the Status field:

 AUTHORISED

 CANCELLED

 ERROR

 NOT_FOUND

 REFUNDED

 SENT_FOR_CAPTURE

 SENT_FOR_REFUND

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

3.3.7.3.1 Example Modification Responses

3.3.7.3.1.1 AUTHORISED

<Event>

<Modification DPGReferenceId="113836"

TransactionId="A99_091127163001">

<ResponseDescription>Transaction

successfull</ResponseDescription>

</PaymentMethod>

<Status>AUTHORISED</Status>

</Modification >

</Event_>

</Response>

3.3.7.3.1.2 CANCELLED

<Event>

<Modification DPGReferenceId="113836"

TransactionId="A99_091127163001">

<ResponseDescription>Transaction

successfull</ResponseDescription>

</PaymentMethod>

<Status>CANCELLED</Status>

</Modification >

</Event>

</Response>

3.3.7.3.1.3 REFUNDED

<Event>

<Modification DPGReferenceId="113835"

TransactionId="A99_091127161216">

<ResponseDescription>Transaction

successfull</ResponseDescription>

</PaymentMethod>

<Status>REFUNDED</Status>

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

</Modification>

</Event>

</Response>

3.3.7.3.1.4 ERROR

<Event>

<Modification DPGReferenceId="113879"

TransactionId="A99_091202120706">

</PaymentMethod>

<Status>ERROR</Status>

<Error>

<Description>PurchaseDetails.AccountDetails.AccountPIN value

invalid</Description>

</Error>

</Modification >

</Event>

</Response>

3.3.7.3.1.5 NOT_FOUND

<Event>

</PaymentMethod>

<Status>NOT_FOUND</Status>

<Error>

<Description>Transaction not found</Description>

</Error>

</Modification >

</Event>

</Response>

3.3.7.3.1.6 SENT_FOR_CAPTURE

<Event>

<Modification DPGReferenceId="41179"

TransactionId="T10_PNTJTNJ4L3IV">

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

<ResponseDescription>Approved and

Completed</ResponseDescription>

</PaymentMethod>

<Status>SENT_FOR_CAPTURE</Status>

</Modification>

</Event>

</Response>

3.3.7.3.1.7 SENT_FOR_REFUND

<Event>

<Modification DPGReferenceId="41181"

TransactionId="T10_NAVD1ABSLAUB">

</PaymentMethod>

<Status>SENT_FOR_REFUND</Status>

</Modification>

</Event>

</Response>

Back to Contents

COMPANY CONFIDENTIAL

This document is intended for the use of DataCash and its clients only. It contains information that is

privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to

anyone else. If you have received this document in error, please notify DataCash immediately.

3.4 APG EVENT NOTIFICATIONS

The APG system has events that take place outside the normal flow of a transaction.

When such events take place, notifications will be sent to the merchant’s Event_URL.

Below is a list of the events that can take place out-of-process:

 AUTHORISED

 CANCELLED

 CAPTURED

 CHARGED_BACK

 MARKED_FOR_REFUND

 PENDING

 REFUNDED

 REFUSED

 SEND_FOR_CAPTURE

 SEND_FOR_REFUND

Example: In a MoneyBookers transaction, the transaction amount exceeds the available

balance in the consumer’s account. This transaction can then become “Pending” in APG

(inside the normal flow of this transaction). The consumer can then either cancel or

pay the remainder on the MoneyBookers website during the next two days.

MoneyBookers will send this final transaction result to the APG (outside the normal flow

of this transaction), and the APG will map this result to one of the responses/events

mentioned above, and send the relevant notification to the merchant’s Event_URL.

When a notification is sent to the Event_URL, the merchant will need to analyze the

event and then take the appropriate action. After receiving the event, the merchant

needs to confirm receipt of the notification by sending an OK response back to the APG

system. In the event that the APG does not receive a confirmation of receipt, the APG

will retry multiple times to send the notification.

Refer to section 3.3.1.2.2 for examples of event notifications (any of the responses,

excluding Redirect responses, can be sent as event notifications).

When a merchant receives this event notification, they then need to respond with the

following XML:

Back to Contents

DataCash Merchant API Data Cash Developers Guide 2.57

Navigation menu

Versions of this User Manual:

Views

Navigation