DataCash Merchant API Data Cash Developers Guide 2.57

User Manual:

Open the PDF directly: View PDF PDF.
Page Count: 818

DownloadDataCash Merchant API Data Cash Developers Guide 2.57
Open PDF In BrowserView PDF
Developers Guide

Prepared for:
DataCash Merchants

Date:
May 2013

© 2013 DataCash. All rights reserved.
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

Document Control
Reference

API001

Date

29/05/2013

File Name

DataCash_Developers_Guide_2.57

Version

2.57

REVISION HISTORY
Revision
2.0
(Release)
2.1

Date

Comments / Reason

26/11/2009

Developers Guide from DPG and APG combined

27/11/2009

Added Fuel Card Service
Added PayPal Reference Transactions
Added Bankcard Query Transactions
InstaDebit and ELV details added (FR)
Standardisation of formatting and layout (JF)

2.2

08/12/2009

2.3
2.4

11/01/2010
28/01/2010

2.5

09/02/2010

2.6

19/02/2010

2.7

03/03/2010

2.8

21/04/2010

2.9

22/04/2010

2.10

25/05/2010

2.11

07/06/2010

2.12

02/08/2010

2.13

16/09/2010

2.14

21/10/2010

2.15

27/10/2010

2.16

16/11/2010

Updated HPS section with details for dynamic capture fields
and expired session handling (NB)
Updated PayPal Reference Transactions (NB)
Updated HpsTxn response table and related XML (CTI)
Updated paReq example – textarea (JF)
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)
Change HPS to HCC (JF)
Updated HCC Section with details for dynamic data
placeholders (RWM)
Updates to ExperCash section (SJ)
Added ExperCash BackCharge information (SJ)
New section added for Full HPS (RWM)
Updates to links to Appendices (AM)
Added GiroPay sample (AM)
New section added for Payout transactions (RJB)
Update to Direct Debit Notifications re Drawdown
Notifications (JF)
Update to 



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.

© 2013 DataCash. All rights reserved.
Page 221 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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 3 rd 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
Request.Transaction
Position:
Elements of MpiTxn
Element Name

Description

Values / Limitations

method

The method of the
transaction

Card

The card details of
the transaction to be
authenticated. This
See 2.1.1.1 for more
element contains sub
information
elements. See
2.1.1.1 for more
information

mpi

Required

R

M

© 2013 DataCash. All rights reserved.
Page 222 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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.

2.4.5.3

XML Attribute
type=”preregistered”
should be supplied in
the opening tag.
The value contained
should be the
datacash_reference of
the card transaction.

M

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.

© 2013 DataCash. All rights reserved.
Page 223 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

Example Enrolment Check Request


99000001
********



387545924537037
10.04

http://www.mywebsite.com/
CDs and DVDs
20060201 3:59:59

*/*
IE/6.0




mpi

4444************
06/12
06/12
06/12





© 2013 DataCash. All rights reserved.
Page 224 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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


150
3DS Payer Verification Required
387546049537037
4300200042810537

…


eJxdUltugzAQ/M8pUA+AHyEQKscSLR/NB1H
U5AKWsypIBRIbStrT14Y4JkGAdnYWdjRjdiwVQH4A2Svgiy
BgBWgtviCoTpuXswgjuiZ4tUxeLGnoffYJl6k26AeUrtqGk
xCHlCEHHV2AkqVoOtcwLSEvb9sdj5MkSglDN+j5GtQ252lK
cJxgzNCEPd+IGvhBKFEyNNaekm3fdOqXr2nMkAOe7tU3H4Y
hPIlOSKHLULY1Q7br5KJnvWzf24aeb7lWJ17k2TB/dvk2Ko
4ZKf7khiE74efNOuAU4xhTTAK6fF2l5mZo7M98qa1gTnCII
2PLhDx9tkIyN2NH5p2ZB71S0EhngkN+AK7ntgHzjYnrXs/U
gpa8A90Zgba8W/PsBHv/eEhVdiYmowwv7Wu6xnxH4mF/ZWI
h1LI3cF/i/mnWuWNmQxkPJF8w9HhY/wFTsbsh

https://www.clicksafe.lloydstsb.com/Lloyds/
tdsecure/pa.jsp?partner=mc&VAA=B/



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:

© 2013 DataCash. All rights reserved.
Page 225 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

Example Validate Authentication Request



99000001 
********



4300200042810537
threedsecure_validate_authentication

uyt45t89cnwu3rhc98a4hterjklth4o8ctsrjzth4



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




yes
05
Q0FWVkNBVlZDQVZWQ0FWVkNBVlY=
MDAwMDAwMDAwMDAwMTIzNDU2NzE=


3200900012345671
LIVE
ACCEPTED
1


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.

© 2013 DataCash. All rights reserved.
Page 226 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

Example Validate Authentication Response from version 2 request




yes
05
1
Q0FWVkNBVlZDQVZWQ0FWVkNBVlY=
MDAwMDAwMDAwMDAwMTIzNDU2NzE=


3200900012345671
LIVE
3658684685
Rbs
ACCEPTED
1


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:



yes
05
1
Q0FWVkNBVlZDQVZWQ0FWVkNBVlY=
MDAwMDAwMDAwMDAwMTIzNDU2NzE=


3200900012345671
LIVE
3658684685
Chase Paymentech
100
Approved
ACCEPTED
1



© 2013 DataCash. All rights reserved.
Page 227 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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



99000001
*******



1001.02
387545924AdkWdd


auth
3200900012345671


1 High Street
This Town Town
Somewhere
United Kingdom
S01 2CD
123






© 2013 DataCash. All rights reserved.
Page 228 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

The response to a subsequent authorization of an MPI Only transaction will be as per
standard bankcard responses.
Example Authorisation Response from the DPG



100000
VISA
United Kingdom

3000900012345672
4421000009
LIVE
ACCEPTED
1



© 2013 DataCash. All rights reserved.
Page 229 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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




no
06


4300200042810537
387546049537037
LIVE
162
3DS Card not Enrolled



© 2013 DataCash. All rights reserved.
Page 230 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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


3200900012345671
LIVE
Authentication can only be performed for enrolled
cards
600


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:

© 2013 DataCash. All rights reserved.
Page 231 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

Example Enrolment Check using Preregistered Card Details


99000001
fred



387545924537037
10.04

http://www.mywebsite.com/
CDs and DVDs
20080808 23:59:59

*/*
IE/6.0




mpi
4300200042810536




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 3D 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
© 2013 DataCash. All rights reserved.
Page 232 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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
Request.Transaction.TxnDetails.CardTxn
Position:
Elements of Secure
Element Name

security_code

Description

Values / Limitations

The Cardholder Authentication
Verification Value (CAVV) for Visa
cards, or Universal Cardholder
Authentication Field (UCAF) for
MasterCard, (Amex) for American
Express

Indicates whether the cardholder was
cardholder_registered registered for 3-D Secure and the
PARes / VERes status

M

yes
no
attempted –
enrolled, PARes
status ‘A’
ch_enrolled_u –
VERes status ‘U’
tx_status_u –
enrolled, PARes
status ‘U’

R

© 2013 DataCash. All rights reserved.
Page 233 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

eci

The Electronic Commerce Indicator
(ECI) obtained from your MPI

01
02
05
06
00

transactionID

The XID from PARes.Purchase.xid

As copied from the
M
PARes

M

Example Secure complex element

no


AAABAwRzYAAAAAAAAAAAAAAAAAA=
yes
06
TbwiW8VLThG3TjDuI7KS5wAJCAI=


© 2013 DataCash. All rights reserved.
Page 234 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

2.4.6.2

XML Example Requests

Example Request XML for 3-D Secure with a 3rd party MPI, for a registered
card


99000001
******



123456
10.00
ecomm



4444********1111
12/09

pre

BwABCEYiBQAAAAAGViIFAAA
AAAA=
yes
06
TbwiW8VLThG3TjDuI7KS5wAJ
CAI=





© 2013 DataCash. All rights reserved.
Page 235 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

Example Request XML for 3-D Secure with a 3rd party MPI, for a registered
card using the Pre-Registered Card service


99000001
******



123456
10.00
ecomm



4900200053281123
pre

BwABCEYiBQAAAAAGViIFAAA
AAAA=
yes
06
TbwiW8VLThG3TjDuI7KS5wAJ
CAI=





© 2013 DataCash. All rights reserved.
Page 236 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

Example Request XML for 3-D Secure with a 3rd party MPI, for an unregistered card


99000001
******



123456
56.26
ecomm



5374********0001
01/08

pre

no





Example Request XML for a card scheme which is not supported for the 3-D
Secure check


99000001
******



45786906
23.45
ecomm



6759********9999
12/07
12/04
03

auth




© 2013 DataCash. All rights reserved.
Page 237 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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
o
o

DeliveryAddress – details the delivery address for the order, section

2.4.7.1.3
BillingAddress – details of the Payer Billing Address, section 2.4.7.1.4
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

© 2013 DataCash. All rights reserved.
Page 238 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

o

o

o

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

BillingAddress

AltPayment

See section 2.4.7.1.3. N/A for PayPal – use
PayPalTxn.ShippingAddress instead
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.

See section 2.4.7.1.12

© 2013 DataCash. All rights reserved.
Page 239 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

OrderInformation

See section 2.4.7.1.16

Example XML for The3rdMan complex elements

...

...
...
...


...


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

alt_telephone

Alternative
Telephone
Number

Max 20 characters
International numbers: include
Country code, exclude access code

customer_dob

Customer
Date Of
Birth

YYYY-MM-DD format

customer_reference

Customer
reference

Max 50 characters. N/A for PayPal.
Gateway will automatically use
TxnDetails.merchantreference

Sectors

RHTG

G

RHTG

© 2013 DataCash. All rights reserved.
Page 240 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

delivery_forename

The first
name of the
person to
Max 50 characters. N/A for PayPal,
which the
use
PayPalTxn.ShippingAddress.name.
order is
being
delivered

R

delivery_phone_number

The phone
number of
the person
Max 20 characters. N/A for PayPal,
to which the use PayPalTxn.ShippingAddress.
telephone_number
order is
being
delivered

-

delivery_surname

The
surname of
the person
Max 50 characters.
to which the N/A for PayPal, use
PayPalTxn.ShippingAddress.name.
order is
being
delivered

R

delivery_title

The title of
the person
Max 10 characters.
to which the
N/A for PayPal, use
order is
PayPalTxn.ShippingAddress.name
being
delivered

R

Driving
driving_licence_number Licence

Max 30 characters. N/A for PayPal

-

Number

email

Email
Address.

Max 50 characters
N/A for PayPal. Gateway will
automatically use the email returned
by PayPal

first_purchase_date

First
Purchase
Date By
Customer

YYYY-MM-DD format

forename

introduced_by

Customer
first name

Customer
Ref Of
Introducing
Customer

Max 50 characters. Gateway will
automatically use the firstname
returned by PayPal

RHTG

G

RHTG

For AltPayment: Max 50 characters.

-

Max 50 characters

-

© 2013 DataCash. All rights reserved.
Page 241 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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

Previous
Purchases

See below

sales_channel

– Mail order
– Telephone order
– Internet
- Other
Type of sale 5 – In store
6 - Kiosk
7 – Mobile
N/A for PayPal transactions –
Gateway will automatically use 4
1
2
3
4

surname

telephone

time_zone

title

Customer
Surname

Max 50 characters. Gateway will
automatically use the lastname
returned by PayPal

RHTG

RHTG

For AltPayment: Max 50 characters

-

Telephone
Number

A maximum of 20 characters.
International numbers: include
Country code, exclude access code.

RHTG

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.

Customer
Title (Mr,
Mrs etc)

Max 10 characters. Gateway will
automatically use the salutation
returned by PayPal
For AltPayment: Max 10 characters

-

RHTG
-

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

© 2013 DataCash. All rights reserved.
Page 242 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

Example XML for CustomerInformation complex elements

CUSTREF000001
Mr
John
Smith
0131 123 1234
0131 123 1234
jsmith@devnull.co.uk
192.168.0.1
1980-03-12
2004-02-21

CUSTREF0004444
SMITH0987654321

GMT


John
Smith


Alice
Smith



2.4.7.1.3

DeliveryAddress

This element contains the delivery details. It has two places within the Request
Schema:
o

The3rdMan
o

o

DeliveryAddress – for the main delivery address. Should not be provided for
PayPal transactions – use PayPalTxn.ShippingAddress instead.
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:
Position:

DeliveryAddress
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

© 2013 DataCash. All rights reserved.
Page 243 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

recommendation does not apply for AdditionalDeliveryAddress elements.

Elements of DeliveryAddress
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

-

Element Name

street_address_1

Description

First
Max 100 characters. For PayPal, use
address line ShippingAddress.street_address1

street_address_2 Second

Max 100 characters. For PayPal, use
address line ShippingAddress.street_address2

RHT
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

10 Stratford Road
Windsor
London
London
826
AB1 2CD


Example XML for DeliveryAddress complex elements


MR
© 2013 DataCash. All rights reserved.
Page 244 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

D
Jones
10 Stratford Road
Windsor
London
826
AB1 2CD


MR
P
Sutherland
12 Stratford Road
Windsor
London
826
AB1 2CD



Example XML for PayPalTxn ShippingAddress complex elements








RT
123
1
25.99



Fraud Street
Stark's Park
GB
WC1B6ST
Mr Fraud Ster
London
Fife



© 2013 DataCash. All rights reserved.
Page 245 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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

street_address_1

street_address_2

city

county

postcode

Description

Values / Limitations

Max 100 characters. For PayPal, use
First
ShippingAddress.street_address1
address line
For AltPayment: Max 100 characters.
Max 100 characters. For PayPal, use
Second
ShippingAddress.street_address2
address line
For AltPayment: Max 100 characters.
City

County

Postcode

Sectors
(see
above)

RHTG
RHTG
-

Max 20 characters. For PayPal, use
ShippingAddress.city

RHTG

For AltPayment: Max 20 characters

-

Max 30 characters. For PayPal, use
ShippingAddress.region

RHTG

For AltPayment: Max 30 characters.

-

Max 9 characters (or 10 for Amex
transactions). For PayPal, use
ShippingAddress.postcode

RHTG

© 2013 DataCash. All rights reserved.
Page 246 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

For AltPayment: Max 9 characters (or 10
for Amex transactions).
Country
Code

country

Use the numeric country codes. For PayPal,
use ShippingAddress.country_code
For AltPayment: Use the numeric country
codes.

RHTG
-

Example XML for BillingAddress complex elements

Mulberry House
15 Acacia Place
Edinburgh
Lothian
826
EH6 7EZ


10 Banana Gardens
Chepstowe
Lothian
826
CH11 4XX


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

© 2013 DataCash. All rights reserved.
Page 247 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

Elements of AccountInformation
Element Name

Description

Address

See section 2.4.7.1.7

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

Values / Limitations

Sector

G

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

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

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

G

G

© 2013 DataCash. All rights reserved.
Page 248 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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


...

...
...
...
...
Mr
Steven
Benson
01505000000
Tier 1
1235
2010-12-02
usage
previous
remaining
22.55
600.53
Active
test@datacash.com
POST
EN
EN
5.50
2.50
OK
Bejewelled
5
2
SENT
Yes
2010-11-15
rake
1IHKD32
55.55
123


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.

© 2013 DataCash. All rights reserved.
Page 249 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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

00000000
12 Bank Street
Scotland
Santander
MR J K BANK
00-00-00


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

© 2013 DataCash. All rights reserved.
Page 250 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

Elements of PreviousDetail
Element
Name

Description

Values / Limitations

Sector

amount_in

Format NNNNNNNNNNNN.NN

-

amount_out

Format NNNNNNNNNNNN.NN

-

(e.g. GBP, EUR, USD). Max 3
characters

-

date

YYYY-MM-DD HH:MM:SS

-

details

Max 100 characters

-

currency

ISO currency code standard
(ISO 4217)

Example XML for PreviousDetails complex element


52.52
30.65
GBP
2010-10-12 11:12:58

Detail text



552.63
125.25
EUR
2010-12-01 15:27:46

Detail text




© 2013 DataCash. All rights reserved.
Page 251 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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


52.47
100.52
10.28



© 2013 DataCash. All rights reserved.
Page 252 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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

Max 100
characters

G

Max 100
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

machine_id

Example XML for UserDetails element


rtr
testid
profile1
profile2
profile3
xc334sv


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

© 2013 DataCash. All rights reserved.
Page 253 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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

...
...
...
...
...
...
55.55


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.

© 2013 DataCash. All rights reserved.
Page 254 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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
Numberic.
Max length 2

alt_issuenumber_or_startdate The card issue number or start_date

Example XML for Card element


0000000000000000
1012



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

auth_code

avs_address_response

Description

Values /
Limitations

The bank authorisation code may be null
if not applicable and is represented as the
empty string. If the transaction type is
Max 30
Update, bank authorisation code should
characters
contain the status of the transaction
(either OK, Rejected, Chargeback or
Chargeback Fraud)
0 = not given
1 = not
checked
2 = pass
4 = fail

© 2013 DataCash. All rights reserved.
Page 255 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

0 = not given
1 = not
checked
2 = pass
4 = fail

avs_postcode_response

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

Security code response

0 = not given
1 = not
checked
2 = pass
4 = fail

cv2_response

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.

security_code

Visa transactions – CAVV
Max 50 characters
Mastercard transactions –AVV

2.4.7.1.16

Numeric. Max length 2

OrderInformation

Element Name: OrderInformation
Position:

Request.Transaction.TxnDetails.The3rdMan

Elements of OrderInformation
Element Name
Products

Description

Values /
Limitations

See section 2.4.7.1.17. N/A for PayPal – use
PayPalTxn.Items elements instead.

Sector

RHT

© 2013 DataCash. All rights reserved.
Page 256 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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

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

YYYY-MM-DD

format

R

Max 30
characters

operator_id
payment_method
route_via_location

Routing information

Max 50
characters

Example XML for OrderInformation complex elements

First Class Post
…


XML Example for PayPalTxn Items complex elements








RT
123
© 2013 DataCash. All rights reserved.
Page 257 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

1
25.99



Fraud Street
Stark's Park
GB
WC1B6ST
Mr Fraud Ster
London
Fife




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
Product

Description

See section
2.4.7.1.18

Values / Limitations

One element for each distinct item
ordered

Sector

RHT

Attributes of Products
Attribute
name
count

Description

Values / Limitations

Total number of items Must match the total of the items
specified in the Product.count fields.
in the order

Sector

RHT

© 2013 DataCash. All rights reserved.
Page 258 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

Example XML for Products complex elements

…


…
…

Example XML for PayPal Items complex elements








RT
123
1
25.99



Fraud Street
Stark's Park
GB
WC1B6ST
Mr Fraud Ster
London
Fife



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 Product
Name:
Position: Request.Transaction.TxnDetails.The3rdMan.OrderInformation.Products

© 2013 DataCash. All rights reserved.
Page 259 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

Elements of Product
Element Name

Description

Values /
Limitations

Sector

T

AirlineInformation See section 2.4.7.1.19
code

The product code for the item. For PayPal, Max 30
use Item.number.
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

prod_description

The product description. For travel use
departure date in DD MMM YYYY HH:MM
Max 100
(e.g. 27 Feb 2014 17:50). For Hotel use
characters
the check-in to check-out date (e.g. 24
Sep 2012 – 29 Sep 2012). For PayPal, use
Item.name

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

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

quantity

The number of items of this product
ordered. For PayPal, use Item.quantity

Non-negative
integer

HT

RHT

H
HT

R

Example XML for Product complex element

32231
125
2
22.99


Double ensuite
125
2
22.99


© 2013 DataCash. All rights reserved.
Page 260 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

Example XML for PayPalTxn Product complex elements








RT
123
1
25.99



Fraud Street
Stark's Park
GB
WC1B6ST
Mr Fraud Ster
London
Fife



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

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.

Sectors

Max 30
characters

© 2013 DataCash. All rights reserved.
Page 261 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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

BA
1970-06-16
Y
059
Y
9876
SA
456789032
LHR-DUB


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).
Numeric
Up to 3 separate counts can be provided (1-3).

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

© 2013 DataCash. All rights reserved.
Page 262 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

Example XML for AdditionalInformation elements

155576
18521
12568
Data as agreed
Data as agreed
Data as agreed
Data as agreed
Data as agreed


2.4.7.2

Example PayPal Request






0987 654654
01234 456789
212.188.171.55


Fraudster
Jack
accept@datacash.com


2013-02-26


rt_do_exp_chk07
25.99




RT
123
1
25.99



FraudStreet
Stark's Park
GB
WC1B6ST
Mr Fraud Ster
London
Fife
© 2013 DataCash. All rights reserved.
Page 263 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL


do_express_checkout_payment
3600900010001070
rt_do_07
order



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-bytransaction 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

Score

-999 to +999

© 2013 DataCash. All rights reserved.
Page 264 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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


5567
12345
333333333
0
1


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
© 2013 DataCash. All rights reserved.
Page 265 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

used for Real Time Fraud Screening.
For Real Time Fraud Screening, there is one additional elements within the The3rdMan
element in the schema:


The3rdMan

RealTime – details for Real Time Callback, section 2.4.8.1.2

o

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
RealTime

Description

Values / Limitations

See section 2.4.8.1.2 Optional

Attributes for Elements of The3rdMan
Attribute
Name

type

Attribute of
Element

The3rdman

Values / Limitations
realtime

Example XML for The3rdMan complex elements

...
...
...
...
...


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
Request.Transaction.TxnDetails.The3rdMan
Position:
© 2013 DataCash. All rights reserved.
Page 266 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

Elements of Realtime
Element Name

Description

Values / Limitations

real_time_callback_format

The interface used to call the
realtime system. Defaults to XML
HTTP.

real_time_callback

The callback URL used by
this transaction if applicable

real_time_callback_options

Max length 200
2

Example XML for Realtime complex elements

XML
http://www.callback.com/cgibin/
callback.cgi/
2


2.4.8.2
2.4.8.2.1

Schema Elements for Realtime Response
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
Response.HpsTxn
Position:

Elements of AuthAttempt
Element Name

Description

Values / Limitations

Will be present for each attempt the Card Holder has made. See
section 2.4.8.2.2.

Attempt

Example XML for AuthAttempts element, with two attempts

...
...

2.4.8.2.2

Attempt

© 2013 DataCash. All rights reserved.
Page 267 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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
Response.HpsTxn.AuthAttempts
Position:

Elements of Attempt
Element Name
The3rdManRealtime

Description
See section 2.4.8.2.3

Values / Limitations
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

...
4100203001856542
7
DECLINED


4400203001856550
179
3DS Payer failed Verification


...
4700203001856619
1
ACCEPTED

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

© 2013 DataCash. All rights reserved.
Page 268 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

o

are submitted against pre or auth transaction
HpsTxn
 AuthAttempts
 Attempt
o The3rdManRealtime – for responses to query XML
Requests which are submitted against HPS
setup_full transactions

Element Name: The3rdManRealtime
Response
Response.QueryTxnResult
Position:
Response.HpsTxn.AuthAttempts.Attempt

Elements of Attempt
Element Name

Description
The risk score

score

Values / Limitations
-999 to 999
0, 1, 2

recommendation

The action recommendation

(accept, refer,
reject)

If an error message is received in response
error

to the fraud check, this element will appear,
populated with the error message.

Example XML for The3rdManRealtime element

500
1


0
1
UnknownCustomer

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.

© 2013 DataCash. All rights reserved.
Page 269 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

Element Name: QueryTxnResult
Response
Position:

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

…
© 2013 DataCash. All rights reserved.
Page 270 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

…
…HSBC
100000
4000900012345671
ecomm

123401
ACCEPTED
not sent
1
2009-12-08 11:35:48


…
…
…
RBS
360955
4000203001855883
ecomm
2011-07-20 15:38:20
14bab328bf6cd337a3
FULFILLED OK
Settled
1
2011-07-19 14:51:35


© 2013 DataCash. All rights reserved.
Page 271 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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
Request.Transaction.FraudOnlyTxn
Position:

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.

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

tran_type

© 2013 DataCash. All rights reserved.
Page 272 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

The payment transaction type associated with a
transaction. If the transaction is being passed to
T3M to notify them of a
alt_tran_type status (e.g. an order has been set to Rejected,
OK, Chargeback or Chargeback Fraud - a
transaction type of Update should be given)

acquirer

The merchant acquirer’s name

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
Max 30

Example XML for FraudOnlyTxn element

...


12345


...
...
...
12.50
...
...


...


© 2013 DataCash. All rights reserved.
Page 273 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

2.4.9.1

Card

Element Name: Card
Request.Transaction.FraudOnlyTxn
Position:

Elements of Card
Element Name

Description

Values /
Limitations

Pan

The full card number. If you prefer
not to provide this you can provide Numeric. Max
alt_bin, alt_last_4_digits and
length 19
alt_pan_sha1 instead.

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
Upper case Hex.
support for additional data to be
Max length 50
added to each card prior to SHA-1
hashing.

expirydate

The card expiry date.

MMYY Format

The card issue number or
start_date

Issue Number
(Numeric 2)
Start Date
(MMYY)(Numeric
4)

issuenumber_or_startdate

Back to Contents

© 2013 DataCash. All rights reserved.
Page 274 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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
Request.Transaction.TxnDetails
Position:

© 2013 DataCash. All rights reserved.
Page 275 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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
Request.Transaction.TxnDetails.Risk
Position:

Attributes of Action
Attribute
name

Description

This will indicate the action(s) to be performed,
based on a set of predefined services.
Service

Values can be:



2.4.10.2.3

Values /
Limitations

Must be either “1”
or “2”

“1” for pre-authorisation fraud screening request
“2” for post-authorisation fraud screening request

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

© 2013 DataCash. All rights reserved.
Page 276 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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

MerchantConfiguration
Element Name(s): CustomerDetails
VerificationDetails
Request.Transaction.TxnDetails.Risk.Action
Position:

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:

© 2013 DataCash. All rights reserved.
Page 277 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL



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.

© 2013 DataCash. All rights reserved.
Page 278 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

2.4.11 Pre & Post Authorisation Fraud Screening
Gaming
•

Merchant Configuration
Field

Type

tag name: channel

Char (1)

Industry
Telephony Retail
•
•

Airline
•

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

tag name: merchant_location

Varchar (30)

definition: This represents the
location of stores or outlets for a
reseller or airline.
Merchant Configuration
- Callback Configuration
Field

•
Type

tag name: callback_format

Varchar(4)

•

definition:
possible values:

°

HTTP
XML
SOAP

tag name: callback_url
definition: The callback URL used
by this transaction if applicable.

Varchar(200)
°

© 2013 DataCash. All rights reserved.
Page 279 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

tag name: callback_options

Char(2)

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.
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.
Customer Details
- Risk Details
Field
tag name: account_number

Varchar (40)

•
•

definition: Customer's Email
Address.

•
•

•
•

•
•

Type
Varchar (30)

definition: An account
number/unique ref number at the
Merchant associated with the
individual who is transacting with
the merchant.

tag name: email_address

°

•

•

°

•

°

°

°

°

Varchar (64)

Note: These are generally
associated with the individual who
is transacting with the merchant.

© 2013 DataCash. All rights reserved.
Page 280 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

tag name: alt_email_address

Varchar(64)

definition: Alternative e-mail
address

°

Note: These are generally
associated with the individual who
is transacting with the merchant.

tag name: session_id

Varchar (255)

definition: a web server generated
session id.

tag name: ip_address

Varchar (15)

definition: Customer’s IP Address.

Format

°

°

°

°

°

°

°

°

°

°

°

°

°

°

°

255.255.255.2

tag name: user_id

Varchar (36)

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.

tag name: usermachine_id

Varchar (255)

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.

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.

Varchar (20)

(e.g. VIP flag, Indication whether
the transaction is part of a
promotion, a confidence level
around the identity of the
customer, etc.)

© 2013 DataCash. All rights reserved.
Page 281 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

tag name: user_profile_2

Varchar (20)

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

tag name: user_profile_3

Varchar (20)

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

tag name:

Char(1)

register_consumer_watch
definition: Register the consumer
associated with this transaction for
the consumer product.

°

possible values:

Y = Yes
N = No

tag name: browser_language

Varchar(30)
°

definition: Language setting of the
respective browser

tag name: execution_order

Int

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
Customer Details
- Personal Details

•
•

•
•

•
•

•
•

© 2013 DataCash. All rights reserved.
Page 282 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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

Varchar (32)

definition: Customer’s name.
Note: The first_name field and
the surname field combined
should not exceed 32 characters.

tag name: surname

Note: The first_name field and the
surname field combined should not
exceed 32 characters.

definition: Customer’s date of
birth.

tag name: nationality
definition: Customer's nationality,
represented by a 2-character code.
Please reference Appendix 11 for
further details.

•

•

•

•

•

•

•

°

•

°

°

°

°

°

°

°

°

°

°

°

°

Varchar (20)

definition: Alternative telephone
number.

tag name: date_of_birth

•

Varchar (20)

definition: Customer's telephone
number.

tag name: telephone_2

•

Varchar (32)

definition: Customer’s surname

tag name: telephone

•

Datetime
Format yyyymm-dd

Char (2)

Note: This is generally used in
respect of certain 3rd party
electronic ID verification services.

© 2013 DataCash. All rights reserved.
Page 283 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

tag name: id_number

Varchar (40)

definition: Passport, ID, or other
verification document number.

°

°

°

°

°

°

°

°

°

°

°

°

Note: This is generally used in
respect of certain 3rd party
electronic ID verification services.

tag name: id_type

Int

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.

tag name: ssn

Int

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.

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)
•

•

•

•

© 2013 DataCash. All rights reserved.
Page 284 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

tag name: address_line2

Varchar (60)

definition: Customer’s address line
2.

tag name: city

Varchar (25)

definition: Customer's City.

tag name: state_province

°

°

°

°

•

•

•

•

°

°

°

°

•

•

°

°

°

°

°

°

Varchar (25)

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.

tag name: country

Char (2)

definition: Customer's Country.
Note: This is a 2-character code
that needs to be supplied. Please
reference Appendix 11 for further
details.

tag name: zip_code

Varchar (10)

definition: Customer's Zip/Postal
code.

Customer Details
•
•
•
•
- Shipping Details
•
Note - these are generally associated with the dispatch of goods/services to intended
recipients.
Field
Type
tag name: title

Varchar(10)

definition: Recipient’s title

tag name: first_name

Varchar (50)

definition: Recipient’s first name.

tag name: surname
definition: Recipient’s surname.

Varchar (50)

°

°

°

© 2013 DataCash. All rights reserved.
Page 285 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

tag name: address_line1

Varchar (60)
°

definition: Customer’s shipping
address line 1.

tag name: address_line2

Varchar (60)
°

definition: Customer’s shipping
address line 2.

tag name: city

Varchar (25)
°

definition: Customer’s shipping
city.

tag name: state_province

Varchar (25)

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.

tag name: country

°

Char (2)

definition: Customer’s shipping
country.

°

Note: This is a 2-character code
that needs to be supplied. Please
reference Appendix 11 for further
details.

tag name: zip_code

Varchar (10)
°

definition: Customer’s shipping zip
code.

tag name: delivery_date
definition: Delivery date

Datetime
Format yyyymm-dd

tag name: delivery_method

Varchar(30)

definition: Method of delivery

°

°

© 2013 DataCash. All rights reserved.
Page 286 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

tag name:

Char(1)

installation_requested
definition: Indicates whether
goods are supplied together with a
physical installation.

°

possible values:

Y = Yes
N = No
Customer Details
- Payment Details
Field

•
•
Type

tag name:

Varchar(20)

•
•

•
•

•
•

transaction_type
definition: The payment
transaction type associated with a
transaction.

°

possible values:

Auth
Blank
Instant
Other

tag name: payment_method

Varchar (2)

definition: This is the mechanism
with which the client chooses to
purchase.
Note: For the screening of noncard based payments, please
consult with DataCash as new
options will be added.

•

•

•

•

Customer Details
•
•
- Payment Details
•
•
- - Wallet Details
•
•
Note – this is for any funding account details other than cards.
Field
Type

•
•
•

•
•
•

possible values:
please refer to Appendix 26
Payment Method Codes.

© 2013 DataCash. All rights reserved.
Page 287 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

tag name: acquirer_number

Varchar (60)

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.
Customer Details
- Order Details
Field

Type

tag name: discount_value

Int

°

°

°

°

•
•

•
•

•
•

•
•

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.

°

tag name: time_zone

Time format

definition: Local time zone, GMT
+/- hours (GMT = 0)

(+/-hh:mm)

°

example: +01:00

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 yyyymm-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

Varchar (50)

definition: The billing account
owner’s name associated with the
transaction.

tag name: address_line1
definition: The billing account
owner’s billing address line 1.

°

°

°

°

°

°

°

°

Varchar (60)

© 2013 DataCash. All rights reserved.
Page 288 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

tag name: address_line2

Varchar (60)

definition: The billing account
owner’s billing address line 2.

tag name: city

°

°

°

°

°

°

°

°

°

°

°

•

•

°

•

°

°

°

°

Varchar (25)

definition: The billing account
owner’s billing city.

tag name: state_province

°

Varchar (25)

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.

tag name: country

Char (2)

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.

tag name: zip_code

Varchar (10)

definition: The billing account
owner’s billing zip code

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)
°

© 2013 DataCash. All rights reserved.
Page 289 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

tag name:

Varchar (50)

product_description

°

definition: Line item description.

tag name: product_category

Varchar (80)
°

definition: Type of item, as
classified by the Merchant.

tag name: product_risk

Varchar(50)

definition: Indication of how
susceptible the product is to fraud.
possible values:

°

High
Medium
Low

tag name: order_quantity

Int

definition: Number of items
ordered.

°

Note: If any one of the Line Item
fields is submitted, then all Line
Item fields become mandatory.

tag name: unit_price

Int

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.

°

Customer Details
- Airline Details
- - Journey
Field

Type

tag name: ticket_number

Varchar (30)

definition: the ticket number
assigned to the journey.

•

•

•

•
•
•

°

© 2013 DataCash. All rights reserved.
Page 290 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

tag name: payer_travelling

Char(1)

definition: an indication whether
the person paying is also travelling
on the ticket.

°

possible values:

Y = Yes
N = No

tag name: pnr

Varchar(10)

definition: Passenger Name Record

°

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

Char (3)

definition: Departure point airport.

•

Note: this is a 3 character code
IATA airport code that needs to be
supplied. http://www.iata.org/

tag name: depart_country

Char (2)

definition: Departure Country.
°

Note: This is a 2-character code
that needs to be supplied. Please
reference Appendix 11 for further
details.

tag name: depart_datetime

Datetime

definition: Local Date & time of
scheduled departure.

Format yyyymm-dd
hh:mm:ss

tag name:

Time format

depart_airport_timezone
definition: Local time zone, GMT
+/- hours.

•

(+/- hh:mm)
•

example: +01:00

© 2013 DataCash. All rights reserved.
Page 291 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

tag name: arrival_airport

Char (3)

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/

tag name: carrier

•

Char (2)

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/

tag name: flight_number

Char (4)

definition: Flight number for the
journey.

•

(Data Capture – not fed into rules
engine)

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.

Char (10)

•

example: HL7LNR

© 2013 DataCash. All rights reserved.
Page 292 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

tag name: fare_class

Char (3)

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)

tag name: base_fare

Int

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)

tag name: currency_code

Char (3)

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)
Customer Details
- Airline Details
- - Journey
- - - Passengers
- - - - Passenger
Field

•

•

•

•
•
•
•
•

Type

© 2013 DataCash. All rights reserved.
Page 293 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

tag name: first_name

Varchar (32)

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.

tag name: surname

°

Varchar (32)

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.

tag name: passenger_type

°

Char (1)

definition: The type of passenger
travelling, e.g. Adult, Child, Infant.
possible values:

•

A = Adult
C = Child
I = Infant

tag name: nationality

Char (2)

definition Customer's Nationality,
represented by a 2-character code.
Please reference Appendix 11 for
further details.

tag name: id_number

°

Varchar (40)

definition: Passport, ID, or other
verification document number.

°

Note: fraud screening block lists
may include a composite
nationality and id_number value.

tag name: loyalty_number
definition: Passenger’s loyalty
scheme number.

Varchar (20)
°

© 2013 DataCash. All rights reserved.
Page 294 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

tag name: loyalty_type

Varchar (20)

definition: Passenger’s loyalty
scheme

°

(e.g. .... Voyager, )
tag name: loyalty_tier

Int

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

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



Edinburgh
W



24972343
email@example.com
FJW35798FHI
127.0.0.1
333
38744
profile
profile1
profile2


Steven
Partridge
555-3937
032749874738
1978-03-10
GB
43579
© 2013 DataCash. All rights reserved.
Page 295 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

1
0000


123 Brick Lane
South Brickford
Livingston
West Lothian
GB
LI43 0SA


123 Brick Lane
Brickford South
Livingston
West Lothian
GB
EH7 8EA


CC

458




Mr Steven Partridge
34 Fake Street
District 7
Terminalville
Western Docklands
TZ
347595



PRN383
Pair of socks
Clothing
11
411


FHEUF
Model dog
Keepsake
2
5.32





478935793


EDI
© 2013 DataCash. All rights reserved.
Page 296 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

UK
2030-10-01 13:23:11
+00:00
WRO
BA
508
LWC
Y
3000
GBP


JHB
SA
2030-08-01 13:23:11
+01:00
LHW
SuperJet
404
FR
Buisiness
7844.00
ZAR




Daniel
Moore
A
GB
666
32974
Super Loyal
3


Fed
McFed
A
CA
574
433
Disloyal
1








© 2013 DataCash. All rights reserved.
Page 297 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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
Screening Response

Description

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

© 2013 DataCash. All rights reserved.
Page 298 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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.

© 2013 DataCash. All rights reserved.
Page 299 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

2.4.11.2.2

Example Pre-Auth Response XML

Example XML Response for an RSG transaction.


640519
VISA




-1
00
Successful
3200900010000275


0
00
Transaction Approved
3200900010000275



3200900010000275
1aa5c31170306f1504
LIVE
ACCEPTED
1



© 2013 DataCash. All rights reserved.
Page 300 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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

© 2013 DataCash. All rights reserved.
Page 301 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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

2.4.11.2.4

This field will display any additional relevant response
information. There can be more than one message tag for this
purpose.
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:

© 2013 DataCash. All rights reserved.
Page 302 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

Example XML Response for an RSG transaction which has been marked for
review.


VISA




0
02
Transaction marked for
Review
3200900010000124



3200900010000124
Transaction marked for review by the RSG
3cb4b5ca105c388ea6
LIVE
Transaction marked for review
1127



Example XML Request for an “accept_fraud” transaction.


*****
99000001



accept_review
123412345




© 2013 DataCash. All rights reserved.
Page 303 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

2.4.12 HTTPS Responses
Responses for each transaction are posted back to your server on a transaction-bytransaction 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:
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

Score

3rd Man internal identifier. Used for
later calls such as the rules string
request.
Score

Recommendation

Recommendation

2.4.12.1

-999 to +999
0=Release
1=Hold
2=Reject
9=Under Investigation

XML Response




5567
12345
333333333
0
1



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

© 2013 DataCash. All rights reserved.
Page 304 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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

© 2013 DataCash. All rights reserved.
Page 305 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

2.5
2.5.1

BACS SERVICE
Direct Debit

Additional non-technical information about this Service is available on the website:
http://www.datacash.com/gettingproducts.php?id=Direct-Credit-Direct-CreditOverview
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

© 2013 DataCash. All rights reserved.
Page 306 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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
Request.Transaction
Position(s)

Elements of DirectDebitTxn
Element Name

Description

Values / Limitations

Six digits
Can contain additional hyphens
and spaces

R

Eight digits
accountnumber The customer's account number Can contain additional hyphens
and spaces

R

sortcode

The sort code of the customer's
bank

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

© 2013 DataCash. All rights reserved.
Page 307 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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

123456
12345678
Mr A. N. Other
setup


123457
12345678
Mr A. N. Other
presetup

2.5.1.1.2

TxnDetails

Element Name: TxnDetails
Request.Transaction
Position(s)

Elements of TxnDetails
Description

merchantrefe
rence

The
reference
number of
the DDI
mandate

Must be of
the format
agreed with
your
Sponsoring R
Bank.
Character
limitations
apply

R

R

R

-

amount

The
drawdown
value

-

R

-

-

-

Element Name

Draw
down

Setup
&
Preset
up

Values /
Confirm
Limitations

Revoke

Cancel

© 2013 DataCash. All rights reserved.
Page 308 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

Example XML Request for TxnDetails elements

123402
30.00


2.5.1.1.3

HistoricTxn

Element Name: HistoricTxn
Request.Transaction
Position(s)
Elements of HistoricTxn
Element
Name

method

Description

Allows the type of
HistoricTxn to be set

Values /
Confirm Revoke Drawdown Cancel
Limitations

confirm
revoke
drawdown

The
datacash_reference
reference
of the original
transaction

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

R

R

R

R

R

R

R

R

-

-

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

© 2013 DataCash. All rights reserved.
Page 309 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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

confirm
12345679


drawdown
12345678


drawdown
12345678
20070101


drawdown
12345678
20070131


cancel
42912928

2.5.1.2 XML Example Requests
2.5.1.2.1
The Initial DataCash Setup

© 2013 DataCash. All rights reserved.
Page 310 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

Example XML Request for presetup


******
99000000



123456
12345678
Mr A. N. Other
presetup


123402




Example XML Request for setup transferring an existing mandate to
DataCash



*****
99000000



123456
12345678
Mr A. N. Other
setup


123402




© 2013 DataCash. All rights reserved.
Page 311 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

Example XML Request for a setup
This will convert an existing non-AUDDIS mandate to AUDDIS



*****
99000000



123456
12345678
Mr A. N. Other
setup


123402




© 2013 DataCash. All rights reserved.
Page 312 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

2.5.1.2.2

Updating Setups

Example XML Request for confirm



******
99000000



confirm
12345679


123401




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



*****
99000001



drawdown
12345678>


123401
10.00




© 2013 DataCash. All rights reserved.
Page 313 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

Example XML Request for a drawdown with a duedate



*****
99000001



drawdown
12345678
20070922


123401
10.00




Example XML Request for a drawdown with a tran_code


*****
99000001



drawdown
12345678
20070815


123401
10.00




2.5.1.2.4

Cancelling Payments

© 2013 DataCash. All rights reserved.
Page 314 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

Example XML Request for a drawdown cancellation



*****
99000001



cancel
123412345




2.5.1.3 XML Example Responses

© 2013 DataCash. All rights reserved.
Page 315 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

In addition to the standard fields, each Response will contain a DirectDebitTxn
element.
Element Name: DirectDebitTxn
Response
Position(s)
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

stage

The current
stage of the
mandate

method

The method
sent through
with the
Request

Indicates
the first
startdate date that a
drawdown
can be
submitted

duedate

The date the
drawdown
will be taken
from the
account

Values /
Limitations

See
Support
Centre

Will be five
working
days
hence

Setup Presetup Confirm Revoke Drawdown Cancel

yes

yes

yes

yes

n/a

n/a

yes

yes

yes

yes

yes

yes

yes

n/a

yes

n/a

n/a

n/a

n/a

n/a

n/a

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.

© 2013 DataCash. All rights reserved.
Page 316 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

2.5.1.3.1

The Initial DataCash Setup

Example XML Response for a successful setup

12345672

setup
active DDI
20020313

123402
TEST
ACKNOWLEDGEMENT
1



Example XML Response for a successful presetup

12345672

presetup
confirm required

123402
ACCREDITATION
ACKNOWLEDGEMENT
1



Example XML Response for a successful setup of an existing DDI

12345672

setup
existing
20020306

123402
LIVE
ACKNOWLEDGEMENT
1



© 2013 DataCash. All rights reserved.
Page 317 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

2.5.1.3.2

Updating Setups

Example XML Response for a successful confirm


confirm
active DDI
20020315

123401
ACKNOWLEDGEMENT
1


Example XML Response for a successful revoke


revoke
revoked

123402
ACKNOWLEDGEMENT
1


2.5.1.3.3

Taking Payments

Example XML Response for a successful drawdown

12345672

20070130
drawdown

123402
TEST
OK
1



© 2013 DataCash. All rights reserved.
Page 318 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

Example XML Response for a successful drawdown

12345672

20060924
drawdown

123402
TEST
OK
1


2.5.1.3.4

Cancelling Payments

Example XML Response for a successful drawdown cancellation

12345671

cancel

12345671
LIVE
CANCELLED OK
1



© 2013 DataCash. All rights reserved.
Page 319 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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
Total
Total
Total

updated:
cancelled:
changed:
reinstated:

9
6
2
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"

© 2013 DataCash. All rights reserved.
Page 320 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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.

© 2013 DataCash. All rights reserved.
Page 321 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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"

© 2013 DataCash. All rights reserved.
Page 322 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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

© 2013 DataCash. All rights reserved.
Page 323 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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
Request.Transaction
Position(s)
Elements of ContAuthTxn
Element Name

start_date

Description

Values / Limitations

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 R
in the format
dd/mm/yyyy
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

number_of_payments Number of regular
payments to be collected.

© 2013 DataCash. All rights reserved.
Page 324 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

amount

Must be specified to two
The value of the drawdown decimal places. GBP
R
only

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
yes
Cont Auth account is to be flagged as the first
no
drawdown

O

last

Indicates whether the last payment made using the
yes
Cont Auth account is to be flagged as the last
no
drawdown

O

For further information about drawdown flagging, please refer to section 2.5.1.1.3.

Example XML for ContAuthTxn elements

drawdown
26/02/2006
weekly
35.00


drawdown
01/04/2005
annually
100.00
3

…


© 2013 DataCash. All rights reserved.
Page 325 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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
Request.Transaction.ContAuthTxn
Position(s)
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

50.00
25/02/2006


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
Request.Transaction.ContAuthTxn
Position(s)

Elements of LastPayment
Element
Name

date

Description

The date the last
payment is to be taken

Values / Limitations

Must be in dd/mm/yyyy format; must be a
minimum of one date after the last regular
payment

© 2013 DataCash. All rights reserved.
Page 326 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

amount

The value of the last
payment

If a currency is supplied, it must be GBP

Example XML for LastPayment

50.00
25/03/2008


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
Request.Transaction
Position(s)
Elements of TxnDetails
Element Name

Description

Values / Limitations

A unique reference number to identify
merchantreference the individual Direct Debit Continuous
Authority account

Between 6 and 26
alphanumeric
characters

Example XML for TxnDetails elements

123402


2.5.2.1.5

HistoricTxn

Element Name: HistoricTxn
Request.Transaction
Position(s)
Elements of HistoricTxn
Element
Name

method

Description

cancellations only

Values /
Limitations

cancel

Drawdown Cancel

-

R

© 2013 DataCash. All rights reserved.
Page 327 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

reference

The datacash_reference of the
original transaction

R

R

Example XML element for cancel

cancel
3000123412345678


Example XML element for drawdown

12345678

2.5.2.2 XML Example Requests
2.5.2.2.1
Payments

Example XML Request for a five weekly payments of 10.00


21859999
*********



drawdown
10/02/2005
weekly
5
10.00


12345678


12345678




© 2013 DataCash. All rights reserved.
Page 328 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

Example XML Request for an unknown number of payments to be taken on
the 31st of each month


21859999
********



drawdown
31/03/2005
monthly
25.00


12345678


12345678




© 2013 DataCash. All rights reserved.
Page 329 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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.


21859999
********



drawdown
31/05/2005
monthly
25.00
6

30.00
20/04/2005


20.00
30/11/2005




12345678


12345678




© 2013 DataCash. All rights reserved.
Page 330 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

2.5.2.2.2

Cancellations

Example XML Request for cancel


99000001
******



cancel
4900200000000001



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


9910670039375669
Direct Debit Continuous Authority account
set up
ABC00005
LIVE
ACCEPTED
1


© 2013 DataCash. All rights reserved.
Page 331 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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 17Oct-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

© 2013 DataCash. All rights reserved.
Page 332 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL





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

© 2013 DataCash. All rights reserved.
Page 333 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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
Request.Transaction
Position(s)

© 2013 DataCash. All rights reserved.
Page 334 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

Elements of TxnDetails
Element Name

Description

Values / Limitations

merchantreference The reference number of the Between six and eighteen
alphanumeric characters
DDI mandate
The value of the refund

amount

Example XML for TxnDetails elements

123402
30.00

2.5.3.1.4

HistoricTxn

The elements within this parent are required for both cancel and ddrefund transaction
types.
Element Name: HistoricTxn
Request.Transaction
Position(s)

Elements of HistoricTxn
Element
Name

Description

method

Identifies the transaction type as a refund of a
direct debit

reference

The datacash_reference of the original
transaction

Values /
Limitations

ddrefund
cancel

Example XML for HistoricTxn element for a ddrefund

ddrefund
12345678


Example XML for HistoricTxn element for a cancel

cancel
4000000012345678

© 2013 DataCash. All rights reserved.
Page 335 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

2.5.3.2 XML Example Requests
Example XML Request for a ddrefund


99000001
*******



ddrefund
12345678


ABCDEF456
10.00



Example XML Request for a cancel


99000001
******



cancel
4000000059832490



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

© 2013 DataCash. All rights reserved.
Page 336 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

Example XML Response for a successful ddrefund

4800200040644359
ABCDEF456
LIVE
Accepted
1



Example XML Response for an unsuccessful ddrefund

4000000059832491
Unable to locate matching DDI
transaction
123411
TEST
Unable to locate matching DDI transaction
137


2.5.3.4.2

Cancellations

Example XML Response for a successfully cancelled Direct Credit

39375274
4800200040644359
CANCELLED OK
1


Example XML Response for an unsuccessful Direct Credit cancellation

Direct Credit has already been
cancelled
4800200040644359
TEST
Already Cancelled
128



2.5.4 Direct Credit – Standard
© 2013 DataCash. All rights reserved.
Page 337 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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

© 2013 DataCash. All rights reserved.
Page 338 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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
Request.Transaction
Position(s)
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

Up to 18 characters, alpha
numerics and spaces only

O

bankreference

Example XML Element DirectCredit

000001
12345609
Julia McDonald
directcredit


000222
12340000
Michael Johnson
return of goods
directcredit


© 2013 DataCash. All rights reserved.
Page 339 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

2.5.4.1.4

TxnDetails

The elements within this parent are required for directcredit transactions, but
excluded for cancel transactions.
Element Name: TxnDetails
Request.Transaction
Position(s)

Elements of TxnDetails
Element Name

Description

Values /
Limitations

merchantreference A unique reference number for each Up to 30
transaction
characters
amount

The value of the refund

Example XML for TxnDetails elements

123402
30.00


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
Request.Transaction.HistoricTxn
Position(s)
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

© 2013 DataCash. All rights reserved.
Page 340 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

Example XML Element HistoricTxn for a cancel

cancel
9999999912345678


2.5.4.2 XML Example Requests

Example XML Request


99000001
******



123402
1000.01


directcredit
123456
12345678
Greg Kane




Example XML Request with optional bankreference


******
99000001



ABDYC003
49.68


directcredit
123456
12340000
Jane Smith
Money for Petrol



© 2013 DataCash. All rights reserved.
Page 341 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

Example XML Request for a cancel


99000001
******



cancel
4000000059832490




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

4803000012345672
ABDYC003
TEST
Accepted
1



Example XML Response for an unsuccessful directcredit

Invalid format for Account Name
384086694791667
TEST
Invalid format for Account Name
134


Examples of directcredit cancellations are available in section 2.5.3.4.2.

© 2013 DataCash. All rights reserved.
Page 342 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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

© 2013 DataCash. All rights reserved.
Page 343 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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
Request.Transaction
Position(s)
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

MM/YY format

O

Up to 18 characters. “COLLECTION
ACCOUNT” will be automatically used
if this element is not presented

O

expirydate The card expiry date
The card holder’s
name

cardname

2.5.5.1.4

TxnDetails

Element Name: TxnDetails
Request.Transaction
Position(s)
Elements of TxnDetails
Element Name

Description

merchantreference A unique reference number for each
transaction
amount

Values /
Limitations

Up to 30
characters

The value of the refund

Example XML for TxnDetails elements

123402
30.00


© 2013 DataCash. All rights reserved.
Page 344 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

2.5.5.1.5

HistoricTxn

Element Name: HistoricTxn
Request.Transaction.HistoricTxn
Position(s)
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

cancel
3009999912345678

2.5.5.2 XML Example Requests

Example XML Request for cardaccountpayment


****
99000001



10397897589
59.00


cardaccountpayment
5473********0007




© 2013 DataCash. All rights reserved.
Page 345 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

Example XML Request for cardaccountpayment


99000001
****



B00123895
23.50


cardaccountpayment
4444********0001
Wes Scantlin
03/09



Example XML Request for a cancel


99000001
******



cancel
4000000059832490




© 2013 DataCash. All rights reserved.
Page 346 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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

4000200045345250
390726429629630
…
Accepted
1



Example XML Requests for unsuccessful cardaccountpayment

4900200043479577
The card number does not pass the standard
Luhn checksum test
384084003240741
…
Bad checksum
25



3600200044366081
No payment details for this card
389377230555556
…
Unknown Payment Details
126



Examples of cancellations are available in section 2.5.3.4.2.
Back to Contents

© 2013 DataCash. All rights reserved.
Page 347 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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

© 2013 DataCash. All rights reserved.
Page 348 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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

-

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

Bank Card

Credit
and
Debit
Cards

Chip and PIN

Account must be
configured for this service.
Section 2.7.1.1
Transaction method must
be auth or refund.

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

BACS
Services

In addition, the following Fraud Screening Services may be used in conjunction with
the Credit and Debit Card Services:
Service
Type

Fraud
Prevention
for Cards

DPG Service
Name
ReD

AVSCV2

Restrictions

Additional
Information

Account must be
configured for this service.
Section 2.4.3
The extended dataset
cannot be provided.
AVS check only. Not
available for Chip and PIN

Section 2.4.1

© 2013 DataCash. All rights reserved.
Page 349 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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

xml_chp_cardtxn

Cardholder Present Cards Section 2.6.3.2

xml_directcredit BACS – Direct Credit
xml_directdebit

BACS - Direct Debit

Section 2.6.3.1
Section 2.6.3.3
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:
Section
fulfill, txn_refund,
2.6.3.8
cancel, accept_fraud
authorize_referral_request

csv_prereg

Credit and
Debit Cards

Pre-Registered Cards

Section
2.6.3.9

Direct Credit
cardaccountpayment

Section
2.6.3.10

csv_dc_cc_account BACS
Services
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

Direct Debit confirm and
revoke

Section
2.6.3.15

csv_dd_setup_edit BACS
Services

2.6.2.2

Batch Submission Elements

© 2013 DataCash. All rights reserved.
Page 350 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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
Request.Transaction
Position:

Elements of BatchInputTxn
Element
Name

Description

Values / Limitations

batchfile

The Batch Request,
compressed using Zlib
compression, then Base64
encoded

txn_count

The total number of
Must be an integer > 0.
transactions in the batchfile

The total gross value of
transactions in the
total_amount batchfile, regardless of
currency and transaction
type

Uncompressed Batch Request must
be less than 1MB

R

R

Tolerant to 0.001. If the format of
the transactions within the Batch
Request does not contain an amount, R
the total_amount must be set to
zero

Attributes of batchfile
Element
Name

format

Description

The format of the file you are
submitting

Values / Limitations

Please refer to section
2.6.2

R

© 2013 DataCash. All rights reserved.
Page 351 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

XML Examples of Batch Submission for BatchInputTxn
complex elements

…
3
395.99


…
16
0


…
4
75.60


…
29
0


…
63
1565.09


© 2013 DataCash. All rights reserved.
Page 352 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

2.6.2.2.3

XML Example Batch Submission

Example XML Batch Submission for a Batch Request in
XML format containing three transactions


******
99000001



…
3
395.99




Example XML Batch Submission for a Batch Request in CSV
format containing five transactions


******
99000001



…
5
2501.00




© 2013 DataCash. All rights reserved.
Page 353 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

Example XML Batch Submission for a Batch Request in XML
format containing five transactions


******
99000001



…
5
395.99




Example XML Batch Submission for a Batch Request in CSV
format containing eighteen transactions


******
99000001



…
18
156.00




© 2013 DataCash. All rights reserved.
Page 354 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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

3900900100010001
batch_ABCDEF
LIVE
ACCEPTED
1



3800900100010006
Supplied and actual transaction counts do
not match
batch_XYZ
LIVE
BatchInput: Error in batch data
262



© 2013 DataCash. All rights reserved.
Page 355 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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
2.6.2.3.2

Schema Elements for Batch Submission Query
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
Request.Transaction
Position:
Elements of HistoricTxn
Element
Name

Description

method

The transaction type

reference

The datacash_reference of the Batch
Submission

Values /
Limitations

query

R
R

Example XML Request for HistoricTxn complex elements

3900900100010001
query


© 2013 DataCash. All rights reserved.
Page 356 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

2.6.2.3.3

XML Example Batch Submission Query

Example XML Batch Query


*****
99000001



query
3900900100010001



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.

© 2013 DataCash. All rights reserved.
Page 357 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

2.6.2.4.2

XML Example Query Response

Two Example XML Batch Query Responses

…
3900900100010001
batch_ABCDEF
LIVE
ACCEPTED
1



3400900100010008
You have queried a Batch Input Transaction,
which is currently being processed
batch_ABCDEG
LIVE
BatchInput: Processing
273


Batch Input Request and Response - Common XML Elements
2.6.2.5.1
Schema Elements for Batch Request
2.6.2.5.2
BatchInputRequest

2.6.2.5

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
BatchInputRequest
Position:
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
R
listed in the Batch Submission

reference

A reference number for
the entire Batch

Must be between six and thirty
alphanumeric in length

R

© 2013 DataCash. All rights reserved.
Page 358 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

Example XML Request for Header complex elements


xml_cardtxn
mybatch0002




xml_directdebit
mybatch_0003


2.6.2.5.2.2 Transactions
Element Name: Transactions
BatchInputRequest
Position:
Elements of Transactions
Element
Name

Request

Description

One Request
element per
transaction

Values / Limitations

Each Request must have identical Authentication
elements, which must also be the same as those supplied R
in the Authentication element of the Batch Submission

Example XML for Transactions complex elements. There are 3 transactions.


...


...


...



© 2013 DataCash. All rights reserved.
Page 359 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

2.6.2.5.3

Example XML Batch Request




xml_cardtxn
batchref1234




...


...


...



2.6.2.5.4
2.6.2.5.5

Schema Elements for Batch Response
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
BatchInputResponse
Position:
Elements of Transactions
Element Name
Response

description
One Response element per original transaction

Example XML for Transactions complex elements.
There are 2 transactions present


...


...



© 2013 DataCash. All rights reserved.
Page 360 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

2.6.2.5.6

Example XML Batch Response

Example XML for a Batch Response, without the transaction details
shown




...
...


An Example XML Response, with 3 transactions






183425
Mastercard
United Kingdom

ADDRESS MATCH ONLY
1

BARCLAYS BANK PLC

3300900100010037
1000001
LIVE
ACCEPTED
1



3300900100010037
123402
Prereg: Merchant Not Subscribed
251




100000

3300900100010037
123402
ACCEPTED
1





© 2013 DataCash. All rights reserved.
Page 361 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

Batch Request and Response - Common CSV Elements
2.6.2.6.1
CSV File Format Definition

2.6.2.6

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

© 2013 DataCash. All rights reserved.
Page 362 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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

2 datacash_ref

The datacash_reference of the
datacash_reference
transaction

3 response_code

The DataCash Response Code

4

status_message

Additional information about the reason
response_code

authcode

The result of the authorisation
request, for transactions
authcode
submitted for authorisation only
–otherwise blank

time

The Unix Timestamp of the
transaction

5

6

merchant_reference

status

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"

© 2013 DataCash. All rights reserved.
Page 363 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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



xml_cardtxn
batchref1234





99000001
******




04/06
01/04
633300*********1

1 High Street, UK 
S01 2CD
1


pre


146.00
1000001





******
99000001

© 2013 DataCash. All rights reserved.
Page 364 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL



123402
249.99


auth

310000008888881212





99000001
******



3100000088888888
txn_refund






2.6.3.2

xml_chp_cardtxn

Example XML Batch Request containing three transactions with a total value
of 120.72 in two currencies



xml_chp_cardtxn
batchref1234





*******
99000001



parked
1234567890blahh
54.00



****************




© 2013 DataCash. All rights reserved.
Page 365 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

auth
10
000123

*
00
54.00
00
031107
826
826
****************
****
****
********
**********
**************
****
**
******
**********
****
****
**
******
32
**************






*******
99000001



keyed
1234560002
30.00






auth
000124

**


444433*********1
12/09

© 2013 DataCash. All rights reserved.
Page 366 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL






*******
99000001



swiped
1234560002
26.23



****************




auth
000125

**






*******
99000001



keyed
1234560002
10.49






refund
000126

**


444433*********1
12/09


© 2013 DataCash. All rights reserved.
Page 367 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL





2.6.3.3 xml_direct_credit
Example XML Batch Request xml_directcredit containing two transactions
with a total value of 80.00



xml_directcredit
45356132





fred
21850000



standardDC0000054
45.00


directcredit
826300
80000990
Jo Bloggs





fred
21850000



ddrefund00434582
35.00


ddrefund
3600900100010007






© 2013 DataCash. All rights reserved.
Page 368 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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



xml_directdebit
batchref1236





99000001
******



938611
02149187
Mr A. N. Other
setup


1000001





******
99000001



123402
100.99


drawdown
90000005





******
99000001



123402
© 2013 DataCash. All rights reserved.
Page 369 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

295.00


drawdown
90000005
20050929





99000001
******



revoke
40488707


383285870486111





99000001
********



confirm
40502431


383366196990741






© 2013 DataCash. All rights reserved.
Page 370 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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
R

1

pan

2

expiry_date

3

start_date

4

issue

M

5

amount

R

6

currency

7

merchant_ref

As described in section 2.2.1.1.1

As described in section 2.2.1.1.3

M

R
R

The transaction type

auth
pre
refund
erp

8

method

9

capturemethod As described in section 2.8.3.10.2

10 authcode

R

The authorisation code
received from the bank

R
M1

If presented, must be value
received from Banks Authorisation O
centre

1

Mandatory 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

© 2013 DataCash. All rights reserved.
Page 371 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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

O

12

address_line_2

O

13

address_line_3 As described in section 2.4.1.1.2

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

© 2013 DataCash. All rights reserved.
Page 372 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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

17 As described in section 2.6.3.5
8

method

The transaction type

auth
refund

R

9

capturemethod

Indicates how the transaction keyed
swiped
was accepted at the POS

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 O
units (i.e. 10.98)

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

Whether the Terminal has
16 magnetic_stripe_reader magnetic stripe reading
capability

true
false

R

17 manual_card_entry

Whether the Terminal has the
true
facility to enable card details false
to be manually entered

R

18 pin_pad_available

Whether the Terminal has a
keypad to enable the PIN to
be entered

R

true
false

© 2013 DataCash. All rights reserved.
Page 373 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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

1 reference DataCash unique reference of
the original transaction

Values / Limitations
-

R

R

2 method

The transaction type

fulfill
txn_refund
cancel
accept_fraud
authorize_referral_request

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.

© 2013 DataCash. All rights reserved.
Page 374 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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

R

4 currency

R

5 method

As described in section 2.7.1.1.5

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

© 2013 DataCash. All rights reserved.
Page 375 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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

1 merchant_ref

The reference number of the
drawdown

2 pan

The card number

3 amount

The value to credit

4 card_name

The card holders name

5 expiry_date

The card expiry date

Values / Limitations

See limitations

R
R

Major.minor currency
units (i.e. (10.99)

R
O
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

1 merchant_ref The reference number of the DDI

Values / Limitations

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

© 2013 DataCash. All rights reserved.
Page 376 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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

2 amount

The value to credit

Major.minor currency units (i.e.
R
(10.99)

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

See limitations

O

6 bank_ref

R

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

© 2013 DataCash. All rights reserved.
Page 377 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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

01
17
18
19

O

5 bacs_tran_code Enables the BACS transaction code
to be explicitly set

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

© 2013 DataCash. All rights reserved.
Page 378 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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.

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

R

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

© 2013 DataCash. All rights reserved.
Page 379 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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

© 2013 DataCash. All rights reserved.
Page 380 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

2.7
2.7.1

CARD HOLDER PRESENT
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

© 2013 DataCash. All rights reserved.
Page 381 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

2.7.1.1.1

TxnDetails

Element Name: TxnDetails
Request.Transaction
Position:
Elements of TxnDetails
Element Name

Values /
Limitations

Description

merchantreference A unique reference number to
distinguish each transaction
amount

The value of the transaction

capturemethod

Indicates how the transaction was
accepted at the POS

See Answer

Required?

R
R

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

123402
59.99
parked


AB78324293452
26.50
swiped


AB78324293452
26.50
swiped

2.7.1.1.2

CardTxn

© 2013 DataCash. All rights reserved.
Page 382 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

Element Name: CardTxn
Request.Transaction
Position:

Elements of CardTxn
Element Name

Values /
Limitations

Description

Keyed Swiped Parked

authcode

The authorisation code,
See note
if on-line authorisation
below
is not required

O

X

X

Card

See section 2.7.1.1.5

R

X

X

card_details

Data read from the
magnetic stripe of the
card, or equivalent
from the ICC

Must be
Base64
encoded

-

X

X

hotcardfile

Indicates which Hot
Card File was used
during the transaction

-

O

O

O

ICC

See section 2.7.1.1.4

-

-

R

method

The transaction
method

auth
creditcheck

R

R

R

reason_online_code For on-line transactions: the reason
for being on-line. As defined by APACs

O

O

O

R

R

R

Terminal

See section 2.7.1.1.3

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

method

Attribute of
element

authcode

Description

Values / Limitations

Must be present if
Indicates how the authcode element is
presented:
authcode was
online
obtained.
terminal
telephone

Required?

R

© 2013 DataCash. All rights reserved.
Page 383 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

auth_datetime authcode

The actual date &
time of the
transaction

type

Indicates the type track2_data
of data

card_details

As a unixtimestamp

R1
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

…

NDkyOTQ5ODMxMTQwMDAwMj0wODAzMjAxMDA5ODgwMDAwMDAwMR8wMA==

…
…
creditcheck
10


Example XML for CardTxn element, for a swiped transaction without an
authcode

…

NDkyOTQ5ODMxMTQwMDAwMj0wODAzMjAxMDA5ODgwMDAwMDAwMR8wMA==

creditcheck


Example XML for CardTxn element, for a swiped or
parked transaction with authcode

…
…
creditcheck
451576


© 2013 DataCash. All rights reserved.
Page 384 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

Example XML for CardTxn element, for a keyed transaction

…
…
auth


2.7.1.1.3

Terminal

Element Name: Terminal
Request.Transaction.CardTxn
Position:
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

© 2013 DataCash. All rights reserved.
Page 385 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

unattended_
device

features_
capabilities

downline_load_
floor_limit

message_
capabilities

downline_
load_referral

message_
capabilities

hold_capability

message_
capabilities

Indicates whether
transaction is
processed from an
unattended terminal

As per APACS
standard 70 book 2
appendix A.9

response_additional message_
_data_support
capabilities

true
false

O

true
false

O

true
false

O

true
false

O

true
false

O

Example XML for Terminal element





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
Request.Transaction.CardTxn
Position:

2.7.1.1.5

Card

This element is only required for keyed transactions.
Element Name: Card
Request.Transaction.CardTxn
Position:
Elements of Card
Element Name

Description

Values / Limitations

© 2013 DataCash. All rights reserved.
Page 386 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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

01/12
444433*********1


01/06
1
01/99
446281*********2

2.7.1.1.6

HistoricTxn

This element should be presented for cancel or authorize_referral_request
transactions only.
Element Name: HistoricTxn
Request.Transaction
Position:
Elements of HistoricTxn
Element Name

method

Description

The transaction type

The
datacash_reference
datacash_reference
of the transaction to
be cancelled
authcode

Values / Limitations

cancel

authorize
_referral
_request

cancel
authorize_referra
l_request

R

R

Must be valid
transaction

R

R

X

R

cancel

authorize
_referral
_request

Value received from
Banks Authorisation
centre

Attributes of Elements in HistoricTxn
Attribute Name

Attribute
of
element

Description

Values / Limitations

© 2013 DataCash. All rights reserved.
Page 387 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

Indicates
whether a
reversal should
be attempted

true
false

O

X

Indicates how
authcode the authcode
was obtained.

online
terminal
telephone

X

R

The actual date
authcode & time of the
transaction

As a unixtimestamp

X

R1

reversal

method

method

auth_datetime
1

Field is required for merchants using NatWest Streamline. For other Acquiring Banks
this field is optional.

Example XML for HistoricTxn element

cancel
4600200040913258


cancel
4500200040913862


4500200040913862
A6
authorize_referral_request


© 2013 DataCash. All rights reserved.
Page 388 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

2.7.1.2

Example XML Requests

Example XML Request for a parked transaction


99000001
mypasswd



57483573457gegrreg
54.00
parked






10
NDkyOTQ5ODMxMTQwMDAwMj
0wODAzMjAxMDA5ODgwMDAwMDAwMR8wMA==

00
00
826
826
ED128CAB559EC54C
5C00
0CF3
81B72731
0000008000
06FE0A03A4A800
80
410302
A0000000031010
0084
7546

creditcheck




© 2013 DataCash. All rights reserved.
Page 389 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

Example XML Request for a swiped transaction


99000001
mypasswd



924100120050503165050 
40.01
swiped






OzQ5Mjk0OTgzMTE0MDAwMDI9MDg
wMzIwMTAwOTg4MDAwMDAwMDE/Pw==
creditcheck




Example XML Request for a cancellation


99000001
mypasswd



cancel
575600720050517212621




© 2013 DataCash. All rights reserved.
Page 390 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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
floorlimit

As described in the APACS30 Response

issuer_auth_data
issuer_script_data

Indicates (where available) the party who provided the
authorisation. Only returned for creditcheck transactions. The
returned value will be one of:
authorising_entity
 card acceptor
 acquirer
 card scheme
 card issuer
Attributes of Elements in Response
Attribute Name Attribute of element

reversal

2.7.1.4

reason

Description

Indicates the status of reversal requests

Example XML Responses

Example XML Response to an auth or creditcheck

AUTH CODE:100100
00

100100
VISA
United Kingdom

…
020
…
ACCEPTED
MDIyMjQ0=
1



© 2013 DataCash. All rights reserved.
Page 391 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

Example XML Responses to Cancellation Requests

…
Too much time has elapsed between the original
txn and the reversal request.
…
…
CANCELLED OK
1



…
Reversal ACCEPTED status=1
authcode=100100
…
…
CANCELLED OK
1


Example XML Response for an authorize_referral_request

…
…
…
ACCEPTED
1



© 2013 DataCash. All rights reserved.
Page 392 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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-ReferenceTransactions-Chip-PIN2.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

© 2013 DataCash. All rights reserved.
Page 393 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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
Request.Transaction
Position(s)
Elements of TxnDetails
Element Name

Description

allocated_reference

The datacash_reference returned from
an allocate_reference transaction

amount

The value of the transaction

Values /
Limitations

16 digit number

Example XML Element TxnDetails for a preallocated reference transaction

3000100012345671
100.00

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
Request.Transaction
Position(s)
Elements of CardTxn
Element Name
method

Description

Values / Limitations

The transaction type allocate_reference

Example XML CardTxn element

allocate_reference


© 2013 DataCash. All rights reserved.
Page 394 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

2.7.2.2

Example Request

Example XML Request for allocate_reference



123402


allocate_reference



Example XML Request

…


4800200040913907
54.00
parked






NDkyOTQ5ODMxMTQwMDAwMj
0wODAzMjAxMDA5ODgwMDAwMDAwMR8wMA==

10
00
00
826
826
ED128CAB559EC54C
5C00
0CF3
81B72731
0000008000
06FE0A03A4A800
80
410302
A0000000031010
0084
7546

creditcheck




© 2013 DataCash. All rights reserved.
Page 395 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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


3000100012345671
123402
LIVE
ACCEPTED
1



Back to Contents

© 2013 DataCash. All rights reserved.
Page 396 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

2.8
2.8.1

OTHER DPG SERVICES
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:


o
o




o


o

Request
Authentication – section 2.1.1.2
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
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
FlightDetails – details of flight legs, section 2.8.1.1.8

© 2013 DataCash. All rights reserved.
Page 397 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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
Request.Transaction
Position(s)

Elements of TxnDetails
Element Name

Description

The value of
the transaction

Values / Limitations

Required
S G D X A C CB UB DR

amount

May be ‘0’ only for D,
where a Billing
Agreement is to be
created with no
initial payment
R - R O R R
taken. For DR it may
be ‘0’ for S if no
initial payment is to
be taken.

-

-

R

A unique
reference
merchantreference number for
each
transaction

Minimum 6,
maximum 30
alphanumeric
characters. Must be
unique

R

R

R

R R R O - -

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.

© 2013 DataCash. All rights reserved.
Page 398 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

Attributes of elements of TxnDetails
Attribute
name

currency

Attribute of
Element

amount

Description

The currency for
the payment

Values / Limitations
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

19.26
123ABC


46548tretr

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
Request.Transaction
Position(s)

© 2013 DataCash. All rights reserved.
Page 399 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

Elements of PayPalTxn
Required
Element Name

Description

Values / Limitations

S G

D R A C V

C
B

UB

D
R

URL to which the
customer is returned
if (s)he does not
approve the use of
PayPal

cancel_url

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 R R R R R R R

R

R

reference

G uses ref from S
D uses ref from S
R uses ref from either D or C
The 16 digit
A uses ref from S
datacash_reference,
C uses ref from A
referring to a previous
V uses ref from A (or D when
successfully processed
payment_action is order)
transaction
CB uses ref from S
UB uses ref from D or CB
DR uses ref from D or CB

- R R R R R R R

R

R

© 2013 DataCash. All rights reserved.
Page 400 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

URL to which the
customer’s browser is
returned.
Recommended to be
the final review page
URL should be URL-encoded
on which the customer
confirms the order
and payment/billing
agreement

R - -

- - - -

-

-

-

MerchantInitiatedBilling –
creates a billing agreement
even if there is an existing
billing agreement
MerchantInitiatedBillingSi R - ngleSource – creates a billing
agreement only if there is no
existing billing agreement with
the buyer

- - - -

-

-

-

Active
Cancelled
Note: an agreement which has
a status of Cancelled can not
be further updated.

- - -

- - - -

-

O

-

Description of goods
billing_agreement_de or services associated
scription
with the billing
agreement

127 single-byte characters

O - -

- - - -

-

O

-

billing_agreement_cu Custom annotation
stom
field for your own use

255 single-byte characters

O - -

- - - -

-

O

-

- - O - - - -

-

-

-

O - -

-

-

-

return_url

billing_type

Type of billing
agreement.

The new/current
billing_agreement_st status of the billing
agreement
atus

An identification code 32 single-byte alphanumeric
for use by third party characters
applications to identify
transactions

buttonsource

channel_type

Type of channel

Merchant – non-auction seller
eBayItem - ebay auction

- - - -

© 2013 DataCash. All rights reserved.
Page 401 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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
255 single-byte alphanumeric
PayPal to return on
characters
get_express_checkou
t_details and
do_express_checkout
_payment

O - O - - - -

-

-

O

description

Description of the
items the customer is
purchasing

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

- - O - - - -

-

-

O

O - -

-

-

-

127 single-byte characters

Total handling costs
for this order
handling_total

header_style

Defines the image,
border colour and
background colours
for the image in the
header of the
payment page.
Header space is 750px
See attributes table below
wide by 90 px high.

- - - -

© 2013 DataCash. All rights reserved.
Page 402 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

invnum

Your own unique
invoice or tracking
number. Is returned
in the
do_express_checkout
_payment response

O - O - - O -

-

-

O

- - O - - - -

-

-

-

- - O - - - -

-

-

O

Please refer to section
2.8.1.1.5

Alphanumerics
- (dash)
* (asterisk)
. (period)

Items

{space}

Sum of cost of all
items in this order

item_total

Numeric with two decimal
places. Must not exceed
$10,000 in any currency. Max
value 9,999,999.99

© 2013 DataCash. All rights reserved.
Page 403 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

Character length and
limitations: 2-character
country code


















localecode

Locale of pages
displayed by PayPal
during checkout

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







O - -

- - - -

-

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)

© 2013 DataCash. All rights reserved.
Page 404 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

-

-

COMPANY CONFIDENTIAL




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=_rendercontent&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

no_shipping

Indicates whether the
shipping address fields 0 - fields displayed (default)
should be displayed
1 - fields not displayed
on the PayPal pages
Custom memo about
the refund

note

Numeric with two decimal
places. Must not exceed
$10,000 in any currency. Max
value 9,999,999.99

O - -

- - - -

-

-

-

O - -

- - - -

-

-

-

- - - O - O O -

-

-

255 single-byte alphanumeric
characters
22 single-byte characters
comprised of:
Alphanumerics
- (dash)
* (asterisk)
. (period)
{space}

© 2013 DataCash. All rights reserved.
Page 405 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

Your URL for receiving 2048 single-byte alphanumeric
Instant Payment
characters
Notification (IPN)
about this transaction
- - O - - - -

-

-

O

- - - -

-

-

-

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

- - - -

-

-

-

notify_url

override_address

Indicates whether the 0 – displays details held on file
shipping address fields (default)
(as set by you) should 1 – displays details set by you
be displayed on the
O - PayPal pages, rather
than the shipping
address details held
on file at PayPal

payment_action

Specifies the type of
PayPal service to use
`sale` - will
use Express Checkout
instant payment
(default)
`order` - will use
Auth Capture

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
O - Profile  Profile subtab of
your PayPal Account

payment_type

Specifies type of
PayPal payment you
require for the billing
agreement

Any
InstantOnly

req_billing_address

Specifies whether you
require the customers
0 – Billing address not
billing address from
required (default)
PayPal. This is
1 – Billing address required
returned the
get_express_checkou
t_details response.

© 2013 DataCash. All rights reserved.
Page 406 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

Indicates whether the
customer’s shipping
req_confirmed_shippi
address on file with
ng
PayPal must be a
confirmed address

0 – need not be confirmed
(default)
1 – must be confirmed

O - -

- - - -

-

-

-

- - O - - - -

-

-

O

- - -

- - O -

-

-

O

O - -

- - - -

-

-

-

- - O - - - -

-

-

O

Total shipping cost for
this order
shipping_total

Per transaction
description of the
payment that is
passed to the
consumer’s credit card
soft_descriptor

solution_type

Alphanumerics
- (dash)
* (asterisk)
. (period)
{space}

Type of checkout flow

Sum of tax for all
items in this order

tax_total

255 single-byte alphanumeric
characters
22 single-byte characters
comprised of:

Sole – for Express Checkout
auctions
Mark – normal Express
Checkout
255 single-byte alphanumeric
characters
22 single-byte characters
comprised of:
Alphanumerics
- (dash)
* (asterisk)
. (period)
{space}

© 2013 DataCash. All rights reserved.
Page 407 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

Time stamped token – 20 single-byte characters max
token expires after
three hours
Normally this is
generated by PayPal
and does not need to
be supplied.

token

ShippingAddress

Please refer to section
2.8.1.1.6
255 single-byte alphanumeric
characters
Please refer to section 22 single-byte characters
comprised of:
2.8.1.1.7
Alphanumerics
- (dash)
* (asterisk)
. (period)
{space}

AirlineItineraryData

O - -

- - - -

-

-

-

- - O - - - -

-

-

-

- - -

-

-

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 singlebyte characters max, URL-encoded.

O

stylename

page_style

Used to select the style of checkout pages. Styles are
configurable in PayPal account settings.

O

© 2013 DataCash. All rights reserved.
Page 408 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

Example XML for PayPal elements

set_express_checkout
https://www.example.com/myshoppingcard?action=
complete&sale_id=xyz123/
https://www.example.com/myshoppingcard?action=
cancel&sale_id=xyz123/
order


Example XML for PayPal elements for txn_refund

txn_refund
4000900012345671


txn_refund
4000900012345671
Refund of half the order, as promised


© 2013 DataCash. All rights reserved.
Page 409 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

Example XML for PayPal elements for do_authorization

do_authorization
4000900012345671


Example XML for PayPal elements for get_express_checkout_details

get_express_checkout_details
4000900012345671

Example XML for PayPal elements for do_express_checkout_payment

do_express_checkout_payment
4000900012345671


do_express_checkout_payment
4000900012345671
Twenty NeverFail(tm) Widgets
UPS_ID=12345678
abc123
foobar
http://www.example.com/mynotifyurl?id=abc123/

85.00
10.00
5.00
11.97
…
…


do_express_checkout_payment
4000900012345671
…


© 2013 DataCash. All rights reserved.
Page 410 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

Example XML for PayPal elements for do_capture

do_capture
4000900012345671

do_capture
4000900012345671
inv1234
Finally, I have captured some funds
FooCorp LLC


do_capture
4000900012345671
yes
inv1234
This is the last capture for this
authorization
FooCorp LLC


Example XML for PayPal elements for do_void

do_void
4000900012345671


do_void
4000900012345671
Excess funds released


Example XML for PayPal elements for create_billing_agreement

create_billing_agreement
4000900012345671


© 2013 DataCash. All rights reserved.
Page 411 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

Example XML for PayPal elements for update_billing_agreement

update_billing_agreement
4000900012345671
Cancelled



update_billing_agreement
4000900012345671
Subscription to FOO
Magazine
Part of our CHEAP09
promotion


2.8.1.1.3

Example XML for PayPal elements for do_reference_transaction


do_reference_transaction
4000900012345671
Twenty NeverFail(tm) Widgets
UPS_ID=12345678
abc123
foobar
http://www.example.com/mynotifyurl?id=abc123/

85.00
10.00
5.00
11.97
...
...


© 2013 DataCash. All rights reserved.
Page 412 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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
Request.Transaction.PayPalTxn
Position(s)

Elements of Items
Element Name

Description

Values /
Limitations

See section 2.8.1.1.5

Item

Required
S

G

D

R

DR

-

-

O

-

O

Example XML for Items element



2.8.1.1.5

id="0">…
id="1">…
id="2">…
id="3">…

Item

The Item elements contain details of each product within the order.
Element Name: Item
Request.Transaction.PayPalTxn.Items
Position(s)
Elements of Item
Element Name

Description

Values /
Limitations

Required
S

G

D

R

DR

Must not exceed
$10,000 in any
currency. Max value
9,999,999.99

-

-

O

-

O

ebay_item_auction_ Auction transaction
txn_id
identification number

225 single-byte
characters

-

-

O

-

O

Auction item number

765 single-byte
characters

-

-

O

-

O

amount

ebay_item_number

Cost of item

© 2013 DataCash. All rights reserved.
Page 413 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

ebay_item_order_id Auction identification
number

64 single-byte
characters

-

-

O

-

O

-

-

O

-

O

-

-

O

-

O

name

The item name

number

The item number

127 single-byte
characters

quantity

The item quantity

Positive integer

-

-

O

-

O

Item sales tax

Must not exceed
$10,000 in any
currency. Max value
9,999,999.99

-

-

O

-

O

taxamt

Attributes for Elements of Item
Attribute Name

id

Attribute of
element

Item

Value / Limitations

Must start from 0 and be
contiguous

Required

R

Example XML for Item elements for do_express_checkout_payment

Widgets
1230212-A
20
73.03
11.97


Example XML for Item elements for do_express_checkout_payment

9988775544
123456123
abc123def890


© 2013 DataCash. All rights reserved.
Page 414 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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
Request.Transaction.PayPalTxn
Position(s)
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 countryspecific 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

© 2013 DataCash. All rights reserved.
Page 415 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

Example XML for ShippingAddress elements

Joe Bloggs
3 Fish Street
Castle Street
Hull
GB
HU1 1AA
01234 345 6789


John Smith
144 Main Street
San Jose
CA
US
99221


© 2013 DataCash. All rights reserved.
Page 416 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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
Request.Transaction.PayPalTxn
Position(s)

Elements of AirlineItineraryDetails
Required
Element Name

Description

Values / Limitations
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
Positive integer
multiple captures against an
authorization. In the case of
single capture against an
authorization, the value
should be 1

R

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
Positive integer
captures against an
authorisation. In the case of
single capture against an
authorisation, the value
should be 1

R

R

FlightDetails

Please refer to section 2.8.1.1.8

-

R

© 2013 DataCash. All rights reserved.
Page 417 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

issuing_carrier_code

Airline code for the airline
issuing the ticket. Obtain the 4 single-byte
airline code from the official
characters max
Airline Guide or its equivalent

R

R

passenger_name

Name of the passenger

25 single-byte
characters max

R

R

restricted_ticket

Indicated whether the ticket
is restricted (refundable)

0 – Ticket is not
restricted
1 – Ticket is restricted

R

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

R

customer_code

A code that the cardholder
supplied to you. Can be used 17 single-byte
for passing in the frequent
characters max
flyer number of the customer

O

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

O

O

total_fare

Total fare for all legs on this
ticket, excluding taxes and
fees

O

O

total_fee

Total fee for all legs on the
ticket

O

O

total_taxes

Total taxes for all legs on the
ticket

O

O

travel_agency_code

The travel agency code. In an
integration by the airline, this
8 single-byte
is the airline code from the
characters max
official Airline Guide or its
equivalent

O

O

travel_agency_name

Name of the travel agency
issuing the ticket. In an
integration by an airline, this
is the airline name

O

O

YYYYMMDD format

Numeric with two
decimal places. Must
not exceed $10,000 in
any currency. Max
value 9,999,999.99

25 single-byte
characters max

© 2013 DataCash. All rights reserved.
Page 418 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

Example XML for AirlineItineraryData elements

Joseph Bloggs
20090701
Super Agents
SUPER1
BLAH1234567890
ABCD
JBLOGGS09713
85.00
10.00
5.00
0
1
1

...


...



Joseph Bloggs
BLAH1234567890
ABCD
0
1
1

...



© 2013 DataCash. All rights reserved.
Page 419 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

2.8.1.1.8

FlightDetails

The FlightDetails elements contain details of each leg of the trip.
Element Name: FlightDetails
Request.Transaction.PayPalTxn.AirlineItineraryData
Position(s)

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

R

carrier_code

Standard abbreviation for airline
carrier. Obtain the code from the
official Airline Guide or its
equivalent

2 single-byte
characters

R

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

R

departure_time

The departure time in local time
at the departure airport

HH:MM format,
between 00:00
and 23:59

R

R

fare_basis_code

The alphanumeric code that
carriers assign to a particular
ticket type, such as business
class, discounted, or nonrefundable

15 single-byte
characters max

R

R

flight_number

The flight number assigned by the 5 single-byte
airline carrier
characters max

R

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

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

R

travel_date

The date of travel in local time at
the departure airport

YYYYMMDD
format

R

R

© 2013 DataCash. All rights reserved.
Page 420 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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

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

O

endorsement_or_restri
ctions

An endorsement can be an
agency-added notation or a
mandatory government required
notation such as value added tax. 20 single-byte
A restriction is a limitation based characters max
on the type of fare such as a
ticket with a non-refundable or 3day minimum stay.

O

O

exchange_ticket

New ticket number that is issued
when a ticket is exchanged

O

O

O

O

O

O

O

O

fare
fee
taxes

15 single-byte
characters max

Amount of the ticket for this leg of Numeric with two
the trip excluding taxes and fees
decimal places.
Must not exceed
Fee amount for this leg of the trip
$10,000 in any
currency. Max
Amount of the taxes for this leg of the trip
value
9,999,999.99

Attributes for Elements of FlightDetails
Attribute Name

leg_id

Attribute of
element

FlightDetails

Value / limitations

Must start from 0 and be
contiguous

Required

R

© 2013 DataCash. All rights reserved.
Page 421 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

Example XML for FlightDetails elements

CONTKT12345678
EXTKT123456789
X
A1
20090801
AB
0
EDI
LHR
FOO12
12:34
13:37
CHEAP1
15.00
5.00
2.00
nonrefundable


A1
20090801
AB
0
EDI
LHR
FOO12
12:34
CHEAP1


© 2013 DataCash. All rights reserved.
Page 422 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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



xxxxxxxx
xxxxxxxx



100.00
12345601


set_express_checkout
https://www.example.com/myshoppingcard?
action=complete&sale_id=xyz123/
https://www.example.com/myshoppingcard?
action=cancel&sale_id=xyz123/
homer@example.com
1000.00
Twenty NeverFail(tm) Widgets
UPS_ID=12345678
abc123
0
0
0
GB



Test User
1 Main Terrace
Highgate
Wolverhampton
West Midlands
GB
E12 4LQ
0121 231 3122





© 2013 DataCash. All rights reserved.
Page 423 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

Example XML for Request



xxxxxxxx
xxxxxxxx



100.00
12345601


set_express_checkout
https://www.example.com/myshoppingcard?
action=complete&sale_id=xyz123/
https://www.example.com/myshoppingcard?
action=cancel&sale_id=xyz123/





Example XML for Request



xxxxxxxx
xxxxxxxx



100.00
12345601


set_express_checkout
https://www.example.com/myshoppingcard?
action=complete&sale_id=xyz123/
https://www.example.com/myshoppingcard?
action=cancel&sale_id=xyz123/
Merchant
Mark
MerchantInitiatedBilling
Delivery by 10pm
Tuesday
Remember to tell
Bob
InstantOnly



© 2013 DataCash. All rights reserved.
Page 424 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

2.8.1.2.2

get_express_checkout_details

Example XML for Request


xxxxxxxx
xxxxxxxx



46548tretr


get_express_checkout_details
4000900012345671



2.8.1.2.3

do_express_checkout_payment



xxxxxxxx
xxxxxxxx



100.00
12345601


do_express_checkout
4000900012345671


9988775544
123456123

abc123def890



Test User
1 Main Terrace
Wolverhampton
GB
E12 4LQ





© 2013 DataCash. All rights reserved.
Page 425 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

Example XML for Request



xxxxxxxx
xxxxxxxx



100.00
12345601


do_express_checkout_payment
4000900012345671




xxxxxxxx
xxxxxxxx



100.00
12345601


do_express_checkout_payment
4000900012345671
Twenty NeverFail(tm) Widgets
UPS_ID=12345678
abc123
foobar
http://www.example.com/mynotifyurl?id=
abc123/
85.00
10.00
5.00
11.97




© 2013 DataCash. All rights reserved.
Page 426 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

Example XML for Request


xxxxxxxx
xxxxxxxx



100.00
12345601


do_express_checkout_payment
4000900012345671

Joseph Bloggs
BLAH1234567890
ABCD
0
1
1

A1
20090801
AB
0
EDI
LHR
FOO12
12:34
CHEAP1






© 2013 DataCash. All rights reserved.
Page 427 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

Example XML for Request without initial payment to be processed via the
PayPal Auth Capture Service


xxxxxxxx
xxxxxxxx



0
12345601


set_express_checkout
https://www.example.com/myshoppingcard?
action=complete&sale_id=xyz123/
https://www.example.com/myshoppingcard?
action=cancel&sale_id=xyz123/
MerchantInitiatedBilling
MerchantInitiatedBilling
Subscription to
Magazine




© 2013 DataCash. All rights reserved.
Page 428 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

2.8.1.2.4

Example XML for Request with initial payment of £45.99 to be processed via
the PayPal Auth Capture Service


xxxxxxxx
xxxxxxxx



45.99
12345601


set_express_checkout
https://www.example.com/myshoppingcard?
action=complete&sale_id=xyz123/
https://www.example.com/myshoppingcard?
action=cancel&sale_id=xyz123/
MerchantInitiatedBillingSingleSource




© 2013 DataCash. All rights reserved.
Page 429 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

2.8.1.2.5

Example XML for Request with initial payment of £45.99 to be
processed via the PayPal Auth Capture Service


xxxxxxxx
xxxxxxxx



45.99
12345601


set_express_checkout
https://www.example.com/myshoppingcard?
action=complete&sale_id=xyz123/
https://www.example.com/myshoppingcard?
action=cancel&sale_id=xyz123/
MerchantInitiatedBillingSingleSource
order




2.8.1.2.6

txn_refund

Example XML for a full refund


xxxxxxxx
xxxxxxxx



txn_refund
4000900012345671


4655eubtr




© 2013 DataCash. All rights reserved.
Page 430 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

Example XML for a partial refund


xxxxxxxx
xxxxxxxx



19.00
45gy7byrty


txn_refund
4000900012345671
Here's the refund I promised




© 2013 DataCash. All rights reserved.
Page 431 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

2.8.1.2.7

do_authorization

Example XML for do_authorization


xxxxxxxx
xxxxxxxx



100.00


do_authorization
4000900012345671



2.8.1.2.8

do_capture

Example XML for do_capture


xxxxxxxx
xxxxxxxx



100.00


do_capture
4000900012345671




© 2013 DataCash. All rights reserved.
Page 432 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

Example XML for do_capture


xxxxxxxx
xxxxxxxx



100.00


do_capture
4000900012345671
yes
inv1234
Finally, I have captured some funds
FooCorp LLC



2.8.1.2.9

do_void

Example XML for do_void



xxxxxxxx
xxxxxxxx



do_void
4000900012345671




© 2013 DataCash. All rights reserved.
Page 433 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

Example XML for do_void


xxxxxxxx
xxxxxxxx



do_void
4000900012345671
Excess funds released



2.8.1.2.10

create_billing_agreement

Example XML for create_billing_agreement


xxxxxxxx
xxxxxxxx



create_billing_agreement
4000900012345671




© 2013 DataCash. All rights reserved.
Page 434 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

2.8.1.2.11

update_billing_agreement

Example XML for update_billing_agreement for cancelling a billing
agreement


xxxxxxxx
xxxxxxxx



update_billing_agreement
4000900012345671
Cancelled




Example XML for update_billing_agreement to update the description
and custom field


xxxxxxxx
xxxxxxxx



update_billing_agreement
4000900012345671
Subscription to FOO Magazine

Part of our CHEAP09 prom





© 2013 DataCash. All rights reserved.
Page 435 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

2.8.1.2.12

do_reference_transaction

Example XML for do_reference_transaction, with immediate settlement
of funds.


xxxxxxxx
xxxxxxxx



do_reference_transaction
4000900012345671
Twenty NeverFail(tm) Widgets
UPS_ID=12345678
abc123
foobar
http://www.example.com/mynotifyurl?id=abc123/

85.00
10.00
5.00
11.97
...
...




Example XML for do_reference_transaction, with delayed settlement of
funds


xxxx
xxxx



100.00


do_reference_transaction
4000900012345671
order




© 2013 DataCash. All rights reserved.
Page 436 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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
Response.Transaction
Position(s)

Elements of PayPalTxn
Element Name

ack

addressid

Description

Values /
Limitations

Provided (if available)?
C
B

U
B

D
E
R

Success
SuccessWith
Warning
Failure
AA A
FailureWithW
arning
Warning

A AAA A

A

A A

- A -

- - - - -

-

- -

S G D R AC V

© 2013 DataCash. All rights reserved.
Page 437 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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
- - A
any currency.
Max value
9,999,999.99

- AAA -

-

A -

1 – the
customer
accepted the
billing
agreement
0 – the
customer did
not agree to
the billing
agreement

- A -

- - - - -

-

- -

The value of the
Billing Agreement
ID originally
billing_agreement_ returned from
id
do_express_checko
ut_payment or
create_billing_ag
reement

- - A

- - - - A

A

- -

The description held 127 singlebilling_agreement_
by PayPal for the
byte
description
Billing Agreement
characters

- -

-

- - - - -

A

- -

The custom
255 singlebilling_agreement_ annotation field held
byte
custom
by PayPal for the
characters
Billing Agreement

- -

-

- - - - -

A

- -

AA A

A AAA A

A

A A

Whether or not the
billing_agreement_ customer accepted
accepted
the billing
agreement

build

A string
representing the
specific software
build that processes
the request and
generated the
response

business

Payer’s business
name

127 singlebyte
characters

- A -

- - - - -

-

- -

correlationid

A string that
identifies the exact
API request that
produced this
response

Max 41
characters

AA A

A - - - A

A

A A

© 2013 DataCash. All rights reserved.
Page 438 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

countrycode

Payer’s country of
residence

currencycode

As defined in
ISO 3166-1

- A -

- - - - -

-

- -

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 nonprimary currency. If
the customer
chooses to pay with
a currency other
than the primary
currency, the
conversion occurs in
the customer’s
account.

feeamt

PayPal fee amount
charged for the
transaction

feerefundamount

Decimal.
Max size 17
characters
including
decimal
point

Must not
exceed
$10,000 in
any
currency.
Transaction fee
refunded to original Max value
recipient of payment 9,999,999.9
9

-

- A

- - A- -

-

- -

-

- A

- - A- -

-

A -

-

- -

A - - - -

-

- -

Payer’s first name

25 singlebyte
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 -

- - - - -

-

- -

firstname

© 2013 DataCash. All rights reserved.
Page 439 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

lastname

Payer’s last name

25 singlebyte
characters

-

A -

- - - - -

-

- -

middlename

25 singlePayer’s middle name 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-MMDDTHH:MM:S SZ

- A

- - A- -

-

A -

payerid

Unique PayPal
customer account
identification
number

13 singlebyte
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

- - - - -

-

- -

17 singlebyte
characters

-

- -

A - - - -

-

- -

20 singlebyte
characters

-

A -

- - - - -

-

- -

refundtransactioni Unique transaction
d
ID for the refund

salutation

Payer’s salutation

© 2013 DataCash. All rights reserved.
Page 440 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

settleamt

Must not
exceed
Amount deposited in $10,000 in
your PayPal account any
after currency
currency.
conversion
Max value
9,999,999.9
9

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 singlebyte
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-MMDDTHH:MM:SS A A
Z

A AAAA A

A A 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 singlebyte
characters

R A

A - - - -

-

transactionid

Unique transaction
ID for the payment

19 singlebyte
characters

- -

A - AAA -

- A -

transactiontype

The type of
transaction

expresscheckout
reversal
merchtpmt

- -

A - - A-

-

- A -

version

PayPal API service
version number

A A

A AAAA A

A A A

authorizationid

Value of
19 singletransactionid
returned in response byte
characters
of
do_authorization

- -

- - - A-

-

- A

- - A- -

-

-

-

A -

- -

- -

- -

© 2013 DataCash. All rights reserved.
Page 441 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

Value of
19 singleparenttransactioni transactionid
byte
returned
in
response
d
characters
of
do_authorization

- -

- - - A-

-

-

- -

19 singleReceipt identification
byte
number
characters

- -

- - - A-

-

-

- -

receipt

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.

multicurrency

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.

© 2013 DataCash. All rights reserved.
Page 442 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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.

buyercomplaint

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

set_express_checkout
https://www.example.com/myshoppingcard?action=
complete&sale_id=xyz123/
https://www.example.com/myshoppingcard?action=
cancel&sale_id=xyz123/
order


Example XML for PayPal elements, for set_express_checkout

Success
1.0006
2010-10-03T13:44:56Z
EC-4VL78907RS990801R
2.300000


© 2013 DataCash. All rights reserved.
Page 443 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

Example XML for PayPal elements, for get_express_checkout_details

Success
PayPal
Confirmed
1

1.0006
6389c035b7785
GB
my_custom_data
abc_11_1191417836_per@example.com
Test
123-456-abc
Arther
User
8PN3BJPN2WNDE
unverified
+44 123 4567
Mr
…
Esq
2010-10-03T13:44:56Z
EC-4VL78907RS990801R
2.300000


Example XML for PayPal elements, for do_express_checkout_payment

Success
10.00
billing123
1.0006
889dd330d54f0
GBP
1.2222
0.54
2010-10-03T13:45:17Z
Completed
instant
None
None
13.22
0.00
2010-10-03T13:45:26Z
EC-4VL78907RS990801R
3YT66098JE5874747
expresscheckout
2.300000


© 2013 DataCash. All rights reserved.
Page 444 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

Example XML for PayPal elements, for refund

1.0006
0.54
2.300000
2010-10-05T13:09:42Z
5db496bf4454
83V1269821897443H
10.00
Success
9.4


Example XML for PayPal elements, for do_authorization

Success
10.00
1.0006
2010-10-03T13:45:26Z
3YT66098JE5874747
2.300000


Example XML for PayPal elements, for do_capture

Success
10.00
123456
1.0006
1.2222
0.54
2010-10-03T13:45:17Z
J660-98E5-8747-473YT
Completed
instant
34FB-SU1K-LAD9-SDA8
13.22
0.00
2010-10-03T13:45:26Z
JE587-4747-3YT6-6098
express-checkout
2.300000


© 2013 DataCash. All rights reserved.
Page 445 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

Example XML for PayPal elements, for do_void

Success
10.00
1.0006
2010-10-03T13:45:26Z
3YT66098JE5874747
2.300000


Example XML for PayPal elements, for create_billing_agreement

Success
B-4C465615S44462100

1.0006
3YT66098JE5874747
2010-10-03T13:45:26Z
2.300000


Example XML for PayPal elements, for update_billing_agreement

Success
Part of our CHEAP09 promo

9.99 per month subscription to
FOO Magazine
B-4C465615S44462100

1.0006
3YT66098JE5874747
2010-10-03T13:45:26Z
2.300000


© 2013 DataCash. All rights reserved.
Page 446 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

Example XML for PayPal elements, for do_reference_transaction

Success
30.00
HOFAOW8973H4FA
1.0006
ABCD123EFGH456
5.00
Completed
instant
25.00
5.00
2010-11-01T12:34:56Z
AUWEHRGLUH92374
merchtpmt
58.000000


Additional XML Example:


xxxxxxxx
xxxxxxxx



100.00
12345601


do_express_checkout_payment
order
4000900012345671




© 2013 DataCash. All rights reserved.
Page 447 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

2.8.1.3.2

Errors

This element will only be returned if a PayPal error or warning occurs.
Elements of Errors
Value

Description
See section 2.8.1.3.3

Error

Example XML for Errors element

…
…
…

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

81104
Missing Parameter
CancelURL : Required parameter
missing
severityCode


10431
Item amount is invalid
Item amount is invalid


© 2013 DataCash. All rights reserved.
Page 448 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

XML Example Responses
2.8.1.4.1
Successful Transactions

2.8.1.4

Example XML Response for a set_express_checkout transaction

4000900012345671
1
12345601
ACCEPTED
LIVE


Success
1.0006
2010-10-03T13:44:56Z
EC-4VL78907RS990801R
2.300000



© 2013 DataCash. All rights reserved.
Page 449 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

Example XML Response for a get_express_checkout_details transaction

4000900012345671
1
12345601
ACCEPTED
LIVE


Success
PayPal
Confirmed

Test User
12 Boddingtons Road
Regeant's Park
Wolverhampton
West Midlands
United Kingdom
GB
Foobar Ltd
Confirmed

1

1.0006
6389c035b7785
GB
my_custom_data>
abc_11_1191417836_per@example.com
Test
123-456-abc
Arther
User
8PN3BJPN2WNDE
unverified
+44 123 4567
Mr

Test User
1 Main Terrace
Highgate
Wolverhampton
West Midlands
United Kingdom
GB
E12 4LQ
0121 231 3122

Esq
2010-10-03T13:44:56Z
EC-4VL78907RS990801R
2.300000


© 2013 DataCash. All rights reserved.
Page 450 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL



Example XML Response for do_express_checkout_payment transaction

4000900012345671
1
12345601
ACCEPTED
LIVE


Success
10.00
billing123
1.0006
889dd330d54f0
GBP
1.2222
0.54
2010-10-03T13:45:17Z
Completed
instant
None
None
13.22
0.00
2010-10-03T13:45:26Z
EC-4VL78907RS990801R
3YT66098JE5874747
expresscheckout
2.300000



© 2013 DataCash. All rights reserved.
Page 451 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

Example XML Response for a refund

4000900012345671
1
12345601
ACCEPTED
LIVE


1.0006
0.54
2.300000
2010-10-05T13:09:42Z
5db496bf4454
83V1269821897443H
10.00
Success
9.4



Example XML Response for a do_authorization

4000900012345671
1
12345601
ACCEPTED
LIVE


Success
10.00
1.0006
2010-10-03T13:45:26Z
3YT66098JE5874747
2.300000



© 2013 DataCash. All rights reserved.
Page 452 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

Example XML Response for a do_capture.which cancels any remaining
funds received against the payers account

4000900012345671
1
12345601
ACCEPTED
LIVE


Success
10.00
123456
1.0006
1.2222
0.54
2010-10-03T13:45:17Z
J660-98E5-8747-473YT
Completed
instant
34FB-SU1K-LAD9-SDA8
13.22
0.00
2010-10-03T13:45:26Z
JE587-4747-3YT6-6098
express-checkout
2.300000



Example XML Response for a do_void

4000900012345671
1
12345601
ACCEPTED
LIVE


Success
10.00
1.0006
2010-10-03T13:45:26Z
3YT66098JE5874747
2.300000



© 2013 DataCash. All rights reserved.
Page 453 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

Example XML Response for a create_billing_agreement

4000900012345671
1
12345601
ACCEPTED
LIVE


Success
B-4C465615S44462100

1.0006
abc123correlationIDftw
2010-11-01T12:34:56Z
58.000000



Example XML Response for an update_billing_agreement


4000900012345671
1
12345601
ACCEPTED
LIVE


Success
Part of our CHEAP09 promo

9.99 per month subscription
to FOO Magazine
B-4C465615S44462100

Active
1.0006
abc123correlationIDftw
2010-11-01T12:34:56Z
58.000000



© 2013 DataCash. All rights reserved.
Page 454 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

Example XML Response for a do_reference_transaction

4000900012345671
1
12345601
ACCEPTED
LIVE


Success
30.00
HOFAOW8973H4FA
1.0006
ABCD123EFGH456
5.00
Completed
instant
25.00
5.00
2010-11-01T12:34:56Z
AUWEHRGLUH92374
merchtpmt
58.000000



© 2013 DataCash. All rights reserved.
Page 455 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

2.8.1.4.2

PayPal Warning and Errors

Example XML Response for an error


4000900012345671
12345601
LIVE

561
PayPal: Error returned in response
The transaction response from PayPal indicated that
an error has occurred - see the extended PayPal
information

Failure
2010-10-03T13:45:26Z
889dd330d54f0
2.300000
1.0006


81104
Missing Parameter
CancelURL : Required parameter
missing
severityCode





© 2013 DataCash. All rights reserved.
Page 456 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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

4000900012345671
12345601
560
PayPal: Not configured for service
Merchant is not configured for the PayPal
service
LIVE



Example XML Response for an invalid transaction

4000900012345671
12345601
565
PayPal: Invalid reference
Referenced transactions is not a
PayPalTxn
LIVE



© 2013 DataCash. All rights reserved.
Page 457 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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

…
1
…
ACCEPTED
LIVE


EC-4VL78907RS990801R


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.

© 2013 DataCash. All rights reserved.
Page 458 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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

3900900100010001
query


2.8.1.6.2

XML Example - PayPal Query Transaction

Example XML PayPal Query


*****
99000001



query
3900900100010001




© 2013 DataCash. All rights reserved.
Page 459 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

2.8.1.6.3

Schema Elements for PayPal Query Response

Element Name: QueryTxnResult
Response
Position:
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

PayPalTxn

Description

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

Capture

Description

Complex element containing details of a single capture. An
element of this type will appear for each capture associated with
the authorization.

© 2013 DataCash. All rights reserved.
Page 460 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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



do_express_checkout_payment

4600900012345673
mref12345680
ACCEPTED
1
2011-07-04 14:57:11

TEST
ACCEPTED
1



© 2013 DataCash. All rights reserved.
Page 461 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

Example XML Response for PayPal Query Txn on an Authorization






4100900012345675
1


4900900012345676
1


do_authorization

4400900012345674
mref12345678
ACCEPTED
1
2011-07-04 15:01:40

TEST
ACCEPTED
1



© 2013 DataCash. All rights reserved.
Page 462 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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




txn_refund
Transaction status has been updated

4100900012345675
mref12345677
ACCEPTED
1
2011-07-04 15:06:12

TEST
ACCEPTED
1



© 2013 DataCash. All rights reserved.
Page 463 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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
Notification
Position:

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

© 2013 DataCash. All rights reserved.
Page 464 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

2.8.1.7.2

Example of a Notification Message

Example XML Message for PayPal IPN Message



4000900001134560
myref1234
reversed


4000900012345671
1



2.8.1.7.3

Schema of a Notification Acknowledgement

Element Name: Acknowledge
Notification
Position:

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

© 2013 DataCash. All rights reserved.
Page 465 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

2.8.1.7.4

Example of a Notification Acknowledgement

Example XML Message for an Acknowledgement


4000900012345671
1



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

o

Authentication – section 2.1.1.1
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

A unique reference
merchantreference number for each
transaction

Values / Limitations
Minimum 6, maximum 30
alphanumeric characters. Must be
unique

© 2013 DataCash. All rights reserved.
Page 466 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

Example XML for EoDTxn elements

48tv3498wy3c4dt

2.8.2.1.2

EoDTxn

There is one element to be presented in this parent element.
1Elements in EoDTxn
Element Name
method

Description

Values / Limitations

The transaction type eod

Example XML for EoDTxn elements

eod

2.8.2.2 Example Requests
Example XML Request


...
...



...


eod




© 2013 DataCash. All rights reserved.
Page 467 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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

4900200047685356
117990881318233
LIVE
ACCEPTED
1



Example XML Response for a rejected transaction

4000200047685351
117990875018165
LIVE
VEoD: already received an EoD
532



© 2013 DataCash. All rights reserved.
Page 468 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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
Request.Transaction
Position:
Elements of RbsGiftCardTxn
Element Name

Description

Values / Limitations

Required

method

The method of the
transaction.

balance_enquiry
redeem
refund
txn_refund

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

R

© 2013 DataCash. All rights reserved.
Page 469 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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


xxxxxxxx
xxxxxxxx



12345601
ecomm


balance_enquiry

xxxxxxxxxxxxxxxx
xxxxxxxx
04/06
01/99





© 2013 DataCash. All rights reserved.
Page 470 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

An example response to a balance enquiry is shown below:
Example Balance Enquiry Response

4000900012345671
1
12345601
ACCEPTED

100000
100.00
GBP

TEST



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


xxxxxxxx
xxxxxxxx



100.00
12345601
ecomm


redeem

xxxxxxxxxxxxxxxx
xxxxxxxx
04/06
01/99

123





© 2013 DataCash. All rights reserved.
Page 471 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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

4000900012345671
1
12345601
ACCEPTED

100000
100.00

TEST


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

4000900012345671
1
12345601
ACCEPTED

100000
-41.00

TEST


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.
© 2013 DataCash. All rights reserved.
Page 472 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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


xxxxxxxx
xxxxxxxx



10.59
12345601
ecomm


refund

xxxxxxxxxxxxxxxx
xxxxxxxx
04/06
01/99




An example response to a successful refund transaction is shown below:
Example Refund Response

4000900012345671
1
12345601
ACCEPTED

100000
100.00

TEST


Note: the response formatting is identical to that for redemption transactions.

© 2013 DataCash. All rights reserved.
Page 473 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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


xxxxxxxx
xxxxxxxx



10.59
ecomm


txn_refund
4100900012345675



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

4000900012345671
1
4000900012345670
ACCEPTED

100000
100.00

TEST



© 2013 DataCash. All rights reserved.
Page 474 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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

4000900012345672
7
12345602
DECLINED

5.25

CARD EXPIRED
TEST



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:

© 2013 DataCash. All rights reserved.
Page 475 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

Example Response for a Invalid Transaction

4000900012345672
631
12345602
Inappropriate card number
The card provided is not an RBS Gift
Card
TEST


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

4000900012345672
6
12345602
BANK DID NOT REPLY
TEST



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
© 2013 DataCash. All rights reserved.
Page 476 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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
Request.Transaction
Position:
Elements of PPTCardTxn
Element Name

Description

Values / Limitations Required

top_up
redeem
refund
balance_enquiry
reversal
txn_refund

method

The method of the transaction

R

pan

The PPT card number. Element
The PPT card
used for “ecomm”, “cnp” and
number
“keyed” capturemethods.

M

pin

A Pin number can optionally be
supplied when performing
“top-up”, “redeem” and
4 digit pin number
“balance_enquiry”
transactions.

O

© 2013 DataCash. All rights reserved.
Page 477 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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

If subscribed to the merchant
reference cancellations service, Merchant reference
merchantreference a “reversal” may be invoked
of the related
transaction
with this element instead of
reference

O

reference

card_details

For the “swiped”
The track2
capturemethod only, this
information from the
element is used instead of pan. PPT gift card

M

Terminal

For PPT transactions using a
terminal (“keyed”, “swiped”
capturemethods), this element
should be present.

M

See section
2.7.1.1.3

2.8.4.3 Schema Elements for Response
Element Name: PPTCardTxn
Response
Position:
Elements of PPTCardTxn
Element Name
Authcode

Description

The authcode of the transaction, this element can also contain
messages from PPT e.g “INVALID PIN”.

PPT may return information in their authorisation
response that indicates that a card has been
card_activated activated as a result of the transaction. This
element will only be included where card activation
has occurred.
Balance

Values /
Limitations

“yes”

The balance remaining on the PPT gift card following the
transaction, returned with major and minor units (i.e 0.00).

© 2013 DataCash. All rights reserved.
Page 478 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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


xxxxxxxx
xxxxxxxx



100.00
12345601
swiped






top_up
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
xxxx




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.

© 2013 DataCash. All rights reserved.
Page 479 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

Example PPT Top Up Response

ACCEPTED
1
GBP
4000900012345671
12345601

100000
100.00
yes

TEST



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


xxxxxxxx
xxxxxxxx



40.00
12345602
keyed






redeem
xxxxxxxxxxxxxxxx
xxxx



Note that the “pin” element is optional.

© 2013 DataCash. All rights reserved.
Page 480 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

An example of a response to the above request is shown below:
Example PPT Redemption Response

ACCEPTED
1
GBP
4800900012345672
12345602

100000
60.00

TEST



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 ecommerce refund request is shown below:
Example PPT Refund Request


xxxxxxxx
xxxxxxxx



30.00
12345603
ecomm


refund
xxxxxxxxxxxxxxxx




© 2013 DataCash. All rights reserved.
Page 481 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

An example response to the above transaction is shown below:
Example PPT Refund Response

ACCEPTED
1
GBP
4800900012345673
12345603

100000
90.00

TEST



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


xxxxxxxx
xxxxxxxx



12345604
ecomm


balance_enquiry
xxxxxxxxxxxxxxxx




© 2013 DataCash. All rights reserved.
Page 482 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

An example response to the above transaction is shown below:
Example PPT Balance Enquiry Response

ACCEPTED
1
GBP
4800900012345674
12345604

100000
90.00

TEST



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


xxxxxxxx
xxxxxxxx



reversal
4800900012345673




© 2013 DataCash. All rights reserved.
Page 483 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

An example response to the above transaction is shown below:
Example PPT Reversal Response

ACCEPTED
1
GBP
4800900012345675
Reversal ACCEPTED status=1
authcode=100000

100000
60.00

TEST



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


xxxxxxxx
xxxxxxxx



10.59


txn_refund
4800900012345672




© 2013 DataCash. All rights reserved.
Page 484 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

An example response to the above transaction is shown below:
Example PPT Txn_Refund Response

ACCEPTED
1
GBP
4800900012345675
12345602

100000
79.41

TEST



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

DECLINED
7
GBP
4800900012345672
12345602

DECLINED
5.25

TEST


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:

© 2013 DataCash. All rights reserved.
Page 485 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

Example of a PPT PIN mismatch response

PIN MISMATCH
7
GBP
4800900012345672
12345602

PIN MISMATCH 010000010000
5.25

TEST



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

4000900012345672
492
12345602
PPT: Inappropriate Request Element
Field LINEITEMDETAIL may not be included in a PPT
transaction
TEST



© 2013 DataCash. All rights reserved.
Page 486 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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

reversed

Description

Indicates whether an automatic reversal
issued by DataCash in the event of a
communications failure was successful.

Values / Limitations

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

4000900012345672
6
12345602
BANK DID NOT REPLY
Reversal attempt FAILED
F
EUR
TEST



© 2013 DataCash. All rights reserved.
Page 487 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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
Request.Transaction.TxnDetails
Position:

Elements of CurrencyConversionTxn
Element Name

Description

exchange_currency

The currency used
by the card

exchange_amount

The amount
provided for the
transaction in the
exchange currency.

exchange_rate

The exchange rate
provided for the
transaction

Values / Limitations

Valid ISO 4217
alphabetic currency
code

Required

R

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

© 2013 DataCash. All rights reserved.
Page 488 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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


xxxxxxxx
xxxxxxxx



100.00
12345601
ecomm

USD
200.00
2.0000



auth

xxxxxxxxxxxxxxxx
12/15





© 2013 DataCash. All rights reserved.
Page 489 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

2.8.5.4

Schema Elements for Response

Element Name: CurrencyConversionTxn
Response
Position:

Elements of CurrencyConversionTxn
Element Name

Description

base_amount

The amount that the
merchant has
requested for the
transaction in their
currency

exchange_currency

The currency used
by the card

exchange_amount

The amount
provided for the
transaction in the
exchange currency

exchange_rate

The exchange rate
provided for the
transaction

Values / Limitations

Valid ISO 4217
alphabetic currency
code

Must contain a decimal
point, and contain no
more than 5 decimal
places

© 2013 DataCash. All rights reserved.
Page 490 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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


100.00
USD
200.00
2.0000


100000
VISA
United Kingdom

4800903000000001
1000000
TEST
ACCEPTED
1



© 2013 DataCash. All rights reserved.
Page 491 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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
Request.Transaction.TxnDetails
Position:

Elements of FexcoDCC
Element Name

Description

Values / Limitations

Required

BaseCurrency

The currency that
Valid ISO 4217
the merchant usually alphabetic currency
trades in
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.

© 2013 DataCash. All rights reserved.
Page 492 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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


xxxxxxxx
xxxxxxxx



200.00
12345601
ecomm

GBP
100.00
2.0000



auth

xxxxxxxxxxxxxxxx
12/15





© 2013 DataCash. All rights reserved.
Page 493 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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/cgibin/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

method

reference

Description

Values / Limitations

The transaction type

query

R

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

© 2013 DataCash. All rights reserved.
Page 494 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

Attributes for Elements of HistoricTxn
Attribute Name Attribute of Element Values / Limitations

type

reference

datacash (default)
O
merchant

Example XML Request for HistoricTxn complex elements

3900900100010001
query


abc12345678
query


2.8.7.3 XML Example - Bankcard Query Transaction
Example XML Bankcard Query


*****
99000001



query
3900900100010001




© 2013 DataCash. All rights reserved.
Page 495 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

2.8.7.4 Schema Elements for Bankcard Query Response
Element Name: QueryTxnResult
Response
Position:
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 3D 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)

© 2013 DataCash. All rights reserved.
Page 496 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

Elements of ThreeDSecure
Element Name

Description

eci

ECI

security_code

CAVV

transactionID

XID

Example XML Response for QueryTxnResult complex elements


1214
444433******1111

natwest
100000
4000900012345671
ecomm
2009-12-08 11:35:48
123401
ACCEPTED
1
1
2009-12-08 11:35:48



0120
0101
633300******0005


11
Q0FWVkNBVlZDQVZWQ0FWVkNBVlY=
MDAwMDAwMDAwMDAwMTIzNDU2NzE=

natwest
100000
4000900012345671
ecomm
2009-12-08 11:56:53
4421000008
ACCEPTED
1
1
2009-12-08 11:56:53


© 2013 DataCash. All rights reserved.
Page 497 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

2.8.7.5 XML Example - Bankcard Query Responses
Example XML Response for successful Query Txn



0120
0101
633300******0005


11
Q0FWVkNBVlZDQVZWQ0FWVkNBVlY=
MDAwMDAwMDAwMDAwMTIzNDU2NzE=

natwest
100000
4000900012345671
ecomm
2009-12-08 11:56:53
4421000008
ACCEPTED
1
1
2009-12-08 11:56:53

TEST
ACCEPTED
1



Example XML Response for unsuccessful Query Txn


4100900012345675
The transaction you are querying
cannot be located
TEST
Cannot locate transaction to query
274



© 2013 DataCash. All rights reserved.
Page 498 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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
Request.Transaction.VtidConfigurationTxn
Position:
Elements of VtidConfigurationTxn
Element Name

Description

Password

See section 2.8.8.2.2

method

The transaction type

2.8.8.2.2

Values / Limitations

R
vtidconfiguration

R

Password

This element must be present with all transactions
Element Name: Password
Request.Transaction.VtidConfigurationTxn.Password
Position:

Elements of Password
Element
Name

Description

Values / Limitations

© 2013 DataCash. All rights reserved.
Page 499 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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.
The password to be
new_password assigned to the
vTID.







More than 8 characters
R
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.

Example XML Request for VtidConfigurationTxn with specified password

vtidconfiguration

########



2.8.8.3

Example XML Requests

Example XML Request for VtidConfigurationTxn for password generation


...
88008800



vtidconfiguration







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
© 2013 DataCash. All rights reserved.
Page 500 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

Element Name

Description

Contains the specified or generated
password as acknowledgement that the
password has been modified.

new_password

Example XML Response for VtidConfigurationTxn

4000900012345671
123400
########
ACCEPTED
1



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.

© 2013 DataCash. All rights reserved.
Page 501 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

2.8.9.2.2 Txn Details
Element Name: TxnDetails
Request.Transaction
Position:

Elements of TxnDetails
Element Name

Description

This is the decimal amount of the transaction. The currency
attribute must be provided as a 3 letter currency code. (See
Example XML)

amount

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
Request.Transaction
Position:

Elements of PreCallTxn
Element
Name

method

2.8.9.2.4

Description

Currently, the only supported method is “precall”, and you should
populate this field with the latter value.

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.

© 2013 DataCash. All rights reserved.
Page 502 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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
Request.Transaction.PreCallTxn.ClientData
Position:
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
Request.Transaction.PreCallTxn
Position:

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-0114T14:22:23+01:00

billing_country

This is the country in which the customer will be billed.

© 2013 DataCash. All rights reserved.
Page 503 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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

2.8.9.2.7

The customers preferred language.

Airline Details

Element Name: AirlineDetails
Request.Transaction.PreCallTxn
Position:

Elements of AirlineDetails
Element Name

airline_country

Description

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
Request.Transaction.PreCallTxn.AirlineDetails.Legs
Position:

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.

© 2013 DataCash. All rights reserved.
Page 504 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

Example XML Request for PreCallTxn

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.

© 2013 DataCash. All rights reserved.
Page 505 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

Example XML Request for PreCall Txn


df855a23df855a23df855a23df855a23df855a23
88008800



1000.00
00001239


precall

00001239
order-15-2011
cust12358
FRALH010Z
IT
agent.com

xyz
xyz
xyz
xyz



2011-01-14T14:22:23+01:00
2011-0325T14:30:00+01:00
DE
true
ecommerce
112.118.128.253
fr


DE
BOOK
SEN


JFK
NYC
NY
US
LH
HAM
HH
HH
DE






© 2013 DataCash. All rights reserved.
Page 506 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

2.8.9.3

Example Request / Response XML

The following represents an example PreCall request and response.

Example XML Response for PreCallTxn



00001239
order-15-2011
cust12358

xyz
xyz
xyz
xyz



PL
CC


4600900012345673
00001239
TEST
ACCEPTED
1



© 2013 DataCash. All rights reserved.
Page 507 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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

© 2013 DataCash. All rights reserved.
Page 508 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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
tokenize
Token generation retokenize

R

Overrides the
shared_secret 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

...
tokenize


...
retokenize
1234567890ABCDEFGHIJ


© 2013 DataCash. All rights reserved.
Page 509 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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
Request.Transaction.CardTxn.Card
Request.Transaction.DirectDebitTxn
Request.Transaction.FuelCardTxn.Card
Position:
Request.Transaction.RbsGiftCardTxn.Card
Request.Transaction.TokenizeTxn.CardTxn.Card
Request.Transaction.DirectcreditTxn
The pan element
Element Name

pan

Description

The card
number, or
token

Values/Limitations

Required for

If the value supplied is a
token, the attribute must
be set appropriately (see
below).

All transaction types

Attributes for pan
Attribute
Name

type

Values / Limitations

Required for

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

3C12DE55292A13227E14D92C6E8D8F4843D21654


© 2013 DataCash. All rights reserved.
Page 510 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

Example XML for Card element, for a tokenize transaction

4444333322221111


Example XML for Card complex elements for a payment using a token

3C12DE55292A13227E14D92C6E8D8F4843D21654
01/49


Example XML for Card complex elements for a payment using a token,
where HCC is being used to collect the CV2 and expiry date


3C12DE55292A13227E14D92C6E8D8F4843D21654


© 2013 DataCash. All rights reserved.
Page 511 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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


*****
99000001




4444333322221111

tokenize


SO20138588-067824




Example XML Request to tokenize a card, providing a new shared secret
with the transaction


*****
99000001




4444333322221111
0123456789abcdeFGHIJ

tokenize


SO20138588-067824




© 2013 DataCash. All rights reserved.
Page 512 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

Example XML Request to tokenize a swiped card, using the default
shared secret configured on the account


*****
99000001





NDQ0NDMzMzMyMjIyMTExMT0yODA5MjAxMDAMDAwMU...YfMA==

tokenize


SO20138588-067826




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.

© 2013 DataCash. All rights reserved.
Page 513 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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


...
...




4444333322221111
01/49

auth
1234567890ABCDEFGHIJ


10000023
95.99




Example XML Request for Direct Credit cardaccountpayment, providing
a new shared secret with the transaction


...
...



10397897589
59.00


cardaccountpayment
545460#######1510
1234567890ABCDEFGHIJ




© 2013 DataCash. All rights reserved.
Page 514 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

Example XML Request for Bank Card payment via HCC, providing a new
shared secret with the transaction


...
...



4900203023045857

auth
1234567890ABCDEFGHIJ


10000023
95.99




2.9.2.4

Using Tokens for Payments

Example XML Request for Bank Card payment using a token


...
...




3C12DE55292A13227E14D92C6E8D8F4843D21654
01/49

auth


10000023
95.99




© 2013 DataCash. All rights reserved.
Page 515 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

Example XML Request for Bank Card payment with 3-D Secure using a
token


...
...




3C12DE55292A13227E14D92C6E8D8F4843D21654
01/49

auth


10000023
95.99

yes
...





Example XML Request for Direct Credit cardaccountpayment using a
token


...
...



cardaccountpayment
3C12DE55292A13227E14D92C6E8D8F4843D21654



10000023
95.99




© 2013 DataCash. All rights reserved.
Page 516 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

Example XML Request for Fuel Card payment using a token


...
...



145.74
74927489270
keyed


fuel_validate





22


59307422C194A22332160C850F415A0164707908

12/15





© 2013 DataCash. All rights reserved.
Page 517 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

Example XML Request for PPT using a token


...
...



145.74
74927489270
keyed






top_up
 781C5A1B53BBC9DEF17AF7334ADE0C9E31841EAC

1234




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
Response
Response.CardTxn
Response.FuelCardTxn
Response.PPTCardTxn
Position:
Response.QueryTxn.CardTxn
Response.RbsGiftCardTxn
Response.TokenizeTxn

The token element
Element
Name

token

Position

Response
Response.CardTxn

Return with

cardaccountpayment
auth, pre, refund and erp

© 2013 DataCash. All rights reserved.
Page 518 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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

...
00691FD152E4CE5582804FD94BBCD202E3966026


...
FE554B87039DAFCB9D03F6AFBB502028B33AA7A1


...
781C5A1B53BBC9DEF17AF7334ADE0C9E31841EAC


2.9.4 Example XML Responses
2.9.4.1

Tokenize and Retokenize

Example XML Response for tokenize or retokenize


Mastercard
United Kingdom
National Westminster Bank Plc
00691FD152E4CE5582804FD94BBCD202E3966026

4900203022056130
TT12010210185712341234
TEST
ACCEPTED
1



© 2013 DataCash. All rights reserved.
Page 519 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

2.9.4.2

Tokenization During Payment

Example XML Responses to a successful Bank Card payment or refund


347721
Mastercard
Poland
FE554B87039DAFCB9D03F6AFBB502028B33AA7A1

4400203020266707
...
TEST
ACCEPTED
1





NO DATA MATCHES

795681
VISA
3C12DE55292A13227E14D92C6E8D8F4843D21654

4800203023045872
...
TEST
ACCEPTED
1



© 2013 DataCash. All rights reserved.
Page 520 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

Example XML Response to a DECLINED Bank Card payment or refund


DECLINED
Maestro
United Kingdom
D4BD81D7C3E0A9563BBAE295BE0658885A6D2B5B

4400203020266707
...
TEST
DECLINED
7



Example XML Response to a Bank Card Payment with 3-D Secure



https://testserver.datacash.com/acs
eJxdUk1PwyAYvu9XEC9eTKFd.../

VISA
3C12DE55292A13227E14D92C6E8D8F4843D21654

4700203022949886
...
TEST
3DS Payer Verification Required
150



© 2013 DataCash. All rights reserved.
Page 521 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

Example XML Response to a Direct Credit cardaccountpayment transaction

4600203020658851
10397897589
TEST
Accepted
1

21351D9FB59E54D4B404E5819D7B8F4151BD2D78


Example XML Response to a RBS Giftcard balance_enquiry transaction


0.00
GBP
781C5A1B53BBC9DEF17AF7334ADE0C9E31841EAC

4100203023047327
12345601
TEST
ACCEPTED
1



Example XML Response to a PPT transaction


CARD HAS NOT BEEN ACTIVATED
no
3746E646A09F2AB421933C7B719BD446D0B25F55

EUR
4800203023047201
12345601
TEST
DECLINED
7



© 2013 DataCash. All rights reserved.
Page 522 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

Example XML Response to a Fuels Card transaction


075216
CHJones Fuel Card
gbr
Key Fuels Bunker+
59307422C194A22332160C850F415A0164707908

AUTH CODE:075216
00
4800203023047017
74927489273
TEST
ACCEPTED
MTIzNA==
1



© 2013 DataCash. All rights reserved.
Page 523 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

2.9.4.3

Tokenization during Query

Example XML Responses to query transactions



Unknown
01/13
Unknown
444433******1111
VISA
3C12DE55292A13227E14D92C6E8D8F4843D21654

RBS
55.00
602509
4200203020699556
ecomm

...
ACCEPTED
Not sent
1
2011-11-16 13:41:18

TEST
ACCEPTED
1





...
Unknown
gbr
01/49
Allocated to Switch
675900****0006
Maestro
D4BD81D7C3E0A9563BBAE295BE0658885A6D2B5B

RBS
10.00
DECLINED
4000203020277500
ecomm

...
DECLINED
Not sent
7
2012-02-01 16:55:19

TEST
© 2013 DataCash. All rights reserved.
Page 524 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

ACCEPTED
1


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

...
3900100821792328

...
0
Approved or completed successfully

...
55555
000001
115010000001


© 2013 DataCash. All rights reserved.
Page 525 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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

...

3900100821792328
...

...
55555
000001
115010000001


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

© 2013 DataCash. All rights reserved.
Page 526 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

Example XML:


...



123


...

...


...



123
123


...

...


...



123





...

...


© 2013 DataCash. All rights reserved.
Page 527 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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:


...



1 High Street
Town
County
United Kingdom
AA1 1AA


...

...


...



1 High Street
Town
County
United Kingdom
AA1 1AA
1


...

...


© 2013 DataCash. All rights reserved.
Page 528 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL


...



1 High Street
Town
County
United Kingdom
AA1 1AA







...

...


Back to Contents

© 2013 DataCash. All rights reserved.
Page 529 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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
Request.Transaction
Position(s)

Attributes of LocalDDTxn
Attribute
Name

type

Attribute of
Element

LocalDDTxn

Values / Limitations

Currently this should only be ‘elv’.

B

A

C

L

R

R

R

X

X

X

© 2013 DataCash. All rights reserved.
Page 530 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

Elements of LocalDDTxn
Element Name

Values/
Limitations

Description

B

A

C

L

R

billing_name

The name of the
account holder

Alphanumeric

R

R

X

X

X

method

Determines the
processing model to be
used

localdd_buy - for one
stage processing
localdd_authorise for two stage
processing

R

R

X

X

X

profile

The respective profile
controls which payment
and transaction
Numeric
methods can be
selected.

R

R

X

X

X

customer_ip

The customer’s IP
address.

R

R

X

X

X

Valid IP address

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
A valid IBAN
borders.

Merchant configurable data field typically used to
A valid
paymentreference identify a customer uniquely within the system,
Payment
regardless of the amount of accounts that the
Reference
customer has.

When the method in use is localdd_buy one of the following elements is required.
Elements of LocalDDTxn
Attribute
Name
delaydays

Description
The number of days on which the direct debit
must be actioned.

Values /
Limitations
Numeric

© 2013 DataCash. All rights reserved.
Page 531 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

debitdate

The date on which the direct debit must be
auctioned.

yyyy-mm-dd

Example XML for LocalDDTxn complex elements:
localdd_buy

192.168.1.1
1
localdd_buy
2
123456
87654321
A Customer

localdd_authorise

192.168.1.1
1
localdd_authorise
123456
87654321
A Customer


2.11.3 TxnDetails
Element Name: TxnDetails
Request.Transaction
Position:

Elements of TxnDetails
Element Name

Description

A unique reference
merchantreference number for each
transaction
amount

Values/
Limitations

Min 6, max 30
alphanumeric
characters. Must be
unique.

The value of the
transaction

B

A

C

L

R

R

R

X

X

X

R

R

O

O

O

Attributes for Elements of TxnDetails

© 2013 DataCash. All rights reserved.
Page 532 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

Attribute
of
Element

Attribute
Name

currency

amount

Values / Limitations

Currency is passed in the 3 character ISO
4217 Alphabetic format e.g. GBP, USD,
EUR.

B

A

C

L

R

R

R

X

X

X

Example XML for TxnDetails complex elements:
Transaction

myreference123459988
146.99

Historic Transaction

146.99


2.11.4 HistoricTxn
This element is the direct equivalent of the Card element (for transactions using card
details).
Element Name: HistoricTxn
Request.Transaction
Position:
Elements of HistoricTxn
Element
Name

Description

reference DataCash unique reference of
the original transaction
method

The transaction type

Values / Limitations

C

L

R

must be a valid
transaction

R

R

R

localdd_capture
localdd_cancel
localdd_refund

R

R

R

Example XML Request for HistoricTxn complex elements

4100200039275407
localdd_capture


© 2013 DataCash. All rights reserved.
Page 533 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

Successful localdd_authorise


150968437
100
Transaction successfull
localdd_authorise

3300900010000208
1c464467c61b2321
LIVE
The APG accepted the transaction
1448


Successful localdd_capture


DD1354319267000
150968507
100
Transaction successfull
localdd_capture

3300900010000208
1c464467c61b2321
LIVE
CAPTURED OK
1


Unsuccessful localdd_buy


localdd_buy

3900900010000210
Field 'delaydays' or 'debitdate' are required for
localdd_buy txns
94ed40155dd418f6
LIVE
Field not supported in APG transaction
1442


Unsuccessful localdd_capture

© 2013 DataCash. All rights reserved.
Page 534 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL



211
Modification.DPGReferenceId refers to
transaction that cannot be captured
localdd_capture

3500900010000207
LIVE
The APG rejected the transaction
1447



Back to Contents

© 2013 DataCash. All rights reserved.
Page 535 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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
Request.Transaction
Position:
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 EMail 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

© 2013 DataCash. All rights reserved.
Page 536 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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

Alphanumeric

O

Alphanumeric

O

billing_state_pro The billing state /
vince
province
billing_country

The billing country.

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
Request.Transaction
Position:
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
Alphanumeric
event of a successful
payment)

R

© 2013 DataCash. All rights reserved.
Page 537 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

failure_url

The failure URL
(customer will be
redirected in the
event of a failed
payment / error)

Alphanumeric

R

Example IdealTxn Payment Request:


#######
14000001



119.76
8301000000000259


payment
en
john@mail.com
127.0.0.1
MR
JOHN
KENT
FR
Address Line 1
CA
12345
DE
2
http://success
http://failure




© 2013 DataCash. All rights reserved.
Page 538 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

Example IdealTxn Payment Response:



value1
value2

123456789
REDIRECT
application/x-www-form-urlencoded
Please wait
POST
http://redirecthost

4200903000000481
8301000000000259
TEST
The APG accepted the transaction
1448



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
Request.Transaction
Position:
Elements of IdealTxn
Element Name

Description

Values/Limitations

For txn refund transactions this must
be "txn_refund".

method

The type of request.

reference

The historic
reference of a
Numeric
previously completed
IdealTxn payment.

R

note

A description of the
transaction.

O

Alphanumeric

R

© 2013 DataCash. All rights reserved.
Page 539 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

Example IdealTxn Txn Refund Request:


******
88100002



50.00


txn_refund
4700900010000485
Refund note




Example IdealTxn Txn Refund Response:


221236068
84695
REFUNDED

4500900010000486
4700900010000485
LIVE
ACCEPTED
1


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
Request.Transaction
Position:
Elements of IdealTxn
Element Name

method

Description

The type of request.

Values/Limitations

For bank list transactions this must
be "idealbanklistitem"

R

© 2013 DataCash. All rights reserved.
Page 540 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

Example IdealTxn Bank List Request:


******
88100002



idealbanklistitem




Example IdealTxn Bank List Response:




1
iDeal Bank A


2
iDeal Bank B

...


4000900010000498
LIVE
ACCEPTED
1



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
Request.Transaction
Position:

© 2013 DataCash. All rights reserved.
Page 541 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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
Alphanumeric
event of a successful
payment)

R

failure_url

The failure URL
(customer will be
redirected in the
event of a failed
payment / error)

R

Alphanumeric

Example Sofort Payment Request:


#######
14000001



119.76
8303000000000258


payment
en
john@mail.com
127.0.0.1
MR
JOHN
KENT
FR
Address Line 1
CA
12345
DE
1
http://success
http://failure




© 2013 DataCash. All rights reserved.
Page 542 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

Example Sofort Payment Response:



12345
56789
119.76
GBP
SU1234567890123
12345
123456789
X4M75U
127.0.0.1
https://epi.expercash.net/3rdPartyNotifica
tion/su_success.php?taid=123456789/
https://epi.expercash.net/3rdPartyNotifica
tion/su_failure.php/
0123456789ABCDEF0123456789ABCDEF01234567

123456789
REDIRECT
application/x-www-form-urlencoded
GET
http://testdb:8180/dc-apgsimulator/payment/

4600903000000479
8303000000000258
TEST
The APG accepted the transaction
1448



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
Request.Transaction
Position:

© 2013 DataCash. All rights reserved.
Page 543 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

Elements of IdealTxn
Element Name

Description

Values/Limitations

For txn refund transactions this must
be "txn_refund".

method

The type of request.

reference

The historic
reference of a
Numeric
previously completed
SofortTxn payment.

R

note

A description of the
transaction.

O

Alphanumeric

R

Example SofortTxn Txn Refund Request:


******
88100002



30.00


txn_refund
4100900010000539
Refund note




Example SofortTxn Txn Refund Response:


221260687
84718
REFUNDED

4900900010000540
4100900010000539
LIVE
ACCEPTED
1



© 2013 DataCash. All rights reserved.
Page 544 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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
Request.Transaction
Position:
Elements of WebMoneyTxn
Element Name

Description

Values/Limitations

success_url

The success URL
(customer will be
Alphanumeric
redirected in the
event of a successful
payment)

R

failure_url

The failure URL
(customer will be
redirected in the
event of a failed
payment / error)

R

Alphanumeric

© 2013 DataCash. All rights reserved.
Page 545 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

Example WebMoneyTxn Request:


#######
14000001



119.76
8501000000000261


payment
en
john@mail.com
127.0.0.1
MR
JOHN
KENT
FR
Address Line 1
CA
12345
DE
http://success
http://failure




© 2013 DataCash. All rights reserved.
Page 546 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

Example WebMoneyTxn Response:



119.76
pursename
payment
number
sim
mode

123456789
REDIRECT
application/x-www-form-urlencoded
Please wait while you are redirected to
WebMoney
GET
http://webmoneyurl

4300903000000485
8501000000000261
TEST
The APG accepted the transaction
1448



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
Request.Transaction
Position:
Elements of MisterCashTxn
Element Name

success_url

Description

The success URL
(customer will be
Alphanumeric
redirected in the
event of a successful
payment)

Values/Limitations

R

© 2013 DataCash. All rights reserved.
Page 547 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

failure_url

The failure URL
(customer will be
redirected in the
event of a failed
payment / error)

Alphanumeric

R

Example MisterCashTxn Request:


#######
14000001



119.76
8302000000000260


payment
en
john@mail.com
127.0.0.1
MR
JOHN
KENT
FR
Address Line 1
CA
12345
DE
http://success
http://failure




© 2013 DataCash. All rights reserved.
Page 548 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

Example MisterCashTxn Response:



123456789
X4M75U
UK
GBP
GBP
john@mail.com
MISTERCASH
en

123456789
REDIRECT
application/x-www-form-urlencoded
Please wait while you are redirected to the Envoy
OneClick site
GET
http://envoy

4800903000000483
8302000000000260
TEST
The APG accepted the transaction
1448



© 2013 DataCash. All rights reserved.
Page 549 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

2.12.6 La Caixa Transactions
Only the common elements described above are applicable to La Caixa transactions.
Element Names: LaCaixaTxn
Request.Transaction
Position:

Example LaCaixaTxn Request:


#######
14000001



119.76
8401000000000256


payment
es
john@mail.com
127.0.0.1
MR
JOHN
KENT
FR
Address Line 1
CA
12345
DE




© 2013 DataCash. All rights reserved.
Page 550 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

Example LaCaixaTxn Response:


Merchant account name
1234567890
Bank of Bankeria
BranchName
123 Bank St, Banktown, Republic of
Bankeria
RB01 CBCO 1234 1234 1234 56
123456789
PENDING
CBCORB00XXX
Display message

4400903000000475
8401000000000256
TEST
The APG accepted the transaction
1448



© 2013 DataCash. All rights reserved.
Page 551 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

2.12.7 Nordea Transactions
Only the common elements described above are applicable to Nordea transactions.
Element Names: NordeaTxn
Request.Transaction
Position:

Example NordeaTxn Request:


#######
14000001



119.76
8402000000000255


payment
en
john@mail.com
127.0.0.1
MR
JOHN
KENT
FR
Address Line 1
CA
12345
DE




© 2013 DataCash. All rights reserved.
Page 552 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

xample NordeaTxn Response:


Merchant account name
1234567890
Bank of Bankeria
BranchName
123 Bank St, Banktown, Republic of
Bankeria
RB01 CBCO 1234 1234 1234 56
123456789
PENDING
CBCORB00XXX
Display message

4900903000000473
8402000000000255
TEST
The APG accepted the transaction
1448



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
Request.Transaction
Position:

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

© 2013 DataCash. All rights reserved.
Page 553 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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
Request.Transaction
Position:

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

© 2013 DataCash. All rights reserved.
Page 554 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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
Request.Transaction
Position:
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

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

telephone1

© 2013 DataCash. All rights reserved.
Page 555 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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.

telephone_area_code

Short;
Consumer's Telephone
US: 3 digit number (e.g. 619 for
Area Code. This is
California).
the 3-digit area code for a CA: 3 digit number (e.g. 867 for
particular region.
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
A valid Payment Reference
uniquely within the
system, regardless of the
amount of accounts that
the customer has.

value must not be prefixed with
a plus (+) e.g. 1 for United States.

O

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.

© 2013 DataCash. All rights reserved.
Page 556 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

2.12.9.2 Modification Transactions
The following request elements are specific to Giropay modification (cance/refund)
transactions.

Element Names: GiropayTxn
Request.Transaction
Position:
Elements of MisterCashTxn
Element Name

Description

Values/Limitations

C

R

method

The type of request.

One of ‘cancel’ or
‘txn_refund’

R

R

reference

DataCash unique
reference of
the original transaction

Must be a valid
transaction

R

R

note

This is a description for
the transaction

Alphanumeric

O

O

© 2013 DataCash. All rights reserved.
Page 557 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

Example GiropayTxn Purchase Request:


#######
14000001



7654321
20.02


payment / payout
en
foo
Mozilla/5.0 (Windows NT 6.1) AppleWebKit/536.5
(KHTML, like Gecko) Chrome/19.0.1084.52 Safari/536.5
john@mail.com
127.0.0.1
M
MR
JOHN
KENT
1234567
44
131
UK
http://success
http://failure
John Kent
Address Line 1
Address Line 2
CA
12345
DE
province
12345678
1234567890



© 2013 DataCash. All rights reserved.
Page 558 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

Example GiropayTxn Purchase Response:



merchantID=123456789&customerRef=X4M75U&count
ry=UK¤cy=GBP&recieveCurrency=GBP&email=john@mail.com&service=GIRO
PAY&language=en

123456789
REDIRECT
application/x-www-form-urlencoded
Please wait while you are redirected to the
Giropay site
GET
http://envoy

4800903000000483
8302000000000260
...
The APG accepted the transaction
1448



Example GiropayTxn Modification Request:


fred
14000001



cancel
4500200040925092
foo




© 2013 DataCash. All rights reserved.
Page 559 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

Example GiropayTxn Modification Response:


00000000000004594228
1002
CANCELLED

...
CANCELLED OK
1



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
Response
Position:
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.

© 2013 DataCash. All rights reserved.
Page 560 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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
Response
Position:
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
Response
Position:
Elements of [RedirectPaymentMethod]Txn
Element Name

redirect_url

Description
rd

This is a URL on the 3 party payment processors website to
which the customer should be redirected.

© 2013 DataCash. All rights reserved.
Page 561 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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:



X4M75U
UK
GBP
GBP
john@mail.com
MISTERCASH
en

...
application/x-www-form-urlencoded
GET
http://envoy

...


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.

© 2013 DataCash. All rights reserved.
Page 562 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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:


#######
14000001



119.76
8303000000000265


setup_full
99999
http://returnurl


payment
en
john@mail.com
127.0.0.1
MR
JOHN
KENT
FR
Address Line 1
CA
12345
DE
1




© 2013 DataCash. All rights reserved.
Page 563 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

Example of HPS Setup Session Response for Sofort Txn:


http://localhost:8180/hps/
ce0be36b-15c1-46e5-9f67-33ce39ad5dc7

4900903000000492
8303000000000265
TEST
ACCEPTED
1



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:

© 2013 DataCash. All rights reserved.
Page 564 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

Example of HPS Setup Session Request with Multiple Txn Blocks:


#######
14000001



119.76
8303000000000265


setup_full
99999
http://returnurl


payment
en
john@mail.com
127.0.0.1
MR
JOHN
KENT
FR
Address Line 1
CA
12345
DE
1


payment
en
john@mail.com
127.0.0.1
MR
JOHN
KENT
FR
Address Line 1
CA
12345
DE




© 2013 DataCash. All rights reserved.
Page 565 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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

© 2013 DataCash. All rights reserved.
Page 566 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL




binlookup

4444333322221111
OR
985B8AB922D42A8649904D7F3B5A437F545C32D0



999999999



****
11111111



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.

© 2013 DataCash. All rights reserved.
Page 567 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL



VISA
gbr
Unknown
538C8AB922D42A8649904F7F3B5A437F545C32D0

1111111111111111
999999999
TEST
ACCEPTED
1



© 2013 DataCash. All rights reserved.
Page 568 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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
Request.Transaction
Position:
Elements of ChinaUnionPayTxn
Element Name

method

Description

The method of the
transaction.

reference

When performing a
txn_refund or
cancel, this element
should be used to
indicate the
transaction that is
being refunded or
cancelled respectively.

mer_abbr

The name of the
merchant submitting
the transaction.

Values / Limitations

auth
cancel
txn_refund
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.
Alphanumeric, up to 32
characters.

Required
A

T

C

R

R

R

-

R

R

R

-

-

© 2013 DataCash. All rights reserved.
Page 569 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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)

© 2013 DataCash. All rights reserved.
Page 570 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

An example authorisation transaction is illustrated below:
Example China Union Pay HPS Setup Request


xxxxxxxx
xxxxxxxx



auth


1300f789b8d1be2381
ecomm
1000.00


1
http://www.merchant.com/paymentmade
setup_full


abc
100
20120203185332
Geoff Jefferson
10
127.0.0.1
http://www.merchant.com/item6103
Face paint
0
1.0.0
1234
merchref_12345
0
auth
12




© 2013 DataCash. All rights reserved.
Page 571 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

An example response to a setup transaction is shown below:
Example China Union Pay HPS Setup Response



https://dpg.example.com:8180/hps/
6f69e357-24b1-492d-ac21-898c83f25e5d

4000900012345671
1300f789b8d1be2381
TEST
ACCEPTED
1



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)

© 2013 DataCash. All rights reserved.
Page 572 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

An example authorisation commencement transaction is shown below
Example China Union Pay Authorisation Commencement Request


xxxxxxxx
xxxxxxxx



1300f789b8d1be2381
ecomm
1000.00


abc
100
20120203185332
Geoff Jefferson
10
127.0.0.1
http://www.merchant.com/item6103
Face paint
0
1.0.0
1234
merchref_12345
0
auth
12




© 2013 DataCash. All rights reserved.
Page 573 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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


xxxxxxxx
xxxxxxxx



10.59


txn_refund
4100900012345675



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.

© 2013 DataCash. All rights reserved.
Page 574 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

An example cancel transaction is shown below:

Example Cancel Request


xxxxxxxx
xxxxxxxx



cancel 
4100900012345675



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


4000900012345671
1
ACCEPTED

000010000200003000041

TEST


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.

© 2013 DataCash. All rights reserved.
Page 575 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

For example:

Example Response for a Invalid Transaction


4000900012345672
1489
China Union Pay: Invalid Order Number
Specified transaction has not completed!
TEST



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


*****
99000001



query
4000900012345671



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.

© 2013 DataCash. All rights reserved.
Page 576 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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.

info

Message indicating the
A message detailing the response
status of the transaction
received from CUP pertaining to
according to China Union
the original transaction.
Pay.

transaction_updated

Whether the transaction has just
been updated by performing this
query.

2.14.7.2

successful
error

true
false

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.

© 2013 DataCash. All rights reserved.
Page 577 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

Example Response for a Query Transaction







China Union Pay have indicated that the transaction was
successful
successful
true

28180826
{orderAmount=10000&orderCurrency=826}
127.0.0.1
dtest1
52d8a5c28afc8e
auth
10000
826
3300900010000128
2012-02-06 18:16:18
201202061816187320872
00
20120206181605
10000
826
0206
732087
0206181618
300000
1
1.0.0

3300900010000128
1
ACCEPTED


3300900010000128

3500900010000127
You have queried a Full-HPS China Union Pay transaction, where the
payment was successfully collected
52d8a5c28afc8e
LIVE
ACCEPTED
1



© 2013 DataCash. All rights reserved.
Page 578 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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





China Union Pay have indicated that the transaction was
successful
successful
true

28180826
{orderAmount=10000&orderCurrency=826}
127.0.0.1
dtest1
7bfc15ad69fc5181cc
cancel
10000
826
3500900010000113
2012-02-04 00:48:02
201202040042077318332
201202040048027318352
00
20120204004715
10000
826
0203
731835
0204004802
300000
31
1.0.0


3500900010000113
LIVE
ACCEPTED
1



© 2013 DataCash. All rights reserved.
Page 579 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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
o

Schema Elements for HCC Setup Request
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.

© 2013 DataCash. All rights reserved.
Page 580 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

2.15.3.1.1

TxnDetails

Element Name: TxnDetails
Request.Transaction
Position:
Elements of TxnDetails
Element Name

Description

A unique reference number to
merchantreference distinguish each transaction

amount

The value of the transaction

capturemethod

Indicates how the transaction was
accepted at the POS

Values /
Limitations

Require
d?

Min 6, max 30
alphanumeric
characters. Must
be unique

R
R
R

ecomm

Attributes for Elements of TxnDetails
Attribute
Name

Attribute
of Element

currency

amount

2.15.3.1.2

Values / Limitations

Required?

Currency is passed in the 3
character ISO 4217 Alphabetic
format (Default is GBP)

O

HpsTxn

This element must be present for all setup transactions. It should not be presented for
other transaction types.
Element Name: HpsTxn
Request.Transaction
Position:
Elements of HpsTxn
Element
Name

method

Description

The action that is being requested

An ID number that signifies the
page_set_id “page set” that should be used
when presenting the data capture
screen to the customer.

Values / Limitations

Required

Must have the value
“setup_paypass_online”

R

An integer value of a page
set that has already been
configured.

R

© 2013 DataCash. All rights reserved.
Page 581 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

return_url

A URL from the customer’s
website. If this value is supplied,
then when the data capture
process has been completed, the Max size 2083.
customer will be redirected to this
URL instead of the default URL
configured within HCC.

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 preregistered 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
Request.Transaction
Position:
Elements of TxnDetails
Element Name

Description

Determines whether a
customer will be prevented
from selecting a shipping
address within the PayPass
suppress_shipping
wallet. If this parameter is
_address
not present the customer
will be able to select a
shipping address within the
PayPass wallet.

Values / Limitations

Required

“TRUE” or ”FALSE”, but
case insensitive

O

© 2013 DataCash. All rights reserved.
Page 582 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

2.15.3.1.4

Example HCC Setup Transaction

An example transaction is illustrated below:
Example PayPass HCC Setup Request


xxxxxxxx
xxxxxxxx



12345678
1000.00
ecomm


setup_paypass_online
1
https://www.merchantexample.com/customer_return


FALSE




© 2013 DataCash. All rights reserved.
Page 583 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

An example response to this setup transaction is shown below:
Example PayPass HCC Setup Response


https://dpg.example.com:8180/hps/
6f69e357-24b1-492d-ac21-898c83f25e5d

4800903000000001
4421000008
LIVE
ACCEPTED
1



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
o

Schema Elements for Full HPS Setup Request
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.

© 2013 DataCash. All rights reserved.
Page 584 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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
Request.Transaction
Position:
Elements of HpsTxn
Element Name

Description

The action that is being
requested

method

Values / Limitations

Required

Must have the value
“setup_paypass_online_
session”

R

Determines whether a
customer will be prevented
from selecting a shipping
address within the PayPass
suppress_shipping_
“TRUE” or ”FALSE”, but
wallet. If this parameter is
address
case insensitive
not present the customer will
be able to select a shipping
address within the PayPass
wallet.
2.15.4.1.2

O

HpsTxn

This element must be present for all setup transactions. It should not be presented for
other transaction types.
Element Name: HpsTxn
Request.Transaction
Position:
Elements of HpsTxn
Element Name

method

Description

The action that is being requested

An ID number that signifies the “page set”
page_set_id that should be used when presenting the
data capture screen to the customer.

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.

Values / Limitations

Required

Must have the
value “setup_full”

R

An integer value of
a page set that has
already been
configured.

R

Max size 2083.

R

© 2013 DataCash. All rights reserved.
Page 585 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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

© 2013 DataCash. All rights reserved.
Page 586 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

2.15.4.1.3

Example Full HPS Setup Transaction

An example transaction is illustrated below:
Example PayPass Full HPS Setup Request


xxxxxxxx
xxxxxxxx



12345678
1000.00
ecomm


setup_paypass_online_session
FALSE


setup_full
1
https://www.merchantexample.com/customer_return




An example response to this setup transaction is shown below:
Example PayPass Full HPS Setup Response


https://dpg.example.com:8180/hps/
6f69e357-24b1-492d-ac21-898c83f25e5d

4800903000000001
4421000008
LIVE
ACCEPTED
1



© 2013 DataCash. All rights reserved.
Page 587 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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
o

Schema Elements for Setup PayPass Online Session Request
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
Request.Transaction
Position:
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 “TRUE” or ”FALSE”, but
parameter is not present
case insensitive
the customer will be able
to select a shipping
address within the
PayPass wallet.

O

© 2013 DataCash. All rights reserved.
Page 588 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

2.15.5.1.2

Example Setup PayPass Online Session Transaction

An example transaction is illustrated below:
Example PayPass Setup PayPass Online Session Request


xxxxxxxx
xxxxxxxx



12345678
1000.00
ecomm


setup_paypass_online_session
http://www.merch.com/paypass
FALSE




An example response to this setup transaction is shown below:
Example PayPass Setup PayPass Online Session Response


https://sandbox.paypass.com/online/Checkout/Authorize?oaut
h_token=1234567890abcdef1234567890abcdef&acceptable_cards=visa,maestro,jcb,m
aster&checkout_identifier=123425334234235234
1234567890abcdef1234567890abcdef

4800903000000001
4421000008
LIVE
ACCEPTED
1



© 2013 DataCash. All rights reserved.
Page 589 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

2.15.5.2
o

Schema Elements for Get Customer Details Request
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
Request.Transaction
Position:
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

Must be a valid URL.

R

The checkout resource URL
paypass_resource returned by PayPass when the
_url
customer is redirected back to
the merchant site from PayPass.

Verifier code returned by
Must be a valid verifier
paypass_verifier PayPass when the customer
code.
completes choosing their details.

R

© 2013 DataCash. All rights reserved.
Page 590 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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


xxxxxxxx
xxxxxxxx



get_customer_details
4800903000000001
http://www.merch.com/details
1234567890abcdef




© 2013 DataCash. All rights reserved.
Page 591 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

An example response to this transaction is shown below:
Example PayPass Get Customer Details Response



Purchase
United States
NY
2000 Purchase St

10577
Joe Test
1-2345678901


02
2013
1111

Buffalo
United States
NY
123 Bison Ln

10600



Joe Test
joe.test@email.com
Joe
Test

1-2345678901

4400

4600903000000002
123401
TEST
ACCEPTED
1



© 2013 DataCash. All rights reserved.
Page 592 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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


xxxxxxxx
xxxxxxxx


query
4800903000000001



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.

© 2013 DataCash. All rights reserved.
Page 593 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

Example PayPass Query Response




http://paypass.mastercard.com/login
aXHfwEYfwehHF23re23
4900900023456780
123401
ACCEPTED
1



02
2013
1234


Test User
test@test.com
Test
User

1-1111111111


Arlington
United States
VA
11 Any Street

22222
Test User
1- 1111111111

3
4900900023456781
ACCEPTED
1



ACCEPTED
1


© 2013 DataCash. All rights reserved.
Page 594 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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
Request.Transaction.CardTxn
Position:

Elements of CardTxn
Element Name

Description

Values / Limitations

card_details

Specifies the
DataCash reference of Required. Must be a 16-digit DataCash
a successful HCC
reference.
session setup.

method

The transaction type

auth
pre

Attributes for Elements of CardTxn
Attribute
Name

type

Attribute of
Element

card_details

Values / Limitations

Specifies the nature of the supplied DataCash
reference. For a PayPass transaction, it must have the
value “from_paypass_online”.

© 2013 DataCash. All rights reserved.
Page 595 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

2.15.7.1.1.1 Example Request
The following example request demonstrates a basic PayPass authorisation request:
Example PayPass Authorisation Request


xxxxxxxx
xxxxxxxx



mref123501
1000.00
ecomm


auth
4000900012345671




© 2013 DataCash. All rights reserved.
Page 596 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

2.15.7.1.1.2 Example Response
Example PayPass Authorisation Response


100000
VISA
United Kingdom

4200903000000001
mref123501
TEST
ACCEPTED
1



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.

© 2013 DataCash. All rights reserved.
Page 597 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

2.16.2.1
o

Schema Elements for Full HPS Setup Request
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
Request.Transaction
Position:
Elements of TxnDetails
Element Name

Description

A unique reference number to
merchantreference distinguish each transaction

Values /
Limitations

Required

Min 6, max 30
alphanumeric
characters. Must
be unique.

R

The value of the transaction

amount

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

© 2013 DataCash. All rights reserved.
Page 598 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

2.16.2.1.2

BoletoBancarioTxn

This element must be present for all the Boleto Bancario transactions.
Element Name: BoletoBancarioTxn
Request.Transaction
Position:

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 The customer’s billing state
ince
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

3 digitis numerical. Valid
values :
11 = Itau
A unique ID set by merchant
12 = Bradesco OR a test
from Account Maintenance. It
transaction
is overridden by the value
13 = Banco do Brasil
submitted in the request.
14 = HSBC
15 = Santander
16 = Caixa

O

customer_ip

The customer’s IP address

Needs to be a valid IP
address

O

© 2013 DataCash. All rights reserved.
Page 599 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

interest_per_day

overdue_fine

2.16.2.1.3

Additional amount of interest
Needs to be in
that must be paid for every
percentage format
day after expiration date.

O

Overall fine that must be
paid for transactions due
after the expiration day.

O

Needs to be in
percentage format

HpsTxn

This element must be present for all setup transactions. It should not be presented for
other transaction types.
Element Name: HpsTxn
Request.Transaction
Position:
Elements of HpsTxn
Element Name

method

Description

The action that is being requested

An ID number that signifies the “page
page_set_id set” that should be used when presenting
the data capture screen to the customer.

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.

Values / Limitations

Required

Must have the value
“setup_full”

R

An integer value of a
page set that has
already been
configured.

R

Max size 2083.

R

© 2013 DataCash. All rights reserved.
Page 600 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

2.16.2.1.4

Example Full HPS Setup Transaction

An example transaction is illustrated below:
Example Boleto Bancario Full HPS Setup Request


xxxxxxxx
xxxxxxxx



boletobancario123
123.56


setup_full
50
https://www.merchant-website.com/done


payment
2013-12-01
Faça o que fizer, não dê esse cara todo o dinheiro.

John
Doe




© 2013 DataCash. All rights reserved.
Page 601 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

An example response to this setup transaction is shown below:
Example Boleto Bancario Full HPS Setup Response


https://dpg.example.com:8180/hps/
6f69e357-24b1-492d-ac21-898c83f25e5d

4800903000000001
boletobancario123
LIVE
ACCEPTED
1



© 2013 DataCash. All rights reserved.
Page 602 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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
Request.Transaction
Position:
Elements of TxnDetails
Element Name

Description

Unique reference number to
merchantreference distinguish each transaction

amount

The value of the transaction

capturemethod

Indicates how the transaction was
accepted at the POS

Values /
Limitations

Require
d?

Min 6, max 30
alphanumeric
characters. Must
be unique

R
R
R

ecomm

Attributes for Elements of TxnDetails
Attribute
Name

Attribute
of Element

currency

amount

Values / Limitations

Currency is passed in the 3
character ISO 4217 Alphabetic
format (Only BRL is accepted)

Required?

O

© 2013 DataCash. All rights reserved.
Page 603 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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
Request.Transaction
Position:
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 The customer’s billing state
ince
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

3 digitis numerical. Valid
values :
A unique ID set by merchant 11 = Itau
from the Account
12 = Bradesco OR a test
Maintenance. It is overridden transaction
by the value submitted in the 13 = Banco do Brasil
request.
14 = HSBC
15 = Santander
16 = Caixa

O

customer_ip

The customer’s IP address

Needs to be a valid IP
address

O

© 2013 DataCash. All rights reserved.
Page 604 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

interest_per_day

overdue_fine

2.16.3.1.3

Additional amount needs to
be paid for every day after
the expiration day

Needs to be in
percentage format

O

Overall fine needs to be paid
for transactions paid after
the expiration day.

Needs to be in
percentage format

O

Example Boleto Bancario payment Transaction

An example transaction is illustrated below:
Example Boleto Bancario Payment Request



88000000
fred



Boleto1234
ecomm
123.56


4900900023456600
payment
2013-12-01
Faça o que fizer, não dê esse cara todo o
dinheiro.

© 2013 DataCash. All rights reserved.
Page 605 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

John
Doe
123 Example Street
Apt. 123
Blahtown
PA
24000-123
BR
123456789099
dude@example.com
12
127.0.0.1
0.1
5.00




2.16.3.1.4

Example Boleto Bancario payment Response

An example response to this payment transaction is shown below:



payment
2013-12-01
Faça o que fizer, não dê esse cara todo o
dinheiro.

© 2013 DataCash. All rights reserved.
Page 606 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

John
Doe
123 Example Street
Apt. 123
Blahtown
PA
24000-123
BR
123456789099
dude@example.com
12
127.0.0.1
0.1
5.00
http://example.com/something
eb7b1eaf-eb6a-49fc-bf94-e175485d3bfa
4568123581487
pending

4900900023456781
Boleto1234
ACCEPTED
1



© 2013 DataCash. All rights reserved.
Page 607 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

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


xxxxxxxx
xxxxxxxx


query
4800903000000001



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



payment
2013-12-01
Faça o que fizer, não dê esse cara todo o
dinheiro.

© 2013 DataCash. All rights reserved.
Page 608 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL

John
Doe
123 Example Street
Apt. 123
Blahtown
PA
24000-123
BR
123456789099
dude@example.com
12
127.0.0.1
0.1
5.00
http://example.com/something
eb7b1eaf-eb6a-49fc-bf94-e175485d3bfa
4568123581487
pending


123.56

4800903000000001
boletobancario123
Payment pending
1911

ACCEPTED
1



payment
2013-12-01
Faça o que fizer, não dê esse cara todo o
dinheiro.
John
Doe
123 Example Street
Apt. 123
Blahtown
PA
24000-123
BR
123456789099
dude@example.com
12
127.0.0.1
0.1
5.00
http://example.com/something
eb7b1eaf-eb6a-49fc-bf94-e175485d3bfa
4568123581487
001
73341232091557
2013-12-01
130.00
OVERPAID

© 2013 DataCash. All rights reserved.
Page 610 of 789
This document is intended for the use of DataCash and its clients only. It contains information that is
privileged and that is the intellectual property of DataCash. You may neither copy nor use it, nor disclose it to
anyone else. If you have received this document in error, please notify DataCash immediately.

COMPANY CONFIDENTIAL



123.56

4800903000000001
boletobancario123
ACCEPTED
1

ACCEPTED
1

Navigation menu