0% found this document useful (0 votes)

64 views177 pages

IPG - Integration Guide - API - 2024-1

The Web Service API Integration Guide provides detailed instructions for integrating Fiserv's payment processing capabilities into applications across various platforms. It covers essential components such as transaction types, security measures, and the required artefacts for secure communication with the API. The guide emphasizes compliance with PCI DSS standards for handling cardholder data and offers troubleshooting support for merchants.

Uploaded by

Mohamed Khairoun

We take content rights seriously. If you suspect this is your content, claim it here.

Available Formats

Download as PDF, TXT or read online on Scribd

0% found this document useful (0 votes)

64 views177 pages

IPG - Integration Guide - API - 2024-1

Uploaded by

Mohamed Khairoun

We take content rights seriously. If you suspect this is your content, claim it here.

Available Formats

Download as PDF, TXT or read online on Scribd

You are on page 1/ 177

Web Service API

Integration Guide
Version 2024-1
© 2024 Fiserv, Inc. or its affiliates. All rights reserved. This work is confidential, and its use is strictly
limited. Use is permitted only in accordance with the terms of the agreement under which it was
furnished. Any other use, duplication, or dissemination without the prior written consent of Fiserv,
Inc. or its affiliates is strictly prohibited. The information contained herein is subject to change without
notice. Except as specified by the agreement under which the materials are furnished, Fiserv, Inc. and
its affiliates do not accept any liabilities with respect to the information contained herein and are not
responsible for any direct, indirect, special, consequential or exemplary damages resulting from the
use of this information. No warranties, either express or implied, are granted or extended by this
document.

http://www.fiserv.com

Fiserv is a registered trademark of Fiserv, Inc.

Other brands and their products are trademarks or registered trademarks of their respective holders
and should be noted as such.
Integration Guide Web Service API

Version 2024-1 (IPG)

Contents
1 Introduction 8
2 Artefacts You Need 9
3 How the API works 10
4 Sending transactions to the Gateway 11
5 Building Transactions in XML 12
5.1 Credit/Debit Card transactions 12
5.2 Sale 13
5.3 Pre-Authorisation 14
5.4 Post-Authorisation 14
5.5 Return 15
5.7 Credit 15
5.8 Void 16
5.9 Recurring Sale (Merchant-triggered) 16
5.9.1 Recurring Transaction with 3-D Secure 18
5.10 Merchant Initiated Transactions 19
5.11 Standing Instructions 21
5.12 SEPA Direct Debit - Germany 22
5.12.1 Sale 22
5.12.2 Void 22
5.12.3 Credit 23
5.12.4 Return 23
5.13 SEPA Direct Debit with Fiserv Local Payments 24
5.14 PayPal 26
5.14.1 PayPal Post-Authorisation Payment Transaction 26
5.14.2 Recurring Payment Transaction 27
5.14.3 Return 27
5.14.4 Void 27
5.14.5 Credit 28
5.15 SOFORT Überweisung 28
5.15.1 Return 28
5.15.2 Return 29
5.16 Generic Transaction Type for Voids and Returns 29
6 Additional Web Service actions 31
6.1 Initiate Clearing 31
6.2 Inquiry Order 31
6.3 Inquiry Transaction 34
6.4 Get Last Orders 35
6.4.1 Latest orders of a Store 35
6.4.2 Latest orders of a Store within a given date range 35
6.4.3 All orders of a Store after a given Order ID 36
6.4.4 Response 36
6.5 Get Last Transactions 39
6.5.1 Latest transactions of a Store 40
6.5.2 All transactions of a Store after a given Transaction ID 40
6.5.3 Response 40
6.6 Recurring Payments (Scheduler) 42
6.6.1 Install 42
6.6.2 Modify 43
6.6.3 Cancel 43
6.6.4 Test Recurring Payments in test environment 43
6.6.5 Response 44
6.7 External transaction status 44
6.8 Trigger email notifications 44
6.9 Card Information Inquiry 45
6.10 Basket Information and Product Catalogue 45
6.10.1 Basket information in transaction messages 45
6.10.2 Setting up a Product Catalogue 46
6.10.3 Manage Product Stock 47
6.10.4 Sale transactions using product stock 47
7 Data Vault 48
7.1 Token Type Options 48
7.2 Store or update payment information when performing a transaction 51
7.3 Store payment information from an approved transaction 51
7.4 Initiate payment transactions using stored data 52
7.5 Store payment information without performing a transaction at the same time 52
7.6 Avoid duplicate cardholder data for multiple records 55
7.7 Display stored records 55
7.8 Delete existing records 56
8 Global Choice™ and Dynamic Pricing 56
8.1 Exchange rate requests for Global Choice™ 56
8.2 Exchange rate requests for Dynamic Pricing 57
8.3 Exchange rate responses 58
8.4 Conversion offering 58
8.5 Declined rate request 59
8.6 Failed rate request 59
8.7 Global Choice™ transactions 60
9 Payment URL 62
9.1 Payment URL creation 62
9.2 Payment URL deletion 63
9.3 Payment URL custom text 64
10 3-D Secure 65
10.1 Authentication with Fiserv as your 3DS provider 65
10.1.1 Frictionless Flow 68
10.1.2 Challenge Flow 70
10.1.3 3RI Flow 73
10.1.4 Decoupled Authentication 74
10.1.5 Fallback to 3DSv1 77
10.2 Authentication with external 3DS Service provider 79
10.3 Non-Payment Authentication (NPA) 82
10.4 Split Authentication 83
11 Purchasing cards 85
12 Network Tokenisation 88
12.1 Network Token Generation 88
12.2 Initiate a payment transaction using HostedDataId 90
12.3 Initiate payment transaction using Network Token and Cryptogram 90
12.4 Display Network Token Details 93
12.5 Store payment information without performing a transaction at the same time 94
13 XML-Tag overview 95
13.1 Overview by transaction type 95
13.2 Description of the XML-Tags 103
13.2.1 CreditCardTxType 103
13.2.2 CreditCardData 103
13.2.3 RecurringType 104
13.2.4 UnscheduledCredentialOnFileType 104
13.2.5 Cardholder & Merchant Initiated Indicators 104
13.2.6 Wallet 105
13.2.7 cardFunction 105
13.2.8 CreditCard3DSecure 105
13.2.9 India Mobile / IVR Extension Verification Request 107
13.2.10 India Mobile / IVR Extension Authentication Request 108
13.2.11 3-D Secure 1.0 Authentication / Verification Redirect Response 108
13.2.13 UnionPay Secure Plus 109
13.2.14 UnionPay SecurePlusRequest 109
13.2.15 DE_DirectDebitTxType 109
13.2.16 DE_DirectDebitData 110
13.2.17 PayPalTxType 110
14.2.18 Payment 110
13.2.19 TransactionDetails 111
13.2.20 Purchasing Cards 113
13.2.21 Purchasing Cards / Line Item Data 114
13.2.22 InquiryRateReference 114
13.2.23 Billing 114
13.2.24 Shipping 115
13.2.25 ClientLocale 116
13.2.26 RequestCardRateForDCC 116
13.2.27 RequestMerchantRateForDynamicPricing 116
13.2.28 CardRateForDCC and MerchantRateForDynamicPricing 117
13.2.29 MCC 6012 Visa and Mastercard Mandate 117
13.2.30 Market Segment Addendum 118
13.2.31 SCA Exemptions 118
13.2.32 China Domestic 118
13.2.33 EMI with ICICI Debit Card 119
13.2.34 Boleto 120
13.2.35 StandIn Details 121
13.2.36 Source of funds 121
13.2.37 Network Tokenisation 122
14 Custom Parameters 123
14.1 Additional parameters for Fraud Detect 123
15 Building a SOAP Request Message 124
16 Reading the SOAP Response Message 125
16.1 SOAP Response Message 125
16.2 SOAP Fault Message 126
16.3 SOAP-ENV:Server 127
16.4 SOAP-ENV:Client 127
17 Analysing the Transaction Result 129
17.1 Transaction Approval 129
17.2 Transaction Failure 132
18 Building an HTTPS POST Request 135
18.1 PHP 135
18.2 ASP 137
19 Establishing a TLS connection 137
19.1 PHP 138
19.2 ASP 139
20 Sending the HTTPS POST Request and Receiving the Response 141
20.1 PHP 141
20.2 ASP 142
21 Using a Java Client to connect to the web service 142
21.1 Instance an IPGApiClient 142
21.2 How to construct a transaction and handle the response 143
21.3 How to construct an action 144
21.4 How to connect behind a proxy 144
22 Appendix 145
22.1 XML 145
22.2 XML Schemata 145
22.3 Union Pay SecurePlus 145
22.4 Bancontact QR code transactions 149
22.5 China domestic processing 151
22.6 Visa Account Funding Transactions (AFT) 152
22.7 Mastercard MoneySend 155
22.8 RuPay 157
Redirection Flow 157
Seamless Flow 160
22.8.1 Rupay Network Token Provisioning with external Token Provider 164
22.9 Guest Checkout Tokenization 165
23 Troubleshooting - Merchant Exceptions 167
23.1 Troubleshooting - Processing Exceptions 171
23.2 Troubleshooting - Login error messages when using cURL 175
Getting Support
There are different manuals available for Fiserv’s eCommerce solutions. This Integration Guide will be
the most helpful for integrating the Web Service API for usage with our distribution channels in Europe,
Asia, Australia, Latin America,Africa and United States.

For information about settings, customisation, reports and how to process transactions manually (by
keying in the information) please refer to the User Guide Virtual Terminal.

If you have read the documentation and cannot find the answer to your question, please contact your
local support team.

Information for merchants with existing Web Service API integration using the Java client to connect
to the web service:

• The implementation of the IPGApiClient and some signatures of methods of this class have been
changed due to a change from appache http client 3.x to appache http client 4.x
• Transaction classes and transaction factory have not been changed
• If the previous IPGApiClient works in your environment, you can continue to use it.
1 Introduction

The Web Service API is an Application Programming Interface which allows you to connect your
application with the Fiserv Gateway. In this way, your application is able to submit payment transactions
without any user interference.

Please note that if you store or process cardholder data within your own application, you must ensure
that your system components are compliant with the Data Security Standard of the Payment Card
Industry (PCI DSS). Depending on your transaction volume, an assessment by a Qualified Security
Assessor may be mandatory to declare your compliance status.

From a technical point of view, this API is a Web Service offering one remote operation for performing
transactions. The three core advantages of this design can be summarized as follows:

• Platform independence: Communicating with the Web Service API means that your application
must only be capable of sending and receiving SOAP messages. There are no requirements
tied to a specific platform, since the Web Service technology builds on a set of open standards.
In short, you are free to choose any technology you want (e.g. J2EE, . PHP, ASP, etc.) for
making your application capable of communicating with the Web Service API.
• Easy integration: Communicating with a Web Service is simple – your application has to build a
SOAP request message encoding your transaction, send it via HTTPS to the Web Service and
wait for a SOAP response message which contains your transaction’s status report. Since
SOAP and HTTP are designed to be lightweight protocols, building requests and responses
becomes a straightforward task. Furthermore, you rarely have to do this manually, since there
are plenty of libraries available in almost every technology. In general, building a SOAP request
and handling the response is reduced to a few lines of code.
• Security: All communication between your application and the Web Service API is TLS-
encrypted. This is established by your application holding a client certificate which identifies it
uniquely at the Web Service. In the same way, the Gateway holds a server certificate which
your application may check for making sure that it speaks to our Web Service API. Finally, your
application has to do a basic authentication (user name / password) before being allowed to
communicate with the Web Service. In this way, the users who are authorised to communicate
with the Gateway are identified. These two security mechanisms guarantee that the transaction
data sent to Fiserv both stays private and is identified as transaction data that your application
has committed and belongs to no one else.
While this represents just a short summary of the Web Service API’s features, the focus of this guide
lies on integrating the Fiserv Gateway functionality into your application. A detailed description,
explaining how this is done step by step, is presented in this guide.
2 Artefacts You Need

Supporting a high degree of security requires several artefacts you need for communicating securely
with the Web Service API. Since these artefacts are referenced throughout the remainder of this guide,
the following checklist shall provide an overview enabling you to make sure that you have received the
whole set when registering your application for the Fiserv Gateway:
o Store ID: Your store ID (e.g. 10012345678) which is required for the basic
authentication.
o User ID: The user ID denoting the user who is allowed to access the Web Service API,
e.g. 1. Again, this is required for the basic authentication.
o Password: The password required for the basic authentication.
o Client Certificate p12 File: The client certificate and private key stored in a p12 file
having the naming scheme WSstoreID._.userID.p12, e.g. in case of the above store ID
/ user ID examples, this would be WS101._.007.p12. This file is used for authenticating
the client at the Gateway. For connecting with Java you need a ks-File, e.g.:
WS10012345678._.1.ks.
o Client Certificate Installation Password: The password which is required to access the
p12 file (containing the client certificate and private key file).
o Client Certificate Private Key: The private key of the client certificate stored in a key file
having the naming scheme WSstoreID._.userID.key, e.g. in case of the above store ID
/ user ID examples, this would be WS10012345678._.1.key. Some tools which support
you in setting up your application for using the Web Service API require the private key
in this format when doing the client authentication at the Gateway.
o Client Certificate Private Key Password: This password protects the private key of the
client certificate. This password is needed to access the private key file (“Client
Certificate Private Key”) It follows the naming scheme ckp_creationTimestamp. For
instance, this might be ckp_1193927132.
o Client Certificate PEM File: The list of client certificates stored in a PEM file having the
naming scheme WSstoreID._.userID.pem, e.g. in case of the above store ID / user ID
examples, this would be WS10012345678._.1.pem. Some tools which support you in
setting up your application for using the Gateway require this file instead of the p12 file
described above.
o Trust Anchor as concatenated PEM File (tlstrust.pem): The file contains a list of client
certificates you should trust to establish a trusted connection to the running the Web
Service API. A Concatenated list of PEM-formatted certificates allow easy installation
for Apache Webservers or PHP.Trust Anchor as Java Keystore File (truststore.jsk): The
file contains a list of client certificates you should trust to establish a trusted connection
to the server running the Web Service API. This format is can easily support Java-based
integrations
o Trust Anchor as PKCS#7 File (tlstrust.p7b): This file contains a list of CA certificates
you should trust to establish a trusted connection to the server running the Web
Service API. PKCS#7 Files allow the easy installation of multiple certificate for example
within Microsoft Windows.

If you should be planning to handle multiple Store IDs through your integration, we can issue a special
API User and Client Certificate for you that you can use across all your Stores. When you submit
transactions from that API user, you do not need to vary the API User Name as the API User is the
same for all your Stores. You will need to include the Store ID in each transaction request in that case.
3 How the API works

The following section describes the API by means of a credit card transaction. The process for other
payment types is similar.

In most cases, a customer starts the overall communication process by buying goods or services with
her credit card in your online store. Following this, your store sends a credit card transaction (mostly in
order to capture the customer’s funds) via the Web Service API. Having received the transaction, the
Gateway forwards it to the credit card processor for authorisation. Based on the result, an approval or
error is returned to your online store. This means that all communication and processing details are
covered by the Gateway and you only have to know how to communicate with this Web Service.

The Web Service Standard defines such an interface by using the Web Service Definition Language
(WSDL). A WSDL file defining the Web Service API for the Fiserv Gateway can be found at:

https://test.ipg-online.com/ipgapi/services/order.wsdl

Note that you will have to supply your client certificate and your credentials, when viewing or requesting
the file e.g. in a Web browser. For instance, in case you want to view the WSDL file in the browser
running on Windows OS, you first have to install your client certificate, and then call the above URL.
This is done by executing the following steps:

1. Open the folder in which you have saved your client certificate p12 file.
2. Double-click the client certificate p12 file.
3. Click Next. Check the file name (which should be already set to the path of your client
certificate p12 file) and click Next.
4. Provide the Client Certificate Installation Password and click Next.
5. Choose the option Automatically select the certificate store based on the type of certificate
and click Next. This will place the certificate in your personal certificate store (more precisely
in the local Windows user’s personal certificate store).
6. Check the displayed settings and click Finish. Your client certificate is now installed.
7. Now, open a browser window and provide the above URL in the address field.
8. After requesting the URL, the server will ask your browser to supply the client certificate to
making sure that it is talking to your application correctly. Since you have installed the
certificate in the previous steps, it is transferred to the server without prompting you for any
input (i.e. you will not notice this process). Then, the Gateway sends its server certificate
(identifying it uniquely) to you. This certificate is verified against pre-installed certificates of
your browser. Again, this is done automatically without prompting you for any input. Now, a
secure connection is established and all data transferred between your application and the
Web Service API is TLS-encrypted. Please note, that only TLS secured communication over
standard HTTPS TCP port 443 is accepted.
9. Next, you will be prompted to supply your credentials for authorisation. As user name you have
to provide your store ID and user ID encoded in the format WSstoreID._.userID (unless you
manage multiple Stores through your integration). For instance, assuming your store ID is 101,
your user ID 007, and your password myPW, you have to supply WS101._.007 in the user
name field and myPW in the password field. Note that your credentials are encrypted before
being passed to the server due to the TLS connection established in the steps above. Then,
click OK.
10. The Web Service API WSDL file is displayed.

In short, the WSDL file defines the operations offered by the Web Service, their input and return
parameters, and how these operations can be invoked. In case of the Gateway Web Service API, it
defines only one operation (IPGApiOrder) callable by sending a SOAP HTTP request to the following
URL:

https://test.ipg-online.com/ipgapi/services

This operation takes an XML-encoded transaction as input and returns an XML-encoded response. Note
that it is not necessary to understand how the WSDL file is composed for using the Gateway. The
following chapters will guide you in setting up your store for building and performing custom credit card
transactions.

However, in case you are using third-party tools supporting you in setting up your store for accessing
the Web Service API, you might have to supply the URL where the WSDL file can be found. In a similar
way as described above, you have to tell your Web Service tool, that the communication is TLS-enabled,
requiring you to provide your client certificate and accept the server certificate as a trusted one.
Furthermore, you have to supply your credentials. How all is done heavily depends on your Web Service
tool. Hence, check the tool’s documentation for details.

4 Sending transactions to the Gateway

The purpose of this chapter is to give you a basic understanding of the steps to be taken when
committing transactions to the Gateway. It describes what happens if a customer pays with her credit
card in an online store using the Web Service API for committing transactions.
• The customer clicks on the Pay button in the online store.
• The online store displays a form asking the customer to provide her credit card number and the
expiry month and year.
• The customer types in these three fields and submits the data to the online store (i. e.
purchases the goods).
• The online store receives the data and builds an XML document encoding a Sale transaction
which includes the data provided by the customer and the total amount to be paid by the
customer.
• After building the XML Sale transaction, the online store wraps it in a SOAP message which
describes the Web Service operation to be called with the transaction XML being passed as a
parameter.
• Having built the SOAP message, the online store prepares it for being transferred over the
Internet by packing its content into an HTTPS POST request. Furthermore, the store sets the
HTTP headers, especially its credentials (note that the credentials are the same as the ones
you have to provide for viewing the WSDL file).
• Now, the store establishes an TLS connection by providing the client and server certificate.
Please note, that only TLS secured communication over standard HTTPS TCP port 443 is
accepted.
• Then, the online store sends the HTTPS request to the Web Service API and waits for an HTTP
response.
• The Web Service API receives the HTTPS request and parses out the authorization information
provided by the store in the HTTP headers.
• Having authorized the store to use the Gateway, the SOAP message contained in the HTTP
request body is parsed out. This triggers the Web Service operation handling the transaction
processing to run.
• The Gateway then performs the transaction processing, builds an XML response document,
wraps it in a SOAP message, and sends this SOAP message back to the client in the body of
an HTTPS response.
• Receiving this HTTPS response wakes up the store which reads out the SOAP message and
response XML document being part of it.
• Depending on the data contained in the XML response document an approval page is sent back
to the customer in case of a successful transaction, otherwise an error page is returned.
• The approval or error page is displayed.

While this example describes the case of a Sale transaction, other transactions basically follow the
same process.

Summarising the scenario, your application has to perform the following steps in order to commit credit
card transactions and analyze the result:

• Build an XML document encoding your transactions

• Wrap that XML document in a SOAP request message
• Build an HTTPS POST request with the information identifying your store provided in the HTTP
header and the SOAP request message in the body
• Establish an TLS connection between your application and the Web Service API
• Send the HTTPS POST request to the Gateway and receive the response
• Read the SOAP response message out of the HTTPS response body
• Analyse the XML response document contained in the SOAP response message

These seven steps are described in the following chapters. They guide you through the process of
setting up your application for performing custom credit card transactions.

5 Building Transactions in XML

This chapter describes how the different transaction types can be built in XML. As the above example
scenario has outlined, a transaction is first encoded in an XML document which is then wrapped as
payload in a SOAP message. That means the XML-encoded transaction represents the parameter
passed to the Web Service API operation.

Note that there exists a variety of Web Service tools supporting you in the generation of client stubs
which might free you of the necessity to deal with raw XML. However, a basic understanding of the
XML format is crucial in order to build correct transactions regardless of the available tool support.
Hence, it is recommended to become familiar with the XML format used by the Web Service API for
encoding transactions.

5.1 Credit/Debit Card transactions

Regardless of the transaction type, the basic XML document structure of a credit/debit card transaction
is as follows:
<ipgapi:IPGApiOrderRequest
xmlns:v1="http://ipg-online.com/ipgapi/schemas/v1"
xmlns:ipgapi="http://ipg-online.com/ipgapi/schemas/ipgapi">
<v1:Transaction>
<v1:CreditCardTxType>...</v1:CreditCardTxType>
<v1:CreditCardData>...</v1:CreditCardData>
<v1:Payment>...</v1:Payment>
<v1:TransactionDetails>...</v1:TransactionDetails>
<v1:Billing>...</v1:Billing>
<v1:Shipping>...</v1:Shipping>
</v1:Transaction>
</ipgapi:IPGApiOrderRequest>

The element CreditCardDataTXType is mandatory for all credit card transactions. The other elements
depend on the transaction type. The transaction content is type-specific. The elements in XML
structure must be kept in the same order as shown in examples, otherwise the OrderRequest will
fail.

5.2 Sale
The following XML document represents an example of a Sale transaction using the minimum set of
elements:

See chapter XML-Tag overview for a detailed description of all elements used in the above example
as well as further optional elements.

The following XML document represents an example of a Sale transaction for API users handling
multiple Store IDs:

<ipgapi:IPGApiOrderRequest
xmlns:ipgapi='http://ipg-online.com/ipgapi/schemas/ipgapi'
xmlns:v1='http://ipg-online.com/ipgapi/schemas/v1'>
<v1:Transaction>
<v1:CreditCardTxType>
<v1:StoreId>1234567890</v1:StoreId>
<v1:Type>sale</v1:Type>
</v1:CreditCardTxType>
<v1:CreditCardData>
<v1:CardNumber>4111******1111</v1:CardNumber>
<v1:ExpMonth>12</v1:ExpMonth>
<v1:ExpYear>27</v1:ExpYear>
<v1:CardCodeValue>XXX</v1:CardCodeValue>
</v1:CreditCardData>
<v1:Payment>
<v1:ChargeTotal>15.00</v1:ChargeTotal>
<v1:Currency>978</v1:Currency>
</v1:Payment>
<v1:TransactionDetails>
<v1:OrderId>12-34-56</v1:OrderId>
<v1:MerchantTransactionId>AB500500</v1:MerchantTransactionId>
<v1:TransactionOrigin>ECI</v1:TransactionOrigin>
<v1:DynamicMerchantName>MyWebsite</v1:DynamicMerchantName>
</v1:TransactionDetails>
<v1:Billing>
<v1:Zip>0001</v1:Zip>
</v1:Billing>
</v1:Transaction>
</ipgapi:IPGApiOrderRequest>

5.3 Pre-Authorisation
The following XML document represents an example of a PreAuth transaction using the minimum set
of elements:

See chapter XML-Tag overview for a detailed description of all elements used in the above example as
well as further optional elements.

5.4 Post-Authorisation
The following XML document represents an example of a PostAuth transaction using the minimum set
of elements:

<ipgapi:IPGApiOrderRequest
xmlns:v1="http://ipg-online.com/ipgapi/schemas/v1"
xmlns:ipgapi="http://ipg-online.com/ipgapi/schemas/ipgapi">
<v1:Transaction>
<v1:CreditCardTxType>
<v1:Type>postAuth</v1:Type>
</v1:CreditCardTxType>
<v1:Payment>
<v1:ChargeTotal>59.00</v1:ChargeTotal>
<v1:Currency>978</v1:Currency>
</v1:Payment>
<v1:TransactionDetails>
<v1:OrderId>03d2723-99b6-4559-8c6d-79748</v1:OrderId>
</v1:TransactionDetails>
</v1:Transaction>
</ipgapi:IPGApiOrderRequest>
In case your system is not aware of the payment method that has been used for the original Pre-
Authorisation transaction, the Post-Authorisation can be performed using any TxType which supports
Post-Authorisations. The Gateway will then select the correct payment method based on the
referenced Order ID.

See chapter XML-Tag overview for a detailed description of all elements used in the above example
as well as further optional elements.

5.5 Return
The following XML document represents an example of a Return transaction using the minimum set of
elements:

In case your system is not aware of the payment method that has been used for the original
transaction, the Return can be performed using any TxType which supports Returns. The Gateway
will then select the correct payment method based on the referenced Order ID.

See chapter XML-Tag overview for a detailed description of all elements used in the above example
as well as further optional elements.

5.7 Credit
Please note that Credit is a transaction type that requires special user permissions.

The following XML document represents an example of a Credit transaction using the minimum set of
elements:

See chapter XML-Tag overview for a detailed description of all elements used in the above example
as well as further optional elements.

5.8 Void
The following XML document represents an example of a Void transaction using the minimum set of
elements:

For referencing to the transaction that shall be voided, this example uses the parameter
‘IpgTransactionId’. If you have assigned a transaction ID (MerchantTransactionId) in the original
transaction, you can alternatively submit this ID as ‘ReferencedMerchantTransactionId instead.
In case your system is not aware of the payment method that has been used for the original
transaction, the Void can be performed using any TxType which supports Voids. The Gateway will
then select the correct payment method based on the referenced Order ID and TDate.

See chapter XML-Tag overview for a detailed description of all elements used in the above example
as well as further optional elements.

5.9 Recurring Sale (Merchant-triggered)

The following XML document represents an example of a first Sale transaction of a series of recurring
payments:

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

In case you have received SchemeTransactionId in the response from the Gateway you should
use its value in the subsequent RecurringType=REPEAT request:

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<ipgapi:IPGApiOrderResponse xmlns:a1="http://ipg-
online.com/ipgapi/schemas/a1" xmlns:ipgapi="http://ipg-
online.com/ipgapi/schemas/ipgapi" xmlns:v1="http://ipg-
online.com/ipgapi/schemas/v1">
<ipgapi:ApprovalCode>Y:403939:4566959508:YYYM:441809</ipgapi:ApprovalCode>
<ipgapi:AVSResponse>YYY</ipgapi:AVSResponse>
<ipgapi:Brand>MASTERCARD</ipgapi:Brand>
<ipgapi:CommercialServiceProvider>BOSMS</ipgapi:CommercialServiceProvider>
<ipgapi:OrderId>A-b64adf8c-8fe8-44cb-97de-fd721033da2e</ipgapi:OrderId>
<ipgapi:IpgTransactionId>84566959508</ipgapi:IpgTransactionId>
<ipgapi:PaymentType>CREDITCARD</ipgapi:PaymentType>
<ipgapi:ProcessorApprovalCode>403939</ipgapi:ProcessorApprovalCode>
<ipgapi:ProcessorCCVResponse>M</ipgapi:ProcessorCCVResponse>
<ipgapi:ProcessorReferenceNumber>119509441809</ipgapi:ProcessorReferenceNumber>
<ipgapi:ProcessorResponseCode>00</ipgapi:ProcessorResponseCode>
<ipgapi:ProcessorResponseMessage>Function performed error-
free</ipgapi:ProcessorResponseMessage>
<ipgapi:SchemeTransactionId>0714MCC417474</ipgapi:SchemeTransactionId>
<ipgapi:TDate>1626255235</ipgapi:TDate>
<ipgapi:TDateFormatted>2021.07.14 11:33:55 (CEST)</ipgapi:TDateFormatted>
<ipgapi:TerminalID>80000860</ipgapi:TerminalID>
<ipgapi:TransactionResult>APPROVED</ipgapi:TransactionResult>
<ipgapi:TransactionTime>1626255235</ipgapi:TransactionTime>
</ipgapi:IPGApiOrderResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Subsequent transactions in a series need to be flagged like this and submitted with the
SchemeTransactionId you have received in the previous step :

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

5.9.1 Recurring Transaction with 3-D Secure

In case you are impacted with PSD2 mandate for Strong Customer Authentication (SCA) and you are
managing recurring payments yourself, you need to authenticate the cardholder during initial recurring
transaction. In such case you need to include additional parameters in the API request as per scheme
requirements.

The following represents an example of recurringType=FIRST request including all mandatory

parameters:

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

<SOAP-ENV:Envelope
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<ns4:IPGApiOrderRequest
xmlns:ns4="http://ipg-online.com/ipgapi/schemas/ipgapi"
xmlns:ns2="http://ipg-online.com/ipgapi/schemas/v1"
xmlns:ns3="http://ipg-online.com/ipgapi/schemas/a1">
<ns2:Transaction>
<ns2:CreditCardTxType>
<ns2:StoreId>1109950006</ns2:StoreId>
<ns2:Type>sale</ns2:Type>
</ns2:CreditCardTxType>
<ns2:CreditCardData>
<ns2:CardNumber>52047******2745</ns2:CardNumber>
<ns2:ExpMonth>12</ns2:ExpMonth>
<ns2:ExpYear>27</ns2:ExpYear>
<ns2:CardCodeValue>XXX</ns2:CardCodeValue>
</ns2:CreditCardData>
<ns2:CreditCard3DSecure>
<ns2:AuthenticateTransaction>true</ns2:AuthenticateTransaction>
<ns2:TermUrl>https://test.webshop.com/simulator/secure3d/return</ns2:TermUrl>
<ns2:ThreeDSMethodNotificationURL>https://test/ipgconfirmation/services/secure3ds</
ns2:ThreeDSMethodNotificationURL>
<ns2:ThreeDSRequestorChallengeIndicator>04</ns2:ThreeDSRequestorChallengeIndicator>
<ns2:ThreeDSRequestorAuthenticationIndicator>02</ns2:ThreeDSRequestorAuthentication
Indicator>
<ns2:recurringFrequency>30</ns2:recurringFrequency>
<ns2:recurringExpiry>20220525</ns2:recurringExpiry>
</ns2:CreditCard3DSecure>
<ns2:recurringType>FIRST</ns2:recurringType>
<ns2:Payment>
<ns2:ChargeTotal>12.99</ns2:ChargeTotal>
<ns2:Currency>978</ns2:Currency>
</ns2:Payment>
</ns2:Transaction>
</ns4:IPGApiOrderRequest>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
After this request the transaction processing continues with EMV 3-D Secure flow and authorization is
triggered automatically once the authentication has been successfully completed.

NOTE: In case you have not submitted the elements ‘recurringFrequency’ and ‘recurringExpiry’ the
Gateway populates these two elements with default values, e.g. ‘recurringFrequency’ = 1 and
‘recurringExpiry’=99991231.

Please see chapter Recurring Payments (Scheduler) for the alternative option to let the Gateway
automatically trigger recurring transactions.

5.10 Merchant Initiated Transactions

Merchant-Initiated Transactions (MIT) are payments initiated by the merchant without cardholder
being in a session.

In case you are located in European Economic Area impacted with PSD2 rules, such payments require
that:
1. SCA is applied to the first transaction or action mandating the merchant to initiate payment(s)
and
2. there is an agreement between the cardholder and the merchant for the provision of products
or services and potential costs associated with these.

In case you would prefer to register your customer and save his credit card credentials on file, you are
obliged to obtain cardholder’s consent by using Strong Customer Authentication (SCA) in your
transaction request.

In order to achieve that, your cardholders must authenticate themselves during transaction
processing, while still in session. PSD2 and scheme rules demand a 3-D Secure challenge flow to be
performed in such case. All mentioned above needs to be indicated to our Gateway, so that proper
flagging is applied in the authorization message.

The following XML document represent an example of a first Credentials-on-File (COF) transaction
indicating 3DS Requestor’s preference to challenge a cardholder:

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

After this request the transaction processing continues with EMV 3-D Secure flow and authorization is
triggered automatically once the authentication has been successfully completed.

The API response you received after your customer got authenticated successfully contains also a
‘SchemeTransactionId’ what must be submitted in your next MIT transaction request:

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<ipgapi:IPGApiOrderResponse
xmlns:a1="http://ipg-online.com/ipgapi/schemas/a1"
xmlns:ipgapi="http://ipg-online.com/ipgapi/schemas/ipgapi"
xmlns:v1="http://ipg-online.com/ipgapi/schemas/v1">
<ipgapi:ApprovalCode>Y:527777:4589932541:YYYM:497437</ipgapi:ApprovalCode>
<ipgapi:AVSResponse>YYY</ipgapi:AVSResponse>
<ipgapi:Brand>MASTERCARD</ipgapi:Brand>
<ipgapi:Country>GBR</ipgapi:Country>
<ipgapi:CommercialServiceProvider>BOSMS</ipgapi:CommercialServiceProvider>
<ipgapi:OrderId>A-55e3fab0-be09-4fb4-a45b-a2e60f97c1ef</ipgapi:OrderId>
<ipgapi:IpgTransactionId>84589932541</ipgapi:IpgTransactionId>
<ipgapi:PaymentType>CREDITCARD</ipgapi:PaymentType>
<ipgapi:ProcessorApprovalCode>527777</ipgapi:ProcessorApprovalCode>
<ipgapi:ProcessorCCVResponse>M</ipgapi:ProcessorCCVResponse>
<ipgapi:ProcessorReferenceNumber>205415497437</ipgapi:ProcessorReferenceNumber>
<ipgapi:ProcessorResponseCode>00</ipgapi:ProcessorResponseCode>
<ipgapi:ProcessorResponseMessage>Functionperformederror-
free</ipgapi:ProcessorResponseMessage>
<ipgapi:SchemeTransactionId>0223MCC599836</ipgapi:SchemeTransactionId>
<ipgapi:TDate>1645631609</ipgapi:TDate>
<ipgapi:TDateFormatted>2022.02.23 16:53:29 (CET)</ipgapi:TDateFormatted>
<ipgapi:TerminalID>80000860</ipgapi:TerminalID>
<ipgapi:TransactionResult>APPROVED</ipgapi:TransactionResult>
<ipgapi:TransactionTime>1645631609</ipgapi:TransactionTime>
<ipgapi:Secure3DResponse>
<v1:ResponseCode3dSecure>1</v1:ResponseCode3dSecure>
</ipgapi:Secure3DResponse>
</ipgapi:IPGApiOrderResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

After you completed the previous step successfully, you will be able to initiate an MIT transaction:

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

Please note, that the solution and examples described above are available only if you utilize Fiserv as your
3DS service provider and your store is setup accordingly.

5.11 Standing Instructions

Standing Instructions are instructions a consumer (payer) gives to a bank to pay a set amount at regular
intervals to another’s (payee) account. They are typically used to pay rent, mortgage or any other fixed
regular payments. If your Store is enabled to process this type of transactions, Standing Instuctions can
be submitted in the following format:

<ipgapi:IPGApiOrderRequest
xmlns:v1="http://ipg-online.com/ipgapi/schemas/v1"
xmlns:ipgapi="http://ipg-online.com/ipgapi/schemas/ipgapi">
<v1:Transaction>
<v1:CreditCardTxType>
<v1:Type>sale</v1:Type>
</v1:CreditCardTxType>
<v1:CreditCardData>
<v1:CardNumber>4111********1111</v1:CardNumber>
<v1:ExpMonth>12</v1:ExpMonth>
<v1:ExpYear>07</v1:ExpYear>
</v1:CreditCardData>
<ns2:recurringType>STANDIN</ns2:recurringType>
<v1:Payment>
<v1:ChargeTotal>19.95</v1:ChargeTotal>
<v1:Currency>978</v1:Currency>
</v1:Payment>
</v1:Transaction>
</ipgapi:IPGApiOrderRequest>
5.12 SEPA Direct Debit - Germany
Regardless of the transaction type, the basic XML document structure of a German Direct Debit
transaction is as follows:

<ipgapi:IPGApiOrderRequest
xmlns:v1="http://ipg-online.com/ipgapi/schemas/v1"
xmlns:ipgapi="http://ipg-online.com/ipgapi/schemas/ipgapi">
<v1:Transaction>
<v1:DE_DirectDebitTxType>...</v1:DE_DirectDebitTxType>
<v1:DE_DirectDebitData>...</v1:DE_DirectDebitData>
<v1:Payment>...</v1:Payment>
<v1:TransactionDetails>...</v1:TransactionDetails>
<v1:Billing>
<v1:Name>Name Surname</v1:Name>
</v1:Billing>
<v1:Shipping>...</v1:Shipping>
</v1:Transaction>
</ipgapi:IPGApiOrderRequest>

The element DE_DirectDebitTXType is mandatory for all debit transactions. The other elements
depend on the transaction type. The transaction content is type-specific.

Note: In case you have a “GLV” contract with your service provider, you need to submit additional
customer data in “Billing” element of your transaction request.

5.12.1 Sale
The following XML document represents an example of a Sale transaction using the minimum set of
elements:

<ipgapi:IPGApiOrderRequest
xmlns:v1="http://ipg-online.com/ipgapi/schemas/v1"
xmlns:ipgapi="http://ipg-online.com/ipgapi/schemas/ipgapi">
<v1:Transaction>
<v1:DE_DirectDebitTxType>
<v1:Type>sale</v1:Type>
</v1:DE_DirectDebitTxType>
<v1:DE_DirectDebitData>
<v1:IBAN>DE345001XXXX32121604</v1:IBAN>
<v1:MandateReference>0/8/15</v1:MandateReference>
</v1:DE_DirectDebitData>
<v1:Billing>
<v1:Name>Markus Mustermann</v1:Name>
</v1:Billing>
<v1:Payment>
<v1:ChargeTotal>19.00</v1:ChargeTotal>
<v1:Currency>978</v1:Currency>
</v1:Payment>
</v1:Transaction>
</ipgapi:IPGApiOrderRequest>

See chapter XML-Tag overview for a detailed description of all elements used in the above example
as well as further optional elements.

5.12.2 Void
The following XML document represents an example of a Void transaction using the minimum set of
elements:

<ipgapi:IPGApiOrderRequest
xmlns:v1="http://ipg-online.com/ipgapi/schemas/v1"
xmlns:ipgapi="http://ipg-online.com/ipgapi/schemas/ipgapi">
<v1:Transaction>
<v1:DE_DirectDebitTxType>
<v1:Type>void</v1:Type>
</v1:DE_DirectDebitTxType>
<v1:TransactionDetails>
<v1:IpgTransactionId>1234567890</v1:IpgTransactionId>
</v1:TransactionDetails>
</v1:Transaction>
</ipgapi:IPGApiOrderRequest>

For referencing to the transaction that shall be voided, this example uses the parameter
IpgTransactionId. If you have assigned a transaction ID (MerchantTransactionId) in the original
transaction, you can alternatively submit this ID as ReferencedMerchantTransactionId instead.
In case your system is not aware of the payment method that has been used for the original
transaction, the Void can be performed using any TxType which supports Voids. The Gateway will
then select the correct payment method based on the referenced Transaction ID.

See chapter XML-Tag overview for a detailed description of all elements used in the above example
as well as further optional elements.

5.12.3 Credit
Please note, that Credit is a transaction type that requires special user permissions.

The following XML document represents an example of a Credit transaction using the minimum set of
elements:

<ipgapi:IPGApiOrderRequest
xmlns:v1="http://ipg-online.com/ipgapi/schemas/v1"
xmlns:ipgapi="http://ipg-online.com/ipgapi/schemas/ipgapi">
<v1:Transaction>
<v1:DE_DirectDebitTxType>
<v1:Type>credit</v1:Type>
</v1:DE_DirectDebitTxType>
<v1:DE_DirectDebitData>
<v1:IBAN>DE34500****0032121604</v1:IBAN>
</v1:DE_DirectDebitData>
<v1:Billing>
<v1:Name>Markus Mustermann</v1:Name>
</v1:Billing>
<v1:Payment>
<v1:ChargeTotal>19.00</v1:ChargeTotal>
<v1:Currency>978</v1:Currency>
</v1:Payment>
</v1:Transaction>
</ipgapi:IPGApiOrderRequest>

See chapter XML-Tag overview for a detailed description of all elements used in the above example
as well as further optional elements.

5.12.4 Return
Please note that Return is a transaction type that requires special user permissions.

The following XML document represents an example of a Return transaction using the minimum set
of elements:
<ipgapi:IPGApiOrderRequest
xmlns:v1="http://ipg-online.com/ipgapi/schemas/v1"
xmlns:ipgapi="http://ipg-online.com/ipgapi/schemas/ipgapi">
<v1:Transaction>
<v1:DE_DirectDebitTxType>
<v1:Type>return</v1:Type>
</v1:DE_DirectDebitTxType>
<v1:Payment>
<v1:ChargeTotal>1.00</v1:ChargeTotal>
<v1:Currency>978</v1:Currency>
</v1:Payment>
<v1:TransactionDetails>
<v1:OrderId>62e3b5df-2911-4e89-8356-1e493</v1:OrderId>
</v1:TransactionDetails>
</v1:Transaction>
</ipgapi:IPGApiOrderRequest>

See chapter XML-Tag overview for a detailed description of all elements used in the above example
as well as further optional elements.

5.13 SEPA Direct Debit with Fiserv Local Payments

The Fiserv Local Payments solution offers a unique combination of global coverage, a single
contracting and integration experience, and a broad and expanding portfolio of local payment
methods.

If your Store has been activated for this product option, you can use this Web Service API to initiate
SEPA Direct Debit payments where you manage the mandates on your side.

This is useful in cases where you have a large number of mandates on file from previously used
solutions and want to continue to use these mandates when migrating to Fiserv.

Recurring payment

Field Name M/O Description

Billing/Email O Consumer’s email address

SepaData/IBAN M Consumer’s IBAN - International Bank

Account Number (22 digits)

Mandate/Type M Sequence type of Direct Debit, defaults to ‘single’

Values:
SINGLE - Direct Debit is executed once
FIRST_COLLECTION - First Direct Debit in a series of recurring
RECURRING_COLLECTION – Follow-up Direct Debit in a series of
recurring
FINAL_COLLECTION – Last Direct Debit in a series of recurring

Mandate/Reference M To be populated with the mandate reference

Mandate/Date M To be populated with the initial mandate signature date

Mandate/Url M To be populated with the valid URL of the SEPA mandate

The following represents an example of a transaction request, which includes reference to the mandate
and the URL, where the mandate could be verified:

<ipgapi:IPGApiOrderRequest
xmlns:v1="http://ipg-online.com/ipgapi/schemas/v1"
xmlns:ipgapi="http://ipg-online.com/ipgapi/schemas/ipgapi">
<v1:Transaction>
<v1:SepaTxType>
<v1:StoreId>990004</v1:StoreId>
<v1:Type>sale</v1:Type>
</v1:SepaTxType>
<v1:SepaData>
<v1:IBAN>DE345001006***32121604</v1:IBAN>
<v1:Mandate>
<v1:Reference>4HJUZ67T</v1:Reference>
<v1:Type>FIRST_COLLECTION</v1:Type>
<v1:Date>20150715</v1:Date>
<v1:Url>https://www.webshop.com</v1:Url>
<v1:Mandate>
</v1:SepaTxType>
<v1:Payment>
<v1:ChargeTotal>1</v1:ChargeTotal>
<v1:Currency>EUR</v1:Currency>
</v1:Payment>
<v1:Billing>
<v1:Name>Testname</v1:Firstname>
<v1:Country>DE</v1:Country>
<v1:Email>youremail@email.com</v1:Email>
</v1:Billing>
</v1:Transaction>
</ipgapi:IPGApiOrderRequest>

When you do not want to manage the SEPA Direct Debit mandates on your side, you can instead use
the out-of-box solution offered by Fiserv. Upon receiving the mandate reference and the mandate
date as part of the Connect response, you can process the subsequent payments under this mandate
via this Web Service API.

Follow-up payment in recurring series:

Field name M/O Description

Billing/Email M Consumer’s email address

SepaData/IBAN M Consumer’s IBAN - International Bank

Account Number (22 digits)

Mandate/Type M Sequence type of Direct Debit

Values:
RECURRING_COLLECTION – Follow-up Direct Debit in a series of
recurring
FINAL_COLLECTION – Last Direct Debit in a series of recurring

Mandate/Reference M To be populated with the mandate reference from the response

Mandate/Date M To be populated with the initial mandate signature date from the
response
The following represents an example of a transaction request, which is owned and managed by Fiserv
and which includes reference to the hosted mandate created with the first transaction in series:

<ipgapi:IPGApiOrderRequest
xmlns:v1="http://ipg-online.com/ipgapi/schemas/v1"
xmlns:ipgapi="http://ipg-online.com/ipgapi/schemas/ipgapi">
<v1:Transaction>
<v1:SepaTxType>
<v1:StoreId>990004</v1:StoreId>
<v1:Type>sale</v1:Type>
</v1:SepaTxType>
<v1:SepaData>
<v1:IBAN>DE**345001006***32121604</v1:IBAN>
<v1:Mandate>
<v1:Reference>25IGX0N</v1:Reference>
<v1:Type>RECURRING_COLLECTION</v1:Type>
<v1:Date>20180124</v1:Date>
<v1:Mandate>
</v1:SepaTxType>
<v1:Payment>
<v1:ChargeTotal>1</v1:ChargeTotal>
<v1:Currency>EUR</v1:Currency>
</v1:Payment>
<v1:Billing>
<v1:Name>Testname</v1:Firstname>
<v1:Country>DE</v1:Country>
<v1:Email>youremail@email.com</v1:Email>
</v1:Billing>
</v1:Transaction>
</ipgapi:IPGApiOrderRequest>

5.14 PayPal
5.14.1 PayPal Post-Authorisation Payment Transaction
After a payment authorisation for PayPal has been submitted via the Gateway’s Connect interface,
the Web Service API can be used to perform post-authorisation payments.

The following XML document represents an example of a PostAuth transaction using the minimum set
of elements:

<ns5:IPGApiOrderRequest
xmlns:ns5="http://ipg-online.com/ipgapi/schemas/ipgapi"
xmlns:ns3="http://ipg-online.com/ipgapi/schemas/a1"
xmlns:ns4="http://ipg-online.com/ipgapi/schemas/v1">
<ns4:Transaction>
<ns4:PayPalTxType>
<ns4:Type>postAuth</ns4:Type>
</ns4:PayPalTxType>
<ns4:Payment>
<ns4:ChargeTotal>1</ns4:ChargeTotal>
<ns4:Currency>EUR</ns4:Currency>
</ns4:Payment>
<ns4:TransactionDetails>
<ns4:OrderId>
C-32121f4d-852f-4f48-8095-8585b917c079
</ns4:OrderId>
</ns4:TransactionDetails>
</ns4:Transaction>
</ns5:IPGApiOrderRequest>

See chapter XML-Tag overview for a detailed description of all elements used in the above example
as well as further optional elements.
5.14.2 Recurring Payment Transaction
The recurring payments for PayPal can be executed via the Connect solution. You have to submit a
SALE transaction request with the corresponding parameters to install the recurring payments. The first
transaction is always conducted immediately along with the request.

The subsequent transactions are executed by the Gateway’s scheduler, via the API Web Service, as
defined during the initial SALE transaction with the instalation.

5.14.3 Return
The following XML document represents an example of a Return transaction using the minimum set of
elements:

<ns5:IPGApiOrderRequest
xmlns:ns5="http://ipg-online.com/ipgapi/schemas/ipgapi"
xmlns:ns3="http://ipg-online.com/ipgapi/schemas/a1"
xmlns:ns4="http://ipg-online.com/ipgapi/schemas/v1">
<ns4:Transaction>
<ns4:PayPalTxType>
<ns4:Type>return</ns4:Type>
</ns4:PayPalTxType>
<ns4:Payment>
<ns4:ChargeTotal>0.4</ns4:ChargeTotal>
<ns4:Currency>EUR</ns4:Currency>
</ns4:Payment>
<ns4:TransactionDetails>
<ns4:OrderId>
C-32121f4d-852f-4f48-8095-8585b917c079
</ns4:OrderId>
</ns4:TransactionDetails>
</ns4:Transaction>
</ns5:IPGApiOrderRequest>

In case your system is not aware of the payment method that has been used for the original
transaction, the Return can be performed using any TxType which supports Returns. The gateway will
then select the correct payment method based on the referenced Order ID.

5.14.4 Void
The following XML document represents an example of a Void transaction using the minimum set of
elements:

<ns5:IPGApiOrderRequest
xmlns:ns5="http://ipg-online.com/ipgapi/schemas/ipgapi"
xmlns:ns3="http://ipg-online.com/ipgapi/schemas/a1"
xmlns:ns4="http://ipg-online.com/ipgapi/schemas/v1">
<ns4:Transaction>
<ns4:PayPalTxType>
<ns4:Type>void</ns4:Type>
</ns4:PayPalTxType>
<ns4:TransactionDetails>
<v1:IpgTransactionId>1234567890</v1:IpgTransactionId>
</ns4:TransactionDetails>
</ns4:Transaction>
</ns5:IPGApiOrderRequest>

For referencing to the transaction that shall be voided, this example uses the parameter
IpgTransactionId. If you have assigned a transaction ID (MerchantTransactionId) in the original
transaction, you can alternatively submit this ID as ReferencedMerchantTransactionId instead of
sending a TDate.
In case your system is not aware of the payment method that has been used for the original
transaction, the Void can be performed using any TxType which supports Voids. The gateway will
then select the correct payment method based on the referenced Transaction ID.

5.14.5 Credit
Please note that Credit is a transaction type that requires special user permissions.

The following XML document represents an example of a Credit transaction using the minimum set of
elements:

<ns5:IPGApiOrderRequest
xmlns:ns5="http://ipg-online.com/ipgapi/schemas/ipgapi"
xmlns:ns2="http://ipg-online.com/ipgapi/schemas/a1"
xmlns:ns4="http://ipg-online.com/ipgapi/schemas/v1">
<ns4:Transaction>
<ns4:PayPalTxType>
<ns4:Type>credit</ns4:Type>
</ns4:PayPalTxType>
<ns4:Payment>
<ns4:ChargeTotal>1</ns4:ChargeTotal>
<ns4:Currency>EUR</ns4:Currency>
</ns4:Payment>
<ns4:Billing>
<ns4:Email>x@y.zz</ns4:Email>
</ns4:Billing>
</ns4:Transaction>
</ns5:IPGApiOrderRequest>

Unlike with other payment methods, PayPal transactions contain no payment data like a card number.
Therefore this transaction requires the resgistered email address of the recipient of the payment. This
email address must be submitted in the field ns4:Billing/ns4:Email.

5.15 SOFORT Überweisung

5.15.1 Return
The following XML document represents an example of a Return transaction using the minimum set of
elements:

<ns5:IPGApiOrderRequest
xmlns:ns5="http://ipg-online.com/ipgapi/schemas/ipgapi
xmlns:ns3="http://ipg-online.com/ipgapi/schemas/a1"
xmlns:ns4="http://ipg-online.com/ipgapi/schemas/v1">
<ns4:Transaction>
<ns4:SofortTxType>
<ns4:Type>return</ns4:Type>
</ns4:SofortTxType>
<ns4:Payment>
<ns4:ChargeTotal>1.00</ns4:ChargeTotal>
<ns4:Currency>EUR</ns4:Currency>
</ns4:Payment>
<ns4:TransactionDetails>
<ns4:OrderId>
C-32121f4d-852f-4f48-8095-8585b917c079
</ns4:OrderId>
</ns4:TransactionDetails>
</ns4:Transaction>
</ns5:IPGApiOrderRequest>

When your are triggering a return for SOFORT Banking transition it will only be marked as being
prepared for the refund on SOFORT’s side but not yet executed. In order for your customer to receive
the money, you need to execute the return transaction via SOFORT’s merchant portal or via its API.
For details please see https://www.sofort.com/integrationCenter-eng-DE/content/view/full/3363.

5.15.2 Return
Please note that this feature is not available through all distribution channels.

The following XML document represents an example of a Return transaction using the minimum set of
elements:

<ns5:IPGApiOrderRequest
xmlns:ns5=http://ipg-online.com/ipgapi/schemas/ipgapi
xmlns:ns3="http://ipg-online.com/ipgapi/schemas/a1"
mlns:ns4="http://ipg-online.com/ipgapi/schemas/v1">
<ns4:Transaction>
<ns4:IdealTxType>
<ns4:Type>return</ns4:Type>
</ns4:IdealTxType>
<ns4:Payment>
<ns4:ChargeTotal>1.00</ns4:ChargeTotal>
<ns4:Currency>EUR</ns4:Currency>
</ns4:Payment>
<ns4:TransactionDetails>
<ns4:OrderId>
C-32121f4d-852f-4f48-8095-8585b917c079
</ns4:OrderId>
</ns4:TransactionDetails>
</ns4:Transaction>
</ns5:IPGApiOrderRequest>

5.16 Generic Transaction Type for Voids and Returns

The Tag SubsequentTransaction allows you to submit Voids and Refunds independently from which
payment method had been used for the original payment transaction.

You can initiate such transactions by referencing to a previous transaction using one of the following
options:
• IPG Transaction ID
• Merchant Transaction ID

The following XML document represents an example of a Void transaction using the minimum set of
elements for IPG Transaction ID:

<ns5:IPGApiOrderRequest
xmlns:ns5="http://ipg-online.com/ipgapi/schemas/ipgapi" xmlns:ns2="http://ipg-
online.com/ipgapi/schemas/v1"
xmlns:ns3="http://ipg-online.com/ipgapi/schemas/a1">
<ns2:SubsequentTransaction>
<ns2:IpgTransactionId>1234567890</ns2:IpgTransactionId>
<ns2:Options>
<ns2:StoreId>120995000</ns2:StoreId>
</ns2:Options>
<ns2:TransactionType>VOID</ns2:TransactionType>
</ns2:SubsequentTransaction>
</ns5:IPGApiOrderRequest>

The following XML document represents an example of a Void transaction using the minimum set of
elements for Merchant Transaction ID:

<ns5:IPGApiOrderRequest
xmlns:ns5="http://ipg-online.com/ipgapi/schemas/ipgapi" xmlns:ns2="http://ipg-
online.com/ipgapi/schemas/v1"
xmlns:ns3="http://ipg-online.com/ipgapi/schemas/a1">
<ns2:SubsequentTransaction>
<ns2:ReferencedMerchantTransactionId>ITID-
000380</ns2:ReferencedMerchantTransactionId>
<ns2:Options>
<ns2:StoreId>44036000750</ns2:StoreId>
</ns2:Options>
<ns2:TransactionType>VOID</ns2:TransactionType>
</ns2:SubsequentTransaction>
</ns5:IPGApiOrderRequest>

The following XML document represents an example of a Return transaction using the minimum set of
elements for IPG Transaction ID:

<ns5:IPGApiOrderRequest
xmlns:ns5="http://ipg-online.com/ipgapi/schemas/ipgapi"
xmlns:ns2="http://ipg-online.com/ipgapi/schemas/v1"
xmlns:ns3="http://ipg-online.com/ipgapi/schemas/a1">
<ns2:SubsequentTransaction>
<ns2:IpgTransactionId>123456789</ns2:IpgTransactionId>
<ns2:Options>
<ns2:StoreId>120995000</ns2:StoreId>
</ns2:Options>
<ns2:TransactionType>RETURN</ns2:TransactionType>
<ns2:Payment>
<ns2:ChargeTotal>1.00</ns2:ChargeTotal>
<ns2:Currency>978</ns2:Currency>
</ns2:Payment>
</ns2:SubsequentTransaction>
</ns5:IPGApiOrderRequest>

The following XML document represents an example of a Return transaction using the minimum set of
elements for Merchant Transaction ID:

<ns5:IPGApiOrderRequest
xmlns:ns5="http://ipg-online.com/ipgapi/schemas/ipgapi"
xmlns:ns2="http://ipg-online.com/ipgapi/schemas/v1"
xmlns:ns3="http://ipg-online.com/ipgapi/schemas/a1">
<ns2:SubsequentTransaction>
<ns2:ReferencedMerchantTransactionId>ITID-
000380</ns2:ReferencedMerchantTransactionId>
<ns2:Options>
<ns2:StoreId>44036000750</ns2:StoreId>
</ns2:Options>
<ns2:TransactionType>RETURN</ns2:TransactionType>
<ns2:Payment>
<ns2:ChargeTotal>1.00</ns2:ChargeTotal>
<ns2:Currency>978</ns2:Currency>
</ns2:Payment>
</ns2:SubsequentTransaction>
</ns5:IPGApiOrderRequest>
6 Additional Web Service actions
6.1 Initiate Clearing

Clearing for transactions can be initiated via the Web Service similar to a payment transaction:

<ipgapi:IPGApiActionRequest
xmlns:a1="http://ipg-online.com/ipgapi/schemas/a1"
xmlns:ipgapi="http://ipg-online.com/ipgapi/schemas/ipgapi">
<a1:Action>
</a1:InitiateClearing>
</a1:Action>
</ipgapi:IPGApiActionRequest>

Clearing will will be executed directly. If clearing was not successful for at least one terminal, the
gateway will send “false” in the response.

6.2 Inquiry Order

The action InquiryOrder allows you to get details about previously processed transactions of a specific
order. You therefore need to submit the corresponding Order ID:

The result contains information about all transactions belonging to the corresponding Order ID:

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<ipgapi:IPGApiActionResponse xmlns:a1="http://ipg-
online.com/ipgapi/schemas/a1" xmlns:ipgapi="http://ipg-
online.com/ipgapi/schemas/ipgapi" xmlns:v1="http://ipg-
online.com/ipgapi/schemas/v1">
<ipgapi:successfully>true</ipgapi:successfully>
<ipgapi:OrderId>A-504a5ebf-6424-41af-bfd1-8f9eaca23378</ipgapi:OrderId>
<v1:Billing/>
<v1:Shipping/>
<a1:TransactionValues>
<v1:CreditCardTxType>
<v1:Type>sale</v1:Type>
</v1:CreditCardTxType>
<v1:CreditCardData>
<v1:CardNumber>401200...1004</v1:CardNumber>
<v1:ExpMonth>12</v1:ExpMonth>
<v1:ExpYear>24</v1:ExpYear>
<v1:Brand>VISA</v1:Brand>
</v1:CreditCardData>
<v1:Payment>
<v1:ChargeTotal>15</v1:ChargeTotal>
<v1:Currency>978</v1:Currency>
</v1:Payment>
<v1:TransactionDetails>
<v1:OrderId>A-504a5ebf-6424-41af-bfd1-8f9eaca23378</v1:OrderId>
<v1:TDate>1677686964</v1:TDate>
<v1:TransactionOrigin>ECI</v1:TransactionOrigin>
</v1:TransactionDetails>
<ipgapi:IPGApiOrderResponse>
<ipgapi:ApprovalCode>Y:309372:4484275011:YYYM:418881</ipgapi:ApprovalCode>
<ipgapi:AVSResponse>YYY</ipgapi:AVSResponse>
<ipgapi:Brand>VISA</ipgapi:Brand>
<ipgapi:OrderId>A-504a5ebf-6424-41af-bfd1-8f9eaca23378</ipgapi:OrderId>
<ipgapi:IpgTransactionId>84484275011</ipgapi:IpgTransactionId>
<ipgapi:PayerSecurityLevel>1</ipgapi:PayerSecurityLevel>
<ipgapi:PaymentType>CREDITCARD</ipgapi:PaymentType>
<ipgapi:ProcessorApprovalCode>309372</ipgapi:ProcessorApprovalCode>
<ipgapi:ProcessorCCVResponse>M</ipgapi:ProcessorCCVResponse>
<ipgapi:ReferencedTDate>1677686964</ipgapi:ReferencedTDate>
<ipgapi:SchemeTransactionId>234567891234560</ipgapi:SchemeTransactionId>
<ipgapi:TDate>1677686964</ipgapi:TDate>
<ipgapi:TDateFormatted>2023.03.01 17:09:24 (CET)</ipgapi:TDateFormatted>
<ipgapi:TerminalID>80000012</ipgapi:TerminalID>
</ipgapi:IPGApiOrderResponse>
<a1:TraceNumber>418881</a1:TraceNumber>
<a1:Brand>VISA</a1:Brand>
<a1:TransactionType>SALE</a1:TransactionType>
<a1:TransactionState>CAPTURED</a1:TransactionState>
<a1:UserID>1</a1:UserID>
<a1:SubmissionComponent>API</a1:SubmissionComponent>
</a1:TransactionValues>
</ipgapi:IPGApiActionResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

If your Store is activated for the Fraud Detect product, you will find the score value in the element
FraudScore as shows an example below:

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<ipgapi:IPGApiActionResponse xmlns:ipgapi="http://ipg-
online.com/ipgapi/schemas/ipgapi" xmlns:a1="http://ipg-
online.com/ipgapi/schemas/a1" xmlns:v1="http://ipg-online.com/ipgapi/schemas/v1">
<ipgapi:successfully>true</ipgapi:successfully>
<ipgapi:OrderId>VT-6d3c8793-f5cb-44c4-99a9-1209f8681693</ipgapi:OrderId>
<v1:Billing/>
<v1:Shipping/>
<a1:TransactionValues>
<v1:CreditCardTxType>
<v1:Type>preauth</v1:Type>
</v1:CreditCardTxType>
<v1:CreditCardData>
<v1:CardNumber>4035*****4977</v1:CardNumber>
<v1:ExpMonth>12</v1:ExpMonth>
<v1:ExpYear>27</v1:ExpYear>
<v1:Brand>VISA</v1:Brand>
</v1:CreditCardData>
<v1:Payment>
<v1:ChargeTotal>10</v1:ChargeTotal>
<v1:Currency>840</v1:Currency>
</v1:Payment>
<v1:TransactionDetails>
<v1:OrderId>VT-6d3c8793-f5cb-44c4-99a9-1209f8681693</v1:OrderId>
<v1:Ip>127.0.0.1</v1:Ip>
<v1:TDate>1498202166</v1:TDate>
<v1:TransactionOrigin>ECI</v1:TransactionOrigin>
</v1:TransactionDetails>
<ipgapi:IPGApiOrderResponse>
<ipgapi:ApprovalCode>Y:471142:0096409818:PPX0:000056</ipgapi:Approva
lCode>
<ipgapi:AVSResponse>PPX</ipgapi:AVSResponse>
<ipgapi:Brand>VISA</ipgapi:Brand>
<ipgapi:FraudScore>102</ipgapi:FraudScore>
<ipgapi:OrderId>VT-6d3c8793-f5cb-44c4-99a9-
1209f8681693</ipgapi:OrderId>
<ipgapi:IpgTransactionId>8383410710</ipgapi:IpgTransactionId>
<ipgapi:PaymentType>CREDITCARD</ipgapi:PaymentType>
<ipgapi:ProcessorApprovalCode>471142</ipgapi:ProcessorApprovalCode>
<ipgapi:ProcessorCCVResponse>0</ipgapi:ProcessorCCVResponse>
<ipgapi:ReferencedTDate>1498202166</ipgapi:ReferencedTDate>
<ipgapi:TDate>1498202166</ipgapi:TDate>
<ipgapi:TDateFormatted>2017.06.23 09:16:06
(CEST)</ipgapi:TDateFormatted>
<ipgapi:TerminalID>1287451</ipgapi:TerminalID>
</ipgapi:IPGApiOrderResponse>
<a1:TraceNumber>000204</a1:TraceNumber>
<a1:Brand>VISA</a1:Brand>
<a1:TransactionType>PREAUTH</a1:TransactionType>
<a1:TransactionState>DECLINED</a1:TransactionState>
<a1:UserID>54001110</a1:UserID>
<a1:SubmissionComponent>VT</a1:SubmissionComponent>
</a1:TransactionValues>
<a1:TransactionValues>
<v1:CreditCardTxType>
<v1:Type>postauth</v1:Type>
</v1:CreditCardTxType>
<v1:CreditCardData>
<v1:Brand>VISA</v1:Brand>
</v1:CreditCardData>
<v1:Payment>
<v1:ChargeTotal>10</v1:ChargeTotal>
<v1:Currency>978</v1:Currency>
</v1:Payment>
<v1:TransactionDetails>
<v1:OrderId>VT-6d3c8793-f5cb-44c4-99a9-1209f8681693</v1:OrderId>
<v1:Ip>127.0.0.1</v1:Ip>
<v1:TDate>1498203371</v1:TDate>
<v1:TransactionOrigin>ECI</v1:TransactionOrigin>
</v1:TransactionDetails>
<ipgapi:IPGApiOrderResponse>
<ipgapi:ApprovalCode>N:-50653:Sent invalid currency or no currencies
were setup for this store.</ipgapi:ApprovalCode>
<ipgapi:Brand>VISA</ipgapi:Brand>
<ipgapi:OrderId>VT-6d3c8793-f5cb-44c4-99a9-
1209f8681693</ipgapi:OrderId>
<ipgapi:IpgTransactionId>8383410730</ipgapi:IpgTransactionId>
<ipgapi:PaymentType>CREDITCARD</ipgapi:PaymentType>
<ipgapi:ReferencedTDate>1498203371</ipgapi:ReferencedTDate>
<ipgapi:TDate>1498203371</ipgapi:TDate>
<ipgapi:TDateFormatted>2017.06.23 09:36:11
(CEST)</ipgapi:TDateFormatted>
</ipgapi:IPGApiOrderResponse>
<a1:Brand>VISA</a1:Brand>
<a1:TransactionType>POSTAUTH</a1:TransactionType>
<a1:TransactionState>DECLINED</a1:TransactionState>
<a1:SubmissionComponent>CONNECT</a1:SubmissionComponent>
</a1:TransactionValues>
<a1:TransactionValues>
<v1:CreditCardTxType>
<v1:Type>postauth</v1:Type>
</v1:CreditCardTxType>
<v1:CreditCardData/>
<v1:Payment>
<v1:ChargeTotal>10</v1:ChargeTotal>
<v1:Currency>840</v1:Currency>
</v1:Payment>
<v1:TransactionDetails>
<v1:OrderId>VT-6d3c8793-f5cb-44c4-99a9-1209f8681693</v1:OrderId>
<v1:Ip>127.0.0.1</v1:Ip>
<v1:TDate>1498203386</v1:TDate>
<v1:TransactionOrigin>ECI</v1:TransactionOrigin>
</v1:TransactionDetails>
<ipgapi:IPGApiOrderResponse>
<ipgapi:ApprovalCode>Y:576275:0096397936:PPX
:0718432585</ipgapi:ApprovalCode>
<ipgapi:AVSResponse>PPX</ipgapi:AVSResponse>
<ipgapi:OrderId>VT-6d3c8793-f5cb-44c4-99a9-
1209f8681693</ipgapi:OrderId>
<ipgapi:IpgTransactionId>8383410731</ipgapi:IpgTransactionId>
<ipgapi:PaymentType>CREDITCARD</ipgapi:PaymentType>
<ipgapi:ProcessorApprovalCode>576275</ipgapi:ProcessorApprovalCode>
<ipgapi:ProcessorReceiptNumber>2585</ipgapi:ProcessorReceiptNumber>
<ipgapi:ProcessorCCVResponse></ipgapi:ProcessorCCVResponse>
<ipgapi:ProcessorTraceNumber>071843</ipgapi:ProcessorTraceNumber>
<ipgapi:ReferencedTDate>1498203386</ipgapi:ReferencedTDate>
<ipgapi:TDate>1498203386</ipgapi:TDate>
<ipgapi:TDateFormatted>2017.06.23 09:36:26
(CEST)</ipgapi:TDateFormatted>
</ipgapi:IPGApiOrderResponse>
<a1:TransactionType>POSTAUTH</a1:TransactionType>
<a1:TransactionState>DECLINED</a1:TransactionState>
<a1:SubmissionComponent>CONNECT</a1:SubmissionComponent>
</a1:TransactionValues>
</ipgapi:IPGApiActionResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

6.3 Inquiry Transaction

The action InquiryTransaction allows you to get details about a previously processed transaction. You
therefore need to either submit the merchantTransactionId if you have assigned one or alternatively
the ipgTransactionId:

<soapenv:Envelope
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ipg="http://ipg-online.com/ipgapi/schemas/ipgapi"
xmlns:a1="http://ipg-online.com/ipgapi/schemas/a1"
xmlns:v1="http://ipg-online.com/ipgapi/schemas/v1">
<soapenv:Header/>
<soapenv:Body>
<ipg:IPGApiActionRequest>
<a1:Action>
<a1:InquiryTransaction>

<a1:StoreId>12072591</a1:StoreId>

<a1:OrderId>C-38fd1bcd-1d67-4248-b9d5-d30376d92163</a1:OrderId>
<a1:TDate>1453814407</a1:TDate>
</a1:InquiryTransaction>
</a1:Action>
</ipg:IPGApiActionRequest>
</soapenv:Body>
</soapenv:Envelope>

The response contains the same elements as in the Inquiry Order example above.

6.4 Get Last Orders

This action provides a query interface for information on the latest orders that have been submitted in
order to support in-app reporting.
This functionality is not enabled by default, as it requires additional configuration. Please contact your
local support team for more information. Please do not use this functionality to regularly request the
result of transactions you have processed but store the API transaction response instead.

6.4.1 Latest orders of a Store

This query returns “the last n orders of the given store”.

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

6.4.2 Latest orders of a Store within a given date range

This query returns “the last n orders of the given store within the given date-range".
It could also be used for pagination.
Both dates DateFrom and DateTo are to be specified, in the form of xs:dateTime

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

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<ns5:IPGApiActionRequest xmlns:ns5="http://ipg-
online.com/ipgapi/schemas/ipgapi" xmlns:ns2="http://ipg-
online.com/ipgapi/schemas/v1" xmlns:ns3="http://ipg-online.com/ipgapi/schemas/a1">
<ns3:Action>
<ns3:GetLastOrders>
<ns3:Count>5</ns3:Count>
<ns3:DateFrom>2014-04-05T10:23:37.143+02:00</ns3:DateFrom>
<ns3:DateTo>2014-05-05T10:23:37.143+02:00</ns3:DateTo>
</ns3:GetLastOrders>
</ns3:Action>
</ns5:IPGApiActionRequest>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
6.4.3 All orders of a Store after a given Order ID
This interface is intended to support pagination of large result-sets. It returns "The last n orders of the
given store after a given order (by orderId)"

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

6.4.4 Response
All query methods return the same structure as a result.

• The success-status is returned by <ipgapi:successfully>true</ipgapi:successfully>

• <ipgapi:ResultInfo>/ <a1:MoreResultsAvailable>true</a1:MoreResultsAvailable>
tells if there are more results available.
o The service is stateless, therefore subsequent queries for pagination have to use
either…
o GetLastOrders(storeID, count, dateFrom, dateTo) w/ dateTo set to the last order's
order_date of the previous resultset OR
o GetLastOrders(storeID, count, orderId) w/ orderId set to the last order of the previous
resultset
• List of orders <ipgapi:OrderValues>, consisting of
o OrderId – the orders’ unique id
o <a1:TransactionValues> transactions
o <v1:Basket> the basket
▪ with basket-items <v1:Item>
▪ and each item with item-options <v1:Option>

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

xmlns:ipgapi="http://ipg-online.com/ipgapi/schemas/ipgapi" xmlns:a1="http://ipg-
online.com/ipgapi/schemas/a1" xmlns:v1="http://ipg-online.com/ipgapi/schemas/v1">
<ipgapi:successfully>true</ipgapi:successfully>
<ipgapi:ResultInfo>
<a1:MoreResultsAvailable>true</a1:MoreResultsAvailable>
</ipgapi:ResultInfo>
<ipgapi:OrderValues>
<a1:OrderId>A-00ddff18-b210-428b-804f-150b2567dbc9</a1:OrderId>
<a1:OrderDate>2015-09-30T13:43:44.000+02:00</a1:OrderDate>
<v1:Basket>
<v1:Item>
<v1:ID>d160c63e-7e9e-4a4a-bd5e-ae50a9133bf7</v1:ID>
<v1:Description>katharistiko</v1:Description>
<v1:ChargeTotal>25</v1:ChargeTotal>
<v1:Quantity>1</v1:Quantity>
</v1:Item>
</v1:Basket>
<v1:Billing/>
<v1:Shipping/>
<a1:TransactionValues>
<v1:CreditCardTxType>
<v1:Type>sale</v1:Type>
</v1:CreditCardTxType>
<v1:CreditCardData>
<v1:CardNumber>5185****9001</v1:CardNumber>
<v1:ExpMonth>04</v1:ExpMonth>
<v1:ExpYear>17</v1:ExpYear>
<v1:Brand>MASTERCARD</v1:Brand>
</v1:CreditCardData>
<v1:Payment>
<v1:ChargeTotal>25</v1:ChargeTotal>
<v1:Currency>978</v1:Currency>
</v1:Payment>
<v1:TransactionDetails>
<v1:OrderId>A-00ddff18-b210-428b-804f-150b2567dbc9</v1:OrderId>
<v1:TDate>1443620624</v1:TDate>
<v1:TransactionOrigin>RETAIL</v1:TransactionOrigin>
</v1:TransactionDetails>
<ipgapi:IPGApiOrderResponse>
<ipgapi:ApprovalCode>Y:024309:0782287817:PPXX:796023</ipgapi:ApprovalCode>
<ipgapi:AVSResponse>PPX</ipgapi:AVSResponse>
<ipgapi:Brand>MASTERCARD</ipgapi:Brand>
<ipgapi:Country>GRC</ipgapi:Country>
<ipgapi:OrderId>A-00ddff18-b210-428b-804f-
150b2567dbc9</ipgapi:OrderId>
<ipgapi:PayerSecurityLevel>N</ipgapi:PayerSecurityLevel>
<ipgapi:PaymentType>CREDITCARD</ipgapi:PaymentType>
<ipgapi:ProcessorApprovalCode>024309</ipgapi:ProcessorApprovalCode>
<ipgapi:ProcessorCCVResponse>X</ipgapi:ProcessorCCVResponse>
<ipgapi:TDate>1443620624</ipgapi:TDate>
<ipgapi:TDateFormatted>2015.09.30 15:43:44
(CEST)</ipgapi:TDateFormatted>
<ipgapi:TerminalID>90000001</ipgapi:TerminalID>
</ipgapi:IPGApiOrderResponse>
<a1:TraceNumber>796023</a1:TraceNumber>
<a1:TransactionState>SETTLED</a1:TransactionState>
<a1:UserID>1</a1:UserID>
<a1:SubmissionComponent>API</a1:SubmissionComponent>
</a1:TransactionValues>
</ipgapi:OrderValues>
<ipgapi:OrderValues>
<a1:OrderId>A-85a682a4-8481-48a3-b94c-a612fdc3a528</a1:OrderId>
<a1:OrderDate>2015-09-29T15:45:46.000+02:00</a1:OrderDate>
<v1:Basket>
<v1:Item>
<v1:ID>5105971d-b5fd-482b-be35-cb8a6569f7c7</v1:ID>
<v1:Description>efimerida</v1:Description>
<v1:ChargeTotal>12.15</v1:ChargeTotal>
<v1:Quantity>1</v1:Quantity>
</v1:Item>
</v1:Basket>
<v1:Billing/>
<v1:Shipping/>
<a1:TransactionValues>
<v1:CreditCardTxType>
<v1:Type>sale</v1:Type>
</v1:CreditCardTxType>
<v1:CreditCardData>
<v1:CardNumber>4060.....8009</v1:CardNumber>
<v1:ExpMonth>02</v1:ExpMonth>
<v1:ExpYear>17</v1:ExpYear>
<v1:Brand>VISA</v1:Brand>
</v1:CreditCardData>
<v1:Payment>
<v1:ChargeTotal>12.15</v1:ChargeTotal>
<v1:Currency>978</v1:Currency>
</v1:Payment>
<v1:TransactionDetails>
<v1:OrderId>A-85a682a4-8481-48a3-b94c-a612fdc3a528</v1:OrderId>
<v1:TDate>1443541546</v1:TDate>
<v1:TransactionOrigin>RETAIL</v1:TransactionOrigin>
</v1:TransactionDetails>
<ipgapi:IPGApiOrderResponse>
<ipgapi:ApprovalCode>Y:201846:0782126690:PPXX:796005</ipgapi:ApprovalCode>
<ipgapi:AVSResponse>PPX</ipgapi:AVSResponse>
<ipgapi:Brand>VISA</ipgapi:Brand>
<ipgapi:Country>GRC</ipgapi:Country>
<ipgapi:OrderId>A-85a682a4-8481-48a3-b94c-
a612fdc3a528</ipgapi:OrderId>
<ipgapi:PayerSecurityLevel>V</ipgapi:PayerSecurityLevel>
<ipgapi:PaymentType>CREDITCARD</ipgapi:PaymentType>
<ipgapi:ProcessorApprovalCode>201846</ipgapi:ProcessorApprovalCode>
<ipgapi:ProcessorCCVResponse>X</ipgapi:ProcessorCCVResponse>
<ipgapi:TDate>1443541546</ipgapi:TDate>
<ipgapi:TDateFormatted>2015.09.29 17:45:46
(CEST)</ipgapi:TDateFormatted>
<ipgapi:TerminalID>90000001</ipgapi:TerminalID>
</ipgapi:IPGApiOrderResponse>
<a1:TraceNumber>796005</a1:TraceNumber>
<a1:TransactionState>SETTLED</a1:TransactionState>
<a1:UserID>1</a1:UserID>
<a1:SubmissionComponent>API</a1:SubmissionComponent>
</a1:TransactionValues>
</ipgapi:OrderValues>
<ipgapi:OrderValues>
<a1:OrderId>A-787829af-2baa-408e-881e-3f43f584496e</a1:OrderId>
<a1:OrderDate>2015-09-29T13:58:15.000+02:00</a1:OrderDate>
<v1:Basket>
<v1:Item>
<v1:ID>bd5c1138-e734-4379-89a7-075c1ac31bd0</v1:ID>
<v1:Description>taigara</v1:Description>
<v1:ChargeTotal>3.5</v1:ChargeTotal>
<v1:Quantity>1</v1:Quantity>
</v1:Item>
</v1:Basket>
<v1:Billing/>
<v1:Shipping/>
<a1:TransactionValues>
<v1:CreditCardTxType>
<v1:Type>sale</v1:Type>
</v1:CreditCardTxType>
<v1:CreditCardData>
<v1:CardNumber>5167.....7382</v1:CardNumber>
<v1:ExpMonth>07</v1:ExpMonth>
<v1:ExpYear>18</v1:ExpYear>
<v1:Brand>MASTERCARD</v1:Brand>
</v1:CreditCardData>
<v1:Payment>
<v1:ChargeTotal>3.5</v1:ChargeTotal>
<v1:Currency>978</v1:Currency>
</v1:Payment>
<v1:TransactionDetails>
<v1:OrderId>A-787829af-2baa-408e-881e-3f43f584496e</v1:OrderId>
<v1:TDate>1443535095</v1:TDate>
<v1:TransactionOrigin>RETAIL</v1:TransactionOrigin>
</v1:TransactionDetails>
<ipgapi:IPGApiOrderResponse>
<ipgapi:ApprovalCode>Y:328188:0782108096:PPXX:795995</ipgapi:ApprovalCode>
<ipgapi:AVSResponse>PPX</ipgapi:AVSResponse>
<ipgapi:Brand>MASTERCARD</ipgapi:Brand>
<ipgapi:Country>GRC</ipgapi:Country>
<ipgapi:OrderId>A-787829af-2baa-408e-881e-
3f43f584496e</ipgapi:OrderId>
<ipgapi:PayerSecurityLevel>N</ipgapi:PayerSecurityLevel>
<ipgapi:PaymentType>CREDITCARD</ipgapi:PaymentType>
<ipgapi:ProcessorApprovalCode>328188</ipgapi:ProcessorApprovalCode>
<ipgapi:ProcessorCCVResponse>X</ipgapi:ProcessorCCVResponse>
<ipgapi:TDate>1443535095</ipgapi:TDate>
<ipgapi:TDateFormatted>2015.09.29 15:58:15
(CEST)</ipgapi:TDateFormatted>
<ipgapi:TerminalID>90000001</ipgapi:TerminalID>
</ipgapi:IPGApiOrderResponse>
<a1:TraceNumber>795995</a1:TraceNumber>
<a1:TransactionState>SETTLED</a1:TransactionState>
<a1:UserID>1</a1:UserID>
<a1:SubmissionComponent>API</a1:SubmissionComponent>
</a1:TransactionValues>
</ipgapi:OrderValues>
<ipgapi:OrderValues>
<a1:OrderId>A-0606cb2c-d947-4557-855e-98722fc100f8</a1:OrderId>
<a1:OrderDate>2015-09-28T21:34:01.000+02:00</a1:OrderDate>
<v1:Basket>
<v1:Item>
<v1:ID>a3686a1e-e2dd-4f2b-aab0-2131af33c141</v1:ID>
<v1:Description>κρασι</v1:Description>
<v1:ChargeTotal>12.8</v1:ChargeTotal>
<v1:Quantity>1</v1:Quantity>
</v1:Item>
</v1:Basket>
<v1:Billing/>
<v1:Shipping/>
<a1:TransactionValues>
<v1:CreditCardTxType>
<v1:Type>sale</v1:Type>
</v1:CreditCardTxType>
<v1:CreditCardData>
<v1:CardNumber>5185.....9001</v1:CardNumber>
<v1:ExpMonth>04</v1:ExpMonth>
<v1:ExpYear>17</v1:ExpYear>
<v1:Brand>MASTERCARD</v1:Brand>
</v1:CreditCardData>
<v1:Payment>
<v1:ChargeTotal>12.8</v1:ChargeTotal>
<v1:Currency>978</v1:Currency>
</v1:Payment>
<v1:TransactionDetails>
<v1:OrderId>A-0606cb2c-d947-4557-855e-98722fc100f8</v1:OrderId>
<v1:TDate>1443476041</v1:TDate>
<v1:TransactionOrigin>RETAIL</v1:TransactionOrigin>
</v1:TransactionDetails>
<ipgapi:IPGApiOrderResponse>
<ipgapi:ApprovalCode>Y:021474:0782015139:PPXX:795975</ipgapi:ApprovalCode>
<ipgapi:AVSResponse>PPX</ipgapi:AVSResponse>
<ipgapi:Brand>MASTERCARD</ipgapi:Brand>
<ipgapi:Country>GRC</ipgapi:Country>
<ipgapi:OrderId>A-0606cb2c-d947-4557-855e-
98722fc100f8</ipgapi:OrderId>
<ipgapi:PayerSecurityLevel>N</ipgapi:PayerSecurityLevel>

6.5 Get Last Transactions

This action provides a query interface for information on the latest transactions that have been
submitted in order to support in-app reporting.
This functionality is not enabled by default, as it requires additional configuration. Please contact your
local support team for more information.
Please do not use this functionality to regularly request the result of transactions you have processed
but store the API transaction response instead.
6.5.1 Latest transactions of a Store
This query returns “the last n transactions of the given store”.

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

6.5.2 All transactions of a Store after a given Transaction ID

This interface is intended to support pagination of large result-sets. It returns "The last n transactions
of the given store before a given transaction (by transactionId {orderId, TDate})"

A transactionID consists of the tuple

• OrderId the ID of the transactions’ order
• TDate the date of the transaction

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

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<ns5:IPGApiActionRequest xmlns:ns5="http://ipg-
online.com/ipgapi/schemas/ipgapi" xmlns:ns2="http://ipg-
online.com/ipgapi/schemas/a1" xmlns:ns3="http://ipg-online.com/ipgapi/schemas/v1">
<ns2:Action>
<ns2:GetLastTransactions>
<ns2:count>2</ns2:count>
<ns2:OrderId>A-eb65437a-c538-4cdd-82b3-
d316ae160c22</ns2:OrderId>
<ns2:TDate>1407373211</ns2:TDate>
</ns2:GetLastTransactions>
</ns2:Action>
</ns5:IPGApiActionRequest>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

6.5.3 Response
All query methods return the same structure as a result.

• The success-status is returned by <ipgapi:successfully>true</ipgapi:successfully>

• List of transactions <a1:TransactionValues>

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

<ipgapi:ApprovalCode>Y:416502:0014750513:PPXM:4625106408</ipgapi:ApprovalCode>
<ipgapi:AVSResponse>PPX</ipgapi:AVSResponse>
<ipgapi:Brand>VISA</ipgapi:Brand>
<ipgapi:OrderId>A-52421c39-69c4-4b2d-959d-
9fdcd3a9420a</ipgapi:OrderId>
<ipgapi:PaymentType>CREDITCARD</ipgapi:PaymentType>
<ipgapi:ProcessorApprovalCode>416502</ipgapi:ProcessorApprovalCode>
<ipgapi:ProcessorReceiptNumber>6408</ipgapi:ProcessorReceiptNumber>
<ipgapi:ProcessorCCVResponse>M</ipgapi:ProcessorCCVResponse>
<ipgapi:ProcessorTraceNumber>462510</ipgapi:ProcessorTraceNumber>
<ipgapi:ReferencedTDate>1407373209</ipgapi:ReferencedTDate>
<ipgapi:TDate>1407373209</ipgapi:TDate>
<ipgapi:TDateFormatted>2014.08.07 03:00:09
(CEST)</ipgapi:TDateFormatted>
<ipgapi:TerminalID>54000666</ipgapi:TerminalID>
</ipgapi:IPGApiOrderResponse>
<a1:TransactionState>CAPTURED</a1:TransactionState>
<a1:UserID>1</a1:UserID>
<a1:SubmissionComponent>BUS</a1:SubmissionComponent>
</a1:TransactionValues>
</ipgapi:IPGApiActionResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

6.6 Recurring Payments (Scheduler)

The action RecurringPayment allows you to install, modify or cancel periodic payments in a way that
subsequent transactions will automatically be triggered by the Gateway.

For every recurring transaction, the gateway can send a server-to-server transaction notification to a
defined Notification URL. Please contact your local support team to get your URL registered for these
notifications.
6.6.1 Install
The following example shows how to install a monthly credit card payment with 12 executions
(InstallmentCount) in 2011 starting on 15 January 2011.
Please note that the RecurringStartDate will be interpreted based on the timezone Europe/Berlin.

<ns4:IPGApiActionRequest
xmlns:ns4="http://ipg-online.com/ipgapi/schemas/ipgapi"
xmlns:ns2="http://ipg-online.com/ipgapi/schemas/a1"
xmlns:ns3="http://ipg-online.com/ipgapi/schemas/v1">
<ns2:Action>
<ns2:RecurringPayment>
<ns2:Function>install</ns2:Function>
<ns2:RecurringPaymentInformation>
<ns2:RecurringStartDate>20110115</ns2:RecurringStartDate>
<ns2:InstallmentCount>12</ns2:InstallmentCount>
<ns2:InstallmentFrequency>1</ns2:InstallmentFrequency>
<ns2:InstallmentPeriod>month</ns2:InstallmentPeriod>
</ns2:RecurringPaymentInformation>
<ns2:CreditCardData>
<ns3:CardNumber>4035……4977</ns3:CardNumber>
<ns3:ExpMonth>12</ns3:ExpMonth>
<ns3:ExpYear>27</ns3:ExpYear>
<ns3:CardCodeValue>XXX</ns3:CardCodeValue>
</ns2:CreditCardData>
<ns3:Payment>
<ns3:ChargeTotal>1</ns3:ChargeTotal>
<ns3:Currency>978</ns3:Currency>
</ns3:Payment>
</ns2:RecurringPayment>
</ns2:Action>
</ns4:IPGApiActionRequest>

If you set the RecurringStartDate to the actual date, the first payment will immediately be initiated. In
this case, the payment data will only be stored for future payments if this first payment was
succesful/approved.
A start date in the past is not allowed.
The default value for TransactionOrigin is ‘ECI’. If you want to change this value, you can submit a
different TransactionOrigin tag in the RecurringPayment tag.

6.6.2 Modify

Modifications of an existing Recurring Payment can be initiated using the Order ID:

You only need to include the elements that need to be changed. If you change the credit card number,
it is also required to include the expiry date, otherwise you can change the expiry date without
specifying the credit card number. If you want to change the amount, you also need to include the
currency.

It is possible to change the payment method, e. g. from Credit Card to German Direct Debit.

Please note, that due to PSD2 regulation it is not allowed to increase transaction amount for a valid
subscription without cardholder’s consent achieved through Strong Customer Authentication (SCA).
In case modified transaction amount is higher than in the initial recurring payment, it is highly
recommended to cancel the schedule and initiate a new request including SCA to avoid declines by
the issuer which would eventually terminate your schedule.

6.6.3 Cancel
To cancel a Recurring Payment, you also use the Order ID:

6.6.4 Test Recurring Payments in test environment

The test system allows you to manually initiate a scheduled payment to test this functionality. This
function will not work in live mode.
<ns4:IPGApiActionRequest
xmlns:ns4="http://ipg-online.com/ipgapi/schemas/ipgapi"
xmlns:ns2="http://ipg-online.com/ipgapi/schemas/a1"
xmlns:ns3="http://ipg-online.com/ipgapi/schemas/v1">
<ns2:Action>
<ns2:RecurringPayment>
<ns2:Function>perform only in test environment</ns2:Function>
<ns2:OrderId>A-eab002b9-5889-9cc9-5bc06b8eaa61</ns2:OrderId>
</ns2:RecurringPayment>
</ns2:Action>
</ns4:IPGApiActionRequest>

6.6.5 Response
The response for a successful instalment, modification or cancellation contains the value true for the
parameter <ns4:successfully>:

6.7 External transaction status

Some payment endpoints do not send the final result of a payment transaction within their response.
In such cases the Gateway returns an approval code that starts with a question mark (?:…).The action
GetExternalTransactionState allows you to request updates on the state of such transactions. You can
use OrderID + TDate, MerchantTransactionId or IpgTransactionId to reference to a transaction.

6.8 Trigger email notifications

The action SendEMailNotification triggers an email notification for a given transaction. The email will
be created with the email template that has been configured for your Store.

See the User Guide Virtual Terminal for more information on transaction notifications by email.

<ns5:IPGApiActionRequest
xmlns:ns5=http://ipg-online.com/ipgapi/schemas/ipgapi
xmlns:ns2="http://ipg-online.com/ipgapi/schemas/a1"
xmlns:ns3="http://ipg-online.com/ipgapi/schemas/v1">
<ns2:Action>
<ns2:SendEMailNotification>
<ns2:OrderId>123456</ns2:OrderId>
<ns2:TDate>1250599046</ns2:TDate>
</ns2:SendEMailNotification>
</ns2:Action>
</ns5:IPGApiActionRequest>

If the optional parameter Email is not set, the email address of the customer stored with the transaction
will be used.
6.9 Card Information Inquiry
The function InquiryCardInformation allows you to check the brand and function of a card by
submitting the card number.

Request:

…<a1:InquiryCardInformation>
<ns2:StoreId>123456789</ns2:StoreId>
<ns2:CardNumber>5413…0002</ns2:CardNumber>
</a1:InquiryCardInformation>…

Response:

…<ipgapi:CardInformation>
<ns2:Brand>MASTERCARD</ns2:Brand>
<ns2:CardFunction>credit</ns2:CardFunction>
<ns2:Country>USA</ns2:Country>
<ns2:Corporate>CORPORATE</ns2:Corporate>
</ipgapi:CardInformation>
</ipgapi:IPGApiActionResponse>

6.10 Basket Information and Product Catalogue

6.10.1 Basket information in transaction messages
The following example shows how you can use the basket parameters to document in the transaction
what has been sold.

<ns5:IPGApiOrderRequest
xmlns:ns5="http://ipg-online.com/ipgapi/schemas/ipgapi"
xmlns:ns2="http://ipg-online.com/ipgapi/schemas/v1"
xmlns:ns3="http://ipg-online.com/ipgapi/schemas/a1">
<ns2:Transaction>
<ns2:CreditCardTxType>
<ns2:Type>sale</ns2:Type>
</ns2:CreditCardTxType>
<ns2:CreditCardData>
<ns2:CardNumber>4035..…4977</ns2:CardNumber>
<ns2:ExpMonth>12</ns2:ExpMonth>
<ns2:ExpYear>24</ns2:ExpYear>
</ns2:CreditCardData>
<ns2:Payment>
<ns2:ChargeTotal>1</ns2:ChargeTotal>
<ns2:Currency>EUR</ns2:Currency>
</ns2:Payment>
<ns2:TransactionDetails>
<ns2:OrderId>68d4a595-fd58-4859-83cd-1ae13962a3ac</ns2:OrderId>
</ns2:TransactionDetails>
<ns2:Basket>
<ns2:Item>
<ns2:ID>product ID xyz</ns2:ID>
<ns2:Description>description of abc</ns2:Description>
<ns2:ChargeTotal>11</ns2:ChargeTotal>
<ns2:Currency>EUR</ns2:Currency>
<ns2:Quantity>5</ns2:Quantity>
<ns2:Option>
<ns2:Name>colour</ns2:Option>
<ns2:Choice>blue</ns2:Choice>
</ns2:Option>
<ns2:Option>
<ns2:Name>size</ns2:Option>
<ns2:Choice>large</ns2:Choice>
</ns2:Option>
</ns2:Item>
</ns2:Basket>
</ns2:Transaction>
</ns5:IPGApiOrderRequest>

6.10.2 Setting up a Product Catalogue

You can store basic information about the products you sell in the following way:

<ns5:IPGApiActionRequest
xmlns:ns5="http://ipg-online.com/ipgapi/schemas/ipgapi"
xmlns:ns2="http://ipg-online.com/ipgapi/schemas/v1"
xmlns:ns3="http://ipg-online.com/ipgapi/schemas/a1">

<ns3:Action>
<ns3:ManageProducts>
<ns3:Function>store</ns3:Function>
<ns3:Product>
<ns3:ProductID>product ID xyz</ns3:ProductID>
<ns2:ChargeTotal>2</ns2:ChargeTotal>
<ns2:Currency>EUR</ns2:Currency>
<ns3:OfferStarts>2014-12-
27T13:29:41.000+01:00</ns3:OfferStarts>
<ns3:OfferEnds>2015-09-
19T14:29:41.000+02:00</ns3:OfferEnds>
<ns2:Option>
<ns2:Name>colour</ns2:Option>
<ns2:Choice>blue</ns2:Choice>
</ns2:Option>
<ns2:Option>
<ns2:Name>size</ns2:Option>
<ns2:Choice>large</ns2:Choice>
</ns2:Option>
</ns3:Product>
</ns3:ManageProducts>
</ns3:Action>
</ns5:IPGApiActionRequest>

OfferStarts and OfferEnds are optional and can be used to restrict the visibility of the related products
in custom applications but they will not restrict the possibility of a sale. There are further optional
fields Description, OptionName and Name. Please take a look at the a1.xsd in the appendix of this
document.
The function display shows the requested product with every characteristics.

<ns5:IPGApiActionRequest
xmlns:ns5="http://ipg-online.com/ipgapi/schemas/ipgapi"
xmlns:ns2="http://ipg-online.com/ipgapi/schemas/v1"
xmlns:ns3="http://ipg-online.com/ipgapi/schemas/a1">
<ns3:Action>
<ns3:ManageProducts>
<ns3:Function>display</ns3:Function>
<ns3:Product>
<ns3:ProductID>product ID xyz</ns3:ProductID>
</ns3:Product>
</ns3:ManageProducts>
</ns3:Action>
</ns5:IPGApiActionRequest>

The function delete can be used to set the available stock of a product to zero.

<ns5:IPGApiActionRequest
xmlns:ns5="http://ipg-online.com/ipgapi/schemas/ipgapi"
xmlns:ns2="http://ipg-online.com/ipgapi/schemas/v1"
xmlns:ns3="http://ipg-online.com/ipgapi/schemas/a1">
<ns3:Action>
<ns3:ManageProducts>
<ns3:Function>delete</ns3:Function>
<ns3:Product>
<ns3:ProductID>product ID xyz</ns3:ProductID>
</ns3:Product>
</ns3:ManageProducts>
</ns3:Action>
</ns5:IPGApiActionRequest>

6.10.3 Manage Product Stock

For every product stock function, the product ID and given options need to exist in your Product
Catalogue.

After you have installed a product, you can fill the product stock with the function add.

<ns5:IPGApiActionRequest
xmlns:ns5=http://ipg-online.com/ipgapi/schemas/ipgapi
xmlns:ns2="http://ipg-online.com/ipgapi/schemas/v1"
xmlns:ns3="http://ipg-online.com/ipgapi/schemas/a1">
<ns3:Action>
<ns3:ManageProductStock>
<ns3:Function>add</ns3:Function>
<ns3:ProductStock>
<ns3:ProductID>product ID xyz</ns3:ProductID>
<ns2:Option>
<ns2:Name>colour</ns2:Option>
<ns2:Choice>blue</ns2:Choice>
</ns2:Option>
<ns2:Option>
<ns2:Name>size</ns2:Option>
<ns2:Choice>large</ns2:Choice>
</ns2:Option>
<ns3:Quantity>13</ns3:Quantity>
</ns3:ProductStock>
</ns3:ManageProductStock>
</ns3:Action>
</ns5:IPGApiActionRequest>

The function substract works in the same way, but will only change the quantity, if the difference will
not be negative. If you want to set the quantity to zero you can use the function delete described
above.

6.10.4 Sale transactions using product stock

After you have set up the product stock, you can use it to verify if there are enough items on stock for
a transaction. A succesful transaction will then substract the quantity. If the product stock contains
less than the requested quantity, the transaction will be rejected without any changes to the product
stock.

To use this function, add <ns2:ProductStock>check</ns2:ProductStock> to Basket.

<ns5:IPGApiOrderRequest
xmlns:ns5="http://ipg-online.com/ipgapi/schemas/ipgapi"
xmlns:ns2="http://ipg-online.com/ipgapi/schemas/v1"
xmlns:ns3="http://ipg-online.com/ipgapi/schemas/a1">
<ns2:Transaction>
<ns2:CreditCardTxType>
<ns2:Type>sale</ns2:Type>
</ns2:CreditCardTxType>
<ns2:CreditCardData>
<ns2:CardNumber>4035....4977</ns2:CardNumber>
<ns2:ExpMonth>12</ns2:ExpMonth>
<ns2:ExpYear>14</ns2:ExpYear>
</ns2:CreditCardData>
<ns2:Payment>
<ns2:ChargeTotal>1</ns2:ChargeTotal>
<ns2:Currency>EUR</ns2:Currency>
</ns2:Payment>
<ns2:TransactionDetails>
<ns2:OrderId>68d4a595-fd58-4859-83cd-1ae13962a3ac</ns2:OrderId>
</ns2:TransactionDetails>
<ns2:Basket>
<ns2:ProductStock>check</ns2:ProductStock>
<ns2:Item>
<ns2:ID>product ID xyz</ns2:ID>
<ns2:Description>description of abc</ns2:Description>
<ns2:ChargeTotal>11</ns2:ChargeTotal>
<ns2:Currency>EUR</ns2:Currency>
<ns2:Quantity>5</ns2:Quantity>
<ns2:Option>
<ns2:Name>colour</ns2:Option>
<ns2:Choice>blue</ns2:Choice>
</ns2:Option>
<ns2:Option>
<ns2:Name>size</ns2:Option>
<ns2:Choice>large</ns2:Choice>
</ns2:Option>
</ns2:Item>
</ns2:Basket>
</ns2:Transaction>
</ns5:IPGApiOrderRequest>

7 Data Vault
With the Data Vault product option you can store sensitive cardholder data in an encrypted
database in Fiserv’s data centre to use it for subsequent transactions without the need to
store this data within your own systems.
If you have ordered this product option, the Web Service API offers you the following functions.

See further possibilities with the Data Vault product in the Integration Guide for the Connect solution.

7.1 Token Type Options

The type of token can be defined with the optional element TokenType, which can have 2 possible
values : “ONETIME” or “MULTIPAY”.

The default value (when no token type gets submitted) is MULTIPAY.

One time token (that are only valid for a specific time span) is an option for merchants, which work with
tokens for every transaction, no matter if the consumer registers or prefers to check out as a “guest”.
The following XML document represents an example of a request with included element
TokenType = MULTIPAY:

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

<ns4:IPGApiOrderRequest
xmlns:ns4="http://ipg-online.com/ipgapi/schemas/ipgapi" xmlns:ns2="http://ipg-
online.com/ipgapi/schemas/v1"
xmlns:ns3="http://ipg-online.com/ipgapi/schemas/a1">
<ns2:Transaction>
<ns2:CreditCardTxType>
<ns2:StoreId>330995001</ns2:StoreId>
<ns2:Type>sale</ns2:Type>
</ns2:CreditCardTxType>
<ns2:CreditCardData>
<ns2:CardNumber>4035*****4977</ns2:CardNumber>
<ns2:ExpMonth>12</ns2:ExpMonth>
<ns2:ExpYear>28</ns2:ExpYear>
<ns2:CardCodeValue>XXX</ns2:CardCodeValue>
</ns2:CreditCardData>
<ns2:Payment>
<ns2:ChargeTotal>27.2</ns2:ChargeTotal>
<ns2:Currency>INR</ns2:Currency>
<ns2:TokenType>MULTIPAY</ns2:TokenType>
</ns2:Payment>
<ns2:TransactionDetails>
<ns2:TransactionOrigin>ECI</ns2:TransactionOrigin>
</ns2:TransactionDetails>
</ns2:Transaction>
</ns4:IPGApiOrderRequest>

The following XML document represents an example of a request with included element
TokenType = ONETIME:

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

<ns4:IPGApiOrderRequest
xmlns:ns4="http://ipg-online.com/ipgapi/schemas/ipgapi"
xmlns:ns2="http://ipg-online.com/ipgapi/schemas/v1"
xmlns:ns3="http://ipg-online.com/ipgapi/schemas/a1">
<ns2:Transaction>
<ns2:CreditCardTxType>
<ns2:StoreId>330995001</ns2:StoreId>
<ns2:Type>sale</ns2:Type>
</ns2:CreditCardTxType>
<ns2:CreditCardData>
<ns2:CardNumber>4035*****4977</ns2:CardNumber>
<ns2:ExpMonth>12</ns2:ExpMonth>
<ns2:ExpYear>28</ns2:ExpYear>
<ns2:CardCodeValue>XXX</ns2:CardCodeValue>
</ns2:CreditCardData>
<ns2:Payment>
<ns2:ChargeTotal>27.2</ns2:ChargeTotal>
<ns2:Currency>INR</ns2:Currency>
<ns2:TokenType>ONETIME</ns2:TokenType>
</ns2:Payment>
<ns2:TransactionDetails>
<ns2:TransactionOrigin>ECI</ns2:TransactionOrigin>
</ns2:TransactionDetails>
</ns2:Transaction>
</ns4:IPGApiOrderRequest>

For cases, where you do not wish to define the token yourselves, but want it to be generated and
returned, the element AssignToken should be set to ‘true’ and no HostedDataId needs to be sent in
the request.

The following XML document represents an example of a request for getting the token generated by
Gateway, with the element AssignToken = true:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Header/>
<soap:Body>
<ns5:IPGApiOrderRequest
xmlns:ns5="http://ipg-online.com/ipgapi/schemas/ipgapi"
xmlns:ns2="http://ipg-online.com/ipgapi/schemas/v1"
xmlns:ns3="http://ipg-online.com/ipgapi/schemas/a1">
<ns2:Transaction>
<ns2:CreditCardTxType>
<ns2:StoreId>2209905999</ns2:StoreId>
<ns2:Type>sale</ns2:Type>
</ns2:CreditCardTxType>
<ns2:CreditCardData>
<ns2:CardNumber>4257******0111</ns2:CardNumber>
<ns2:ExpMonth>12</ns2:ExpMonth>
<ns2:ExpYear>27</ns2:ExpYear>
<ns2:CardCodeValue>XXX</ns2:CardCodeValue>
</ns2:CreditCardData>
<ns2:Payment>
<ns2:ChargeTotal>700.00</ns2:ChargeTotal>
<ns2:Currency>GBP</ns2:Currency>
<ns2:AssignToken>true</ns2:AssignToken>
</ns2:Payment>
<ns2:TransactionDetails>
<ns2:TransactionOrigin>MOTO</ns2:TransactionOrigin>
</ns2:TransactionDetails>
<ns2:Billing>
<ns2:Address1>Flat 412a 123 London Rd</ns2:Address1>
<ns2:City>London</ns2:City>
<ns2:Zip>CH488AQ</ns2:Zip>
<ns2:Country>GB</ns2:Country>
</ns2:Billing>
</ns2:Transaction>
</ns5:IPGApiOrderRequest>
</soap:Body>
</soap:Envelope>

The following XML document represents an example of a response with the token generated in the
element HostedDataID:

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<ipgapi:IPGApiOrderResponse
xmlns:ipgapi="http://ipg-online.com/ipgapi/schemas/ipgapi"
xmlns:a1="http://ipg-online.com/ipgapi/schemas/a1"
xmlns:v1="http://ipg-online.com/ipgapi/schemas/v1">
<ipgapi:ApprovalCode>Y:609287:8383366115:PPXP:006295</ipgapi:ApprovalCode>
<ipgapi:AVSResponse>PPX</ipgapi:AVSResponse>
<ipgapi:Brand>VISA</ipgapi:Brand>
<ipgapi:Country>ESP</ipgapi:Country>
<ipgapi:CommercialServiceProvider>CARDNET</ipgapi:CommercialServiceProvide
r>
<ipgapi:OrderId>A-0dd18b32-bc19-40ea-8173-80537093b18f</ipgapi:OrderId>
<ipgapi:IpgTransactionId>8383366115</ipgapi:IpgTransactionId>
<ipgapi:PaymentType>CREDITCARD</ipgapi:PaymentType>
<ipgapi:ProcessorApprovalCode>609287</ipgapi:ProcessorApprovalCode>
<ipgapi:ProcessorCCVResponse>P</ipgapi:ProcessorCCVResponse>
<ipgapi:ProcessorReferenceNumber>702514006295</ipgapi:ProcessorReferenceNu
mber>
<ipgapi:ProcessorResponseCode>00</ipgapi:ProcessorResponseCode>
<ipgapi:ProcessorResponseMessage>Function performed error-
free</ipgapi:ProcessorResponseMessage>
<ipgapi:TDate>1485354544</ipgapi:TDate>
<ipgapi:TDateFormatted>2017.01.25 15:29:04 (MEZ)</ipgapi:TDateFormatted>
<ipgapi:TerminalID>IPGCNP00</ipgapi:TerminalID>
<ipgapi:TransactionResult>APPROVED</ipgapi:TransactionResult>
<ipgapi:TransactionTime>1485354544</ipgapi:TransactionTime>
<ipgapi:HostedData>
<ipgapi:HostedDataID>7F98D913-85CF-4B88-B994-
B59CB0D4AEB2</ipgapi:HostedDataID>
</ipgapi:HostedData>
</ipgapi:IPGApiOrderResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

7.2 Store or update payment information when performing a transaction

Additionally send the parameter HostedDataID together with the transaction data as a unique
identification for the payment information in this transaction. Depending on the payment type, credit
card number and expiry date or account number and bank code will be stored under this ID. In cases
where the submitted ‚HostedDataID’ already exists for your store, the stored payment information
will be updated.

<ipgapi:IPGApiOrderRequest
xmlns:v1="http://ipg-online.com/ipgapi/schemas/v1"
xmlns:ipgapi="http://ipg-online.com/ipgapi/schemas/ipgapi">
<v1:Transaction>
<v1:CreditCardTxType>
<v1:Type>sale</v1:Type>
</v1:CreditCardTxType>
<v1:CreditCardData>
<v1:CardNumber>4111********1111</v1:CardNumber>
<v1:ExpMonth>12</v1:ExpMonth>
<v1:ExpYear>27</v1:ExpYear>
</v1:CreditCardData>
<v1:Payment>
<v1:HostedDataID>HDID customer1234567</v1:HostedDataID>
<v1:ChargeTotal>19.00</v1:ChargeTotal>
<v1:Currency>978</v1:Currency>
</v1:Payment>
</v1:Transaction>
</ipgapi:IPGApiOrderRequest>

The record is only being stored if the authorisation of the payment transaction is successful and your
Store has been setup for this service.

If you want to assign multiple IDs to the same payment information (e.g. because your customer has
several contracts or accounts with you where they want to used the same card for payment), you can
include the parameter HostedDataID multiple times with different values.

7.3 Store payment information from an approved transaction

Payment information can also be stored referring to a previously approved transaction

<ns4:IPGApiActionRequest
xmlns:ns4="http://ipg-online.com/ipgapi/schemas/ipgapi"
xmlns:ns2="http://ipg-online.com/ipgapi/schemas/a1"
xmlns:ns3="http://ipg-online.com/ipgapi/schemas/v1">
<ns2:Action>
<ns2:StoreHostedData>
<ns2:DataStorageItem>
<ns2:OrderId>1234567890</ns2:OrderId>
<ns2:HostedDataID>4e72021b-d155-4062-872a-30228c0fe023
</ns2:HostedDataID>
</ns2:DataStorageItem>
</ns2:StoreHostedData>
</ns2:Action>
</ns4:IPGApiActionRequest>
This action stores the payment information of the transaction with the order id 1234567890. The
transaction must be an approved transaction, otherwise this action fails.

7.4 Initiate payment transactions using stored data

If you stored cardholder information using the Data Vault product, you can perform transactions using
the ‚HostedDataID’ without the need to pass the credit card or bank account data again.

Please note that it is not allowed to store the card code (in most cases on the back of the card) so
that for credit card transactions, the cardholder still needs to enter this value. For the checkout
process in your web shop, we recommend that you also store the last four digits of the credit card
number on your side and display it when it comes to payment. In that way the cardholder can see
which of his maybe several cards has been registered in your shop and will be used for this payment
transaction.

7.5 Store payment information without performing a transaction at the same time
Besides the possibility to store new records when performing a payment transaction, you can store
payment information using an Action Request. In that way it is also possible to upload multiple
records at once. The following example shows the upload for a record with credit card data as well as
the direct debit data. Please note that also in this case, existing records will be updated if the
HostedDataID is the same.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:a1="http://ipg-online.com/ipgapi/schemas/a1"
xmlns:ipg="http://ipg-online.com/ipgapi/schemas/ipgapi" xmlns:v1="http://ipg-
online.com/ipgapi/schemas/v1">
<soapenv:Header/>
<soapenv:Body>
<ipg:IPGApiActionRequest>
<a1:Action>
<a1:StoreHostedData>
<a1:StoreId>120992233</a1:StoreId>
<a1:DataStorageItem>
<a1:DE_DirectDebitData>
<v1:IBAN>DE**34*************1604</v1:IBAN>
<v1:MandateReference>12/12/19</v1:MandateReference>
</a1:DE_DirectDebitData>
<a1:AssignToken>true</a1:AssignToken>
<a1:BillingName>Test User</a1:BillingName>
</a1:DataStorageItem>
<a1:DataStorageItem>
<a1:CreditCardData>
<v1:CardNumber>5426******4979</v1:CardNumber>
<v1:ExpMonth>12</v1:ExpMonth>
<v1:ExpYear>27</v1:ExpYear>
<v1:CardCodeValue>XXX</v1:CardCodeValue>
</a1:CreditCardData>
<a1:AssignToken>true</a1:AssignToken>
</a1:DataStorageItem>
</a1:StoreHostedData>
</a1:Action>
</ipg:IPGApiActionRequest>
</soapenv:Body>
</soapenv:Envelope>

The result for a successful storage contains the HostedDataID:

<ipgapi:IPGApiActionResponse
xmlns:a1="http://ipg-online.com/ipgapi/schemas/a1" xmlns:ipgapi="http://ipg-
online.com/ipgapi/schemas/ipgapi" xmlns:v1="http://ipg-
online.com/ipgapi/schemas/v1">
<ipgapi:successfully>true</ipgapi:successfully>
<ipgapi:DataStorageItem>
<a1:DE_DirectDebitData>
<v1:BIC>PBNKDEFFXXX</v1:BIC>
<v1:IBAN>DE**34*******1604</v1:IBAN>
<v1:BankCode>50010060</v1:BankCode>
<v1:AccountNumber>32121604</v1:AccountNumber>
</a1:DE_DirectDebitData>
<a1:HostedDataID>0EFC3495-4F4F-4A1B-BCA5-
C81F80D834C0</a1:HostedDataID>
</ipgapi:DataStorageItem>
<ipgapi:DataStorageItem>
<a1:CreditCardData>
<v1:CardNumber>5426******4979</v1:CardNumber>
<v1:ExpMonth>12</v1:ExpMonth>
<v1:ExpYear>27</v1:ExpYear>
<v1:Brand>MASTERCARD</v1:Brand>
</a1:CreditCardData>
<a1:HostedDataID>136DFF32-5BE3-4FCE-A537-
6F491DA31039</a1:HostedDataID>
</ipgapi:DataStorageItem>
</ipgapi:IPGApiActionResponse>

Example of Request to store the data under given hostedDataID:

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<ns4:IPGApiActionRequest
xmlns:ns4="http://ipg-online.com/ipgapi/schemas/ipgapi" xmlns:ns2="http://ipg-
online.com/ipgapi/schemas/a1"
xmlns:ns3="http://ipg-online.com/ipgapi/schemas/v1">
<ns2:Action>
<ns2:StoreHostedData>
<ns2:DataStorageItem>
<ns2:CreditCardData>
<ns3:CardNumber>4035******4977</ns3:CardNumber>
<ns3:ExpMonth>12</ns3:ExpMonth>
<ns3:ExpYear>27</ns3:ExpYear>
</ns2:CreditCardData>
<ns2:HostedDataID>2a356872-54c7-4d09-800c-0be221e72edb</ns2:HostedDataID>
</ns2:DataStorageItem>
<ns2:DataStorageItem>
<ns2:DE_DirectDebitData>
<ns3:BankCode>50010060</ns3:BankCode>
<ns3:AccountNumber>32121604</ns3:AccountNumber>
</ns2:DE_DirectDebitData>
<ns2:HostedDataID>6f6de992-e484-4a68-a520-
5f3a32e46fad</ns2:HostedDataID>
<ns2:Billing>Name>Test Owner</ns2:BillingName>
</ns2:DataStorageItem>
</ns2:StoreHostedData>
</ns2:Action>
</ns4:IPGApiActionRequest>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

The result for a successful storage contains the value true for the parameter <ns4:successfully>:

In cases where one or more records have not been stored successfully, the corresponding Hosted Data
IDs are marked in the result:

<ns4:IPGApiActionResponse
xmlns:ns4="http://ipg-online.com/ipgapi/schemas/ipgapi"
xmlns:ns2="http://ipg-online.com/ipgapi/schemas/a1"
xmlns:ns3="http://ipg-online.com/ipgapi/schemas/v1">
<ns4:successfully>true</ns4:successfully>
<ns2:Error Code="SGSDAS-020300">
<ns2:ErrorMessage>
Could not store the hosted data id:
691c7cb3-a752-4d6d-abde-83cad63de258.
Reason: An internal error has occured while processing
your request
</ns2:ErrorMessage>
</ns2:Error>
</ns4:IPGApiActionResponse>

Example of response in case of missing mandatory parameter:

Example of response in case where hosted data has not been stored successfully:

<ipgapi:IPGApiActionResponse xmlns:ipgapi="http://ipg-
online.com/ipgapi/schemas/ipgapi" xmlns:a1="http://ipg-
online.com/ipgapi/schemas/a1" xmlns:v1="http://ipg-online.com/ipgapi/schemas/v1">
<ipgapi:successfully>true</ipgapi:successfully>
<a1:Error>
<a1:ErrorMessage>hosted data id: E99F19BB9D4F4503B8908D9F86C183F8.
Invalid expiration date: CreditCard [cardNumber=492181...2311, expirationMonth=3,
expirationYear=2020, trackData=(masked), trackOneData=(masked),
trackTwoData=(masked), cardCodeValue=(len:null, isChipCard=null,
enrichedCreditCard=EnrichedCreditCard [typeString=null, issuername=null,
country=null, binCreditCardTypes=[], creditCardInformationList=[],
creditCardType=null, cardFunction=null, commercialCardType=null]]
</a1:ErrorMessage>
</a1:Error>
</ipgapi:IPGApiActionResponse>

7.6 Avoid duplicate cardholder data for multiple records

To avoid customers using the same cardholder data for multiple user accounts, the additional tag
DeclineHostedDataDuplicates can be sent along with the request. The valid values for this tag are
‘true’/’false’. If the value for this tag is set to ‘true’ and the cardholder data in the request is already
found to be associated with another ‘hosteddataid’, the transaction will be declined.

7.7 Display stored records

Existing records can be displayed using the action Display:

<ns4:IPGApiActionRequest
xmlns:ns4="http://ipg-online.com/ipgapi/schemas/ipgapi"
xmlns:ns2="http://ipg-online.com/ipgapi/schemas/v1"
xmlns:ns3="http://ipg-online.com/ipgapi/schemas/a1">
<ns3:Action>
<ns3:StoreHostedData>
<ns3:DataStorageItem>
<ns3:Function>display</ns3:Function>
<ns3:HostedDataID>
d56feaaf-2d96-4159-8fd6-887e07fc9052
</ns3:HostedDataID>
</ns3:DataStorageItem>
</ns3:StoreHostedData>
</ns3:Action>
</ns4:IPGApiActionRequest>

The response contains the stored information. For security reasons, only the first 6 and last 4 digits of
credit card numbers are being sent back.

<ns4:IPGApiActionResponse
xmlns:ns4="http://ipg-online.com/ipgapi/schemas/ipgapi"
xmlns:ns2="http://ipg-online.com/ipgapi/schemas/a1"
xmlns:ns3="http://ipg-online.com/ipgapi/schemas/v1">
<ns4:successfully>true</ns4:successfully>
<ns4:DataStorageItem>
<ns2:CreditCardData>
<ns3:CardNumber>4035*****4977</ns3:CardNumber>
<ns3:ExpMonth>12</ns3:ExpMonth>
<ns3:ExpYear>27</ns3:ExpYear>
</ns2:CreditCardData>
<ns2:HostedDataID>
d56feaaf-2d96-4159-8fd6-887e07fc9052
</ns2:HostedDataID>
</ns4:DataStorageItem>
</ns4:IPGApiActionResponse>

If the Hosted Data ID does not exist, the API response indicates an error:

<ns4:IPGApiActionResponse
xmlns:ns4="http://ipg-online.com/ipgapi/schemas/ipgapi"
xmlns:ns2="http://ipg-online.com/ipgapi/schemas/a1"
xmlns:ns3="http://ipg-online.com/ipgapi/schemas/v1">
<ns4:successfully>true</ns4:successfully>
<ns2:Error Code="SGSDAS-020301">
<ns2:ErrorMessage>
Hosted data id:
6c814261-a843-49fb-bacd-1411d3780286 not found.
</ns2:ErrorMessage>
</ns2:Error>
</ns4:IPGApiActionResponse>

The value successfully contains false, only if the data vault can’t determined because the request
finished in an error.

7.8 Delete existing records

The action “Delete” allows you to remove data records that are no longer needed:

<ns4:IPGApiActionRequest
xmlns:ns4="http://ipg-online.com/ipgapi/schemas/ipgapi"
xmlns:ns2="http://ipg-online.com/ipgapi/schemas/v1"
xmlns:ns3="http://ipg-online.com/ipgapi/schemas/a1">
<ns3:Action>
<ns3:StoreHostedData>
<ns3:DataStorageItem>
<ns3:Function>delete</ns3:Function>
<ns3:HostedDataID>
9605c2d1-428c-4de2-940e-4bec4737ab5d
</ns3:HostedDataID>
</ns3:DataStorageItem>
</ns3:StoreHostedData>
</ns3:Action>
</ns4:IPGApiActionRequest>

A successful deletion will be confirmed with the following response:

8 Global Choice™ and Dynamic Pricing

With Fiserv’s Global Choice™, foreign customers have the choice to pay for goods and services
purchased online in their home currency when using their Visa or MasterCard credit card for the
payment. The currency conversion is quick and eliminates the need for customers to mentally
calculate the estimated cost of the purchase in their home currency.

International Visa and MasterCard eCommerce customers can make informed decisions about their
online purchases and eradicate any unexpected pricing or foreign exchange conversions on receipt of
their monthly statements.

Another option for your foreign customers is to display all pricing within your online store in their
home currency using our Dynamic Pricing solution. This solution removes the need for your company
to set pricing in any other currency other than your home currency.

If your Store has been activated for one of these product options, you can use this Web Service API
to request the currency exchange rates for such transactions.

8.1 Exchange rate requests for Global Choice™

The following example shows a request to the Web Service API to request a card-related exchange
rate.
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<ns5:IPGApiActionRequest xmlns:ns5="http://ipg-
online.com/ipgapi/schemas/ipgapi" xmlns:ns2="http://ipg-
online.com/ipgapi/schemas/v1" xmlns:ns3="http://ipg-online.com/ipgapi/schemas/a1">
<ns3:Action>
<ns3:RequestCardRateForDCC>
<ns3:StoreId>110994125</ns3:StoreId>
<ns3:BIN>402939</ns3:BIN>
<ns3:BaseAmount>100.5</ns3:BaseAmount>
</ns3:RequestCardRateForDCC>
</ns3:Action>
</ns5:IPGApiActionRequest>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

A successful respose is shown in the following answer:

• The status is given by <ipgapi:successfully>true</ipgapi:successfully>

• The response is wrapped within <ipgapi:CardRateForDCC>

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

8.2 Exchange rate requests for Dynamic Pricing

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

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<ns5:IPGApiActionRequest xmlns:ns5="http://ipg-
online.com/ipgapi/schemas/ipgapi" xmlns:ns2="http://ipg-
online.com/ipgapi/schemas/v1" xmlns:ns3="http://ipg-online.com/ipgapi/schemas/a1">
<ns3:Action>
<ns3:RequestMerchantRateForDynamicPricing>
<ns3:StoreId>110994125</ns3:StoreId>
<ns3:ForeignCurrency>826</ns3:ForeignCurrency>
<ns3:BaseAmount>100.5</ns3:BaseAmount>
</ns3:RequestMerchantRateForDynamicPricing>
</ns3:Action>
</ns5:IPGApiActionRequest>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

A successful respose is shown in the following answer from IPG:

• The status is given by <ipgapi:successfully>true</ipgapi:successfully>
• The response is wrapped within <ipgapi:MerchantRateForDynamicPricing>

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

8.3 Exchange rate responses

All rate responses share the same XML data-type, they are just wrapped in different parent-tags.

Common fields for all requests are the following:

• Success-status: given with <ipgapi:successfully>true</ipgapi:successfully>
• The ID of the request, given with <v1:InquiryRateId>49150</v1:InquiryRateId>

The latter InquiryRateId is later to be used to reference the rate request, when performing a
transaction with a converted transaction amount.

8.4 Conversion offering

A rate request with an offering returned is shown with the following example.
• The offering is denoted with <a1:DccOffered>true</a1:DccOffered>
• Each offering has associated timestamps, given as xml:date-time.
o Source time <a1:ExchangeRateSourceTimestamp>2014-07-
14T12:46:00.000+02:00</a1:ExchangeRateSourceTimestamp>
o Expiration time <a1:ExpirationTimestamp>2015-06-
23T13:46:00.000+02:00</a1:ExpirationTimestamp>
• The source of the curreny-conversion is shown by
<a1:ExchangeRateSourceName>REUTERS WHOLESALE
INTERBANK</a1:ExchangeRateSourceName>
• Finally, the currency conversion results are given by the following fields
o Foreign currency: <a1:ForeignCurrencyCode>978</a1:ForeignCurrencyCode>
o Foreign amount: <a1:ForeignAmount>130.33</a1:ForeignAmount>
o Exchange rate: <a1:ExchangeRate>1.2968</a1:ExchangeRate>

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

8.5 Declined rate request

A rate request with a declined offering is shown with the following example.
• The declined offering is denoted with <a1:DccOffered>false</a1:DccOffered>
• Also for declined offerings an ID is returned: <v1:InquiryRateId>4051</v1:InquiryRateId>

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

8.6 Failed rate request

A rate request which couldn’t be processed successfully is shown by the following example:
• Failure-status: given with <ipgapi:successfully>false</ipgapi:successfully>
• The error-element:
o The error-code by the Code attribute: <a1:Error Code="SGS-27440">
o The human readable message:
<a1:ErrorMessage>no amount given</a1:ErrorMessage>

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

8.7 Global Choice™ transactions

For compliance reasons Fiserv’s Global Choice can only be offered on transactions that take place in
full at that time (e.g. Sale, Refund) and not on any delayed settlement (e.g. pre/post auth, recurring)
due to the fluctuation of the rate of exchange.

Performing transactions with a converted amount involves the following steps

1. Perform a rate request as described in the sections above.
2. Use the returned InquiryRateId to reference the conversion in the payment transaction
message. Use the field DccApplied to denote whether the user has chosen to use the
proposed conversion or not.

Please note that an InquiryRateId may be used only once. After each transaction request, whether
successful or not, regardless of the dccApplied setting used, a new rate has to be requested.
Re-using a conversion-rate will result in an error message CORE-DCC-10, since the rate-inquiry is
already associated with another transaction.

Step 1: Rate request

The Global Choice™ card-rate-request is shown here to give a complete example:

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<ns5:IPGApiActionRequest xmlns:ns5="http://ipg-
online.com/ipgapi/schemas/ipgapi" xmlns:ns2="http://ipg-
online.com/ipgapi/schemas/v1" xmlns:ns3="http://ipg-online.com/ipgapi/schemas/a1">
<ns3:Action>
<ns3:RequestCardRateForDCC>
<ns3:StoreId>110994125</ns3:StoreId>
<ns3:BIN>419681</ns3:BIN>
<ns3:BaseAmount>202.02</ns3:BaseAmount>
</ns3:RequestCardRateForDCC>
</ns3:Action>
</ns5:IPGApiActionRequest>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

The order to be used in a later transaction, the request has to be

• Successful: <ipgapi:successfully>true</ipgapi:successfully>
• With a returned conversion offering <a1:DccOffered>true</a1:DccOffered>
• Not expired <a1:ExpirationTimestamp>2015-06-
23T12:46:00.000+02:00</a1:ExpirationTimestamp>

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

Step 2: Using the conversion rate for the payment transaction

The Global Choice™ feature is selected by the element <ns2:InquiryRateReference>.

o The rate-id is used to reference the conversion rate:
<ns2:InquiryRateId>8391</ns2:InquiryRateId>
o The users choice whether to apply the proposed rate is specified by:
<ns2:DccApplied>true</ns2:DccApplied>

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<ns5:IPGApiOrderRequest xmlns:ns5="http://ipg-
online.com/ipgapi/schemas/ipgapi" xmlns:ns2="http://ipg-
online.com/ipgapi/schemas/v1" xmlns:ns3="http://ipg-online.com/ipgapi/schemas/a1">
<ns2:Transaction>
<ns2:CreditCardTxType>
<ns2:StoreId>110994125</ns2:StoreId>
<ns2:Type>return</ns2:Type>
</ns2:CreditCardTxType>
<ns2:Payment>
<ns2:ChargeTotal>202.02</ns2:ChargeTotal>
<ns2:Currency>826</ns2:Currency>
</ns2:Payment>
<ns2:TransactionDetails>
<ns2:OrderId>API-Test</ns2:OrderId>
<ns2:InquiryRateReference>
<ns2:InquiryRateId>8391</ns2:InquiryRateId>
<ns2:DccApplied>true</ns2:DccApplied>
</ns2:InquiryRateReference>
</ns2:TransactionDetails>
</ns2:Transaction>
</ns5:IPGApiOrderRequest>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

For completeness the successful response is also shown here.

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

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<ipgapi:IPGApiOrderResponse
xmlns:ipgapi="http://ipg-online.com/ipgapi/schemas/ipgapi"
xmlns:a1="http://ipg-online.com/ipgapi/schemas/a1"
xmlns:v1="http://ipg-online.com/ipgapi/schemas/v1">
<ipgapi:ApprovalCode>Y:000000:0014746213:PPXM:0000</ipgapi:ApprovalCode>
<ipgapi:AVSResponse>PPX</ipgapi:AVSResponse>
<ipgapi:Brand>VISA</ipgapi:Brand>
<ipgapi:Country>MLT</ipgapi:Country>
<ipgapi:CommercialServiceProvider>BOSMS</ipgapi:CommercialServiceProvider>
<ipgapi:OrderId>API-Test</ipgapi:OrderId>
<ipgapi:PaymentType>CREDITCARD</ipgapi:PaymentType>
<ipgapi:ProcessorApprovalCode>000000</ipgapi:ProcessorApprovalCode>
<ipgapi:ProcessorCCVResponse>M</ipgapi:ProcessorCCVResponse>
<ipgapi:ProcessorResponseCode>00</ipgapi:ProcessorResponseCode>
<ipgapi:ProcessorResponseMessage>Authorised</ipgapi:ProcessorResponseMessage>
<ipgapi:ReferencedTDate>1407154820</ipgapi:ReferencedTDate>
<ipgapi:TDate>1407154821</ipgapi:TDate>
<ipgapi:TDateFormatted>2014.08.04 14:20:21
(CEST)</ipgapi:TDateFormatted>
<ipgapi:TerminalID>80000012</ipgapi:TerminalID>
<ipgapi:TransactionResult>APPROVED</ipgapi:TransactionResult>
<ipgapi:TransactionTime>1407154821</ipgapi:TransactionTime>
</ipgapi:IPGApiOrderResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

9 Payment URL
Payment URL is a functionality that allows you to provide a link to your customers (e.g. in an email
invoice, WhatsApp message, SMS, QR code, etc. which then takes the customer to a Fiserv-hosted
page to securely make the payment with their preferred payment method, whenever convenient for
them.

This is especially useful in scenarios where goods get paid after delivery, where no goods get shipped
at all (e.g. final payment for trips that have been booked months ago) or for the payment of monthly
bills.

You can also implement this functionality for unsuccessful purchases where the original payment
transaction has been declined so that you can proactively give your customer a second chance to make
their purchase.

The Gateway provides:

• The capability to request a Payment URL (link) for a specific amount through this Web Service
API

• A hosted payment page where the customer can select the preferred payment method (based
on the payment methods that are activated for your account) and make the payment

• A hosted result page that tells the customer if the payment was successful or not, including a
Retry button where the customer can chose a different payment method in case the transaction
was not successful

• Support for the specific fields that are required for Visa transactions with MCC 6012 in the UK

9.1 Payment URL creation

The request for a Payment URL includes transaction type, amount and currency as well as the language
that shall be used on the payment page that will be shown to the customer after accessing the URL.

The URL request stays valid for 182 days (182 * 24 * 3600 seconds) + 1 day (on which the URL was
generated).
A merchant can override these settings by setting 'Expiration element' to desired value, which is an
expiration date in unix timestamp (in seconds, while the Gateway calculates it in milliseconds), this
value shall be calculated by a merchant himself.
<?xml version="1.0" encoding="UTF-8"?><SOAP-ENV:Envelope xmlns:SOAP-
ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<ns5:IPGApiActionRequest
xmlns:ns5="http://ipg-online.com/ipgapi/schemas/ipgapi"
xmlns:ns2="http://ipg-online.com/ipgapi/schemas/a1"
xmlns:ns3="http://ipg-online.com/ipgapi/schemas/v1">
<ns2:Action>
<ns2:CreatePaymentURL>
<ns2:Transaction>
<ns3:PaymentUrlTxType>
<ns3:StoreId>120995000</ns3:StoreId>
<ns3:Type>sale</ns3:Type>
</ns3:PaymentUrlTxType>
<ns3:Payment>
<ns3:ChargeTotal>13.99</ns3:ChargeTotal>
<ns3:Currency>EUR</ns3:Currency>
</ns3:Payment>
<ns3:TransactionDetails/>
<ns3:ClientLocale>
<ns3:Language>en</ns3:Language>
<ns3:Country>GB</ns3:Country>
</ns3:ClientLocale>
</ns2:Transaction>
</ns2:CreatePaymentURL>
</ns2:Action>
</ns5:IPGApiActionRequest>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

The Response contains the Payment URL:

<?xml version="1.0" encoding="UTF-8"?><SOAP-ENV:Envelope xmlns:SOAP-

ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<ipgapi:IPGApiActionResponse
xmlns:ipgapi="http://ipg-online.com/ipgapi/schemas/ipgapi"
xmlns:a1="http://ipg-online.com/ipgapi/schemas/a1"
xmlns:v1="http://ipg-online.com/ipgapi/schemas/v1">
<ipgapi:successfully>true</ipgapi:successfully>
<ipgapi:OrderId>A-a22cd17f-0e50-4541-9404-159aa62815f0</
ipgapi:OrderId>
<ipgapi:TransactionId>88963651</ipgapi:TransactionId>
<ipgapi:paymentUrl>https://test.ipg-
online.com/connect/gateway/processing?storename=120995000&oid=A-6d6f02ee-1020-
4935-a8fd-e8d34e0ace03&paymentUrlId=efc0d59b-7128-4d36-ba7d-
0f7b642fd9ea</ipgapi:paymentUrl>
</ipgapi:IPGApiActionResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

When the customer completed the payment transaction, the gateway can send a server-to-server
transaction notification to a defined Notification URL. Please contact your local support team to get
your URL registered for these notifications.

9.2 Payment URL deletion

For cases, when you need to prevent your customers to make a payment twice, you can use
“DeletePaymentURL” feature.

<?xml version="1.0" encoding="UTF-8"?><SOAP-ENV:Envelope xmlns:SOAP-

When processing a Payment URL an additional check ensures the Payment URL has not been voided,
and if it has, the URL will lead the customer to a screen that explains that the URL is no longer valid.

9.3 Payment URL custom text

For cases where you would like to add a free text to be shown above the payment options on the
page that the consumer will see when going to the URL for making the payment, you can submit an
element hostedPaymentPageText in your request to our Gateway:

<?xml version="1.0" encoding="UTF-8"?><SOAP-ENV:Envelope xmlns:SOAP-

ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<ns5:IPGApiActionRequest
xmlns:ns5="http://ipg-online.com/ipgapi/schemas/ipgapi"
xmlns:ns2="http://ipg-online.com/ipgapi/schemas/a1"
xmlns:ns3="http://ipg-online.com/ipgapi/schemas/v1">
<ns2:Action>
<ns2:CreatePaymentURL>
<ns2:Transaction>
<ns3:PaymentUrlTxType>
<ns3:StoreId>120995000</ns3:StoreId>
<ns3:Type>sale</ns3:Type>
</ns3:PaymentUrlTxType>
<ns3:Payment>
<ns3:Currency>EUR</ns3:Currency>
</ns3:Payment>
<ns3:TransactionDetails/>
<ns3:ClientLocale>
<ns3:Language>en</ns3:Language>
<ns3:Country>GB</ns3:Country>
</ns3:ClientLocale>
</ns2:Transaction>
<ns2:hostedPaymentPageText>This is a sample text
</ns2:hostedPaymentPageText>
</ns2:CreatePaymentURL>
</ns2:Action>
10 3-D Secure

10.1 Authentication with Fiserv as your 3DS provider

3-D Secure is an authentication mechanism designed to reduce fraud and chargebacks in relation to
Card-Not-Present transactions.

EMVCo in cooperation with major international schemes defined new EMV 3DS specification for the
benefit of the entire industry to collaboratively develop the next generation of 3-D Secure protocol.
The new version promotes frictionless consumer authentication and enables consumers to
authenticate themselves with their card issuer when making card-not-present e-commerce
purchases.
EMV 3-D Secure protocol supports app-based authentication and integration with digital wallets, as
well as traditional browser-based e-commerce transactions and delivers industry leading security
features.

With our Hosted Payment Page solution (see separate Integration Guide Connect), we can manage
the required flows for the authentication process for you. If you should however prefer to handle this
process and the required redirections yourself, the Web Service API allows you to make single API
calls for the required steps.

In case you use the Gateway for 3DS web-based authentication, in the first step you need to submit a
verification request with an ‘AuthenticateTransaction’ parameter set to “true” and indicate which
URL the result of the authentication should be sent to with using ‘TermUrl’ parameter.
If you wish to be notified about 3DSMethod form display completion, you need to submit also
optional element “ThreeDSMethodNotificationURL” in your transaction request. The URL should
be uniquely identifiable, so when there is a notification received on this URL, you should be able to
map it with the corresponding transaction. This eliminates any dependency on the
ThreeDSServerTransID, which you will receive with the 3DSMethod form response. An easy way
how to ensure correct transaction mapping is to is to pass a transaction reference as a query string.
For example:
https://www.mywebshop.com/process3dSecureMethodNotification?transactionReferenceNu
mber=ffffffff-ba0b-539f-8000-016b2343ad7e

Note: The purpose of 3DSMethod is explained below under ‘Sale’ transaction example.

In case you would like to influence which authentication flow should be used, you can submit
“Challenge Indicator” element with one of the values listed below. In case Challenge Indicator is not
sent within your transaction request, the Gateway will populate the default value “01” – No
preference.

Challenge indicator available values for 3DS protocol version 2.x are:
“01” = No preference (You have no preference whether a challenge should be performed. This is the
default value)
“02” = No challenge requested (You prefer that no challenge should be performed.)
“03” = Challenge requested: 3DS Requestor Preference (You prefer that a challenge should be
performed)
“04” = Challenge requested: Mandate (There are local or regional mandates that mean that a
challenge must be performed)
“05” = No challenge requested (Transaction Risk Analysis is already performed)
“06” = No challenge requested (Data Share Only)
“07” = No challenge requested (SCA is already performed)
“08” = No challenge requested (Utilize whitelist exemption if no challenge required)
“09” = Challenge requested (Whitelist prompt requested if challenge required)

Note: It is highly recommended to include also Billing and Shipping details in your transaction request
to lower the risk of authentication declines.

In case you would like to define the size of the challenge window displayed to your customers during
the authentication process, you can submit optional "Challenge Window Size" element with one of the
values listed below.

01 = 250 x 400
02 = 390 x 400
03 = 500 x 600
04 = 600 x 400
05 = Full screen

Note: Based on the payment schemes' observation it is highly recommended to use the value "05 -
Full screen" only for browser-based flows. Using full screen mode in app-based flows where the
authentication of the cardholder happens on a smartphone or tablet might cause time-outs and trigger
an error on issuer/ACS side.

In order to comply with scheme’s data integrity requirements, we highly recommend to include also
following conditionally required parameters in your initial authentication request, what can dramatically
improve authentication approval rate.

Path Type Description

v1:CardHolderBrowserParameters/ xs:string45max Cardholder’s browser IP Address
v1:BrowserIP
v1:CardHolderBrowserParameters/ xs:string Cardholder’s browser screen height
v1:BrowserScreenHeight
v1:CardHolderBrowserParameters/ xs:string Cardholder’s browser screen width
v1:BrowserScreenWidth
v1:Billing/ xs:string96max Cardholder’s name
v1:Name
v1:Billing/ xs:string32max Cardholder’s phone number
v1:Phone
v1:Billing/ xs:string Cardholder’s email address
v1:Email
v1:Billing/ xs:string96max Cardholder‘s billing address line 1 (street)
v1:Address1
v1:Billing/ xs:string96max Cardholder‘s billing address city
v1:City
v1:Billing/ xs:string96max Cardholder‘s billing address state (if
v1:State
applicable)
v1:Billing/ xs:string24max Cardholder‘s billing address postal code
v1:Zip
v1:Billing/ xs:string32max Cardholder‘s billing address country
v1:Country

The following XML document represents an example of a Sale transaction request:

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

<SOAP-ENV:Envelope
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<ns4:IPGApiOrderRequest
xmlns:ns4="http://ipg-online.com/ipgapi/schemas/ipgapi"
xmlns:ns2="http://ipg-online.com/ipgapi/schemas/v1"
xmlns:ns3="http://ipg-online.com/ipgapi/schemas/a1">
<ns2:Transaction>
<ns2:CreditCardTxType>
<ns2:StoreId>1109950006</ns2:StoreId>
<ns2:Type>sale</ns2:Type>
</ns2:CreditCardTxType>
<ns2:CreditCardData>
<ns2:CardNumber>426588******0049</ns2:CardNumber>
<ns2:ExpMonth>12</ns2:ExpMonth>
<ns2:ExpYear>28</ns2:ExpYear>
<ns2:CardCodeValue>XXX</ns2:CardCodeValue>
</ns2:CreditCardData>
<ns2:CreditCard3DSecure>
<ns2:AuthenticateTransaction>true</ns2:AuthenticateTransaction>
<ns2:TermUrl>https://test.webshop.com/simulator/secure3d/return</ns2:TermUrl>
<ns2:ThreeDSMethodNotificationURL>https://test.ipg-
online.com/ipgconfirmation/services/secure3ds</ns2:ThreeDSMethodNotificationURL>
<ns2:ThreeDSRequestorChallengeIndicator>01</ns2:ThreeDSRequestorChallengeIndicator>
<ns2:ThreeDSRequestorChallengeWindowSize>01</ns2:ThreeDSRequestorChallengeWindowSiz
e>
<ns2:CardHolderBrowserParameters>
<ns2:BrowserAcceptHeader>Accept: text/html, application/xhtml+xml,
application/xml;q=0.9, image/webp, */*;q=0.8</ns2:BrowserAcceptHeader>
<ns2:BrowserIP>85.117.56.12</ns2:BrowserIP>
<ns2:BrowserLanguage>en-GB</ns2:BrowserLanguage>
<ns2:BrowserColorDepth>32</ns2:BrowserColorDepth>
<ns2:BrowserScreenHeight>1080</ns2:BrowserScreenHeight>
<ns2:BrowserScreenWidth>1920</ns2:BrowserScreenWidth>
<ns2:BrowserTimeZone>-300</ns2:BrowserTimeZone>
<ns2:BrowserUserAgent>Lynx/2.8.4rel.1 libwww-FM/2.14 SSL-MM/1.4.1
OpenSSL/0.9.6c</ns2:BrowserUserAgent>
</ns2:CardHolderBrowserParameters>
</ns2:CreditCard3DSecure>
<ns2:Payment>
<ns2:ChargeTotal>15.00</ns2:ChargeTotal>
<ns2:Currency>EUR</ns2:Currency>
</ns2:Payment>
<ns2:Billing>
<ns2:Name>Max Mustermann</ns2:Name>
<ns2:Address1>Street 123</ns2:Address1>
<ns2:Address2>App2</ns2:Address2>
<ns2:City>Frankfurt</ns2:City>
<ns2:State>Hessen</ns2:State>
<ns2:Zip>98765</ns2:Zip>
<ns2:Country>Germany</ns2:Country>
<ns2:Phone>+4979331234</ns2:Phone>
<ns2:Email>test@test.com</ns2:Email>
</ns2:Billing>
</ns2:Transaction>
</ns4:IPGApiOrderRequest>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

NOTE: In case you submitted 'OrderId' element in your request, please make sure to include only
allowed characters: A-Z, a-z, 0-9, "-"

If the response from the Gateway contains ‘3DSMethod’ element, it generates hidden iframe, that
helps to collect the browser data for the issuers. This information adds to the overall consumer profile
and helps in identifying potentially fraudulent transactions.
You MUST include the 3DSMethod in your website as hidden iframe. No user interface screen is
presented to the cardholder.
The following XML document represents an example of a response:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<ipgapi:IPGApiOrderResponse xmlns:a1="http://ipg-
online.com/ipgapi/schemas/a1" xmlns:ipgapi="http://ipg-
online.com/ipgapi/schemas/ipgapi" xmlns:v1="http://ipg-
online.com/ipgapi/schemas/v1">
<ipgapi:ApprovalCode>?:waiting 3dsecureMethod</ipgapi:ApprovalCode>
<ipgapi:Brand>VISA</ipgapi:Brand>
<ipgapi:Country>SGP</ipgapi:Country>
<ipgapi:CommercialServiceProvider>BOSMS</ipgapi:CommercialServiceProvider>
<ipgapi:OrderId>A-2b45e6ab-9456-4e11-a721-95ab325a1011</ipgapi:OrderId>
<ipgapi:IpgTransactionId>84637755726</ipgapi:IpgTransactionId>
<ipgapi:PaymentType>CREDITCARD</ipgapi:PaymentType>
<ipgapi:TDate>1695815106</ipgapi:TDate>
<ipgapi:TDateFormatted>2023.09.27 13:45:06 (CEST)</ipgapi:TDateFormatted>
<ipgapi:TransactionTime>1695815106</ipgapi:TransactionTime>
<ipgapi:Secure3DResponse>
<v1:Secure3DMethod>
<v1:Secure3DMethodForm><![CDATA[<iframe id="tdsMmethodTgtFrame"
name="tdsMmethodTgtFrame" style="visibility: hidden; width: 1px; height: 1px;"
xmlns="http://www.w3.org/1999/xhtml">

</iframe><form id="tdsMmethodForm" name="tdsMmethodForm" action="https://3ds-
acs.test.modirum.com/mdpayacs/3ds-method" method="post" target="tdsMmethodTgtFrame"
xmlns="http://www.w3.org/1999/xhtml">
<input type="hidden" name="3DSMethodData"
value="eyAidGhyZWVEU1NlcnZlclRyYW5zSUQiIDogIjNhYjdhYjQ5LWI5ZGQtNWU0My04MDAwLTAwMDAw
MWFlMDQ0MyIsICJ0aHJlZURTTWV0aG9kTm90aWZpY2F0aW9uVVJMIiA6ICJodHRwczovL3Rlc3QuaXBnLW9
ubGluZS5jb20vaXBnY29uZmlybWF0aW9uL3NlcnZpY2VzL3NlY3VyZTNkcz9yZWZlcmVuY2VkVHJhbnNhY3
Rpb25JZD04NDYzNzc1NTcyNiIgfQ"/>
<input type="hidden" name="threeDSMethodData"
value="eyAidGhyZWVEU1NlcnZlclRyYW5zSUQiIDogIjNhYjdhYjQ5LWI5ZGQtNWU0My04MDAwLTAwMDAw
MWFlMDQ0MyIsICJ0aHJlZURTTWV0aG9kTm90aWZpY2F0aW9uVVJMIiA6ICJodHRwczovL3Rlc3QuaXBnLW9
ubGluZS5jb20vaXBnY29uZmlybWF0aW9uL3NlcnZpY2VzL3NlY3VyZTNkcz9yZWZlcmVuY2VkVHJhbnNhY3
Rpb25JZD04NDYzNzc1NTcyNiIgfQ"/>
<script type="text/javascript">
document.getElementById("tdsMmethodForm").submit();
</script>
</form>]]></v1:Secure3DMethodForm>

<v1:Secure3DServerTransactionId>28181571</v1:Secure3DServerTransactionId>
</v1:Secure3DMethod>
</ipgapi:Secure3DResponse>
</ipgapi:IPGApiOrderResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

10.1.1 Frictionless Flow

When a transaction is considered to be a low-risk or an exemption is requested, a frictionless flow is

applied. In such case the Gateway proceeds with the authorization without additional authentication
of the cardholder.
Once the 3DS Method call has been completed, you MUST notify the Gateway, that the
authentication process can continue by submitting the ‘Secure3DMethodNotificationStatus’
element with the values based on corresponding conditions:

• Secure3DMethodNotificationStatus = “RECEIVED” in case you have submitted the

element ThreeDSMethodNotificationURL in the initial Sale transaction request and have
received the notification from ACS within 10 seconds, you will receive HTTP POST message
from ACS, which will contain a unique transaction identifier represented by
threeDSServerTransID
• Secure3DMethodNotificationStatus = “EXPECTED_BUT_NOT_RECEIVED” in case you
have submitted the element ThreeDSMethodNotificationURL in the initial Sale transaction
request and have not received the notification from ACS within 10 seconds
• Secure3DMethodNotificationStatus = “NOT_EXPECTED” in case you have NOT
submitted the element ThreeDSMethodNotificationURL in the initial Sale transaction
request.

The following XML document represents an example of a request to be sent after 3DSMethod form
display:

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

The following XML document represents an example of a response you receive from the Gateway
indicating, that the authorization has been successful and fully authenticated:

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

<SOAP-ENV:Envelope
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<ipgapi:IPGApiOrderResponse
xmlns:ipgapi="http://ipg-online.com/ipgapi/schemas/ipgapi"
xmlns:a1="http://ipg-online.com/ipgapi/schemas/a1"
xmlns:v1="http://ipg-online.com/ipgapi/schemas/v1">
<ipgapi:ApprovalCode>Y:416502:0014750513:PPXM:4625106408</ipgapi:Approv
alCode>
<ipgapi:AVSResponse>PPX</ipgapi:AVSResponse>
<ipgapi:Brand>VISA</ipgapi:Brand>
<ipgapi:OrderId>A-52421c39-69c4-4b2d-959d-9fdcd3a9420a</ipgapi:OrderId>
<ipgapi:PaymentType>CREDITCARD</ipgapi:PaymentType>
<ipgapi:ProcessorApprovalCode>416502</ipgapi:ProcessorApprovalCode>
<ipgapi:ProcessorReceiptNumber>6408</ipgapi:ProcessorReceiptNumber>
<ipgapi:ProcessorCCVResponse>M</ipgapi:ProcessorCCVResponse>
<ipgapi:ProcessorTraceNumber>462510</ipgapi:ProcessorTraceNumber>
<ipgapi:ReferencedTDate>1407373209</ipgapi:ReferencedTDate>
<ipgapi:TDate>1407373209</ipgapi:TDate>
<ipgapi:TDateFormatted>2014.08.07 03:00:09
(CEST)</ipgapi:TDateFormatted>
<ipgapi:TerminalID>54000666</ipgapi:TerminalID>
<ipgapi:Secure3DResponse>
<v1:ResponseCode3dSecure>1</v1:ResponseCode3dSecure>
</ipgapi:Secure3DResponse>
</ipgapi:IPGApiOrderResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

10.1.2 Challenge Flow

Challenge flow is applied when the transaction is not considered to be a low-risk or in case the issuer
requires additional authentication of the cardholder. The whole process starts with initial “Sale”
transaction request as described above until the step where 3DS Method is displayed.

Once the 3DS Method call has been completed, you MUST notify the Gateway that the
authentication process can continue by submitting the ‘Secure3DMethodNotificationStatus’
element with the values based on corresponding conditions:

• Secure3DMethodNotificationStatus = “RECEIVED” in case you have submitted the

element ThreeDSMethodNotificationURL in the initial Sale transaction request (page 3)
and have received the notification from ACS within 10 seconds, you will receive HTTP POST
message from ACS, which will contain a unique transaction identifier represented by
threeDSServerTransID
• Secure3DMethodNotificationStatus = “EXPECTED_BUT_NOT_RECEIVED” in case you
have submitted the element ThreeDSMethodNotificationURL in the initial Sale transaction
request and have not received the notification from ACS within 10 seconds
• Secure3DMethodNotificationStatus = “NOT_EXPECTED” in case you have NOT
submitted the element ThreeDSMethodNotificationURL in the initial Sale transaction
request

The following XML document represents an example of a request to process 3DSMethod call:

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

Our Gateway verifies the response and provides the result back to you, including the challenge result
data.
The following XML document represents an example of a response:

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

<SOAP-ENV:Envelope
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<ipgapi:IPGApiOrderResponse
xmlns:ipgapi="http://ipg-online.com/ipgapi/schemas/ipgapi"
xmlns:a1="http://ipg-online.com/ipgapi/schemas/a1"
xmlns:v1="http://ipg-online.com/ipgapi/schemas/v1">
<ipgapi:ApprovalCode>?:waiting 3dsecure</ipgapi:ApprovalCode>
<ipgapi:Brand>MASTERCARD</ipgapi:Brand>
<ipgapi:CommercialServiceProvider>AIBMS</ipgapi:CommercialServiceProvider>
<ipgapi:OrderId>A-4b9804e6410b84475809e59e1b26</ipgapi:OrderId>
<ipgapi:IpgTransactionId>8383394827</ipgapi:IpgTransactionId>
<ipgapi:PaymentType>CREDITCARD</ipgapi:PaymentType>
<ipgapi:TDate>1493130774</ipgapi:TDate>
<ipgapi:TDateFormatted>2017.04.25 16:32:54(CEST)</ipgapi:TDateFormatted>
<ipgapi:TransactionTime>1493130774</ipgapi:TransactionTime>
<ipgapi:Secure3DResponse>
<v1:Secure3DVerificationResponse>
<v1:VerificationRedirectResponse>
<v1:AcsURL>https://3ds-acs.test.simulator.com/mdpayacs/creq</v1:AcsURL>
<v1:CReq>ewogICAiYWNzVHJhbCIgOiA...wMDAtMDAwMDAwMDA0MWE5Igp9</v1:CReq>
<v1:TermUrl>https://www.mywebshop.com/process3dSecure/</v1:TermUrl>
<v1:ThreeDSSessionData>50F2156E03083CA665BCB4..</v1:ThreeDSSessionData>
</v1:VerificationRedirectResponse>
</v1:Secure3DVerificationResponse>
</ipgapi:Secure3DResponse>
</ipgapi:IPGApiOrderResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

In the next step you have to POST the data to the indicated URL usually implemented as auto-submit
form. This needs to be implemented within your website. We recommend you to POST the challenge
request element without capitals (e.g. ‘creq’) to avoid any problems in a communication with the ACS.
Example:

<form name="frm" method="POST" action="https://3ds-acs.simulator.com/mdpayacs/creq ">

The cardholders will be redirected to the ACS and presented with the UI to collect the authentication
details - for example enter one-time-password or perform authentication using their banking app.
After authentication completion the consumer is redirected back to your webpage.

After you received the data from the ACS you need to submit them back to the Gateway in ‘CRes’
element together with the reference to the original transaction.
The following XML document represents an example of a request with CRes element:
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<ns4:IPGApiOrderRequest
xmlns:ns4="http://ipg-online.com/ipgapi/schemas/ipgapi"
xmlns:ns2="http://ipg-online.com/ipgapi/schemas/v1"
xmlns:ns3="http://ipg-online.com/ipgapi/schemas/a1">
<ns2:Transaction>
<ns2:CreditCardTxType>
<ns2:StoreId>120995000</ns2:StoreId>
<ns2:Type>sale</ns2:Type>
</ns2:CreditCardTxType>
<ns2:CreditCard3DSecure>
<ns2:Secure3DRequest>
<ns2:Secure3DAuthenticationRequest>
<ns2:AcsResponse>
<ns2:CRes>ewogICAiYWNzUmVmZX…Fuc1N0YXR…IKfQ==</ns2:CRes>
</ns2:AcsResponse>
</ns2:Secure3DAuthenticationRequest>
</ns2:Secure3DRequest>
</ns2:CreditCard3DSecure>
<ns2:TransactionDetails>
<ns2:IpgTransactionId>8383394827</ns2:IpgTransactionId>
</ns2:TransactionDetails>
</ns2:Transaction>
</ns4:IPGApiOrderRequest>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Since this transaction was initiated as Sale, the authorization is performed as part of this step if the
authentication was successful.
The following XML document represents an example of a response you receive from the Gateway
indicating, that the authorization has been successful:

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

<SOAP-ENV:Envelope
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<ipgapi:IPGApiOrderResponse
xmlns:ipgapi="http://ipg-online.com/ipgapi/schemas/ipgapi"
xmlns:a1="http://ipg-online.com/ipgapi/schemas/a1"
xmlns:v1="http://ipg-online.com/ipgapi/schemas/v1">
<ipgapi:ApprovalCode>Y:416502:0014750513:PPXM:4625106408</ipgapi:Approv
alCode>
<ipgapi:AVSResponse>PPX</ipgapi:AVSResponse>
<ipgapi:Brand>VISA</ipgapi:Brand>
<ipgapi:OrderId>A-52421c39-69c4-4b2d-959d-9fdcd3a9420a</ipgapi:OrderId>
<ipgapi:PaymentType>CREDITCARD</ipgapi:PaymentType>
<ipgapi:ProcessorApprovalCode>416502</ipgapi:ProcessorApprovalCode>
<ipgapi:ProcessorReceiptNumber>6408</ipgapi:ProcessorReceiptNumber>
<ipgapi:ProcessorCCVResponse>M</ipgapi:ProcessorCCVResponse>
<ipgapi:ProcessorTraceNumber>462510</ipgapi:ProcessorTraceNumber>
<ipgapi:ReferencedTDate>1407373209</ipgapi:ReferencedTDate>
<ipgapi:TDate>1407373209</ipgapi:TDate>
<ipgapi:TDateFormatted>2014.08.07 03:00:09
(CEST)</ipgapi:TDateFormatted>
<ipgapi:TerminalID>54000666</ipgapi:TerminalID>
<ipgapi:Secure3DResponse>
<v1:ResponseCode3dSecure>1</v1:ResponseCode3dSecure>
</ipgapi:Secure3DResponse>
</ipgapi:IPGApiOrderResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
In principle, it may occur that 3-D Secure authentications cannot be processed successfully for
technical reasons. If one of the systems involved in the authentication process is temporarily not
responding, the payment transaction will be processed as a “regular” eCommerce transaction (ECI 7).
A liability shift to the card issuer for possible chargebacks is not warranted in this case. If you prefer
that such transactions shall not be processed at all, our technical support team can block them for
your Store on request.

10.1.3 3RI Flow

The main purpose of 3DS Requestor Initiated (3RI) flow is to provide additional information to the
issuer on how to handle the request in situations where the cardholder is not present.
Typical use cases include:
• To add a card to Card-on-File without payment
• To refresh authentication value before expiration
• To provide additional information for subsequent recurring and MIT payments

As 3RI transactions are performed without a cardholder being in session, a frictionless flow without
3DSMethod is applied.

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<ipgapi:IPGApiOrderResponse xmlns:a1="http://ipg-
online.com/ipgapi/schemas/a1" xmlns:ipgapi="http://ipg-
online.com/ipgapi/schemas/ipgapi" xmlns:v1="http://ipg-
online.com/ipgapi/schemas/v1">
<ipgapi:ApprovalCode>Y:309372:4484275011:YYYM:418881</ipgapi:ApprovalCode>
<ipgapi:AVSResponse>YYY</ipgapi:AVSResponse>
<ipgapi:Brand>VISA</ipgapi:Brand>
<ipgapi:CommercialServiceProvider>BOSMS</ipgapi:CommercialServiceProvider>
<ipgapi:OrderId>A-504a5ebf-6424-41af-bfd1-8f9eaca23378</ipgapi:OrderId>
<ipgapi:IpgTransactionId>84484275011</ipgapi:IpgTransactionId>
<ipgapi:PaymentType>CREDITCARD</ipgapi:PaymentType>
<ipgapi:ProcessorApprovalCode>309372</ipgapi:ProcessorApprovalCode>
<ipgapi:ProcessorCCVResponse>M</ipgapi:ProcessorCCVResponse>
<ipgapi:ProcessorReferenceNumber>306016418881</ipgapi:ProcessorReferenceNumber>
<ipgapi:ProcessorResponseCode>00</ipgapi:ProcessorResponseCode>
<ipgapi:ProcessorResponseMessage>Function performed error-
free</ipgapi:ProcessorResponseMessage>
<ipgapi:SchemeTransactionId>234567891234560</ipgapi:SchemeTransactionId>
<ipgapi:TDate>1677686964</ipgapi:TDate>
<ipgapi:TDateFormatted>2023.03.01 17:09:24 (CET)</ipgapi:TDateFormatted>
<ipgapi:TerminalID>80000012</ipgapi:TerminalID>
<ipgapi:TransactionResult>APPROVED</ipgapi:TransactionResult>
<ipgapi:TransactionTime>1677686964</ipgapi:TransactionTime>
<ipgapi:Secure3DResponse>
<v1:ResponseCode3dSecure>1</v1:ResponseCode3dSecure>
</ipgapi:Secure3DResponse>
</ipgapi:IPGApiOrderResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

10.1.4 Decoupled Authentication

Decoupled Authentication is an authentication method whereby authentication can occur independent

from the cardholder’s experience. It may happen that, in a challenge situation, issuers want to reach
out to authenticate their cardholders outside of the EMV 3DS message flows.

Please note, that not all the issuers support decoupled authentication and the processing as described
below demonstrates the case, where this flow is supported.

In the first step you need to indicate, you wish to perform customer authentication using decoupled
flow with including “ThreeDSDecoupledAuthenticationParameters” as highlighted below.

The following XML document represents an example of a decoupled authentication using minimal set
of elements:

</SOAP-ENV:Envelope>ope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<ns4:IPGApiOrderRequest xmlns:ns4="http://ipg-online.com/ipgapi/schemas/ipgapi"
xmlns:ns2="http://ipg-online.com/ipgapi/schemas/v1" xmlns:ns3="http://ipg-
online.com/ipgapi/schemas/a1">
<ns2:Transaction>
<ns2:CreditCardTxType>
<ns2:StoreId>540997003</ns2:StoreId>
<ns2:Type>sale</ns2:Type>
</ns2:CreditCardTxType>
<ns2:CreditCardData>
<ns2:CardNumber>499999****0003</ns2:CardNumber>
<ns2:ExpMonth>12</ns2:ExpMonth>
<ns2:ExpYear>23</ns2:ExpYear>
<ns2:CardCodeValue>XXX</ns2:CardCodeValue>
</ns2:CreditCardData>
<ns2:CreditCard3DSecure>
<ns2:AuthenticateTransaction>true</ns2:AuthenticateTransaction>
<ns2:TermUrl>https://test3.ipg-
online.com/webshop/simulator/secure3d/return</ns2:TermUrl>
<ns2:ThreeDSMethodNotificationURL>https://test3.ipg-
online.com/ipgconfirmation/services/secure3ds</ns2:ThreeDSMethodNotificationURL>
<ns2:ThreeDSRequestorChallengeIndicator>01</ns2:ThreeDSRequestorChallengeIndicator>
<ns2:ThreeDSRequestorChallengeWindowSize>01</ns2:ThreeDSRequestorChallengeWindowSiz
e>
</ns2:CreditCard3DSecure>
<ns2:ThreeDSDecoupledAuthenticationParameters>
<ns2:ThreeDSRequestorDecReqInd>Y</ns2:ThreeDSRequestorDecReqInd>
<ns2:ThreeDSRequestorDecMaxTime>14</ns2:ThreeDSRequestorDecMaxTime>
</ns2:ThreeDSDecoupledAuthenticationParameters>
<ns2:Payment>
<ns2:ChargeTotal>199</ns2:ChargeTotal>
<ns2:Currency>USD</ns2:Currency>
</ns2:Payment>
<ns2:Billing>
<ns2:Phone>001-6642345678</ns2:Phone>
</ns2:Billing>
</ns2:Transaction>
</ns4:IPGApiOrderRequest>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Unlike a standard challenge flow, the customer authentication is performed outside of EMV protocol,
therefore it does not contain CReq and CRes message types.
Transaction remains in waiting status until you submit a request to our Gateway to complete the
authentication.

Once you received the feedback, that you consumers have successfully authenticated themselves,
you must submit API request including parameter “Secure3DAdditionalStep” as on the example
below. It is highly recommended to submit CVV value in the request again, as the Gateway cannot
store it while waiting for a decoupled authentication to be completed.

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<ns3:IPGApiOrderRequest xmlns:ns3="http://ipg-
online.com/ipgapi/schemas/ipgapi" xmlns:ns2="http://ipg-
online.com/ipgapi/schemas/v1" xmlns:ns4="http://ipg-online.com/ipgapi/schemas/a1">
<ns2:Transaction>
<ns2:CreditCardTxType>
<ns2:StoreId>540997003</ns2:StoreId>
<ns2:Type>sale</ns2:Type>
</ns2:CreditCardTxType>
<ns2:CreditCardData>
<ns2:CardCodeValue>XXX</ns2:CardCodeValue>
</ns2:CreditCardData>
<ns2:CreditCard3DSecure>
<ns2:Secure3DAdditionalStep>COMPLETE_DECOUPLED_AUTHENTICATION</ns2:Secure3DAd
ditionalStep>
</ns2:CreditCard3DSecure>
<ns2:Payment/>
<ns2:TransactionDetails>
<ns2:IpgTransactionId>84340519820</ns2:IpgTransactionId>
</ns2:TransactionDetails>
</ns2:Transaction>
</ns3:IPGApiOrderRequest>
</soap:Body>
</soap:Envelope>

Once the Gateway verified the transaction status, you will receive a response as on the example
below:

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<ipgapi:IPGApiOrderResponse
xmlns:a1="http://ipg-online.com/ipgapi/schemas/a1"
xmlns:ipgapi="http://ipg-online.com/ipgapi/schemas/ipgapi"
xmlns:v1="http://ipg-online.com/ipgapi/schemas/v1">
<ipgapi:ApprovalCode>Y:OK1449:4438118015:PPXX:937657</ipgapi:ApprovalCode>
<ipgapi:AVSResponse>PPX</ipgapi:AVSResponse>
<ipgapi:Brand>VISA</ipgapi:Brand>
<ipgapi:CommercialServiceProvider>GMA</ipgapi:CommercialServiceProvider>
<ipgapi:OrderId>A-06510028-eb05-4dc7-8b35-1e41556198d5</ipgapi:OrderId>
<ipgapi:IpgTransactionId>84438118015</ipgapi:IpgTransactionId>
<ipgapi:PaymentType>CREDITCARD</ipgapi:PaymentType>
<ipgapi:ProcessorApprovalCode>OK1449</ipgapi:ProcessorApprovalCode>
<ipgapi:ProcessorCCVResponse>X</ipgapi:ProcessorCCVResponse>
<ipgapi:ProcessorReferenceNumber>84438118015</ipgapi:ProcessorReferenceNumber>
<ipgapi:ProcessorResponseCode>00</ipgapi:ProcessorResponseCode>
<ipgapi:ProcessorNetworkInformation>VISA</ipgapi:ProcessorNetworkInformation>
<ipgapi:ProcessorAssociationResponseCode>000</ipgapi:ProcessorAssociationResponseCo
de>
<ipgapi:ProcessorResponseMessage>APPROVAL</ipgapi:ProcessorResponseMessage>
<ipgapi:SchemeTransactionId>013144535118039</ipgapi:SchemeTransactionId>
<ipgapi:TDate>1684903630</ipgapi:TDate>
<ipgapi:TDateFormatted>2023.05.24 06:47:10 (CEST)</ipgapi:TDateFormatted>
<ipgapi:TerminalID>1588390</ipgapi:TerminalID>
<ipgapi:TransactionResult>APPROVED</ipgapi:TransactionResult>
<ipgapi:TransactionTime>1684903630</ipgapi:TransactionTime>
<ipgapi:Secure3DResponse>
<v1:ResponseCode3dSecure>1</v1:ResponseCode3dSecure>
</ipgapi:Secure3DResponse>
</ipgapi:IPGApiOrderResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

10.1.5 Fallback to 3DSv1

Please note, that since October 2022 the 3DS v1.0.2 has been decommissioned for all major
international brands worldwide except for merchants located in India, Bangladesh and Sri Lanka.
For all other countries 3DS v1 is no longer supported by major international brands.

For cases, where issuers do not support EMV 3DS protocol, the Gateway provides an option to
“downgrade” to 3DS 1.0 authentication instead.

In the first step you submit Sale transaction request as you would for 3DS v2:

<?xml version="1.0" encoding="UTF-8"?><SOAP-ENV:Envelope xmlns:SOAP-

ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<ns3:IPGApiOrderRequest
xmlns:ns3="http://ipg-online.com/ipgapi/schemas/ipgapi"
xmlns:ns2="http://ipg-online.com/ipgapi/schemas/v1"
xmlns:ns4="http://ipg-online.com/ipgapi/schemas/a1">
<ns2:Transaction>
<ns2:CreditCardTxType>
<ns2:StoreId>120995000</ns2:StoreId>
<ns2:Type>sale</ns2:Type>
</ns2:CreditCardTxType>
<ns2:CreditCardData>
<ns2:CardNumber>542606XXXXXX4979</ns2:CardNumber>
<ns2:ExpMonth>12</ns2:ExpMonth>
<ns2:ExpYear>33</ns2:ExpYear>
<ns2:CardCodeValue>XXX</ns2:CardCodeValue>
</ns2:CreditCardData>
<ns2:CreditCard3DSecure>
<ns2:AuthenticateTransaction>true</ns2:AuthenticateTransaction>
<ns2:TermUrl>https://www.mywebshop.com/process3dSecure</ns2:TermUrl>
<ns2:ThreeDSMethodNotificationURL>https://www.mywebshop.com/process3dSecureMethodNo
tification</ns2:ThreeDSMethodNotificationURL>
<ns2:ThreeDSRequestorChallengeIndicator>1</ns2:ThreeDSRequestorChallengeIndicator>
</ns2:CreditCard3DSecure>
<ns2:Payment>
<ns2:ChargeTotal>13.99</ns2:ChargeTotal>
<ns2:Currency>978</ns2:Currency>
</ns2:Payment>
</ns2:Transaction>
</ns3:IPGApiOrderRequest>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

As soon as our 3DS Server identifies, that used credit card is not eligible for EMV 3DS protocol, the
Gateway automatically initiates fallback request and redirects to the dedicated DS. The Gateway then
checks the card participation from the 3-D Secure directory and returns the redirection URL of the
card issuer’s Access Control Server (ACS).
If the card is enrolled in 3-D Secure 1.0, the response contains the following key values:
• PaReq: The Payer Authentication Request, required to initiate the authentication
• ACS URL: The target of 3D Secure redirection
• Term URL: The URL, that the ACS should send the outcome to in your application
• MD: Merchant Data which have to be sent to ACS URL
Please note, that there might be cases, when MD element is not present in the response and its
presence does not have to be validated in the next step.

The following represents an example of a response:

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

<ipgapi:IPGApiOrderResponse
xmlns:ipgapi="http://ipg-online.com/ipgapi/schemas/ipgapi"
xmlns:a1=http://ipg-online.com/ipgapi/schemas/a1
xmlns:v1="http://ipg-online.com/ipgapi/schemas/v1">
<ipgapi:ApprovalCode>?:waiting 3dsecure</ipgapi:ApprovalCode>
<ipgapi:Brand>MASTERCARD</ipgapi:Brand>
<ipgapi:Country>DEU</ipgapi:Country>
<ipgapi:CommercialServiceProvider>TELECASH
</ipgapi:CommercialServiceProvider>
<ipgapi:OrderId>A-9278d36a-0cb1-4b6a-918b-34c723c41c6a</ipgapi:OrderId>
<ipgapi:IpgTransactionId>84514040874</ipgapi:IpgTransactionId>
<ipgapi:PaymentType>CREDITCARD</ipgapi:PaymentType>
<ipgapi:TDate>1505997548</ipgapi:TDate>
<ipgapi:TDateFormatted>2017.09.21 14:39:08 (CEST)
</ipgapi:TDateFormatted>
<ipgapi:TransactionTime>1505997548</ipgapi:TransactionTime>
<ipgapi:Secure3DResponse>
<v1:Secure3DVerificationResponse>
<v1:VerificationRedirectResponse>
<v1:AcsURL>https://3ds-acs.test.com/mdpayacs/pareq</v1:AcsURL>
<v1:PaReq>eJxVUslugzAQ……….lqLXbOUx691d/</v1:PaReq>
<v1:TermUrl>https://www.mywebshop.com/..</v1:TermUrl>
<v1:MD>MD_120020170921123……f1f3-4768-998f </v1:MD>
</v1:VerificationRedirectResponse>
</v1:Secure3DVerificationResponse>
</ipgapi:Secure3DResponse>
</ipgapi:IPGApiOrderResponse>

After you have redirected the cardholder for authentication and have received the payer authentication
response (PARes) from the card issuer, you submit the PARes and MD (if present) in your next
request to our API:

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

<ipg:IPGApiOrderRequest xmlns:ipg="http://ipg-online.com/ipgapi/schemas/ipgapi">
<v1:Transaction xmlns:v1="http://ipg-online.com/ipgapi/schemas/v1">
<v1:CreditCardTxType>
<v1:StoreId>120995000</v1:StoreId>
<v1:Type>sale</v1:Type>
</v1:CreditCardTxType>
<v1:CreditCard3DSecure>
<v1:Secure3DRequest>
<v1:Secure3DAuthenticationRequest>
<v1:AcsResponse>
<v1:MD>MD09211deP2Yur……8b64-f1f3-4768-998f</v1:MD>
<v1:PaRes>eJzVWE.....v9/X/Lq/P8ARjWe/A==</v1:PaRes>
</v1:AcsResponse>
</v1:Secure3DAuthenticationRequest>
</v1:Secure3DRequest>
</v1:CreditCard3DSecure>
<v1:TransactionDetails>
<v1:IpgTransactionId>84514043377</v1:IpgTransactionId>
</v1:TransactionDetails>
</v1:Transaction>
</ipg:IPGApiOrderRequest>

Our Gateway verifies the response and provides the result back to you:

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

xmlns:ipgapi="http://ipg-online.com/ipgapi/schemas/ipgapi"
xmlns:a1="http://ipg-online.com/ipgapi/schemas/a1"
xmlns:v1="http://ipg-online.com/ipgapi/schemas/v1">
<ipgapi:ApprovalCode>Y:282266:8385028528:PPXM:3056131932</ipgapi:ApprovalCode>
<ipgapi:AVSResponse>PPX</ipgapi:AVSResponse>
<ipgapi:Brand>VISA</ipgapi:Brand>
<ipgapi:Country>USA</ipgapi:Country>
<ipgapi:CommercialServiceProvider>TELECASH</ipgapi:CommercialServiceProvider>
<ipgapi:OrderId>API-Test-Order123456789</ipgapi:OrderId>
<ipgapi:IpgTransactionId>8385028528</ipgapi:IpgTransactionId>
<ipgapi:PaymentType>CREDITCARD</ipgapi:PaymentType>
<ipgapi:ProcessorApprovalCode>282266</ipgapi:ProcessorApprovalCode>
<ipgapi:ProcessorReceiptNumber>1932</ipgapi:ProcessorReceiptNumber>
<ipgapi:ProcessorCCVResponse>M</ipgapi:ProcessorCCVResponse>
<ipgapi:ProcessorReferenceNumber>55063291</ipgapi:ProcessorReferenceNumber>
<ipgapi:ProcessorResponseCode>00</ipgapi:ProcessorResponseCode>
<ipgapi:ProcessorResponseMessage>Function performed error-
free</ipgapi:ProcessorResponseMessage>
<ipgapi:ProcessorTraceNumber>305613</ipgapi:ProcessorTraceNumber>
<ipgapi:TDate>1553773696</ipgapi:TDate>
<ipgapi:TDateFormatted>2019.03.28 12:48:16 (CET)</ipgapi:TDateFormatted>
<ipgapi:TerminalID>54000668</ipgapi:TerminalID>
<ipgapi:TransactionResult>APPROVED</ipgapi:TransactionResult>
<ipgapi:TransactionTime>1553773696</ipgapi:TransactionTime>
<ipgapi:Secure3DResponse>
<v1:ResponseCode3dSecure>1</v1:ResponseCode3dSecure>
</ipgapi:Secure3DResponse>
</ipgapi:IPGApiOrderResponse>

10.2 Authentication with external 3DS Service provider

In case you are using your own or external 3DS Service provider and plan to send authorization
request to the Gateway, you need to submit the authentication values obtained from your 3DS
Service provider.

The following XML document represents an example of a sale transaction submitted to our Gateway
after being fully authenticated by an external service provider:

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

xmlns:ns4="http://ipg-online.com/ipgapi/schemas/ipgapi"
xmlns:ns2="http://ipg-online.com/ipgapi/schemas/a1"
xmlns:ns3="http://ipg-online.com/ipgapi/schemas/v1">
<ns3:Transaction>
<ns3:CreditCardTxType>
<ns3:Type>sale</ns3:Type>
</ns3:CreditCardTxType>
<ns3:CreditCardData>
<ns3:CardNumber>403587XXXXXX4977</ns3:CardNumber>
<ns3:ExpMonth>12</ns3:ExpMonth>
<ns3:ExpYear>27</ns3:ExpYear>
<ns3:CardCodeValue>XXX</ns3:CardCodeValue>
</ns3:CreditCardData>
<ns3:CreditCard3DSecure>
<ns3:AuthenticationValue>xgQO57LRAAAAAAAAAA=</ns3:AuthenticationValue>
<ns3:Secure3D2TransactionStatus>Y</ns3:Secure3D2TransactionStatus>
<ns3:Secure3D2AuthenticationResponse>Y</ns3:Secure3D2AuthenticationResponse>
<ns3:Secure3DProtocolVersion>2.1.0</ns3:Secure3DProtocolVersion>
<ns3:DirectoryServerTransactionId>925a0317-9143-5130-8000-0000000f8742
</ns3:DirectoryServerTransactionId>
</ns3:CreditCard3DSecure>
<ns3:Payment>
<ns3:ChargeTotal>1.00</ns3:ChargeTotal>
<ns3:Currency>978</ns3:Currency>
</ns3:Payment>
<ns3:TransactionDetails>
<ns3:OrderId>API-Test-Order123456789</ns3:OrderId>
</ns3:TransactionDetails>
</ns3:Transaction>
</ns4:IPGApiOrderRequest>

The following XML document represents an example of a response:

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

xmlns:ipgapi="http://ipg-online.com/ipgapi/schemas/ipgapi"
xmlns:a1="http://ipg-online.com/ipgapi/schemas/a1"
xmlns:v1="http://ipg-online.com/ipgapi/schemas/v1">
<ipgapi:ApprovalCode>Y:282266:8385028528:PPXM:3056131932</ipgapi:ApprovalCode>
<ipgapi:AVSResponse>PPX</ipgapi:AVSResponse>
<ipgapi:Brand>VISA</ipgapi:Brand>
<ipgapi:Country>USA</ipgapi:Country>
<ipgapi:CommercialServiceProvider>TELECASH</ipgapi:CommercialServiceProvider>
<ipgapi:OrderId>API-Test-Order123456789</ipgapi:OrderId>
<ipgapi:IpgTransactionId>8385028528</ipgapi:IpgTransactionId>
<ipgapi:PaymentType>CREDITCARD</ipgapi:PaymentType>
<ipgapi:ProcessorApprovalCode>282266</ipgapi:ProcessorApprovalCode>
<ipgapi:ProcessorReceiptNumber>1932</ipgapi:ProcessorReceiptNumber>
<ipgapi:ProcessorCCVResponse>M</ipgapi:ProcessorCCVResponse>
<ipgapi:ProcessorReferenceNumber>55063291</ipgapi:ProcessorReferenceNumber>
<ipgapi:ProcessorResponseCode>00</ipgapi:ProcessorResponseCode>
<ipgapi:ProcessorResponseMessage>Function performed error-
free</ipgapi:ProcessorResponseMessage>
<ipgapi:ProcessorTraceNumber>305613</ipgapi:ProcessorTraceNumber>
<ipgapi:TDate>1553773696</ipgapi:TDate>
<ipgapi:TDateFormatted>2019.03.28 12:48:16 (CET)</ipgapi:TDateFormatted>
<ipgapi:TerminalID>54000668</ipgapi:TerminalID>
<ipgapi:TransactionResult>APPROVED</ipgapi:TransactionResult>
<ipgapi:TransactionTime>1553773696</ipgapi:TransactionTime>
<ipgapi:Secure3DResponse>
<v1:ResponseCode3dSecure>1</v1:ResponseCode3dSecure>
</ipgapi:Secure3DResponse>
</ipgapi:IPGApiOrderResponse>

The following XML document represents an example of a sale transaction submitted to our Gateway
after successful authentication attempt:

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

xmlns:ns4="http://ipg-online.com/ipgapi/schemas/ipgapi"
xmlns:ns2="http://ipg-online.com/ipgapi/schemas/a1"
xmlns:ns3="http://ipg-online.com/ipgapi/schemas/v1">
<ns3:Transaction>
<ns3:CreditCardTxType>
<ns3:Type>sale</ns3:Type>
</ns3:CreditCardTxType>
<ns3:CreditCardData>
<ns3:CardNumber>403587XXXXXX4977</ns3:CardNumber>
<ns3:ExpMonth>12</ns3:ExpMonth>
<ns3:ExpYear>27</ns3:ExpYear>
<ns3:CardCodeValue>XXX</ns3:CardCodeValue>
</ns3:CreditCardData>
<ns3:CreditCard3DSecure>
<ns3:AuthenticationValue>xgQO57LRAAAAAAA=</ns3:AuthenticationValue>
<ns3:Secure3D2AuthenticationResponse>A</ns3:Secure3D2AuthenticationResponse>
<ns3:Secure3DProtocolVersion>2.1.0</ns3:Secure3DProtocolVersion>
<ns3:DirectoryServerTransactionId>123456</ns3:DirectoryServerTransactionId>
</ns3:CreditCard3DSecure>
<ns3:Payment>
<ns3:ChargeTotal>1.00</ns3:ChargeTotal>
<ns3:Currency>978</ns3:Currency>
</ns3:Payment>
<ns3:TransactionDetails>
<ns3:OrderId>API-Test-Order12345678910</ns3:OrderId>
</ns3:TransactionDetails>
</ns3:Transaction>
</ns4:IPGApiOrderRequest>

The following XML document represents an example of a response:

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

xmlns:ipgapi="http://ipg-online.com/ipgapi/schemas/ipgapi"
xmlns:a1="http://ipg-online.com/ipgapi/schemas/a1"
xmlns:v1="http://ipg-online.com/ipgapi/schemas/v1">
<ipgapi:ApprovalCode>Y:282266:8385028528:PPXM:3056131932</ipgapi:ApprovalCode>
<ipgapi:AVSResponse>PPX</ipgapi:AVSResponse>
<ipgapi:Brand>VISA</ipgapi:Brand>
<ipgapi:Country>USA</ipgapi:Country>
<ipgapi:CommercialServiceProvider>TELECASH</ipgapi:CommercialServiceProvider>
<ipgapi:OrderId>API-Test-Order12345678910</ipgapi:OrderId>
<ipgapi:IpgTransactionId>8385028528</ipgapi:IpgTransactionId>
<ipgapi:PaymentType>CREDITCARD</ipgapi:PaymentType>
<ipgapi:ProcessorApprovalCode>282266</ipgapi:ProcessorApprovalCode>
<ipgapi:ProcessorReceiptNumber>1932</ipgapi:ProcessorReceiptNumber>
<ipgapi:ProcessorCCVResponse>M</ipgapi:ProcessorCCVResponse>
<ipgapi:ProcessorReferenceNumber>55063291</ipgapi:ProcessorReferenceNumber>
<ipgapi:ProcessorResponseCode>00</ipgapi:ProcessorResponseCode>
<ipgapi:ProcessorResponseMessage>Function performed error-
free</ipgapi:ProcessorResponseMessage>
<ipgapi:ProcessorTraceNumber>305613</ipgapi:ProcessorTraceNumber>
<ipgapi:TDate>1553773696</ipgapi:TDate>
<ipgapi:TDateFormatted>2019.03.28 12:48:16 (CET)</ipgapi:TDateFormatted>
<ipgapi:TerminalID>54000668</ipgapi:TerminalID>
<ipgapi:TransactionResult>APPROVED</ipgapi:TransactionResult>
<ipgapi:TransactionTime>1553773696</ipgapi:TransactionTime>
<ipgapi:Secure3DResponse>
<v1:ResponseCode3dSecure>4</v1:ResponseCode3dSecure>
</ipgapi:Secure3DResponse>
</ipgapi:IPGApiOrderResponse>

The following ‘Secure3D2AuthenticationResponse’ element values are available:

Y = Authentication successful
U = Authentication could not be performed due to technical or other problem on DS or ACS side
A = Attempts processing performed; not authenticated, but a proof of attempted authentication is
provided

Please note, that failed or rejected authentications are not allowed to be passed to the authorization
platform and will be declined by the Gateway.

IPG3dsecu
Secure3D2 Secure3D2 Authenticati
re
Use Case Authenticati TransactionSta onValue Gateway action
response
onResponse tus (CAVV/AAV)
code
Fully authenticated
transaction the authorization message is sent to the
Y Y Value 1
(ECI2, ECI5) authorization host

Successful Attempt to
authenticate the Field Must Not The authorization message is sent to the
A Value 4
cardholder Be Submitted authorization host
(ECI1, ECI6)

Unable to authenticate Field Must The authorization message is sent to the

Field Must Not
due to issue on DS or U Not Be 6 authorization host, if ECI7 transactions
Be Submitted
ACS side (ECI7) Submitted are not blocked in store configuration
10.3 Non-Payment Authentication (NPA)

For cases, where you prefer to register your customers’ credit cards on file without charging them in
the same session, you can submit a payerAuth request to our Gateway with a value ‘02’ in
“threeDSEmvCoMessageCategory” element.
As it is mandatory to use Strong Customer Authentication (SCA) for all new cards added to Card-On-
File, NPA transaction request must include “ThreeDSRequestorChallengeIndicator” value ’04’ and
“ThreeDSRequestorAuthenticationIndicator” value ‘04=Add card’.

The following represents an example of a ‘payerAuth’ request with basic set of elements:

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

After this request a standard EMV 3-D Secure authentication flow as described in chapter 10.1
Authentication with Fiserv as your 3DS provider follows and is completed with a final ‘payerAuth’
response:

Please note, that fully authenticated NPA cannot be used as a proof of authentication for any
subsequent transactions and serves only to verify identity of your clients while adding their card on
file.

10.4 Split Authentication

If your business or technical processes require the cardholder authentication to be separated from the
payment transaction (authorization), you can use the transaction type “payer_auth”. This transaction
type only performs the authentication and stores the authentication results.

The following represents an example of a ‘payerAuth’ request with minimal set of elements:

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

For cases where a frictionless flow has been performed you will receive the following response
directly:

For cases where a challenge flow has been requested, please follow the process as described in
chapter “10.1 Authentication with Fiserv as your 3DS provider” of this guide.

In a second step, you can then submit the payment transaction (sale or preauth) and reference to the
prior authentication using the ‘igpTransactionId’ from the payerAuth response.

The following XML document represents an example of a “sale” request with minimal set of
elements:

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

The following XML document represents an example of the response:

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<ipgapi:IPGApiOrderResponse
xmlns:a1="http://ipg-online.com/ipgapi/schemas/a1"
xmlns:ipgapi="http://ipg-online.com/ipgapi/schemas/ipgapi"
xmlns:v1="http://ipg-online.com/ipgapi/schemas/v1">
<ipgapi:ApprovalCode>Y:245155:4484283852:YYYM:419397</ipgapi:ApprovalCode>
<ipgapi:AVSResponse>YYY</ipgapi:AVSResponse>
<ipgapi:Brand>VISA</ipgapi:Brand>
<ipgapi:CommercialServiceProvider>BOSMS</ipgapi:CommercialServiceProvider>
<ipgapi:OrderId>A-5f2b2d63-024a-47a7-abc2-c13b3c5afb80</ipgapi:OrderId>
<ipgapi:IpgTransactionId>84484279058</ipgapi:IpgTransactionId>
<ipgapi:PaymentType>CREDITCARD</ipgapi:PaymentType>
<ipgapi:ProcessorApprovalCode>245155</ipgapi:ProcessorApprovalCode>
<ipgapi:ProcessorCCVResponse>M</ipgapi:ProcessorCCVResponse>
<ipgapi:ProcessorReferenceNumber>306209419397</ipgapi:ProcessorReferenceNumber>
<ipgapi:ProcessorResponseCode>00</ipgapi:ProcessorResponseCode>
<ipgapi:ProcessorResponseMessage>Function performed error-
free</ipgapi:ProcessorResponseMessage>
<ipgapi:SchemeTransactionId>234567891234560</ipgapi:SchemeTransactionId>
<ipgapi:TDate>1677836064</ipgapi:TDate>
<ipgapi:TDateFormatted>2023.03.03 10:34:24 (CET)</ipgapi:TDateFormatted>
<ipgapi:TerminalID>80000012</ipgapi:TerminalID>
<ipgapi:TransactionResult>APPROVED</ipgapi:TransactionResult>
<ipgapi:TransactionTime>1677836064</ipgapi:TransactionTime>
<ipgapi:Secure3DResponse>
<v1:ResponseCode3dSecure>1</v1:ResponseCode3dSecure>
</ipgapi:Secure3DResponse>
</ipgapi:IPGApiOrderResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

11 Purchasing cards

Purchasing Cards offer businesses the ability to allow their employees to purchase items with a credit
card while providing additional information on sales tax, customer code etc. When providing specific
details on the payment being made with a Purchasing card favourable addendum interchange rates
are applied.

There are three levels of details required for Purchasing Cards:

• Level I — The first level is the standard transaction data; no enhanced data is required at this
level.
• Level II — The second level requires that data such as tax amount and customer code be
supplied in addition to the standard transaction date. (Visa only have a level II option)
• Level III — The third level allows a merchant to pass a detailed accounting of goods and
services purchased to the buyer. All the data for Level I and Level II must also be passed to
participate in Level III. (Visa and Mastercard).

PurchaseCard element can contain contain 0-100 LineItemData elements.

Detailed description of all PurchaseCard elements can be found in the XML-Tag overview chapter of
this document.

The following represents an example of a purchasing card L3 transaction including a single

LineItemData element and mandatory fields:

<?xml version="1.0" encoding="UTF-8"?><SOAP-ENV:Envelope xmlns:SOAP-

ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<ns4:IPGApiOrderRequest
xmlns:ns4="http://ipg-online.com/ipgapi/schemas/ipgapi"
xmlns:ns2="http://ipg-online.com/ipgapi/schemas/a1"
xmlns:ns3="http://ipg-online.com/ipgapi/schemas/v1">
<ns3:Transaction>
<ns3:CreditCardTxType>
<ns3:StoreId>110995100</ns3:StoreId>
<ns3:Type>sale</ns3:Type>
</ns3:CreditCardTxType>
<ns3:CreditCardData>
<ns3:CardNumber>4035*****4977</ns3:CardNumber>
<ns3:ExpMonth>12</ns3:ExpMonth>
<ns3:ExpYear>28</ns3:ExpYear>
<ns3:CardCodeValue>XXX</ns3:CardCodeValue>
</ns3:CreditCardData>
<ns3:Payment>
<ns3:ChargeTotal>23</ns3:ChargeTotal>
<ns3:Currency>GBP</ns3:Currency>
</ns3:Payment>
<ns3:TransactionDetails>
<ns3:PurchaseCard>
<ns3:CustomerReferenceID>9632587410</ns3:CustomerReferenceID>
<ns3:SupplierInvoiceNumber>321456987</ns3:SupplierInvoiceNumber>
<ns3:SupplierVATRegistrationNumber>GB18150620</ns3:SupplierVATRe
gistrationNumber>
<ns3:LineItemData>
<ns3:CommodityCode>0</ns3:CommodityCode>
<ns3:Description>DIRECT MARKETING PURCH</ns3:Description>
<ns3:Quantity>200000</ns3:Quantity>
<ns3:UnitOfMeasure>TPR</ns3:UnitOfMeasure>
<ns3:UnitPrice>1200</ns3:UnitPrice>
<ns3:LineItemTotal>1200</ns3:LineItemTotal>
</ns3:LineItemData>
</ns3:PurchaseCard>
</ns3:TransactionDetails>
</ns3:Transaction>
</ns4:IPGApiOrderRequest>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

If LineItemData element were removed, the example above would represent a purchasing card level
II transaction.

The following represents an example of a purchasing card Level III transaction including multipule
LineItemData elements with all possible fields populated:

<?xml version="1.0" encoding="UTF-8"?><SOAP-ENV:Envelope

xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<ns3:IPGApiOrderRequest
xmlns:ns3="http://ipg-online.com/ipgapi/schemas/ipgapi"
xmlns:ns2="http://ipg-online.com/ipgapi/schemas/v1"
xmlns:ns4="http://ipg-online.com/ipgapi/schemas/a1">
<ns2:Transaction>
<ns2:CreditCardTxType>
<ns2:StoreId>110995100</ns2:StoreId>
<ns2:Type>preAuth</ns2:Type>
</ns2:CreditCardTxType>
<ns2:CreditCardData>
<ns2:CardNumber>4035*****4977</ns2:CardNumber>
<ns2:ExpMonth>12</ns2:ExpMonth>
<ns2:ExpYear>28</ns2:ExpYear>
<ns2:CardCodeValue>XXX</ns2:CardCodeValue>
</ns2:CreditCardData>
<ns2:Payment>
<ns2:SubTotal>15</ns2:SubTotal>
<ns2:ValueAddedTax>4</ns2:ValueAddedTax>
<ns2:DeliveryAmount>5</ns2:DeliveryAmount>
<ns2:ChargeTotal>24</ns2:ChargeTotal>
<ns2:Currency>GBP</ns2:Currency>
</ns2:Payment>
<ns2:TransactionDetails>
<ns2:PurchaseCard>
<ns2:CustomerReferenceID>9632587410</ns2:CustomerReferenceID>
<ns2:SupplierInvoiceNumber>321456987</ns2:SupplierInvoiceNumber>
<ns2:SupplierVATRegistrationNumber>GB1820</ns2:SupplierVATRegistrationNumber>
<ns2:TotalDiscountAmountAndRate>
<ns2:Amount>55</ns2:Amount>
<ns2:Rate>99.99</ns2:Rate>
</ns2:TotalDiscountAmountAndRate>
<ns2:VATShippingAmountAndRate>
<ns2:Amount>35</ns2:Amount>
<ns2:Rate>0.10</ns2:Rate>
</ns2:VATShippingAmountAndRate>
<ns2:LineItemData>
<ns2:CommodityCode>1112</ns2:CommodityCode>
<ns2:ProductCode>22369852147</ns2:ProductCode>
<ns2:Description>DIRECTMARKETINGPURCH</ns2:Description>
<ns2:Quantity>200000</ns2:Quantity>
<ns2:UnitOfMeasure>TPR</ns2:UnitOfMeasure>
<ns2:UnitPrice>1200</ns2:UnitPrice>
<ns2:VATAmountAndRate>
<ns2:Amount>9999</ns2:Amount>
<ns2:Rate>0.1</ns2:Rate>
</ns2:VATAmountAndRate>
<ns2:DiscountAmountAndRate>
<ns2:Amount>13</ns2:Amount>
<ns2:Rate>99.99</ns2:Rate>
</ns2:DiscountAmountAndRate>
<ns2:LineItemTotal>1200</ns2:LineItemTotal>
</ns2:LineItemData>
<ns2:LineItemData>
<ns2:CommodityCode>5647</ns2:CommodityCode>
<ns2:ProductCode>22369852148</ns2:ProductCode>
<ns2:Description>DIRECTMARKETINGPURCH</ns2:Description>
<ns2:Quantity>200001</ns2:Quantity>
<ns2:UnitOfMeasure>DAY</ns2:UnitOfMeasure>
<ns2:UnitPrice>1201</ns2:UnitPrice>
<ns2:VATAmountAndRate>
<ns2:Amount>9999</ns2:Amount>
<ns2:Rate>0.2</ns2:Rate>
</ns2:VATAmountAndRate>
<ns2:DiscountAmountAndRate>
<ns2:Amount>14</ns2:Amount>
<ns2:Rate>99.99</ns2:Rate>
</ns2:DiscountAmountAndRate>
<ns2:LineItemTotal>1202</ns2:LineItemTotal>
</ns2:LineItemData>
<ns2:LineItemData>
<ns2:CommodityCode>575</ns2:CommodityCode>
<ns2:ProductCode>22369852149</ns2:ProductCode>
<ns2:Description>DIRECTMARKETINGPURCH</ns2:Description>
<ns2:Quantity>200002</ns2:Quantity>
<ns2:UnitOfMeasure>ACR</ns2:UnitOfMeasure>
<ns2:UnitPrice>1203</ns2:UnitPrice>
<ns2:VATAmountAndRate>
<ns2:Amount>9999</ns2:Amount>
<ns2:Rate>0.3</ns2:Rate>
</ns2:VATAmountAndRate>
<ns2:DiscountAmountAndRate>
<ns2:Amount>15</ns2:Amount>
<ns2:Rate>99.99</ns2:Rate>
</ns2:DiscountAmountAndRate>
<ns2:LineItemTotal>1204</ns2:LineItemTotal>
</ns2:LineItemData>
</ns2:PurchaseCard>
</ns2:TransactionDetails>
</ns2:Transaction>
</ns3:IPGApiOrderRequest>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

12 Network Tokenisation

Network tokens are surrogate values that replace Primary Account Number (PAN) stored
electronically throughout the payments system. Network Tokens can be used to conduct payment
transactions securely and can provide improved protection against fraud, because network tokens can
require cryptogram validation or be limited to use in a specific domain or circumstance, such as token
requestor, device or channel.

In order to utilize network tokens, it is necessary to change predefined value of the Data Vault service
configuration item “tokenProvider” to “networkToken”. Please contact your boarding team or
customer support team to manage the setup for you.

NOTE: In case you are located in India, due to compliance requirements you need to obtain and
capture customer’s consent and perform Strong Customer Authentication (SCA) before customer’s
credit card is tokenized. You can authenticate your customer by using a 3-D Secure request followed
by successful authorization which thereby provides you with the permission to request a network
token.

12.1 Network Token Generation

In order to request a network token to store the credit card information you used in the previous step
in which the customer consent was captured, you need to send an action request to the Gateway and
provide ‘OrderId’ and ‘HostedDataID’ of this transaction.

The following XML document represents an example of a request including your own ‘HostedDataID’:
<ns4:IPGApiActionRequest
xmlns:ns4="http://ipg-online.com/ipgapi/schemas/ipgapi"
xmlns:ns2="http://ipg-online.com/ipgapi/schemas/a1"
xmlns:ns3="http://ipg-online.com/ipgapi/schemas/v1">
<ns2:Action>
<ns2:StoreHostedData>
<ns2:StoreId>330115006</ns2:StoreId>
<ns2:DataStorageItem>
<ns2:OrderId>C-bd4e8baa-b2310cc20eb0</ns2:OrderId>
<ns2:HostedDataID>test123</ns2:HostedDataID>
</ns2:DataStorageItem>
</ns2:StoreHostedData>
</ns2:Action>
</ns4:IPGApiActionRequest>
A network token is provisioned by the Gateway for the card data used in submitted ‘OrderId’ and
linked to the ‘HostedDataID’ you have provided in the previous request. The call to retrieve a token
from the schemes is made by our system automatically.

You will be provided with a response, if the request has been completed successfully:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<ipgapi:IPGApiActionResponse
xmlns:a1="http://ipg-online.com/ipgapi/schemas/a1"
xmlns:ipgapi="http://ipg-online.com/ipgapi/schemas/ipgapi"
xmlns:v1="http://ipg-online.com/ipgapi/schemas/v1">
<ipgapi:successfully>true</ipgapi:successfully>
</ipgapi:IPGApiActionResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

In case you do not wish to define your own ‘HostedDataID’ in your token provisioning request, the
Gateway will generate its value for you and you will obtain it in the API response.

The following XML document represents an example of a request without submitted ‘HostedDataID’ :

<ns4:IPGApiActionRequest
xmlns:ns4="http://ipg-online.com/ipgapi/schemas/ipgapi"
xmlns:ns2="http://ipg-online.com/ipgapi/schemas/a1"
xmlns:ns3="http://ipg-online.com/ipgapi/schemas/v1">
<ns2:Action>
<ns2:StoreHostedData>
<ns2:StoreId>330115006</ns2:StoreId>
<ns2:DataStorageItem>
<ns2:OrderId>C-bd4e8baa-b2310cc20eb0</ns2:OrderId>
<ns2:AssignToken>true</ns2:AssignToken>
</ns2:DataStorageItem>
</ns2:StoreHostedData>
</ns2:Action>
</ns4:IPGApiActionRequest>

The following XML document represents an example of the response including generated
‘HostedDataID’:

You can use the ‘HostedDataID’ linked to a network token for further transaction processing.
12.2 Initiate a payment transaction using HostedDataId

With generated ‘HostedDataID’ you can perform transactions without the need to pass the credit card
or bank account data again.
Please note, that it is not allowed to store the card code (in most cases on the back of the card) so
that for credit card transactions, the cardholder still needs to enter this value.

12.3 Initiate payment transaction using Network Token and Cryptogram

You can also perform a transaction using network token and cryptogram instead of using
HostedDataID. Network token and a cryptogram will be provided in the API response after you
submitted the following action request to the Gateway:

The following XML document represents the example of the response including associated credit
card details, token number and token cryptogram.
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<ipgapi:IPGApiActionResponse
xmlns:a1="http://ipg-online.com/ipgapi/schemas/a1"
xmlns:ipgapi="http://ipg-online.com/ipgapi/schemas/ipgapi"
xmlns:v1="http://ipg-online.com/ipgapi/schemas/v1">
<ipgapi:successfully>true</ipgapi:successfully>
<ipgapi:NetworkTokenData>
<v1:NetworkTokenNumber>5204XXXX80216</v1:NetworkTokenNumber>
<v1:ExpMonth>12</v1:ExpMonth>
<v1:ExpYear>24</v1:ExpYear>
<v1:CardLast4>3006</v1:CardLast4>
<v1:Brand>MASTERCARD</v1:Brand>
<v1:TokenCryptogram>AJ0BWvQntOkiAAHFcGgADFA==</v1:TokenCryptogram>
</ipgapi:NetworkTokenData>
</ipgapi:IPGApiActionResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Received data can be used to trigger a sale or preauth request.

A payment transaction using network token can be initiated by submitting the network token number
you received in previous API response as a value of the element ‘CardNumber’ and the expiry date of
the credit card replaced by the network token expiry. It is important to include the ‘TokenCryptogram’
in the request as well.

The following XML document represents an example of a Sale transaction using network token and
token cryptogram elements:

The following XML document represents an example of the API response:

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<ipgapi:IPGApiOrderResponse
xmlns:a1="http://ipg-online.com/ipgapi/schemas/a1"
xmlns:ipgapi="http://ipg-online.com/ipgapi/schemas/ipgapi"
xmlns:v1="http://ipg-online.com/ipgapi/schemas/v1">
<ipgapi:ApprovalCode>Y:006953:4381648535:PPX:113009626785</ipgapi:ApprovalCode>
<ipgapi:AVSResponse>PPX</ipgapi:AVSResponse>
<ipgapi:Brand>MASTERCARD</ipgapi:Brand>
<ipgapi:CommercialServiceProvider>IMS</ipgapi:CommercialServiceProvider>
<ipgapi:OrderId>A-d47b2da7-f64d-475f-8d1f-75be94d1419b</ipgapi:OrderId>
<ipgapi:IpgTransactionId>84381648535</ipgapi:IpgTransactionId>
<ipgapi:PaymentType>CREDITCARD</ipgapi:PaymentType>
<ipgapi:ProcessorApprovalCode>006953</ipgapi:ProcessorApprovalCode>
<ipgapi:ProcessorReferenceNumber>113009626785</ipgapi:ProcessorReferenceNumber>
<ipgapi:ProcessorResponseCode>00</ipgapi:ProcessorResponseCode>
<ipgapi:ProcessorResponseMessage>Function performed error-
free</ipgapi:ProcessorResponseMessage>
<ipgapi:TDate>1638266046</ipgapi:TDate>
<ipgapi:TDateFormatted>2021.11.30 10:54:06 (CET)</ipgapi:TDateFormatted>
<ipgapi:TerminalID>12345678</ipgapi:TerminalID>
<ipgapi:TransactionResult>APPROVED</ipgapi:TransactionResult>
<ipgapi:TransactionTime>1638266046</ipgapi:TransactionTime>
</ipgapi:IPGApiOrderResponse>

Please note, that in case you are located in European Union or India, you are mandated to perform
3-D Secure authentication for every ecommerce transaction. In case you are using network tokens
with such transaction, you need to include tokenCryptogram element in all sale/preAuth requests for
all 3DS protocols (1.0.2, 2.1 and 2.2).

The following XML document represents an example of a Sale transaction using network token and
token cryptogram elements together with 3DS v2 authentication call:

3-D Secure authentication and subsequent Sale transaction are performed as per standard process
described in chapter 10.1 Authentication with Fiserv as your 3DS provider of this guide.

12.4 Display Network Token Details

For cases when you would like to get information about the network token associated with your store
and “HostedDataId”, you can use a display function with submitting the “StoreID” and
“HostedDataID” in your request:

<soapenv:Envelope
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ipg="http://ipg-online.com/ipgapi/schemas/ipgapi"
xmlns:a1="http://ipg-online.com/ipgapi/schemas/a1"
xmlns:v1="http://ipg-online.com/ipgapi/schemas/v1">
<soapenv:Header/>
<soapenv:Body>
<ns4:IPGApiActionRequest
xmlns:ns4="http://ipg-online.com/ipgapi/schemas/ipgapi"
xmlns:ns2="http://ipg-online.com/ipgapi/schemas/a1"
xmlns:ns3="http://ipg-online.com/ipgapi/schemas/v1">
<ns2:Action>
<ns2:StoreHostedData>
<ns2:StoreId>330115006</ns2:StoreId>
<ns2:DataStorageItem>
<ns2:Function>display</ns2:Function>
<ns2:HostedDataID>A03D6777-D729-4C35-A556-
8D6B285E440D</ns2:HostedDataID>
</ns2:DataStorageItem>
</ns2:StoreHostedData>
</ns2:Action>
</ns4:IPGApiActionRequest>
</soapenv:Body>
</soapenv:Envelope>

You will receive the details in the API response:

For cases where you would prefer to store credit card details without performing a transaction at the
same time, you can submit an action request including credit card details as on example below:

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

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<ns4:IPGApiActionRequest
xmlns:ns2="http://ipg-online.com/ipgapi/schemas/a1"
xmlns:ns3="http://ipg-online.com/ipgapi/schemas/v1"
xmlns:ns4="http://ipg-online.com/ipgapi/schemas/ipgapi">
<ns2:Action>
<ns2:StoreHostedData>
<ns2:StoreId>330115006</ns2:StoreId>
<ns2:DataStorageItem>
<ns2:CreditCardData>
<ns3:CardNumber>5204********006</ns3:CardNumber>
<ns3:ExpMonth>12</ns3:ExpMonth>
<ns3:ExpYear>24</ns3:ExpYear>
<ns3:CardCodeValue>XXX</ns3:CardCodeValue>
</ns2:CreditCardData>
<ns2:AssignToken>true</ns2:AssignToken>
</ns2:DataStorageItem>
</ns2:StoreHostedData>
</ns2:Action>
</ns4:IPGApiActionRequest>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Please note, that you have to obtain customer’s consent and perform additional strong customer
authentication via 3-D Secure before submitting the request to store card credentials.

You will get assigned ‘HostedDataID’ in the API response:

For XML-tags related to Card Present transactions with a chip reader and PIN entry device please refer
to the xsd’s in the Appendix of this document.

Abbreviations:
m: mandatory
o: optional
d: optional with default value
a and b:maximum one of the two values (In case you will find a value=”a” in the column for a
transaction type, it means either all those elements marked with “a” need to be present in the
message, or the one marked with “b”.)
1: if a or b is provided optional,
mandatory if a and b have not been provided
3: mandatory for 3D Secure transactions
s: see details in 3D Secure chapter
f: mandatory for Visa transactions of UK-based Financial Institutions with Merchant
Category Code 6012
r: mandatory for recurring SEPA Direct Debit
p: mandatory for split shipment
q: see details in Purchasing cards chapter
u: mandatory for Union Pay Secure Plus transactions

Path/ Credit Card Direct Debit

Name
ForceTicket

PostAuth

all paths relative to

PreAuth

Return

Return
Credit

Credit

ipgapi:IPGApiOrderRequest/
Void

Void
Sale

Sale

v1:Transaction
v1:CreditCardTxType/
m m m m m m m
v1:Type
v1:CreditCardData/
a a a a
v1:CardNumber
v1:CreditCardData/
a a a a
v1:ExpMonth
v1:CreditCardData/
a a a a
v1:ExpYear
v1:CreditCardData/
o o o o
v1:CardCodeValue
v1:CreditCardData/
b b b b
v1:TrackData
v1:CreditCardData/
o o o o
v1:Brand
v1:CreditCard3DSecure/
3 3 3 3
v1:VerificationResponse
v1:CreditCard3DSecure/
s s s s
v1:PayerAuthenticationResponse
v1:CreditCard3DSecure/
s s s s
v1:DRSPECI
v1:CreditCard3DSecure/
s s s s
v1:AuthenticationValue
v1:CreditCard3DSecure/
s s s s
v1:XID
v1:CreditCard3DSecure/
s s s s
v1:AuthenticateTransaction
v1:CreditCard3DSecure/
v1:Secure3DRequest/
s s s s
v1: Secure3DAuthenticationRequest/
v1: IVRAuthenticationRequest
v1:CreditCard3DSecure/
v1:Secure3DRequest/
s s s s
v1:Secure3DAuthenticationRequest/
v1:AcsResponse
v1:CreditCard3DSecure/
v1:Secure3DRequest/
s s s s
v1: Secure3DVerificationRequest
v1: IVRVerificationRequest
v1:CreditCard3DSecure/
v1:Secure3DverificationResponse/ s s s s
v1:IVRVerificationResponse
v1:CreditCard3DSecure/
v1:Secure3DverificationResponse/ s s s s
v1:VerificationRedirectResponse
v1:CreditCardData/
u u u u
v1:Upop
v1:cardFunction/
o o o o
v1:Type
v1:DE_DirectDebitTxType/
m m m m
v1:Type
v1:DE_DirectDebitData/
o 1
v1:BIC
v1:DE_DirectDebitData/
a a
v1:IBAN
v1:DE_DirectDebitData/
b b
v1:TrackData
v1:DE_DirectDebitData/
m
v1:MandateReference
v1:DE_DirectDebitData/
d,r
v1:MandateType
v1:DE_DirectDebitData/
r
v1:DateOfMandate
v1:Payment/
1 1 1 1 1 1
v1:HostedDataID
v1:Payment/
1 1 1 1 1 1
v1:HostedDataStoreID
v1:Payment/
1 1 1 1 1 1
v1:DeclineHostedDataDuplicates
v1:Payment/
o
v1:numberOfInstallments
v1:Payment/
d
v1:installmentsInterest
v1:Payment/
o
v1:installmentDelayMonths
v1:Payment/
o o o o o o o o o
v1:SubTotal
v1:Payment/
o o o o o o o o o
v1:ValueAddedTax
v1:Payment/
o o o o o o o o o
v1:localTax
v1:Payment/
o o o o o o o o o
v1:DeliveryAmount
v1:Payment/
m m m m m m m m m
v1:ChargeTotal
v1:Payment/
m m m m m m m m m
v1:Currency

o
v1:recurringType
o
v1:WalletType
o
v1:WalletID
v1:TransactionDetails/
o o o m m o a o m o a
v1:OrderId
v1:TransactionDetails/
o o o o o o o o o o o
v1:MerchantTransactionId
v1:TransactionDetails/
o o o o o
v1:Ip
v1:TransactionDetails/
m
v1:ReferenceNumber
v1:TransactionDetails/
a a
v1:Tdate
v1:TransactionDetails/
b b
v1:ReferencedMerchantTransactionId
v1:TransactionDetails/
d d d
v1:TransactionOrigin
v1:TransactionDetails/
o o o o o o o
v1:InvoiceNumber
v1:TransactionDetails/
o o o o o o
v1:PONumber
v1:TransactionDetails/
o o o o o o
v1:DynamicMerchantName
v1:TransactionDetails/
o o o o o o o o o o o
v1:Comments
v1:TransactionDetails/
q q q q q q q q q q q
v1:PurchaseCard
v1:TransactionDetails/
v1:Terminal/ o o o o o o
v1:TerminalID
v1:TransactionDetails/
o o o
v1:InquiryRateReference
v1:TransactionDetails/
v1:SplitShipment/ o o
v1:SequenceCount
v1:TransactionDetails/
v1:SplitShipment/ p
v1:FinalShipment
v1:Billing/
o o o o o o
v1:CustomerID
v1:Billing/
o o o o m m
v1:Name
v1:Billing/
o o o o o o
v1:Firstname
v1:Billing/
o o o o o o
v1:Middlename
v1:Billing/
o o o o o o
v1:Surname
v1:Billing/
o o o o o o
v1:Company
v1:Billing/
o o o o o o
v1:Address1
v1:Billing/
o o o o o o
v1:Address2
v1:Billing/
o o o o o o
v1:City
v1:Billing/
o o o o o o
v1:State
v1:Billing/
o o o o o o
v1:Zip
v1:Billing/
o o o o o o
v1:Country
v1:Billing/
o o o o o o
v1:Phone
v1:Billing/
o o o o o o
v1:Fax
v1:Billing/
o o o o o o
v1:Email
v1:Billing/
o o o o o o
v1:AccountOwnerType
v1:Shipping/
o o o o o o
v1:Type
v1:Shipping/
o o o o o o
v1:Name
v1:Shipping/
o o o o o o
v1:Address1
v1:Shipping/
o o o o o o
v1:Address2
v1:Shipping/
o o o o o o
v1:City
v1:Shipping/
o o o o o o
v1:State
v1:Shipping/
o o o o o o
v1:Zip
v1:Shipping/
o o o o o o
v1:Country
v1:Basket/
v1:Item/ o o o o o o
v1:ID
v1:Basket/
v1:Item/ o o o o o o
v1:Description
v1:Basket/
v1:Item/
v1:SubTotal
v1:Basket/
v1:Item/
v1:ValueAddedTax
v1:Basket/
v1:Item/
v1:DeliveryAmount
v1:Basket/
v1:Item/ o o o o o o
v1:ChargeTotal
v1:Basket/
v1:Item/
v1:Currency
v1:Basket/
v1:Item/ o o o o o o
v1:Quantity
v1:Basket/
v1:Item/
o o o o o o
v1:Option/
v1:Name
v1:Basket/
v1:Item/ o o o o o o
v1:Choice
v1:ClientLocale/
d d d d d d d d d d d
v1:Language
v1:ClientLocale/
d d d d d d d d d d d
v1:Country
v1:MCC6012Details/
f f f
v1:BirthDate
v1:MCC6012Details/
f,a f,a f,a
v1:AccountFirst6
v1:MCC6012Details/
f,a f,a f,a
v1:AccountLast4
v1:MCC6012Details/
f,b f,b f,b
v1:AccountNumber
v1:MCC6012Details/
f f f
v1:PostCode
v1:MCC6012Details/
f f f
v1:Surname
Mobile
Path/ PayPal Top-up
Name

MPCharge
PostAuth
all paths relative to

Return

Credit
ipgapi:IPGApiOrderRequest/

Void
v1:Transaction
v1:CreditCardTxType/
v1:Type
v1:CreditCardData/
v1:CardNumber
v1:CreditCardData/
v1:ExpMonth
v1:CreditCardData/
v1:ExpYear
v1:CreditCardData/
v1:CardCodeValue
v1:CreditCardData/
v1:TrackData
v1:CreditCard3DSecure/
v1:VerificationResponse
v1:CreditCard3DSecure/
v1:PayerAuthenticationResponse
v1:CreditCard3DSecure/
v1:AuthenticationValue
v1:CreditCard3DSecure/
v1:XID
v1:DE_DirectDebitTxType/
v1:Type
v1:DE_DirectDebitData/
v1:BIC
v1:DE_DirectDebitData/
v1:IBAN
v1:DE_DirectDebitData/
v1:MandateReference
v1:DE_DirectDebitData/
v1:MandateType
v1:DE_DirectDebitData/
v1:TrackData
v1:PayPalTxType/
m m m m
v1:Type
v1:Payment/
v1:HostedDataID
v1:Payment/
v1:HostedDataStoreID
v1:Payment/
v1:DeclineHostedDataDuplicates
v1:Payment/
o o o o
v1:SubTotal
v1:Payment/
o o o o
v1:ValueAddedTax
v1:Payment/
o o o o
v1:DeliveryAmount
v1:Payment/
m m m m
v1:ChargeTotal
v1:Payment/
m m m m
v1:Currency
v1:TransactionDetails/
m m o m o
v1:OrderId
v1:TransactionDetails/
o o o o o
v1:MerchantTransactionId
v1:TransactionDetails/
o o
v1:Ip
v1:TransactionDetails/
v1:ReferenceNumber
v1:TransactionDetails/
a
v1:Tdate
v1:TransactionDetails/
b
v1:ReferencedMerchantTransactionId
v1:TransactionDetails/
d
v1:TransactionOrigin
v1:TransactionDetails/
o o
v1:InvoiceNumber
v1:TransactionDetails/
o o
v1:PONumber
v1:TransactionDetails/
o o
v1:DynamicMerchantName
v1:TransactionDetails/
o o o o o
v1:Comments
v1:Billing/
o o
v1:CustomerID
v1:Billing/
o o
v1:Name
v1:Billing/
o o
v1:Company
v1:Billing/
o o
v1:Address1
v1:Billing/
o o
v1:Address2
v1:Billing/
o o
v1:City
v1:Billing/
o o
v1:State
v1:Billing/
o o
v1:Zip
v1:Billing/
o o
v1:Country
v1:Billing/
o o
v1:Phone
v1:Billing/
o o
v1:Fax
v1:Billing/
m o
v1:Email
v1:Shipping/
o
v1:Type
v1:Shipping/
o
v1:Name
v1:Shipping/
o
v1:Address1
v1:Shipping/
o
v1:Address2
v1:Shipping/
o
v1:City
v1:Shipping/
o
v1:State
v1:Shipping/
o
v1:Zip
v1:Shipping/
o
v1:Country
v1:Basket/
v1:Item/ o
v1:ID
v1:Basket/
v1:Item/ o
v1:Description
v1:Basket/
v1:Item/
v1:SubTotal
v1:Basket/
v1:Item/
v1:ValueAddedTax
v1:Basket/
v1:Item/
v1:DeliveryAmount
v1:Basket/
v1:Item/ o
v1:ChargeTotal
v1:Basket/
v1:Item/
v1:Currency
v1:Basket/
v1:Item/ o
v1:Quantity
v1:Basket/
v1:Item/
o
v1:Option/
v1:Name
v1:Basket/
v1:Item/ o
v1:Choice
v1:TopUpTxType/
v1:MPCharge/ m
v1:MNSP
v1:TopUpTxType/
v1:MPCharge/ m
v1:MSISDN
v1:TopUpTxType/
v1:MPCharge/ m
v1:PaymentType
v1:ClientLocale/
d d d d d
v1:Language
v1:ClientLocale/
d d d d d
v1:Country

13.2 Description of the XML-Tags

13.2.1 CreditCardTxType
Path/Name XML Description
Schema
type
v1:CreditCardTxType/ xs:string Stores the transaction type. Possible values are
v1:Type sale, forceTicket, preAuth, postAuth, return,
credit and void.

13.2.2 CreditCardData
Path/Name XML Description
Schema
type
v1:CreditCardData/ xs:string Stores the customer’s credit card number.
v1:CardNumber Make sure that the string contains only digits,
i.e. passing the number e.g. in the format xxxx-
xxxx-xxxx-xxxx will result in an error returned
by the Web Service API.
v1:CreditCardData/ xs:string Stores the expiration month of the customer’s
v1:ExpMonth credit card. Make sure that the content of this
element always contains two digits, i.e. a card
expiring in July will have this element with
value 07.
For authorisations on the Nashville front-end
only: for cases, where you do not know the
credit card expiry date, please send the value
12.
v1:CreditCardData/ xs:string Stores the expiration year of the customer’s
v1:ExpYear credit card. The same formatting restrictions as
for the v1:ExpMonth element apply here.
For authorisations on the Nashville front-end
only: for cases, where you do not know the
credit card expiry date, please send the value
99.
v1:CreditCardData/ xs:string Stores the three or four digit card security code
v1:CardCodeValue (CSC) – sometimes also referred to as card
verification value (CVV) or code (CVC) – which
is typically printed on the back of the credit
card. For information about the benefits of CSC
contact support.
v1:CreditCardData/ xs:string Stores the track data of a card when using a
v1:TrackData card reader instead of keying in card data (can
optionally be used instead of transmitting
CardNumber, ExpMonth and ExpYear). This
field needs to contain at least the concatenated
track 1 and 2 data. Track data 3 is optional. The
track data must include the track and field
separators as they are stored on the card.
Example for the track data separator from track
data 1 and 2 without the data: %…?;…?
v1:CreditCardData/ xs:string Optional field for the brand of the credit card. If
v1:TrackData this field is set, the transaction will only be
processed if the card number matches the
brand.

For XML-tags related to Card Present transactions with a chip reader and PIN entry device please refer
to the xsd’s in the Appendix of this document.

13.2.3 RecurringType
Path/Name XML Schema Description
type
v1:recurringType xs:string This field allows you to flag transactions as
recurring. It can be set to FIRST for the first
transaction of a series and to REPEAT for the
subsequent transactions in a series.
All available values:
FIRST
REPEAT
STANDIN

13.2.4 UnscheduledCredentialOnFileType
Path/Name XML Description
Schema
type
v1:unscheduledCredentialOnFileType xs:string This field allows you to flag transactions as
Unscheduled Credential On File Type. Currently
the valid values are FIRST,
CARDHOLDER_INITIATED or
MERCHANT_INITIATED to advise the scenario
if the credential is stored on your side.

13.2.5 Cardholder & Merchant Initiated Indicators

Path/Name XML Description
Schema
type
v1:CardholderInitiatedIndicator xs:string Specifies the type of cardholder initiated
transactions (CIT), available values:
CREDENTIAL_ON_FILE_FIRST
STANDING_ORDER
SUBSCRIPTION
INSTALLMENT
CREDENTIAL_ON_FILE_SUBSEQUENT
v1:MerchantInitiatedIndicator xs:string Specifies the type of merchant initiated
transactions (MIT), available values:
UNSCHEDULED_CREDENTIAL_ON_FILE
STANDING_ORDER
SUBSCRIPTION
INSTALLMENT
PARTIAL_SHIPMENT
DELAYED_CHARGE
NO_SHOW_CHARGE
RESUBMISSION

13.2.6 Wallet
Path/Name XML Schema Description
type
v1:Wallet/ xs:string This field allows you to submit the wallet type
v1:WalletType for transactions that have been initiated through
a digital wallet. Currently the valid values are
MASTERPASS, APPLE_PAY, SAMSUNG_PAY,
ANDROID_PAY
v1:Wallet/ xs:string This field allows you to submit the wallet ID for
v1:WalletID transactions that have been initiated through a
digital wallet.

13.2.7 cardFunction
Path/Name XML Schema Description
type
v1:cardFunction/ xs:string This field allows you to indicate the card function
v1:Type in case of combo cards which provide credit and
debit functionality on the same card. It can be set
to credit or debit.

13.2.8 CreditCard3DSecure
Path/Name XML Description
Schema
type
v1:CreditCard3DSecure/ xs:string Stores the VerificationResponse (VERes) of
v1:VerificationResponse your Merchant Plug-in, relevant for 3DS
protocol 1.0 only
v1:CreditCard3DSecure/ xs:string Stores the PayerAuthenticationResponse
v1:PayerAuthenticationResponse (PARes) of your Merchant Plug-in, relevant for
3DS protocol 1.0 only
v1:CreditCard3DSecure/ xs:string To set ECI value for Digital Secure Remote
v1:DSRPECI Payments. If you submit this parameter, any
values for parameters VerificationResponse
and PayerAuthenticationResponse will be
ignored.
v1:CreditCard3DSecure/ xs:string Stores the AuthenticationValue (MasterCard:
v1:AuthenticationValue AAV or VISA: CAAV) of your Merchant Plug-in.
v1:CreditCard3DSecure/ xs:string Stores the XID of your Merchant Plug-in,
v1:XID relevant for 3DS protocol 1.0 only
v1:CreditCard3DSecure/ xs:boolean Indicates, if transaction is going to be
v1:AuthenticateTransaction authenticated as 3DSecure transaction.
v1:CreditCard3DSecure/ xs:boolean Set true, if for this transaction you would like
v1:Override3dsCountryExclusion to enforce 3-D Secure authentication, despite
this country possibly being exempted from
authentication due to the merchant configured
list of countries where 3-D Secure is not
required.

v1:CreditCard3DSecure/ xs:boolean Set to true, if for this transaction you would

v1:SkipTRA enforce 3-D Secure authentication, despite of
the result of Transaction Risk Analysis
performed by RiskShield
v1:CreditCard3DSecure/ xs:string The URL where the issuer(ACS) shall return
v1:TermUrl 500 max the result of the authentication after
cardholder’s challenge.
v1:CreditCard3DSecure/ xs:string The URL where the the notification of
v1:ThreeDSMethodNotificationURL 500 max 3DSMethod completion from the ACS shall be
sent. Applicable for 3DS 2.x protocol only.
v1:CreditCard3DSecure/ xs:string Optional parameter to be used for 3DS 2.1
v1:ThreeDSRequestorChallengeIndicat protocol in order to indicate the preferred type
or of authentication, default value submitted by
the Gateway is “01”.
Currently supported values:
01 = NO PREFERENCE
02 = NO CHALLENGE REQUESTED
03 = CHALLENGE REQUESTED 3DS
REQUESTOR PREFERENCE
04 = CHALLENGE REQUESTED MANDATE
05 = NO CHALLENGE REQUESTED
(Transaction Risk Analysis is already
performed)
06 = NO CHALLENGE REQUESTED (Data
Share Only)
07 = NO CHALLENGE REQUESTED (SCA is
already performed)
08 = NO CHALLENGE REQUESTED (Utilize
whitelist exemption if no challenge required)
09 = CHALLENGE REQUESTED (Whitelist
prompt requested if challenge required)
v1:CreditCard3DSecure/ xs:string Represents the type of purchased item,
v1:ThreeDSTransType mandatory for Visa and Brazilian market,
otherwise optional. If no specific value is
present in the transaction request, default
value “01” is used.
01 = Goods/ Service Purchase
03 = Check Acceptance
10 = Account Funding
11 = Quasi-Cash Transaction
28 = Prepaid Activation and Load
v1:CreditCard3DSecure/ xs:string Represents the size of the challenge window
v1:ThreeDSRequestorChallengeWindo displayed to your customers during the
wSize authentication process, you can submit this
element with one of the values:
01 = 250 x 400
02 = 390 x 400
03 = 500 x 600
04 = 600 x 400
04 = Full screen
Note: Based on the payment schemes'
observation it is highly recommended to use
the value "05 - Full screen" only for browser-
based flows. Using full screen mode in app-
based flows where the authentication of the
cardholder happens on a smartphone or tablet
might cause time-outs and trigger an error on
issuer/ACS side.
v1:CreditCard3DSecure/ xs:string Represents EMVCo definition of the
v1:ThreeDSEmvCoMessageCategory authentication category, if no specific value is
present in the transaction request, default
value “01” is used.
01 = Payment Authentication
02 = Non-Payment Authentication
80 = Mastercard Data Only (available for
Brazilian merchants only)
v1:CreditCard3DSecure/ xs:string Indicates the type of Authentication request
v1:ThreeDSRequestorAuthenticationIn as in EMVCo specification:
dicator 01 = Payment transaction
02 = Recurring transaction
03 = Installment transaction
04 = Add card
05 = Maintain card
06 = Card holder verification as part of EMV
token ID and Value
v1:CreditCard3DSecure/ Indicates the minimum number of days
v1:recurringFrequency between authorisations. If no value is
submitted, the default value = “1” is
populated by the Gateway
v1:CreditCard3DSecure/ Date after which no further authorisations
v1:recurringExpiry shall be performed for recurring transactions.
If no value is submitted, the default value =
“99991231” is populated by the Gateway

Please note, that some of these values you either receive from your own MPI/3DSServer or from your
3-D Secure provider. The integrated 3-D Secure functionality of the Hosted Payment Pages/Direct
POST feature can not be used for transactions via the API for technical reasons.

13.2.9 India Mobile / IVR Extension Verification Request

Path/Name XML Schema Description
type
v1:IVRVerificationRequest/ xs:string Cardholder Phone or Mobile Device ID Format ,
v1:IVRDeviceIdFormat possible values are “I” for International format
(with country code), “D” for domestic format
v1:IVRVerificationRequest/ xs:string Cardholder’s phone number (with no “+” or
v1:IVRDeviceId leading zeros)
v1:IVRVerificationRequest/ xs:string Indicates how the transaction is being initiated:
v1:IVRShoppingChannel IVR, CLIENT (J2EE or STK app), TTP (via trusted
3rd party), SMS, WAP, native-app
v1:IVRVerificationRequest/ xs:string Indicates if the data entered by the customer
v1:IVRAuthenticationChannel was encrypted using the key provided in the
VERes (true/false). The ACS reads this tag and
decrypts the
value provided by the customer before
processing.

13.2.10 India Mobile / IVR Extension Authentication Request

Path/Name XML Schema Description

type
v1:IVRAuthenticationRequest/ xs:string Specifies the data being requested by the ACS
v1:IVRUserDataName (value from VERes): SP (static password), OTP1
(issued to cardholder prior to transaction), OTP2
(issued to cardholder during transaction), TTP
(authentication performed by a Trusted Third
Party), ICB (Issuer Call-Back), other (e.g.
Netbanking PIN)
v1:IVRAuthenticationRequest/ xs:string Value entered by the customer
v1:IVRUserDataValue
v1:IVRAuthenticationRequest/ xs:string Provides a status of the user interaction:
v1:IVRUserDataStatus “Y” User entered
“N” Value not received
“T” Transaction timed out
“U” Undefined failure
v1:IVRAuthenticationRequest/ xs:boolean Indicates if the data entered by the customer
v1:IVRUserDataEncrypted was encrypted using the key provided in the
VERes (true/false). The ACS reads this tag and
decrypts the
value provided by the customer before
processing.

13.2.11 3-D Secure 1.0 Authentication / Verification Redirect Response

Path/Name XML Schema Description

type
v1:VerificationRedirectResponse xs:string Represents the target of the 3-D Secure
v1:AcsURL redirection
v1:VerificationRedirectResponse xs:string Represents the PAReq data which has to be
v1:PaReq sent in the "PAReq" attribute to the ACS URL.
v1: VerificationRedirectResponse/ xs:string Represents the default TermURL, which should
v1:TermUrl be used in order to process the response from
the 3-D Secure process.
In case that a merchant would like to parse the
response by himself, he has to specify the
"TermUrl" parameter in the form with his
custom URL, in which he will process the
response and call the API with the response
PARes and Merchant Data.
v1: VerificationRedirectResponse/ xs:string Represents the merchant data which has to be
v1:MD sent in the "MD" attribute to the ACS URL.
13.2.12 3-D Secure 1.0 Authentication / ACS Response

Path/Name XML Schema Description

type
v1:AcsResponse xs:string Merchant Data from ACS redirection POST
v1:MD attribute ("MD"attribute). Please note, that this
element might not be sent back by the issuer
(ACS) in case of EMV 3DS protocol (3DS 2.0)
v1:AcsResponse xs:string Represents PARes data from ACS redirection
v1:PaRes POST attribute ("PARes" attribute).

13.2.13 UnionPay Secure Plus

Path/Name XML Schema Description

type
v1:Upop xs:boolean Indicates, if transaction is going to be
v1:AuthenticateTransaction authenticated as SecurePlus transaction. Set the
element to “true”, if you would like to
authenticate the transaction via Secure Plus.
v1:Upop xs:string Represents the response code from SMS
v1:SendSmsResponseCode verification authentication response, possible
values are “0-9”, max. 2 digits
v1:Upop xs:string Represents the sms code from Secure Plus on
v1:VCode Verify-Enrollment request, minLength value="1"
,maxLength value="200"
v1:Upop xs:string Represents a response from Secure Plus on
v1:ActivateStatus Verify-Enrollment request, the element could be
populated only with the following values: “A”,
“Y”, “F”, “N” or “L”
v1:Upop xs:string The element needs to be included in the Secure
v1:SecurePlusRequest Plus request to verify the validity of sent sms
code

13.2.14 UnionPay SecurePlusRequest

Path/Name XML Description

Schema
type
v1:SecurePlusRequest xs:string The element needs to be sent in the Secure Plus
v1:SecurePlusVerifySmsCodeRequest request to verify the validity of sent sms code
v1:SecurePlusRequest xs:string Represents the SMS code received on the
v1:SecurePlusVerifySmsCodeRequest (32 max) cardholder's mobile phone
v1:smsCode

13.2.15 DE_DirectDebitTxType
Path/Name XML Schema Description
type
v1:DE_DirectDebitTxType/ xs:string Stores the transaction type. Available values are
v1:Type sale or void.
13.2.16 DE_DirectDebitData
Path/Name XML Schema Description
type
v1:DE_DirectDebitData/ xs:string Stores the IBAN (International Bank Account
v1:IBAN Number) of the customer. Please make sure that
the value contains no spaces.
v1:DE_DirectDebitData/ xs:string Stores the SEPA mandate reference
v1:MandateReference
v1:DE_DirectDebitData/ xs:string Stores the type of SEPA mandate. Possible
v1:MandateType values are SINGLE for one-off debit collections,
FIRST_COLLECTION when submitting the initial
transaction related to
a mandate for recurring Direct Debit collections
or RECURRING_COLLECTION for subsequent
recurring transactions. As a default, transactions
where this parameter is not submitted by the
merchant will be flagged as a single debit
collection.
Please note that it is mandatory to submit a
MandateReference in case of recurring
collections.
v1:DE_DirectDebitData/ xs:string Stores the reference to the date of the original
v1:DateOfMandate mandate when performing recurring Direct
Debit transactions.
The date needs to be submitted in format
YYYYMMDD.
Please note that this is a mandatory field for
recurring Direct Debit transactions.
v1:DE_DirectDebitData/ xs:string Stores the track data of a card when using a
v1:TrackData card reader instead of keying in card data (can
optionally be used instead of transmitting
BankCode and AccountNumber). The field
needs to contain the concatenated track 2 and 3
data. The track data must include the track and
field separators as they are stored on the card.
Example for the track data separator from track
data 1 and 2 without the data: %…?;…?3s

13.2.17 PayPalTxType
Path/Name XML Description
Schema
type
v1:PayPalTxType/ xs:string Stores the transaction type. Possible values are
v1:Type postAuth, return, credit and void.

14.2.18 Payment
Path/Name XML Schema Description
type
v1:Payment/ xs:string Stores the Hosted Data ID for the Data
v1:HostedDataID Vault product
v1:Payment/ xs:string Stores the Hosted Data ID for the Data
v1:HostedDataStoreID Vault product in this store (only as
technical user)
v1:Payment/ xs:string Declines duplicate credit card or German
v1:DeclineHostedDataDuplicates direct debit accounts
v1:Payment/ xs:string Stores the number of instalments for a
v1:numberOfInstallments Sale transaction if the customer pays the
amount in several parts
v1:Payment/ xs:string Indicates, if the installment interest has
v1:installmentsInterest been applied; possible values "yes" or "no"
v1:Payment/ xs:string Represents the number of months the
v1:installmentDelayMonths first payment will be delayed; possible
values in the range
<1; 99>
v1:Payment/ xs:string If setup with the value = true indicates
v1:revolvingPayment the cardholder applied for Revolving
payment (available only for our
distribution channel in Japan).
v1:Payment/ xs:decimal Stores the Sub Total of an order. If this
v1:SubTotal member is set, then also ChargeTotal has
to be set.
v1:Payment/ xs:decimal Stores the VAT of an order. If this member
v1:ValueAddedTax is set, then also SubTotal has to be set.
v1:Payment/ xs:decimal Stores the delivery amount of an order. If
v1:DeliveryAmount this member is set, then also SubTotal has
to be set.
v1:Payment/ xs:double Stores the transaction amount. Make sure
v1:ChargeTotal that the number of positions after the
decimal point does not exceed 2, e.g.
3.123 would be invalid – however, 3.12,
3.1, and 3 are correct.
v1:Payment/ xs:string Stores the currency as a three-digit ISO
v1:Currency 4217 value (e. g. 978 for Euro)

13.2.19 TransactionDetails
Path/Name XML Schema Description
type
v1:TransactionDetails/ xs:string Stores the order ID. This must be unique per
v1:OrderId Store ID. If no Order ID is transmitted, the
Gateway will generate one automatically.
Note: For cases where you plan to use EMV
3DS Authentication prior to the authoriazation,
please use only the following characters in
OrderId:
A-Z, a-z, 0-9, ‘-‘
v1:TransactionDetails/ xs:string Allows you to assign a unique ID for the
v1:MerchantTransactionId transaction. This ID can be used to reference to
this transactions in a Void request
(ReferencedMerchantTransactionId) or to
retrieve transaction details with the API action
InquiryTransaction. Uniqueness needs to be
enforced by the merchant.
v1:TransactionDetails/ xs:string Stores the customer’s IP address which can be
v1:Ip used by the Web Service API for fraud
detection by IP address. Make sure that you
supply the IP in the format xxx.xxx.xxx.xxx, e.g.
128.0.10.2 would be a valid IP.
v1:TransactionDetails/ xs:string Stores the six digit reference number you have
v1:ReferenceNumber received as the result of a successful external
authorization (e.g. by phone). The Gateway
needs this number for uniquely mapping a
ForceTicket transaction to a previously
performed external authorization.
v1:TransactionDetails/ xs:string Stores the purchasing card Level II and Level III
v1:PurchaseCard transaction data.
v1:TransactionDetails/ xs:string Stores the TDate of the Sale, PostAuth,
v1:TDate ForceTicket, Return, or Credit transaction this
Void transaction refers to. A TDate value is
returned within the response to a successful
transaction of one of these five types. When
performing a Void transaction, you have to pass
the TDate in addition to the order ID for
uniquely identifying the transaction to be
voided. The scenario presented below gives an
example.
v1:TransactionDetails/ xs:string Stores the MerchantTransactionId of the Sale,
v1:ReferencedMerchantTransactio PostAuth, ForceTicket, Return, or Credit
nId transaction this Void transaction refers to. This
can be used as an alternative to TDate if you
assigne a MerchantTransactionId in the original
transaction request.
v1:TransactionDetails/ xs:string The source of the transaction. The possible
v1:TransactionOrigin values are ECI (if the order was received via
email or Internet), MOTO (mail order /
telephone order), MAIL (mail order), PHONE
(telephone order) and RETAIL (face to face).
v1:TransactionDetails/ xs:int Stores the total number of shipments in case
v1:SplitShipment/ of split shipment. Can either be included in
v1:SequenceCount the PreAuth or the first PostAuth. A different
value in the first PostAuth overwrites the
value from the PreAuth.
v1:TransactionDetails/ xs:boolean Needs to be set to “true” in the final PostAuth
v1:SplitShipment/ of a series of split shipments.
v1:FinalShipment
v1:TransactionDetails/ xs:string Stores the invoice number.
v1:InvoiceNumber
v1:TransactionDetails/ xs:string Stores the purchase order number.
v1:PONumber
v1:TransactionDetails/ xs:string Stores a dynamic merchant name for the
v1:DynamicMerchantName cardholder’s statement
v1:TransactionDetails/ xs:string Stores the comments.
v1:Comments
v1:TransactionDetails/ xs:string Indicates the reason to skip Strong Customer
v1:SCAExemptionIndicators Authentication (SCA), e.g. 3-D Secure with
submitting directly an authorization request.
For available values and more details see the
chapter 13.2.30
v1:TransactionDetails/ xs:boolean Needs to be set to ‘true’, for transactions
v1:HighRiskPurchaseIndicator handling a cryptocurrency and initiated from a
MCC 6051(Quasi Cash—Merchant) store; or
for transactions handling high risk securities
initiated from the store with MCC 6211
(Securities—Brokers/ Dealers).
v1:TransactionDetails/ xs:string 8 characters Visa Merchant Identifier assigned
v1:vmid by Visa, required for Trusted Merchant and
Delegated Authentication. Can be used only if
you are enrolled with Visa’s Delegated
Authentication program.
v1:TransactionDetails/ xs:boolean Set it to “true” if the transaction is set for
v1:IpgDeferredAuth deferred authorization.
v1:TransactionDetails/ xs:string Represents a two-character code that
v1:BusinessApplicationIdentifier identifies the intended use of a push payment.
Available values:
FUNDS_DISBURSEMENT
GAMBLING_PAYOUT
ONLINE_GAMBLING_PAYOUT
ACCOUNT_TO_ACCOUNT
PERSON_TO_PERSON

v1:TransactionDetails/ xs:string12max Purpose of payment code must be send for

v1:PurposeOfPaymentCode Visa OCT transaction with cards issued in
India, Bangladesh, Argentina and Egypt. The
codes are defined by the recipient issuer's
country and therefore will differ for each
country.
v1:TransactionDetails/ xs:string The purpose of this parameter is to identify
v1:MarketplaceForeignRetailerIndi domestic transactions involving a marketplace
cator retailer that is in a different country.
Available values:
“F” – populate if a marketplace retailer is
foreign
If above condition has not been met, leave the
field empty.
Note: applicable for APAC region only

13.2.20 Purchasing Cards

Path/Name XML Schema Description
type
v1:PurchaseCard xs:string A reference to a Customer Code/Customer
v1:CustomerReferenceID (20max) Reference ID
v1:PurchaseCard xs:string A reference to a Purchase Identifier/Merchant
v1:SupplierInvoiceNumber (30max) related data.
v1:PurchaseCard xs:string Represents a Merchant VAT registration/Single
v1:SupplierVATRegistrationNumber (30max) Business Reference Number/Merchant Tax ID or
Corporation VAT Number
v1:PurchaseCard xs:string Represents the total discount amount applied
v1:TotalDiscountAmountAndRate to a transaction (i.e. total transaction percentage
discounts, fixed transaction amount reductions
or summarization of line item discounts).
v1:PurchaseCard xs:string Represents the total freight/shipping amount
v1:VATShippingAmountAndRate applied to a transaction.
v1:PurchaseCard xs:string Represents mandatory data for Level III
v1:LineItemData transactions.

13.2.21 Purchasing Cards / Line Item Data

Path/Name XML Schema Description
type
v1:LineItemData xs:numeric A reference to a commodity code used to
v1:CommodityCode (positive, classify purchased item
4max)
v1:LineItemData xs:string A reference to a merchant product identifier, the
v1:ProductCode (20max) Universal Product Code (UPC) of purchased item
v1:LineItemData xs:string Represents a description of purchased item
v1:Description (30max)
v1:LineItemData xs:numeric Represents a quantity of purchased items.
v1:Quantity (minInclusive
value="1")

v1:LineItemData xs:string Represents a unit of measure of purchased

v1:UnitOfMeasure (3 max) items

v1:LineItemData xs:decimal Represents mandatory data for Level III

v1:UnitPrice transactions.
v1:LineItemData xs:decimal Represents a rate of the VAT amount, e.g. 0.09
v1:VATAmountAndRate (means 9%)
v1:LineItemData xs:decimal Represents a rate of the discount amount, e.g.
v1:DiscountAmountAndRate 0.09 (means 9%)
v1:LineItemData xs:decimal This field is a calculation of the unit cost
v1:LineItemTotal multiplied by the quantity and less the discount
per line item. The calculation is reflected as:
[Unit Cost * Quantity] - Discount per Line Item
= Line Item Total.

13.2.22 InquiryRateReference
Path/Name XML Schema Description
type
v1:InquiryRateReference/ xs:long A reference to a rate-inquiry for transactions with
v1:InquiryRateId Global Choice™or Dynamic Pricing.
v1:InquiryRateReference/ xs:boolean Specifies whether a cardholder has choosen to
v1:DccApplied accept the proposed currency conversion
offering when using Global Choice™.
13.2.23 Billing
Path/Name XML Schema Description
type
v1:Billing/ xs:string Stores your ID for your customer.
v1:CustomerID
v1:Billing/ xs:string Stores the customer’s name. If provided, it
v1:Name will appear on your transaction reports.
Please note that this is a mandatory field for
SEPA Credit Transfers.
Field is used for Visa Account Name Inquiries.
v1:Billing/ xs:string Represents the customer’s first name for
v1:Firstname billing information. Field is used for Visa
Account Name Inquiries.
v1:Billing/ xs:string Represents the customer’s middle name for
v1:Middlename billing information. Field is used for Visa
Account Name Inquiries.
v1:Billing/ xs:string Represents the customer’s surname for billing
v1:Surname information. Field is used for Visa Account
Name Inquiries.
v1:Billing/ xs:string Stores the customer’s company. If provided, it
v1:Company will appear on your transaction reports.
v1:Billing/ xs:string Stores the first line of the customer’s address.
v1:Address1 If provided, it will appear on your transaction
reports.
v1:Billing/ xs:string Stores the second line of the customer’s
v1:Address2 address. If provided, it will appear on your
transaction reports.
v1:Billing/ xs:string Stores the customer’s city. If provided, it will
v1:City appear on your transaction reports.
v1:Billing/ xs:string Stores the customer’s state. If provided, it will
v1:State appear on your transaction reports.
v1:Billing/ xs:string Stores the customer’s zip code. If provided, it
v1:Zip will appear on your transaction reports.
v1:Billing/ xs:string Stores the customer’s country. If provided, it
v1:Country will appear on your transaction reports.
v1:Billing/ xs:string Stores the customer’s phone number. If
v1:Phone provided, it will appear on your transaction
reports.
v1:Billing/ xs:string Stores the customer’s fax number. If provided,
v1:Fax it will appear on your transaction reports.
v1:Billing/ xs:string Stores the customer’s Email address. If
v1:Email provided, it will appear on your transaction
reports. If you are using the email transaction
notification feature, this email address will be
used for notifications to your customer.
v1:Billing/ xs:string Stores the information whether a person is
v1:AccountOwnerType considered to be the main owner of the
account or the person has limited access to the
account. Field is used for Visa Account Name
Inquiries.
Available values:
PRIMARY
SECONDARY

13.2.24 Shipping
Path/Name XML Schema Description
type
v1:Shipping/ xs:string Stores the name of the recipient. If provided, it
v1:Name will appear on your transaction reports.
v1:Shipping/ xs:string Stores the first line of the shipping address. If
v1:Address1 provided, it will appear on your transaction
reports.
v1:Shipping/ xs:string Stores the second line of the shipping address.
v1:Address2 If provided, it will appear on your transaction
reports.
v1:Shipping/ xs:string Stores the recipient’s city. If provided, it will
v1:City appear on your transaction reports.
v1:Shipping/ xs:string Stores the recipient’s state. If provided, it will
v1:State appear on your transaction reports.
v1:Shipping/ xs:string Stores the recipient’s zip code. If provided, it
v1:Zip will appear on your transaction reports.
v1:Shipping/ xs:string Stores the recipient’s country. If provided, it
v1:Country will appear on your transaction reports.

13.2.25 ClientLocale
Path/Name XML Schema Description
type
v1:ClientLocale/ xs:string If you are using the email transaction notification
v1:Language feature, this language will be used for
notifications to your customer. Possible values
are: de, en, it.
v1:ClientLocale/ xs:string Specifies the variant of the language. This
v1:Country member can only be set if the language is set.
Possible values are: DE, GB, IT. If you do not
define a country, a matching country will be
chosen.

If you do not submit language information in the transaction, the language settings of your store will be
used for the email notifications.

13.2.26 RequestCardRateForDCC
Path/Name XML Schema Description
type
v1:RequestCardRateForDCC/ xs:string Your Store ID. The base currency is derived from
v1:StoreId (max 20) the Store settings.
v1:RequestCardRateForDCC/ xs:int The credit cards’ Bank Identifier Number (first 6
v1:BIN digits of credit card number)
v1:RequestCardRateForDCC/ xs:decimal The amount to be converted (optional).
v1:BaseAmount When no amount is given in the request, no
amount will be returned, only the conversion
rate.

13.2.27 RequestMerchantRateForDynamicPricing
Path/Name XML Schema Description
type
v1:RequestCardRateForDCC/ xs:string Your Store ID. The base currency is derived from
v1:StoreId (max 20) the Store settings.
v1:RequestCardRateForDCC/ xs:string The currency to be converted to. (ISO_4217
v1:ForeignCurrency format)
v1:RequestCardRateForDCC/ xs:decimal The amount to be converted (optional).
v1:BaseAmount When no amount is given in the request, no
amount will be returned, only the conversion
rate.
13.2.28 CardRateForDCC and MerchantRateForDynamicPricing
Both elements are of the same xml-type InquiryRateType, therefore their substructure is exactly the
same and described only once.

Path/Name XML Schema Description

type
<InquiryRateType>/ xs:long The Store ID. The base currency is derived
v1: InquiryRateId from the Store’s settings.
<InquiryRateType>/ xs:string The currency that the amount has been
v1:ForeignCurrencyCode converted to (ISO_4217 format)
<InquiryRateType>/ xs:decimal The converted amount.
v1:ForeignAmount
<InquiryRateType>/ xs:decimal The exchange rate of the currency conversion
v1:ExchangeRate
<InquiryRateType>/ xs:boolean Whether the user accepted the DCC offering or
v1:DccApplied not.
<InquiryRateType>/ xs:boolean Whether an offering for dynamic currency
v1:DccOffered conversion was extended
<InquiryRateType>/ xs:dateTime Timestamp after which this DCC offering
v1:ExpirationTimestamp expires
<InquiryRateType>/ xs:decimal Optional margin information.
v1:MarginRatePercentage
<InquiryRateType>/ xs:string The source of the currency conversion.
v1:ExchangeRateSourceName
<InquiryRateType>/ xs:dateTime The timestamp when the source has done the
v1:ExchangeRateSourceSourceTim currency conversion
estamp

Note:Instead of <InquiryRateType> substitute either CardRateForDCC or

MerchantRateForDynamicPricing

13.2.29 MCC 6012 Visa and Mastercard Mandate

For UK-based Financial Institutions with Merchant Category Code 6012, Visa and Mastercard have
mandated additional information of the primary recipient of the loan to be included in the authorization
message.

If you are a UK 6012 merchant use the following parameters for your transaction request:

Path/Name XML Schema Description

type
v1:MCC6012Details/ xs:string Date of birth in format YYYYMMDD
v1:BirthDate
v1:MCC6012Details/ xs:string First 6 digits of recipient PAN (where the
v1:AccountFirst6 primary recipient account is a card)
v1:MCC6012Details/ xs:string Last 4 digits of recipient PAN (where the
v1:AccountLast4 primary recipient account is a card)
v1:MCC6012Details/ xs:string Recipient account number (where the
v1:AccountNumber (max 50) primary recipient account is not a card)
v1:MCC6012Details/ xs:string Post Code
v1:PostCode (max 50)
v1:MCC6012Details/ xs:string Surname
v1:Surname (max 100)
If you are a UK merchant with Merchant Category Code 6051 and 7299, you can optionally use the
same MCC6012 parameters in your request for debt repayment transactions.

13.2.30 Market Segment Addendum

Card transactions in specific market segments can obtain incentive rates when they include
addendum data.
The Web Service API allows you to submit addendum data for the following industries:

Airlines v1:AirlineDetails, v1: TravelRoute

(MCC 3000-3299 or 4511)
Car Rental v1:CarRental
(MCC 3351-3500, 7512, 7513 or 7519
Hotel Lodgings v1:HotelLodgings
(MCC 3501-3999 or 7011)

Please see v1.xsd for details (link in Appendix).

13.2.31 SCA Exemptions

Following PSD2 mandate requirements you are able to request an exemption from Strong Customer
Authentication (SCA) with including one of the available SCAExemptionIndicators in your transaction
request to the Gateway.

v1:SCAExemptionIndicator/ Used for transaction amounts below 30 EUR or

Low Value Exemption respective value in other European currencies.
v1:SCAExemptionIndicator/ Used for cases where transaction risk analysis has been
TRA Exemption already perfomed.
v1:SCAExemptionIndicator/ Used for cases where merchant has been flagged as
Trusted Merchant Exemption trusted by their customers.
v1:SCAExemptionIndicator/ Used for secure corporate payments transactions.
SCP Exemption
v1:SCAExemptionIndicator/ Authentication failure must persist for at least five
Authentication Outage Exception minutes, leading all authentications to fail (i.e. no
attempt responses provided) before the Authentication
Outage Exception is used.
v1:SCAExemptionIndicator/ Used for cases where the issuer delegated SCA to the
Delegated Authentication merchant.

Note: PSD2 mandate is only applicable for European distribution channels.

13.2.32 China Domestic

Path/Name XML Schema Description

type
v1:Transaction/ xs:string Transaction types enabled for WeChat
v1:WeChatTxType payment option, available values :sale, return
v1:Transaction/ xs:string Transaction types enabled for Alipay payment
v1:AlipayTxType option, available values :sale, return
xs:string Transaction types enabled for Union Pay e-
v1:Transaction/ banking and QuickPay payment options,
v1:CUPDomesticTxType available values :sale, return
v1:Transaction/ xs:string Mandatory element for transactions with China
v1:ChinaDomesticInformation Domestic payment methods
v1:Transaction/ xs:boolean Allows only debit cards to be processed
v1:ChinaDomesticInformation/
v1:LimitCardFunctionToDebit
v1:Transaction/ xs:string32max Identification of the customer, the field is
v1:ChinaDomesticInformation/ optional, but recommended in case the
v1:CustomerId consumer has this information
xs:string32max Product code of purchased item, all available
v1:Transaction/ values could be found here:
v1:ChinaDomesticInformation/ https://docs.firstdata.com/org/gateway/node/4
v1:ProductCode 01
v1:Transaction/ xs:int Quantity of purchased products
v1:ChinaDomesticInformation/
v1:ProductQuantity
v1:Transaction/ xs:decimal Price of purchased product
v1:ChinaDomesticInformation/
v1:ProductPrice
v1:Transaction/ xs:string100max Description of purchased products
v1:ChinaDomesticInformation/
v1:ProductDescription
v1:Transaction/ xs:anyURI URL where you want the Chinese platform
v1:ChinaDomesticInformation/ (PNR) redirect you to after the transaction
v1:RedirectUrl processing have been competed on their end
v1:Transaction/ xs:string8max Identification of the bank, the field is required
v1:ChinaDomesticInformation/ only for payment methods Union Pay e-banking
v1:BankId and Union Pay QuickPay

13.2.33 EMI with ICICI Debit Card

The following elements to be included in a transaction request with Equated Monthly Installments
(EMI) payments with the debit card issued by ICICI.
Please note, that this functionality is only available in India.

Path/Name XML Schema Description

type
v1:Transaction/ xs:string EMI Common element contains basic
v1:EMIDetails/ information about EMI, such as mobile number
v1:EMICommon and EMI Indicator
v1:Transaction/ xs:string Consists of all EMI specific transactions details
v1:EMIDetails/
v1:EMIPlan
v1:Transaction/ xs:string EMI Direct Integration element includes the
v1:EMIDetails/ values for EMI, that have been retrieved
v1:DirectIntegration outside the Gateway and then submitted in
the transaction request
v1:Transaction/ xs:string Customer’s mobile phone number.
v1:EMIDetails/
v1:EMICommon
v1:MobileNumber
v1:Transaction/ xs:string10max EMI Indicator
v1:EMIDetails/
v1:EMICommon
v1:Indicator
v1:Transaction/ xs:string Transaction amount = Product Amount -
v1:EMIDetails/ Discount
v1:EMIPlan
v1:TransactionAmount
v1:Transaction/ xs:string Full product amount (without discount)
v1:EMIDetails/
v1:EMIPlan
v1:ProductAmount
v1:Transaction/ xs:string Discount offered for the product
v1:EMIDetails/
v1:EMIPlan
v1:DiscountAmount
v1:Transaction/ xs:int Tenure in months, min=1, max=12
v1:EMIDetails/
v1:EMIPlan
v1:Tenure
v1:Transaction/ xs:decimal EMI transaction interest rate
v1:EMIDetails/
v1:EMIPlan
v1:InterestRate
v1:Transaction/ xs:string The processing fee for EMI transaction
v1:EMIDetails/
v1:EMIPlan
v1:ProcessingFee
v1:Transaction/ xs:string Total amount to be paid by a customer; EMI per
v1:EMIDetails/ month x Tenure
v1:EMIPlan
v1:TotalAmount
v1:Transaction/ xs:string Transaction amount per month
v1:EMIDetails/
v1:EMIPlan
v1:AmountPerMonth
v1:Transaction/ xs:string20max Merchant’s reference value, unique transaction
v1:EMIDetails/ ID
v1:DirectIntegration
v1:MerchantReference
v1:Transaction/ xs:string20max Issuer eligibility reference number for EMI
v1:EMIDetails/ specific transactions
v1:DirectIntegration
v1:IssuerEligibilityReference
v1:Transaction/ xs:string12max Bank System Trace Audit Number
v1:EMIDetails/
v1:DirectIntegration

13.2.34 Boleto

Path/Name XML Schema Description

type
v1:Transaction/ xs:string Transaction types enabled for Boleto, available
v1:BoletoTxType value:sale
v1:Transaction/ xs:string Authorizer code assigned by Software Express,
v1:AuthorizerId available values for Boleto are:
Itaú Shopline (authorizer_id = 7)
Banco do Brasil – Boleto (authorizer_id = 404)

For more information about the activation of this payment method please reach out to your local
support team.

13.2.35 StandIn Details

The following elements to be included in a transaction request with Standin Instruction payments.
Please note, that this functionality is only available in India.

Path/Name XML Schema Description

type
v1:Transaction/ xs:string Indicates standin instruction Type, available
v1: StandInDetails/ values:
v1: StandInType FIXED_AMOUNT
MAXIMUM_AMOUNT
v1:Transaction/ xs:string Indicates number of standin instruction debits.
v1: StandInDetails/ Possible values can be two digit number or UN
v1: NumberOfDebits (Until it is cancelled, only for Visa) or ND (Not
defined, only for Visa)
v1:Transaction/ xs:boolean Indicates standin instruction validation flag, it
v1: StandInDetails/ can be true or false. "false" - Not validated,
v1: SIValidated "true" - Validated
v1:Transaction/ xs:string Represents maximum debit amount per
v1: StandInDetails/ standin instruction transaction
v1: MaximumTransactionAmount
v1:Transaction/ xs:string 10 max Unique identifier for SI mandate
v1: StandInDetails/
v1: SIHubID
v1:Transaction/ xs:string Indicates frequency of the standin instruction
v1: StandInDetails/ debit, available values:
v1: Frequency WEEKLY
FORTNIGHTLY
MONTHLY
QUARTERLY
HALFYEARLY
YEARLY
UNSCHEDULED
13.2.36 Source of funds
The following element provides details about the source of funds related to original credit transactions
processing.

Path/Name XML Schema Description

type
v1:TransactionDetails/ xs:string Identifies the source of the funds for money
v1:SourceOfFunds/ and non-money transfer transactions:
Available values:
'CREDIT_ACCOUNT'
'DEBIT_ACCOUNT',
'PREPAID_ACCOUNT'
'CASH'
'DEPOSIT_ACCOUNT' – for Mastercard only;
'OTHER_CREDIT_ACCOUNT' – for Visa only
'MOBILE_MONEY_ACCOUNT'– for
Mastercard only

13.2.37 Network Tokenisation

Path/Name XML Schema Description

type
v1:NetworkToken/ xs:string Network Token expiry month
v1:NetworkTokenNumber/ (0[1-9])|(1[0-
v1:ExpiryMonth 2])

v1:NetworkToken/ xs:string Network Token expiry year

v1:NetworkTokenNumber/ [0-9]{2}
v1:ExpiryYear

v1:NetworkToken/ xs:string Last four digits of the original card number

v1:NetworkTokenData/ \d{4} encrypted under Network Token
v1:CardLast4

v1:NetworkToken/ xs:string Card scheme providing network token,

v1:NetworkTokenData/ available values:
v1:Brand "AMEX"
"DINERS/DISCOVER
"EFTPOS"
"JCB"
"MAESTRO"
"MASTERCARD"
"RUPAY"
"VISA"
v1:NetworkToken/ xs:string Token cryptogram as assigned by a scheme.
v1:NetworkTokenData/ minLength
v1:TokenCryptogram value="20
maxLength
value="255"
v1:NetworkTokenProvisionStatus xs:string This field provides the status of the network
token being provisioned for the supplied PAN.
Available values:
"REQUESTED"
"PROVISIONED"
"QUEUED"

13.2.38 Additional Custom Parameter to handle Intra Country data for Mastercard

v1:AdditionalRequestParameters/ xs:string In case your business is conduced in France,

v1:keyValuePair/ [0-9]{9} you’re obliged to submit “transitOfferId“
v1:transitOfferId parameter in your transaction request. Please
note, that this is Mastercard’s requirement
applied only to transit operators and ticketing
providers.
14 Custom Parameters
You can send up to ten additional parameters as individual key-value pairs. The values will be stored so
that they can be returned in Inquiry Actions and be visible in the Virtual Terminal’s Order Details view.

Please refer to the element AdditionalRequestParamaters in the XSD.

14.1 Additional parameters for Fraud Detect

In case you use the Fraud Detect product and want to pass mobile device details for the scoring, you
need to pass these with the following parameter naming:
• deviceRiskId
• deviceRiskAPIKey
• deviceRiskHost

The following represents an example of a Sale transaction with Fraud Detect special custom
parameters:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ipg="http://ipg-online.com/ipgapi/schemas/ipgapi" xmlns:v1="http://ipg-
online.com/ipgapi/schemas/v1">
<soapenv:Header/>
<soapenv:Body>
<ipg:IPGApiOrderRequest>

<v1:Transaction>

<v1:CreditCardTxType>

<v1:StoreId>120995000</v1:StoreId>
<v1:Type>sale</v1:Type>
</v1:CreditCardTxType>


<v1:CreditCardData>
<v1:CardNumber>4257********0111</v1:CardNumber>
<v1:ExpMonth>12</v1:ExpMonth>
<v1:ExpYear>27</v1:ExpYear>
<v1:CardCodeValue>XXX</v1:CardCodeValue>
</v1:CreditCardData>

<v1:Payment>
<v1:ChargeTotal>10.00</v1:ChargeTotal>
<v1:Currency>GBP</v1:Currency>
</v1:Payment>
<v1:TransactionDetails>
<v1:AdditionalRequestParameters>
<v1:keyValuePair>
<v1:key>deviceRiskId</v1:key>
<v1:value>********</v1:value>
</v1:keyValuePair>
<v1:keyValuePair>
<v1:key>deviceRiskHost</v1:key>
<v1:value>*********</v1:value>
</v1:keyValuePair>
<v1:keyValuePair>
<v1:key>deviceRiskAPIKey</v1:key>
<v1:value>************</v1:value>
</v1:keyValuePair>
<v1:keyValuePair>
<v1:key>deviceIntelligenceVendor</v1:key>
<v1:value>**********************</v1:value>
</v1:keyValuePair>
<v1:keyValuePair>
<v1:key>deviceIntelligenceSessionID</v1:key>
<v1:value>**********************</v1:value>
</v1:keyValuePair>
</v1:AdditionalRequestParameters>
<v1:TransactionOrigin>ECI</v1:TransactionOrigin>
</v1:TransactionDetails>
<v1:Billing>
<v1:CustomerID>C001</v1:CustomerID>
<v1:Name>Max Mustermann</v1:Name>
<v1:Company>BCompany</v1:Company>
<v1:Address1>Hellersbergstraße</v1:Address1>
<v1:City>Frankfurt</v1:City>
<v1:State>Hessen</v1:State>
<v1:Zip>12345</v1:Zip>
<v1:Country>DEU</v1:Country>
<v1:Phone>01522113356</v1:Phone>
<v1:Email>example@gmail.com</v1:Email>
</v1:Billing>
<v1:Shipping>
<v1:Name>Max Mustermann</v1:Name>
<v1:Address1>407,Gilpin Drive</v1:Address1>
<v1:Address2>407,Gilpin Drive2</v1:Address2>
<v1:City>Frankfurt</v1:City>
<v1:State>Hessen</v1:State>
<v1:Zip>12345</v1:Zip>
<v1:Country>DEU</v1:Country>
<v1:Phone>1234567890</v1:Phone>
</v1:Shipping>
</v1:Transaction>
</ipg:IPGApiOrderRequest>
</soapenv:Body>
</soapenv:Envelope>

15 Building a SOAP Request Message

After building your transaction in XML, a SOAP request message describing the Web Service operation
call, you wish to perform, has to be created. That means while the XML-encoded transaction you have
established as described in the previous chapter represents the operation argument, the SOAP request
message encodes the actual operation call.
Building such a SOAP request message is a rather straightforward task. The complete SOAP message
wrapping the XML-Sale-transaction looks as follows:

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

In short, the SOAP request message contains a SOAP envelope consisting of a header and a body.
While no specific header entries are required for calling the Web Service, the SOAP body takes the
transaction XML document as sub element as shown above. Note that there are no further
requirements for transactions of a type other than Sale. That means the general format of the SOAP
request message regardless of the actual transaction type is as follows:

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

Finally, you may have noticed that there are no specific entries describing which Web Service
operation to call. In fact, the Gateway automatically maps the
ipgapi:IPGApiOrderRequest element to the corresponding Web Service operation.

16 Reading the SOAP Response Message

The SOAP response message may be understood as the Web Service operation result. Hence,
processing the SOAP request message may have either resulted in a SOAP response message in the
success case (i.e. the return parameter) or a SOAP fault message in case of a failure (i.e. the thrown
exception). Both SOAP message types are contained in the body of the HTTP response message.

16.1 SOAP Response Message

A SOAP response message is received as the result to the credit card processor (started by the
Gateway) having approved your transaction. It always has the following scheme:

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

<SOAP-ENV:Envelope
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header />
<SOAP-ENV:Body>
<ipgapi:IPGApiOrderResponse
xmlns:ipgapi="http://ipg-online.com/ipgapi/schemas/ipgapi">

</ipgapi:IPGApiOrderResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
If you have send an Action, you get an ipgapi:IPGApiActionResponse.

Again, no headers are defined. The SOAP body contains the actual transaction result contained in the
ipgapi:IPGApiOrderResponse or ipgapi:IPGApiOrderRequest element. Its sub elements and their
meanings are presented in the next chapter. However, in order to provide a quick example, an approved
Sale transaction is wrapped in a SOAP message similar to the following example:

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

<SOAP-ENV:Envelope
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header />
<SOAP-ENV:Body>
<ipgapi:IPGApiOrderResponse
xmlns:ipgapi="http://ipg-online.com/ipgapi/schemas/ipgapi">
<ipgapi:CommercialServiceProvider>
BNLP
</ipgapi:CommercialServiceProvider>
<ipgapi:TransactionTime>
1192111687392
</ipgapi:TransactionTime>
<ipgapi:ProcessorReferenceNumber>
3105
</ipgapi:ProcessorReferenceNumber>
<ipgapi:ProcessorResponseMessage>
Function performed error-free
</ipgapi:ProcessorResponseMessage>
<ipgapi:ErrorMessage />
<ipgapi:OrderId>
62e3b5df-2911-4e89-8356-1e49302b1807
</ipgapi:OrderId>
<ipgapi:ApprovalCode>
Y:440368:0000057177:PPXM:0043364291
</ipgapi:ApprovalCode>
<ipgapi:AVSResponse>PPX</ipgapi:AVSResponse>
<ipgapi:TDate>1192140473</ipgapi:TDate>
<ipgapi:TransactionResult>
APPROVED
</ipgapi:TransactionResult>
<ipgapi:TerminalID>123456</ipgapi:TerminalID>
<ipgapi:ProcessorResponseCode>
00
</ipgapi:ProcessorResponseCode>
<ipgapi:ProcessorApprovalCode>
440368
</ipgapi:ProcessorApprovalCode>
<ipgapi:ProcessorReceiptNumber>
4291
</ipgapi:ProcessorReceiptNumber>
<ipgapi:ProcessorTraceNumber>
004336
</ipgapi:ProcessorTraceNumber>
</ipgapi:IPGApiOrderResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

16.2 SOAP Fault Message

In general, a SOAP fault message returned by the Web Service API has the following format:

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

<SOAP-ENV:Envelope
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header />
<SOAP-ENV:Body>
<SOAP-ENV:Fault>
<faultcode>SOAP-ENV:Client</faultcode>
<faultstring xml:lang="en-US">

</faultstring>
<detail>

</detail>
</SOAP-ENV:Fault>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Basically, the faultstring element carries the fault type. According to the fault type, the other elements
are set. Note that not all of the above shown elements have to occur within the SOAP-ENV:Fault
element. Which elements exist for which fault type is described in the upcoming sections.

16.3 SOAP-ENV:Server
In general, this fault type indicates that the Web Service has failed to process your transaction due to
an internal system error. If you receive this as response, please contact our support team to resolve
the problem.

An InternalException always looks like the example below:

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

<SOAP-ENV:Envelope
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header />
<SOAP-ENV:Body>
<SOAP-ENV:Fault>
<faultcode>SOAP-ENV:Server</faultcode>
<faultstring xml:lang="en-US">
unexpected error
</faultstring>
</SOAP-ENV:Fault>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

The SOAP fault message elements – relative to the SOAP-ENV:Envelope/SOAP-ENV:Body/SOAP-

ENV:Fault element – are set as follows:
Path/Name XML Schema type Description
faultcode xs:string This element is always set to
SOAP-ENV:Server, indicating that
the fault cause is due to the
system underlying the API having
failed.
faultstring xs:string This element always carries the
following fault string:
unexpected error

16.4 SOAP-ENV:Client
MerchantException
This fault type occurs if the Gateway can trace back the error to your store having passed incorrect
information. This may have one of the following reasons:
1. Your store is registered as being closed. In case you will receive this information despite your
store being registered as open, please contact support.
2. The store ID / user ID combination you have provided for HTTPS authorization is syntactically
incorrect.
3. The XML does not match the schema.

A MerchantException always looks as shown below:

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

<SOAP-ENV:Envelope
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header />
<SOAP-ENV:Body>
<SOAP-ENV:Fault>
<faultcode>SOAP-ENV:Client</faultcode>
<faultstring xml:lang="en-US">
MerchantException
</faultstring>
<detail>

</detail>
</SOAP-ENV:Fault>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

The SOAP fault message elements – relative to the SOAP-ENV:Envelope/SOAP-ENV:Body/SOAP-

ENV:Fault element – are set as follows:

Path/Name XML Schema type Description

faultcode xs:string This element is always set to
SOAP-ENV:Client
faultstring xs:string
This element is always set to
MerchantException
detail/reason xs:string
Minimum one reason

See section Merchant Exceptions in the Appendix for detailed analysis of errors.

16.5 Processing Exception

A fault of this type is raised whenever the Gateway has detected an error while processing your
transaction. The difference to the other fault types is that the transaction passed the check against
the xsd.

A ProcessingException always looks as shown below:

<SOAP-ENV:Envelope
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header />
<SOAP-ENV:Body>
<SOAP-ENV:Fault>
<faultcode>SOAP-ENV:Client</faultcode>
<faultstring xml:lang="en-US">
ProcessingException: Processing the request
resulted in an error - see SOAP details for more
information
</faultstring>
<detail>
<ipgapi:IPGApiOrderResponse
xmlns:ipgapi="https://ipg-online.com/ipgapi/schemes/ipgapi">
<ipgapi:CommercialServiceProvider>
BNLP
</ipgapi:CommercialServiceProvider>
<ipgapi:TransactionTime>
1192111156423
</ipgapi:TransactionTime>
<ipgapi:ProcessorReferenceNumber />
<ipgapi:ProcessorResponseMessage>
Card expiry date exceeded
</ipgapi:ProcessorResponseMessage>
<ipgapi:ErrorMessage>
SGS-000033: Card expiry date exceeded
</ipgapi:ErrorMessage>
<ipgapi:OrderId>
62e3b5df-2911-4e89-8356-1e49302b1807
</ipgapi:OrderId>
<ipgapi:ApprovalCode />
<ipgapi:AVSResponse />
<ipgapi:TDate>1192139943</ipgapi:TDate>
<ipgapi:TransactionResult>
FAILED
</ipgapi:TransactionResult>
<ipgapi:TerminalID>123456</ipgapi:TerminalID>
<ipgapi:ProcessorResponseCode/>
<ipgapi:ProcessorApprovalCode />
<ipgapi:ProcessorReceiptNumber />
<ipgapi:ProcessorTraceNumber />
</ipgapi:IPGApiOrderResponse>
</detail>
</SOAP-ENV:Fault>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

The SOAP fault message elements – relative to the SOAP-ENV:Envelope/SOAP-ENV:Body/SOAP-

ENV:Fault element – are set as described below.

Path/Name XML Schema type Description

faultcode xs:string This element is always set to
SOAP-ENV:Client, indicating that
the fault cause is likely to be
found in invalid transaction data
having been passed.
faultstring xs:string This element always carries the
following fault string:
ProcessingException
detail/ Composite element This element contains the error.
ipgapi:IPGApiOrderResponse Since there are numerous causes
for raising such an exception, the
next chapter will give an overview
by explaining the data contained
in this element.

See section Processing Exceptions in the Appendix for detailed analysis of errors.

17 Analysing the Transaction Result

17.1 Transaction Approval
The SOAP message wrapping a transaction approval has been presented in the previous chapter
together with an example. The transaction status report generated by the Gateway is contained in the
ipgapi:IPGApiOrderResponse element and can be understood as the data returned by the Web Service
operation. In the following, its elements – relative to the ipgapi:IPGApiOrderResponse super element –
are described. Note that always the full set of elements is contained in the response – however, some
elements might be empty.
Path/Name XML Schema Description
type
ipgapi: xs:string Indicates your provider.
CommercialServiceProvider
ipgapi:TransactionTime xs:string The time stamp which is set by the Gateway
before returning the transaction approval.
ipgapi: xs:string In some cases, this element might be
ProcessorReferenceNumber empty. It stores a number allowing the
credit card processor to refer to this
transaction. You do not need to provide this
number in any further transaction. However,
have that number ready, in case you detect
any problems with your transaction and you
want to contact support.
ipgapi: xs:string In case of an approval, this element contains
ProcessorResponseMessage either contains the response message
provided by the authorisation system (e.g.
an auth code) or in case there is no such
message, the string:
Function performed error-free
ipgapi: xs:string The response code from the credit card
ProcessorResponseCode processor
ipgapi:ErrorMessage xs:string This element is empty in case of an
approval.
ipgapi:FraudScore xs:int This element contains the fraud score of the
transaction, if the Store is activated for the
Fraud Detect product.
ipgapi:OrderId xs:string This element contains the order ID. For Sale,
PreAuth, ForceTicket, and Credit
transactions, a new order ID is returned. For
PostAuth, Return, and Void transactions,
supply this number in the v1:OrderId
element for making clear to which
transaction you refer. The ipgapi:OrderId
element of a transaction approval to a
PostAuth, Return, or Void transaction simply
returns the order ID, such a transaction has
referred to.
ipgapi:ApprovalCode xs:string Stores the approval code the transaction
processor has created for this transaction.
You do not need to provide this code in any
further transaction. However, have that
number ready, in case you detect any
problems with your transaction and you
want to contact support.
ipgapi:AVSResponse xs:string Returns the address verification system
(AVS) response.
ipgapi:TDate xs:string Stores the TDate you have to supply when
voiding this transaction (which is only
possible for Sale and PostAuth
transactions). In this case, pass its value in
the v1:TDate element of the Void
transaction you want to build.
ipgapi:TransactionResult xs:string Stores the transaction result which is always
set to APPROVED in case of an approval or
WAITING in case the final result is not yet
clear and will be updated at a later point.
ipgapi:TerminalID xs:string The Terminal ID used for this transaction.
ipgapi:PaymentType xs:string The payment type used for this transaction.
ipgapi:Brand xs:string The brand of the card used for this
transaction.
ipgapi:ConvenienceFee xs:decimal The Convenience fee value, returned in the
response if you have this feature configured
and this is applicable for Sale transaction.
ipgapi:Country xs:string The country where the card has been issued
that has been used for this transaction.
ipgapi:SecurePlusResponse xs:string The response from UnionPay SecurePlus
authentication
ipgapi:SchemeTransactionId xs:string Returned in the response by Mastercard
for stored credentials transactions.
ipgapi:MerchantAdviceCodeIndicator xs: string2max The transaction response code for declines
for authorizations on Nashville
ipgapi:UpdatedPrimaryAccountNumbe xs:string The response from Mastercard and Visa
r Account Updater when stored credentials
are not managed by the Gateway
ipgapi:UpdatedExpirationDate xs:string The response from Mastercard and Visa
Account Updater when stored credentials
are not managed by the Gateway
ipgapi:UpdatedAccountStatus xs:string The response from Mastercard and Visa
Account Updater when stored credentials
are not managed by the Gateway; available
values:
ACCOUNT_CHANGED
ACCOUNT_CLOSED
EXPIRY_CHANGED
CONTACT_CARDHOLDER
ipgapi:UpdatedAccountErrorCode xs:string The response from Mastercard Account
Updater when stored credentials are not
managed by the Gateway

ipgapi:RedirectUrl xs:string100max The URL included in the response from the

Gateway, where you are supposed to
redirect the consumer using China domestic
or Boleto payment methods to, so they can
continue with the transaction processing
ipgapi:StandinResponseDetails xs:string Authentication details returned from Standin
instruction payment transaction; available
for Indian market only
ipgapi:Secure3DResponse/ xs:string A text optionally provided by the issuer to
v1:CardHolderInfo the cardholder during frictionless
transaction that was not authenticated by
the ACS.

ipgapi:MerchantAdviceMessage xs:string Additional information provided by Issuer in

17.2 Transaction Failure

As shown in the previous chapter, a SOAP fault message, resulting from the credit card processor
having failed to process your transaction, contains an ipgapi:IPGApiOrderResponse element passed as
child of a SOAP detail element. Note that its sub elements are exactly the same as in the transaction
approval case. Their meaning in the failure case is described below:

Path/Name XML Schema Description

type
ipgapi: xs:string Indicates your provider.
CommercialServiceProvider
ipgapi:TransactionTime xs:string The time stamp which is set by the Gateway
before returning the transaction failure. The
format is Unix time
(https://en.wikipedia.org/wiki/Unix_time).
ipgapi: xs:string In some cases, this element might be empty.
ProcessorReferenceNumber Stores a number allowing the credit card
processor to refer to this transaction. You do
not need to provide this number in any
further transactions. However, have that
number ready, in case you detect any
problems with your transaction and you want
to contact support.
ipgapi: xs:string Stores the error message the credit card
ProcessorResponseMessage processor has returned. For instance, in case
of an expired credit card this might be:
Card expiry date exceeded
ipgapi: xs:string The response code from the credit card
ProcessorResponseCode processor
ipgapi: xs:string The approval code from the credit card
ProcessorApprovalCode processor
ipgapi: xs:string The receipt number from the credit card
ProcessorReceiptNumber processor
ipgapi: xs:string The trace number from the credit card
ProcessorTraceNumber processor
ipgapi:ErrorMessage xs:string Stores the error message returned by the
Gateway. It is always encoded in the format
SGS-XXXXXX: Message with XXXXXX being
a six digit error code and Message describing
the error (this description might be different
from the processor response message). For
instance, in the above example the error
message SGS-000033: Card expiry date
exceeded is returned. Make sure to have the
error code and message ready when
contacting support.
ipgapi:OrderId xs:string Stores the order ID. In contrast to an
approval, this order ID is never required for
any further transaction, but needed for
tracing the cause of the error. Hence, make
sure to have it ready when contacting
support.
ipgapi:ApprovalCode xs:string This element is empty in case of a
transaction failure.
ipgapi:AVSResponse xs:string Returns the address verification system
(AVS) response.
ipgapi:TDate xs:string Stores the TDate. Similar to the order ID, the
TDate is never required for any further
transaction, but needed for tracing the error
cause. Hence, make sure to have it ready
when contacting support.
ipgapi:TransactionResult xs:string In the failure case, there are three possible
values:
• DECLINED
• FRAUD
• FAILED
DECLINED is returned in case the credit card
processor does not accept the transaction,
e.g. when finding the customer’s funds not
to be sufficient. FRAUD is returned in case a
fraud attempt is assumed by the Gateway. If
an internal gateway error should occur, the
returned value is FAILED.
ipgapi:TerminalID xs:string The Terminal ID used for this transaction.
ipgapi:TransactionDeclineReason xs:string Provides further advise how to handle the
transaction decline.
Examples of the values:
• “Retry Later”
• “No Updated Credentials, Do not retry”
• “Authentication may improve likely
hood of approval”
• “Suspected fraud, do not retry”

ipgapi:MerchantAdviceMessage xs:string Additional information provided by Issuer in

case specific card types have been used.
Currently available values:
• “Single-use virtual card number
presented”
• “Non-reloadable prepaid card
presented”
ipgapi:ProcessorAssociationRespo xs:string A text provided by the authorisation system
nseMessage that presents details of the transaction
status; applicable for Mastercard and Visa.
Example value: “Partial Approval”
ipgapi:AccountNameMatchRespon xs:string Field for Visa Account Name Inquiries;
se a value consists of 5 characters
representing the status of the billing
name match:
• 1st letter for FullName
• 2nd for FirstName
• 3rd for MiddleName
• 4th for LastName
with possible values:
• M for match
• P for partial match
• N for no match
and a 5th letter as NameVerificationIndicator
with possible values:
• P for performed
• S not supported
• E exception (not perfomed)
Example response value: 'MNPMP'
18 Building an HTTPS POST Request
Building an HTTPS POST request is a task you rarely have to do “by hand”. There are plenty of tools
and libraries supporting you in the composition of HTTPS requests. Mostly, the required functionality
for doing this task is contained in the standard set of libraries coming with the technological
environment in which you develop your online store.
Since all of these libraries slightly differ in their usage, no general building process can be described. In
order to illustrate the basic concepts, the following chapters will give examples showing how to build
a valid HTTPS request in PHP and ASP. In general, the set of parameters you have to provide for building
a valid HTTPS request in whatever technology is as follows:

Parameter Value Description

URL https:// This is the full URL of the Web Service API –
test.ipg-online.com/ depending on the functionality you use for building
ipgapi/services HTTP requests, you might have to split this URL
into host and service and provide this information
in the appropriate HTTP request headers.
Please note, that only TLS secured
communication over standard HTTPS TCP port
443 is accepted.
Content-Type text/xml This is an additional HTTP header needed to be
set. This is due to the SOAP request message
being encoded in XML and passed as content in
the HTTP POST request body.
Authorization Type: Basic Your store is identified at the Gateway by checking
Username: these credentials. In order to use the Web Service
WSstoreID._.userID API, you have to provide your store ID, user ID,
Password: yourPassword and password as the content of an HTTP Basic
authorization header. For instance, if your store ID
is 101, your user ID 007, and your password
myPW, the authorization user name is
WS101._.007. The complete HTTP authorization
header would be:
Authorization: Basic
V1MxMDEuXy4wMDc6bXlQVw==
Note that the latter string is the base 64 encoding
result of the string WS101._.007:myPW.
HTTP Body SOAP request XML The HTTP POST request body takes the SOAP
request message

Please note, that the Gateway is using GSLB (Global Server Load Balancing) solution to route traffic to
different locations. By default, DNS returns IP address of a primary datacenter. This may change
during planned maintenance or unplanned outage – in such case a different IP is returned, pointing to
DR (disaster recovery) location. It is therefore critical, that you respect IP address and TTL returned by
DNS. Please consider that while setting up firewalls, proxy whitelists etc.

18.1 PHP
Doing HTTP communication in PHP is mostly accomplished with the aid of cURL which is shipped both
as library and command line tool. In newer PHP versions, cURL is already included as extension which
has to be “activated”, thus making the cURL functionality available in any PHP script. While this is a
rather straightforward task in case your Web server operates on Microsoft Windows, it might require
to compile PHP on Unix/Linux machines. Therefore, you might consider to call the cURL command line
tool from your PHP script instead of using the cURL extension. Both variants are considered in the
following beginning with the usage of the cURL extension in PHP 5.2.4 running on a Windows machine.

Using the cURL PHP Extension

Mostly, activating the cURL extension in PHP 5.2.4 simply requires to uncomment the following line in
your php.ini configuration file:

;extension=php_curl.dll

Note that other PHP versions might require other actions in order to enable cURL support in PHP. Refer
to your PHP documentation for more information. After activating cURL, an HTTP request with the
above parameters is set up with the following PHP statements:

<?php
// storing the SOAP message in a variable – note that the plain XML code
// is passed here as string for reasons of simplicity, however, it is
// certainly a good practice to build the XML e.g. with DOM – furthermore,
// when using special characters, you should make sure that the XML string
// gets UTF-8 encoded (which is not done here):
$body = "<SOAP-ENV:Envelope ...>...</SOAP-ENV:Envelope>";
// initializing cURL with the IPG API URL:
$ch = curl_init("https://test.ipg-online.com/ipgapi/services");
// setting the request type to POST:
curl_setopt($ch, CURLOPT_POST, 1);
// setting the content type:
curl_setopt($ch, CURLOPT_HTTPHEADER, array("Content-Type: text/xml"));
// setting the authorization method to BASIC:
curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
// supplying your credentials:
curl_setopt($ch, CURLOPT_USERPWD, "WS101._.007:myPW");
// filling the request body with your SOAP message:
curl_setopt($ch, CURLOPT_POSTFIELDS, $body);
...
?>

Setting the security options which are necessary for enabling TLS communication will be discussed in
the next chapter extending the above script.

Using the cURL Command Line Tool

For the reasons described above, you might consider using the cURL command line tool instead of the
extension. Using the tool does not require any PHP configuration efforts – your PHP script simply has
to call the executable with a set of parameters. Since the security settings are postponed to the next
chapter, the following script only shows how to set up the standard HTTP parameters, i.e. the script is
extended with the TLS parameters in the next chapter.

<?php
// storing the SOAP message in a variable – note that you have to escape
// " and \n, since the latter makes the command line tool fail,
// furthermore note that the plain XML code is passed here as string
// for reasons of simplicity, however, it is certainly a good practice
// to build the XML e.g. with DOM – finally, when using special
// characters, you should make sure that the XML string gets UTF-8 encoded
// (which is not done here):
$body = "<SOAP-ENV:Envelope ...>...</SOAP-ENV:Envelope>";
// setting the path to the cURL command line tool – adapt this path to the
// path where you have saved the cURL binaries:
$path = "C:\curl\curl.exe";
// setting the IPG API URL:
$apiUrl = " https://test.ipg-online.com/ipgapi/services";
// setting the content type:
$contentType = " --header \"Content-Type: text/xml\"";
// setting the authorization method to BASIC and supplying
// your credentials:
$user = " --basic --user WS101._.007:myPW";
// setting the request body with your SOAP message – this automatically
// marks the request as POST:
$data = " --data \"".$body."\"".
...
?>

18.2 ASP
There are multiple ways of building an HTTP request in ASP. However, in the following, the usage of
WinHTTP 5.1 is described as it ships with Windows Server 2003 and Windows XP SP2. Furthermore,
only a few lines of code are required in order to set up a valid HTTP request. Note that the following
code fragment is written in JavaScript. Using VB Script instead does not fundamentally change the
shown statements.

<%@ language="javascript"%>
<html>...<body>
<%
// storing the SOAP message in a variable – note that the plain XML code
// is passed here as string for reasons of simplicity, however, it is
// certainly a good practice to build the XML e.g. with DOM – furthermore,
// when using special characters, you should make sure that the XML string
// gets UTF-8 encoded (which is not done here):
var body = "<SOAP-ENV:Envelope ...>...</SOAP-ENV:Envelope>";
// constructing the request object:
var request = Server.createObject("WinHttp.WinHttpRequest.5.1");
// initializing the request object with the HTTP method POST
// and the IPG API URL:
request.open("POST", "https://test.ipg-online.com/ipgapi/services");
// setting the content type:
request.setRequestHeader("Content-Type", "text/xml");
// setting the credentials:
request.setCredentials("WS10036000750._.1001", "testinger", 0);
...
%>
</body></html>

Note that the above script is extended in the next chapter by setting the security options which are
required for establishing the TLS channel.

19 Establishing a TLS connection

Before sending the HTTP request built in the previous chapter, a secure communication channel has to
be established, guaranteeing both that all data is passed encrypted and that the client (your application)
and server (running the Web Service API) can be sure of communicating with each other and no one
else.
Please note, that only TLS secured communication over standard HTTPS TCP port 443 is accepted.

Both are achieved by establishing an TLS connection with the client and server exchanging certificates.
A certificate identifies a communication party uniquely. Basically, this process works as follows:

1. TLS: The client requests access to www.ipg-online.com

2. TLS: The server presents its certificate to the client
3. TLS: The client verifies the server’s certificate (optional)
4. TLS: The server asks the client for a client certificate
5. TLS: The client sends its certificate to the server
6. TLS: The server verifies the client’s credentials
7. TLS: If successful, the server establishes TLS tunnel to www.ipg-online.com and all the data
exchanged between parties is encrypted.
8. HTTP: Start HTTP and request the URL part: /ipgapi/services […]

Following this process, your application has to do two things: First, start the communication by sending
its client certificate. Second, verify the received server certificate. How this is accomplished differs
from platform to platform. However, in order to illustrate the basic concepts, the PHP and ASP scripts
started in the previous chapter will be continued by extending them with the relevant statements
necessary for setting up a TLS connection.

19.1 PHP
Picking up the distinction between using either the PHP cURL extension or the command line tool, the
following two sections will continue the two different ways of enabling secure HTTP communication.
However, regardless of which approach you intend to use, you will be confronted with one special
feature of cURL: cURL requires the client certificate to be passed as PEM file with the Client Certificate
Private Key passed in an extra file. Finally, the Client Certificate Private Key password has to be supplied.
Simply spoken, the PEM file contains the list of client certificates with all information necessary for
allowing the server to identify the client. The private key is not really necessary for this kind of
communication. However, it is crucial for making cURL work.

Using the PHP cURL Extension

Building on the script started in the previous chapter, the parameters which are necessary for
establishing an TLS connection with cURL are set in the following statements:

<?php
...
// telling cURL to verify the server certificate:
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, 1);
// setting the path where cURL can find the certificate to verify the
// received server certificate against:
curl_setopt($ch, CURLOPT_CAINFO, "C:\certs\tlstrust.pem");
// setting the path where cURL can find the client certificate:
curl_setopt($ch, CURLOPT_SSLCERT, "C:\certs\WS101._.007.pem");
// setting the path where cURL can find the client certificate’s
// private key:
curl_setopt($ch, CURLOPT_SSLKEY, "C:\certs\WS101._.007.key");
// setting the key password:
curl_setopt($ch, CURLOPT_SSLKEYPASSWD, "ckp_1193927132");
...
?>

Note that this script is extended in the next chapter by the statements doing the actual HTTP request.
Using the cURL Command Line Tool
Building on the script started in the previous chapter, the statements which initialize the TLS
parameters passed to the cURL command line tool are as follows:

<?php
...
// setting the path where cURL can find the certificate to verify the
// received server certificate against:
$serverCert = " --cacert C:\certs\tlstrust.pem";
// setting the path where cURL can find the client certificate:
$clientCert = " --cert C:\certs\WS101._.007.pem";
// setting the path where cURL can find the client certificate’s
// private key:
$clientKey = " --key C:\certs\WS101._.007.key";
// setting the key password:
$keyPW = " --pass ckp_1193927132";
...
?>

Note that this script is extended in the next chapter by the statements doing the actual HTTP request.

19.2 ASP
For making the above TLS initialization process work, ASP requires both the client and the server
certificate to be present in certificate stores. In other words, before ASP can communicate via TLS,
both certificates have to be installed first. The following steps which assume ASP running on Microsoft
IIS 5.1 under Windows XP, will guide you through this set up process:
1. Click Start, click Run..., type mmc and click OK.
2. Open the File menu, select Add/Remove Snap-In.
3. Click Add.
4. Under Snap-In choose Certificates and click Add.
5. You will be prompted to select the account for which you want to manage the certificates.
Since IIS uses the computer account, choose Computer Account and click Next.
6. Choose Local Computer and click Finish.
7. Click Close and then OK.
8. Expand the Certificates (Local Computer) tree - the client certificate will be installed in the
Personal folder.
9. Therefore, right click the Certificates folder, select All Tasks, click Import... – this will open the
Certificate Import Wizard.
10. Click Next. Choose your client certificate p12 file and click Next.
11. Provide the client certificate installation password and click Next.
12. Select Place all certificates in the following store and browse for the Personal folder if not yet
displayed. Click Next.
13. Check the displayed settings and click Finish. Your client certificate is now installed in the local
computer’s personal certificates store. Here, IIS (running ASP) can lookup the client certificate
when communicating with another server via HTTP.
14. Now, the server certificate has to be installed in the Trusted Root Certification Authorities store.
The certificates in this store are used for verification whenever receiving a certificate from a
server. That means the Web Service API server certificate has to be installed here. In this way,
IIS is able to verify the server certificate received when contacting the Web Service. Therefore,
choose Trusted Root Certification Authorities from the Certificates (Local Computer) tree open
the sub folder Certificates.
15. Right click the Certificates folder, select All Tasks, click Import... – this will open the Certificate
Import Wizard again.
16. Click Next. Choose the Trust Anchor PKCS#7 file and click Next.
17. Select Place all certificates in the following store and browse for the Trusted Root Certification
Authorities folder if not yet displayed. You should trust all client certificates listed to establish
a trusted connection to the server. Click Next.
18. Check the displayed settings and click Finish. The server certificate is now installed in the local
computer’s trusted certificates store. Here, IIS can lookup the server certificate for verification
against the Web Service API server certificate received during the TLS setup process.

After installing both certificates one could assume that the environment allowing ASP to communicate
via TLS is set up. However, there is still one thing which makes the communication fail: IIS – running
your ASP – has a Windows user which does not have the necessary rights to access the client certificate
private key. Although accessing the private key is not really necessary for establishing the TLS
connection to the Gateway, the IIS user needs access rights for running the authentication process in
ASP. For granting rights to a user, Microsoft provides the WinHttpCertCfg.exe tool you can download
for free under:

http://www.microsoft.com/downloads/details.aspx?familyid=c42e27ac-3409-40e9-8667-
c748e422833f&displaylang=en

After installing the tool, open a command prompt, switch to the directory where you have installed the
tool, and type in the following line for granting access to the IIS user:

winhttpcertcfg -g -c LOCAL_MACHINE\My -s WS101._.007 -a IWAM_MyMachine

LOCAL_MACHINE\My determines the key store where the personal certificates for the local machine
account are stored. After installing the client certificate in the personal certificates store as described
above, the client certificate can be found under this path, so there is no need to provide another path.
WS101._.007 is the name of the client certificate. You have to adapt this name to the name of your
client certificate. Therefore, check the name displayed for the client certificate in the mmc console after
installing it as described above. Finally, IWAM_MyMachine denotes the IIS user name. Note that IIS
5.1 uses IWAM_MachineName by default. That means if your machine has the name
IISServerMachine, the IIS user will be called IWAM_IISServerMachine. Note that other IIS versions
might use a different naming scheme. If you do not know your machine name or IIS user name, check
the IIS documentation and contact your administrator.

Now you are ready to use TLS in your ASP code. The code extending the ASP script started in the
previous chapter is reduced to only one additional statement which tells WinHTTP which client
certificate to send (and where to find it) when contacting the Gateway:

<%@ language="javascript"%>
<html>...<body>
<%
...
// setting the path where the client certificate to send can be found:
request.setClientCertificate("LOCAL_MACHINE\\My\\WS101._.007");
...
%>
</body></html>

Note that if you use VB Script, the code looks almost the same – however, do not forget to replace the
doubled backslashes in the path with single ones (i.e. the path to the certificate would be
"LOCAL_MACHINE\My\WS101._.007" instead).

Note that this script is extended in the next chapter by the statements doing the actual HTTP request.
20 Sending the HTTPS POST Request and Receiving the Response

The actual communication with the Web Service API takes place when sending the HTTPS request and
waiting for a response. Again, how this is done depends on the technology you are using. Most HTTP
libraries fully cover the underlying communication details and reduce this process to a single operation
call returning the HTTP response as result object.
In any case, the parameters which are required for successfully performing an HTTP POST request over
TLS and receiving the response (carrying a 200 HTTP status code) have been described in the previous
two chapters. Setting invalid or incorrect parameters results in the web server running the Web Service
API to return a standard HTTP error code in the HTTP header of the response or sending an TLS failure.
Their meanings can be found in any HTTP/TLS guide.
Please note, that only TLS secured communication over standard HTTPS TCP port 443 is accepted.

However, there is one important exception: In case the HTTP parameters you have provided are correct,
but the Web Service has failed to process your transaction due to an incorrect value contained in the
SOAP request message (e.g. an invalid credit card number), a SOAP exception is thrown and transferred
in the body of an HTTP response carrying the error code 500. Details about the exception cause are
provided in the SOAP fault message which is described in the context of the next chapter.

In order to complete the PHP and ASP scripts, built gradually in the previous chapters, the following
two chapters will provide the statements necessary for doing an HTTP call using these technologies.

20.1 PHP
Again, the distinction between the PHP cURL extension and the cURL command line tool is made in
the following:

Using the PHP cURL Extension

The PHP script using the cURL extension is finally completed by doing the call with the statements
shown below. Note that the HTTP call returns a SOAP response or fault message in the HTTP response
body.

<?php
...
// telling cURL to return the HTTP response body as operation result
// value when calling curl_exec:
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
// calling cURL and saving the SOAP response message in a variable which
// contains a string like "<SOAP-ENV:Envelope ...>...</SOAP-ENV:Envelope>":
$result = curl_exec($ch);
// closing cURL:
curl_close($ch);
?>

Using the cURL Command Line Tool

Doing the HTTP call with the cURL command line tool simply requires completing the command line
statement and executing the external tool. However, reading the HTTP response is more complicated
as the PHP exec command saves each line returned by an external program as one element of an array.
Concatenating all elements of that array results in the SOAP response or fault message which has been
returned in the HTTP response body. The following statements handle the HTTP call and complete the
script:

<?php
...
// saving the whole command in one variable:
$curl = $path.
$data.
$contentType.
$user.
$serverCert.
$clientCert.
$clientKey.
$keyPW.
$apiUrl;
// preparing the array containing the lines returned by the cURL
// command line tool:
$returnArray = array();
// performing the HTTP call by executing the cURL command line tool:
exec($curl, $returnArray);
// preparing a variable taking the complete result:
$result = "";
// concatenating the different lines returned by the cURL command
// line tool – this result in the variable $result carrying the entire
// SOAP response message as string:
foreach($returnArray as $item)
$result = $result.$item;
?>

20.2 ASP
Doing the actual HTTP call with WinHTTP in ASP is limited to one simple operation call taking the SOAP
request XML as a parameter. After successfully performing the request a SOAP response or fault
message is returned which can be retrieved as a string by accessing the request object’s responseText
property. How such a SOAP response message looks like is described in the next chapter. The following
statements complete the ASP script:

<%@ language="javascript"%>
<html>...<body>
<%
...
// doing the HTTP call with the SOAP request message as input:
request.send(body);
// saving the SOAP response message in a string variable:
var response = request.responseText;
%>
</body></html>

21 Using a Java Client to connect to the web service

For quick and simple integration, Fiserv provides a Java Client to connect to the Gateway web service.
An instance of the IPGApiClient class manages the connection to the web service, builds XML and the
SOAP messages and evaluates the responses. To construct a transaction or to handle a response, the
developer works with simple Java bean classes.

The IPGApiClient uses the apache http client. Some settings of the http client impact every http client
for the same class loader environment.

21.1 Instance an IPGApiClient

There are several constructors available to instantiate the IPGApiClient. The example below illustrates
how to use the easiest one of the constructors. The getBytes method is also included for the
completion and simplification of the example.
String url = "https://test.ipg-online.com/ipgapi/services";
String storeId = "your store id";
String password = "your password";
byte[] key = getBytes("/path/to/your/keyStore.ks");
String keyPW = "your key store password";

IPGApiClient client = new IPGApiClient(url, storeId, password, key, keyPW);

/**
* getBytes
* reads a resource and returns a byte array
* @param resource the resource to read
* @return the resource as byte array
*/
public static byte[] getBytes(final String resource) throws IOException {
final InputStream input = IO.class.getResourceAsStream(resource);
if (input == null) {
throw new IOException(resource);
}
try {
final byte[] bytes = new byte[input.available()];
input.read(bytes);
return bytes;
} finally {
try {
input.close();
} catch (IOException e) {
log.warn(resource);
}
}
}

21.2 How to construct a transaction and handle the response

There are different classes for transactions with the following card types:

• Credit Card
• German Direct Debit
• UK Debit Cards.

The following factory class can be used to generate the class you need:

de.firstdata.ipgapi.client.transaction.IPGApiTransactionFactory
The following example shows a Credit Card Sale transaction for an amount of 7 Euros:

Amount amount = new Amount("7", "978"); // ISO 4217: EUR = 978

CreditCard cC = new CreditCard("111122******4444", "07", "27", null);
CCSaleTransaction transaction =
IPGApiTransactionFactory.createSaleTransactionCredit(amount, cC);
// some transactions may include further information e.g. the customer
transaction.setName("a name");
try {
IPGApiResult result = client.commitTransaction(transaction);
// now you can read the conclusion
System.out.println(result.getOrderId());
System.out.println(result.getTransactionTime());
// ...
} catch (ProcessingException e) {
// ERROR: transaction not passed
}

21.3 How to construct an action

The following Factory Class can be used to generate the class you need:

de.firstdata.ipgapi.client.transaction.IPGApiActionFactory

To commit an action you need to use the commitAction method of the IPGApiClient. The further
process is similar to payment transactions.

21.4 How to connect behind a proxy

Before you use the IPGApiClient behind a proxy you must set the proxy configuration of the client
with the IPGApiClient method:

IPGApiClient.setProxy(
final String host, final Integer port,
final String user, final String password,
final String workstation, final String domain)

The parameters user, password, workstation and domain should be null if no identification needed. If
you need to identify on a MS Windows proxy you must set the parameter domain. To identify on
systems like Unix the parameter domain must be null. For more information see the apache javadoc.

After setting the proxy parameters you must call the IPGApiClient.init() method.
22 Appendix

22.1 XML
The Web Service API uses the XML standard for communication as described on

http://www.w3.org/standards/xml/core

including the specification of namespaces described on

http://www.w3.org/TR/2009/REC-xml-names-20091208/

To make the names of the XML tags unique (e.g. in IPG: IPGApiActionRequest, Action,
RecurringPayment, etc.), namespaces are used.

Example:
http://ipg-online.com/ipgapi/schemas/ipgapi, http://ipg-online.com/ipgapi/schemas/a1, …

These namespaces are defined in the xsd files like

xmlns:ipgapi="http://ipg-online.com/ipgapi/schemas/ipgapi".

The same namespaces must be declared in the XML files (no parsing with hardcoded namespace
references), starting with keyword xmlns.

To aviod errors with the namespaces we recommend to use libaries to manage the XML messages.

In the course of future product develoment, it may be necessary that we extend the IPGApiRequest
or IPGApiResponse with further members. While extending the request will have no impact on your
implemented code, extending the response might cause errors if you check the response against
ipgapi.xsd. We therefore recommend to deactivate the check.

22.2 XML Schemata

The definitions for the XML document building blocks can be found here:

ipgapi.xsd https://www.ipg-online.com/ipgapi/schemas/ipgapi.xsd
v1.xsd https://www.ipg-online.com/ipgapi/schemas/v1.xsd
a1.xsd https://www.ipg-online.com/ipgapi/schemas/a1.xsd

22.3 Union Pay SecurePlus

SecurePlus is an eCommerce payment solution designed by UnionPay to reduce the risk of fraudulent
transactions, similar to 3-D Secure.
Please note that this feature is not available through all distribution channels.

There are three API request types to support SecurePlus Transactions. Two for authentication:
1. A request to verify enrollment and to send a SMS code to the cardholder
2. A request to verify the SMS code provided by the cardholder, to be the one they have sent
before
And then the authorisation which can either be the full SecurePlus sale request, or if the store is
allowed to skip, can be sent without reference to authentication. but then liability is with merchant (ECI
10).

The Web Service API allows you to make following API calls for the required steps:

API call for Step 1

To verify if the card has been enrolled and to receive an SMS code sent by issuer, you need to submit
a request with an AuthenticateTransaction parameter set to “true”, TxType = payerAuth and
enter the mobile phone number registered with the SecurePlus program.

The following represents an example of the full SecurePlusVerification Request with

TxType=payerAuth:

<?xml version="1.0" encoding="UTF-8"?><SOAP-ENV:Envelope

xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<ns4:IPGApiOrderRequest
xmlns:ns4="http://ipg-online.com/ipgapi/schemas/ipgapi"
xmlns:ns2="http://ipg-online.com/ipgapi/schemas/a1"
xmlns:ns3="http://ipg-online.com/ipgapi/schemas/v1">
<ns3:Transaction>
<ns3:CreditCardTxType>
<ns3:StoreId>47123***11088</ns3:StoreId>
<ns3:Type>payerAuth</ns3:Type>
</ns3:CreditCardTxType>
<ns3:CreditCardData>
<ns3:CardNumber>6222*****0017</ns3:CardNumber>
<ns3:ExpMonth>12</ns3:ExpMonth>
<ns3:ExpYear>33</ns3:ExpYear>
<ns3:CardCodeValue>XXX</ns3:CardCodeValue>
</ns3:CreditCardData>
<ns3:Upop>
<ns3:AuthenticateTransaction>true</ns3:AuthenticateTransaction>
</ns3:Upop>
<ns3:Payment>
<ns3:ChargeTotal>100</ns3:ChargeTotal>
<ns3:Currency>344</ns3:Currency>
</ns3:Payment>
<ns3:Billing>
<ns3:MobilePhone>86-13012345678</ns3:MobilePhone>
</ns3:Billing>
</ns3:Transaction>
</ns4:IPGApiOrderRequest>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

The following represents an example of a IPGApiOrderResponse:

<?xml version="1.0" encoding="UTF-8"?><SOAP-ENV:Envelope xmlns:SOAP-

ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<ipgapi:IPGApiOrderResponse xmlns:ipgapi="http://ipg-
online.com/ipgapi/schemas/ipgapi" xmlns:a1="http://ipg-
online.com/ipgapi/schemas/a1" xmlns:v1="http://ipg-online.com/ipgapi/schemas/v1">
<ipgapi:ApprovalCode>?:waiting authentication</ipgapi:ApprovalCode>
<ipgapi:Brand>UNIONPAY</ipgapi:Brand>
<ipgapi:Country>CHN</ipgapi:Country>
<ipgapi:CommercialServiceProvider>FDMS-
HK</ipgapi:CommercialServiceProvider>
<ipgapi:OrderId>A-046a5c58-5213-4952-b3ca-fb52de4a2f57</ipgapi:OrderId>
<ipgapi:IpgTransactionId>8383509671</ipgapi:IpgTransactionId>
<ipgapi:PaymentType>CREDITCARD</ipgapi:PaymentType>
<ipgapi:ProcessorResponseCode>00</ipgapi:ProcessorResponseCode>
<ipgapi:ProcessorResponseMessage>成功[0000000]</ipgapi:ProcessorResponse
Message>
<ipgapi:TDate>1523535455</ipgapi:TDate>
<ipgapi:TDateFormatted>2018.04.12 14:17:35 (MESZ)</ipgapi:TDateFormatte
d>
<ipgapi:TransactionResult>WAITING</ipgapi:TransactionResult>
<ipgapi:TransactionTime>1523535455</ipgapi:TransactionTime>
<ipgapi:SecurePlusResponse>
<v1:AuthenticateResponse>
<v1:smsSent>true</v1:smsSent>
</v1:AuthenticateResponse>
</ipgapi:SecurePlusResponse>
</ipgapi:IPGApiOrderResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

API call for Step 2

In your second API call you need to request Union Pay to verify the SMS code provided by the
cardholder.

The following represents an example of a verification request:

<?xml version="1.0" encoding="UTF-8"?><SOAP-ENV:Envelope

xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<ns4:IPGApiOrderRequest
xmlns:ns4="http://ipg-online.com/ipgapi/schemas/ipgapi"
xmlns:ns2="http://ipg-online.com/ipgapi/schemas/a1"
xmlns:ns3="http://ipg-online.com/ipgapi/schemas/v1">
<ns3:Transaction>
<ns3:CreditCardTxType>
<ns3:StoreId>47123**11088</ns3:StoreId>
<ns3:Type>payerAuth</ns3:Type>
</ns3:CreditCardTxType>
<ns3:CreditCardData>
<ns3:CardCodeValue>XXX</ns3:CardCodeValue>
</ns3:CreditCardData>
<ns3:Upop>
<ns3:SecurePlusRequest>
<ns3:SecurePlusVerifySmsCodeRequest>
<ns3:smsCode>111111</ns3:smsCode>
</ns3:SecurePlusVerifySmsCodeRequest>
</ns3:SecurePlusRequest>
</ns3:Upop>
<ns3:Payment>
<ns3:ChargeTotal>100</ns3:ChargeTotal>
<ns3:Currency>344</ns3:Currency>
</ns3:Payment>
<ns3:TransactionDetails>
<ns3:IpgTransactionId>8383509671</ns3:IpgTransactionId>
</ns3:TransactionDetails>
</ns3:Transaction>
</ns4:IPGApiOrderRequest>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

The following represents an example of a IPGApiOrderResponse:

<?xml version="1.0" encoding="UTF-8"?><SOAP-ENV:Envelope xmlns:SOAP-

ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<ipgapi:IPGApiOrderResponse
xmlns:ipgapi="http://ipg-online.com/ipgapi/schemas/ipgapi"
xmlns:a1="http://ipg-online.com/ipgapi/schemas/a1"
xmlns:v1="http://ipg-online.com/ipgapi/schemas/v1">
<ipgapi:ApprovalCode>Y:ECI9:Authenticated</ipgapi:ApprovalCode>
<ipgapi:Brand>UNIONPAY</ipgapi:Brand>
<ipgapi:Country>CHN</ipgapi:Country>
<ipgapi:CommercialServiceProvider>FDMS-HK</ipgapi:CommercialServiceProvider>
<ipgapi:OrderId>A-046a5c58-5213-4952-b3ca-fb52de4a2f57</ipgapi:OrderId>
<ipgapi:IpgTransactionId>8383509671</ipgapi:IpgTransactionId>
<ipgapi:PaymentType>CREDITCARD</ipgapi:PaymentType>
<ipgapi:ProcessorResponseCode>00</ipgapi:ProcessorResponseCode>
<ipgapi:ProcessorResponseMessage>成功[0000000]</ipgapi:ProcessorResponseMessage>
<ipgapi:TDate>1523535455</ipgapi:TDate>
<ipgapi:TDateFormatted>2018.04.12 14:17:35 (MESZ)</ipgapi:TDateFormatted>
<ipgapi:TransactionResult>APPROVED</ipgapi:TransactionResult>
<ipgapi:TransactionTime>1523535455</ipgapi:TransactionTime>
<ipgapi:SecurePlusResponse>
<v1:VerifySmsCodeResponse>
<v1:responseCode>1</v1:responseCode>
</v1:VerifySmsCodeResponse>
</ipgapi:SecurePlusResponse>
</ipgapi:IPGApiOrderResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

API call for Step 3

In your third API call you submit the authorization, which can either be the full SecurePlus sale
request, or if your store is allowed to skip, can be sent without reference to authentication, but then
liability is with merchant (ECI 10).

The following represents an example of an authorization request:

<?xml version="1.0" encoding="UTF-8"?><SOAP-ENV:Envelope xmlns:SOAP-

The following represents an example of a IPGApiOrderResponse:

<?xml version="1.0" encoding="UTF-8"?><SOAP-ENV:Envelope

xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<ipgapi:IPGApiOrderResponse
xmlns:ipgapi="http://ipg-online.com/ipgapi/schemas/ipgapi"
xmlns:a1="http://ipg-online.com/ipgapi/schemas/a1"
xmlns:v1="http://ipg-online.com/ipgapi/schemas/v1">
<ipgapi:ApprovalCode>Y:440368:0000057177:PPXM:0043364291</ipgapi:ApprovalCode>
<ipgapi:AVSResponse>PPX</ipgapi:AVSResponse>
<ipgapi:Brand>UNIONPAY</ipgapi:Brand>
<ipgapi:Country>CHN</ipgapi:Country>
<ipgapi:CommercialServiceProvider>FDMS-HK</ipgapi:CommercialServiceProvide
r>
<ipgapi:OrderId>A-046a5c58-5213-4952-b3ca-fb52de4a2f57</ipgapi:OrderId>
<ipgapi:IpgTransactionId>90419835</ipgapi:IpgTransactionId>
<ipgapi:PaymentType>CREDITCARD</ipgapi:PaymentType>
<ipgapi:ProcessorApprovalCode>000000</ipgapi:ProcessorApprovalCode>

<ipgapi:ProcessorResponseCode>00</ipgapi:ProcessorResponseCode>
<ipgapi:ProcessorResponseMessage>Function performed error-free
</ipgapi:ProcessorResponseMessage>
<ipgapi:TDate>1523969700</ipgapi:TDate>
<ipgapi:TDateFormatted>2018.04.17 14:55:00(CEST)</ipgapi:TDateFormatted>
<ipgapi:TerminalID>00001118</ipgapi:TerminalID>
<ipgapi:TransactionResult>APPROVED</ipgapi:TransactionResult>
<ipgapi:TransactionTime>1523969700</ipgapi:TransactionTime>
<ipgapi:SecurePlusResponse>
<v1:VerifySmsCodeResponse>
<v1:responseCode>1</v1:responseCode>
</v1:VerifySmsCodeResponse>
</ipgapi:SecurePlusResponse>
</ipgapi:IPGApiOrderResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

22.4 Bancontact QR code transactions

The Bancontact card processing capabilities on the Gateway have been enhanced to offer a new
option for QR-Code based payments with the Bancontact App.
Please note, that this feature is not available through all distribution channels and supports only pass-
through authentication model, where the 3-D Secure authentication is handled by external MPI
provider.
You are able to include additional parameters in your API requests that support the QR-Code based
authorization with an indicator, if you pay using the Bancontact app or the traditional way, entering the
card details.

The following represents an example of an authorization request for payment with Bancontact App:

<?xml version="1.0" encoding="UTF-8"?><SOAP-ENV:Envelope

xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<ns4:IPGApiOrderRequest
xmlns:ns4="http://ipg-online.com/ipgapi/schemas/ipgapi"
xmlns:ns2="http://ipg-online.com/ipgapi/schemas/a1"
xmlns:ns3="http://ipg-online.com/ipgapi/schemas/v1">
<ns3:Transaction>
<ns3:CreditCardTxType>
<ns3:StoreId>230995000</ns3:StoreId>
<ns3:Type>sale</ns3:Type>
</ns3:CreditCardTxType>
<ns3:CreditCardData>
<ns3:CardNumber>6703*****4449</ns3:CardNumber>
<ns3:ExpMonth>07</ns3:ExpMonth>
<ns3:ExpYear>27</ns3:ExpYear>
<ns3:CardCodeValue>XXX</ns3:CardCodeValue>
</ns3:CreditCardData>
<ns3:CreditCard3DSecure>
<ns3:VerificationResponse>Y</ns3:VerificationResponse>
<ns3:PayerAuthenticationResponse>Y</ns3:PayerAuthenticationResponse>
<ns3:AuthenticationValue>BwABC…neJAAAAAAA=</ns3:AuthenticationValue>
<ns3:XID>nhrtvl22IdlqdioLX6eQmd3jL6U=</ns3:XID>
</ns3:CreditCard3DSecure>
<ns3:Payment>
<ns3:ChargeTotal>708</ns3:ChargeTotal>
<ns3:Currency>EUR</ns3:Currency>
</ns3:Payment>
<ns3:TransactionDetails>
<ns3:TransactionOrigin>ECI</ns3:TransactionOrigin>
</ns3:TransactionDetails>
<ns3:BancontactQR>
<ns3:TransactionRoutingMeans>QR Code</ns3:TransactionRoutingMeans>
<ns3:IssuerCustomerReference>as23..fsdf</ns3:IssuerCustomerReference>
</ns3:BancontactQR>
</ns3:Transaction>
</ns4:IPGApiOrderRequest>

The following represents an example of an authorization request for payment with Bancontact card:

<?xml version="1.0" encoding="UTF-8"?><SOAP-ENV:Envelope

xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<ns4:IPGApiOrderRequest
xmlns:ns4="http://ipg-online.com/ipgapi/schemas/ipgapi"
xmlns:ns2="http://ipg-online.com/ipgapi/schemas/a1"
xmlns:ns3="http://ipg-online.com/ipgapi/schemas/v1">
<ns3:Transaction>
<ns3:CreditCardTxType>
<ns3:StoreId>230995000</ns3:StoreId>
<ns3:Type>sale</ns3:Type>
</ns3:CreditCardTxType>
<ns3:CreditCardData>
<ns3:CardNumber>6703*****4449</ns3:CardNumber>
<ns3:ExpMonth>07</ns3:ExpMonth>
<ns3:ExpYear>27</ns3:ExpYear>
<ns3:CardCodeValue>XXX</ns3:CardCodeValue>
</ns3:CreditCardData>
<ns3:CreditCard3DSecure>
<ns3:VerificationResponse>Y</ns3:VerificationResponse>
<ns3:PayerAuthenticationResponse>Y</ns3:PayerAuthenticationResponse>
<ns3:AuthenticationValue>BwABC…neJAAAAAAA=</ns3:AuthenticationValue>
<ns3:XID>nhrtvl22IdlqdioLX6eQmd3jL6U=</ns3:XID>
</ns3:CreditCard3DSecure>
<ns3:Payment>
<ns3:ChargeTotal>708</ns3:ChargeTotal>
<ns3:Currency>EUR</ns3:Currency>
</ns3:Payment>
<ns3:TransactionDetails>
<ns3:TransactionOrigin>ECI</ns3:TransactionOrigin>
</ns3:TransactionDetails>
<ns3:BancontactQR>
<ns3:TransactionRoutingMeans>URL Intent</ns3:TransactionRoutingMeans>
<ns3:IssuerCustomerReference>as23..fsdf</ns3:IssuerCustomerReference>
</ns3:BancontactQR>
</ns3:Transaction>
</ns4:IPGApiOrderRequest>

An optional element IssuerCustomerReference allows you to also include an identifier for the
cardholder.

22.5 China domestic processing

Fiserv has partnered with Huifu, a payment provider in China, to offer the ability to route Chinese
transactions and settle domestically in China.
This solution includes China UnionPay, Alipay and WeChat Pay with a redirection of the consumer to
pages in Chinese language provided by the local partner.

The following represents an example of a transaction request with payment method “CUP
Domestic”:

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

<ns4:IPGApiOrderRequest
xmlns:ns4="http://ipg-online.com/ipgapi/schemas/ipgapi" xmlns:ns2="http://ipg-
online.com/ipgapi/schemas/a1"
xmlns:ns3="http://ipg-online.com/ipgapi/schemas/v1">
<ns3:Transaction>
<ns3:CUPDomesticTxType>
<ns3:StoreId>471230011057</ns3:StoreId>
<ns3:Type>sale</ns3:Type>
</ns3:CUPDomesticTxType>
<ns3:CUPDomesticInformation>
<ns3:CustomerId>123</ns3:CustomerId>
<ns3:ProductCode>400005</ns3:ProductCode>
<ns3:ProductQuantity>1</ns3:ProductQuantity>
<ns3:ProductPrice>1</ns3:ProductPrice>
<ns3:ProductDescription>product01</ns3:ProductDescription>
<ns3:RedirectUrl>http://www.testURL.com</ns3:RedirectUrl>
<ns3:BankId>abc</ns3:BankId>
</ns3:CUPDomesticInformation>
<ns3:Payment>
<ns3:ChargeTotal>2</ns3:ChargeTotal>
<ns3:Currency>840</ns3:Currency>
</ns3:Payment>
<ns3:TransactionDetails>
<ns3:OrderId>API-TestTxn</ns3:OrderId>
</ns3:TransactionDetails>
</ns3:Transaction>
</ns4:IPGApiOrderRequest>
The RedirectURL in the request is where Chinese platform (PNR) is going to redirect you to after the
processing is done at their end.

Please note, that for payment method “CUP_domestic” the element ‘BankId’ is mandatory and the
element ‘CustomerId’ is recommended to be submitted in case your consumer knows its value.

Valid ‘ProductCode’ element values are available here:

ProductCatalogofX
bordersystem跨境系统商品类别_v0%201EN.xlsx
:

For payment method Alipay please use the elements AlipayTxType AND
AlipayDomesticInformation.
For payment method WeChat please use the elements WeChatTxType AND
WeChatDomesticInformation.

The following represents an example of a transaction response:

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

xmlns:ipgapi="http://ipg-online.com/ipgapi/schemas/ipgapi" xmlns:a1="http://ipg-
online.com/ipgapi/schemas/a1"
xmlns:v1="http://ipg-online.com/ipgapi/schemas/v1">
<ipgapi:ApprovalCode>?:waiting CHINAPNR</ipgapi:ApprovalCode>
<ipgapi:AVSResponse>PPX</ipgapi:AVSResponse>
<ipgapi:CommercialServiceProvider>FDMS-HK</ipgapi:CommercialServiceProvider>
<ipgapi:OrderId>API-TestTxn</ipgapi:OrderId>
<ipgapi:IpgTransactionId>8383903542</ipgapi:IpgTransactionId>
<ipgapi:ProcessorResponseCode>000000</ipgapi:ProcessorResponseCode>
<ipgapi:ProcessorResponseMessage>ChinaPnR
success</ipgapi:ProcessorResponseMessage>
<ipgapi:TDate>1548783233</ipgapi:TDate>
<ipgapi:TDateFormatted>2019.10.29 18:33:53 (MEZ)</ipgapi:TDateFormatted>
<ipgapi:TerminalID>0010001</ipgapi:TerminalID>
<ipgapi:TransactionResult>WAITING</ipgapi:TransactionResult>
<ipgapi:TransactionTime>1548783233</ipgapi:TransactionTime>
<ipgapi:RedirectUrl>https://hfgj.chinapnr.com/pay/redirectGw.htm?sequenceId=200
0019929&mac=6783F30480FE694B429ABCA1685ED</ipgapi:RedirectUrl>
</ipgapi:IPGApiOrderResponse>

The ‘RedirectURL’ in the IPG response is where you need to redirect your consumer so that they can
continue with the transaction processing on PNR platform side.

More integration options for China domestic payment methods are described in the Gateway’s
Connect integration guide.

22.6 Visa Account Funding Transactions (AFT)

The Account Funding Transaction (AFT) is a transaction used to pull funds from a card account in
order to fund a push OCT to a different account, which can be either the cardholder's or another
person's account.

The table provides an overview of all mandatory and optional fields to be included in the API request
in case you are eligible to perform AFT transactions:
Path/Name XML Schema Description
type
v1:TransactionDetails/ xs:string Represents the identity of the merchant
v1:BusinessApplicationIdentifier participating in AFT program, available values:
• ACCOUNT_TO_ACCOUNT
• BANK_INITIATED_TRANSFER
• BUSINESS_TO_BUSINESS
• CARD_BILL_PAYMENT
• FUNDS_DISBURSEMENT
• FUND_TRANSFER
• GAMBLING_PAYOUT
• GENERAL_FUNDS_DISBURSEMENT
• GOVERNMENT_DISBURSEMENT
• LOYALTY_PAYMENTS
• MERCHANT_DISBURSEMENT
• MERCHANT_PAYMENT
• NON_CARD_BILL_PAYMENT
• ONLINE_GAMBLING_PAYOUT
• PAYROLL_OR_PENSION_DISBURSEMENT
• PERSON_TO_PERSON
• TOPUP_FOR_ENHANCED_PREPAID_LOADS
• TOP_OFF
• WALLET_TRANSFER
• ZERO_DOLLAR_AUTHORIZATION
v1:Transaction/ xs:string Sender’s Name
v1:Sender/ 100max
v1:Name

v1:Transaction/ xs:string Sender’s Account Number

v1:Sender/ 34max
v1:AccountNumber
v1:Transaction/ xs:string Optional element Sender Reference Number;
v1:Sender/ 32max contains a transaction reference number that is
v1:ReferenceNumber provided by the originator and can be used to
uniquely identify the sender
v1:Transaction/ xs:string Sender’s Address
v1:Sender/ 250max
v1:Address
v1:Transaction/ xs:string Sender’s City
v1:Sender/ 50max
v1:City
v1:Transaction/ xs:string Sender’s State (if applicable)
v1:Sender/ 96max
v1:State
v1:Transaction/ xs:string Sender’s ZIP code
v1:Sender/ 10max
v1:Zip
v1:Transaction/ xs:string Sender’s Phone Number
v1:Sender/ 32max
v1:Phone
v1:Transaction/ xs:string Sender’s Country
v1:Sender/
v1:Country
v1:Transaction/ xs:string Recipient’s Name
v1:Receiver/ 100max
v1:Name
v1:Transaction/ xs:string Recipient’s Account Number
v1:Receiver/
v1:AccountNumber
v1:Transaction/ xs:string Recipient’s Reference Number
v1:Receiver/ 32max
v1:ReferenceNumber

The following xml document represents an example of a Visa AFT transaction including mandatory
and optional set of elements, mandatory elements are highlighted:

Mastercard MoneySend makes it possible to credit a Mastercard account (for a credit, debit or
prepaid card) via the existing payments system infrastructure.

The table provides an overview of all mandatory and optional fields to be included in the API request
in case you are eligible to perform account funding transactions:

Path/Name XML Description

Schema type
v1:TransactionDetails/ xs:string Represents the identity of the merchant participating
v1:TransactionTypeIdentifier in MoneySend program, available values:
• BUSINESS_DISBURSEMENT_MONEY_SEND
• BUSINESS_DISBURSEMENT_MONEY_TRANSFER
• BUSINESS_TO_BUSINESS_MONEY_SEND
• BUSINESS_TO_BUSINESS_MONEY_TRANSFER
• CARD_BILL_PAYMENT_MONEY_SEND
• CARD_BILL_PAYMENT_MONEY_TRANSFER
• GOVERNMENT_DISBURSEMENT_NONPROFIT
• OWN_ACCOUNT_MONEY_SEND
• OWN_ACCOUNT_MONEY_TRANSFER
• OWN_DEBIT_PREPAID_TRANSFER
• OWN_WALLET_TRANSFER
• PERSON_TO_PERSON_CARD_ACCOUNT
• PERSON_TO_PERSON_MONEY_SEND
• PERSON_TO_PERSON_MONEY_TRANSFER
• RAPID_MERCHANT_SETTLEMENT
v1:Transaction/ xs:string Sender’s Name
v1:Sender/ 100max
v1:Name

v1:Transaction/ xs:string Sender’s Account Number

v1:Sender/ 34max
v1:AccountNumber
v1:Transaction/ xs:string Sender Reference Number; contains a transaction
v1:Sender/ 32max reference number that is provided by the originator
v1:ReferenceNumber and can be used to uniquely identify the sender
v1:Transaction/ xs:string Sender’s Address
v1:Sender/ 250max
v1:Address
v1:Transaction/ xs:string Sender’s City
v1:Sender/ 50max
v1:City
v1:Transaction/ xs:string Sender’s State (if applicable)
v1:Sender/ 96max
v1:State
v1:Transaction/ xs:string Sender’s ZIP code
v1:Sender/ 10max
v1:Zip
v1:Transaction/ xs:string Sender’s Phone Number
v1:Sender/ 32max
v1:Phone
v1:Transaction/ xs:string Sender’s Country
v1:Sender/
v1:Country
v1:Transaction/ xs:string Recipient’s Name
v1:Receiver/ 100max
v1:Name
v1:Transaction/ xs:string Recipient’s Account Number
v1:Receiver/
v1:AccountNumber
v1:Transaction/ xs:string Recipient’s Reference Number
v1:Receiver/ 32max
v1:ReferenceNumber

The following xml document represents an example of a Mastercard MoneySend transaction

including mandatory and optional set of elements, mandatory elements are highlighted:

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<ipgapi:IPGApiOrderRequest xmlns:v1="http://ipg-online.com/ipgapi/schemas/v1"
xmlns:ipgapi="http://ipg-online.com/ipgapi/schemas/ipgapi">
<v1:Transaction>
<v1:CreditCardTxType>
<v1:StoreId>364829</v1:StoreId>
<v1:Type>sale</v1:Type>
</v1:CreditCardTxType>
<v1:CreditCardData>
<v1:CardNumber>5595********9545</v1:CardNumber>
<v1:ExpMonth>12</v1:ExpMonth>
<v1:ExpYear>24</v1:ExpYear>
<v1:CardCodeValue>545</v1:CardCodeValue>
</v1:CreditCardData>
<v1:Payment>
<v1:ChargeTotal>14</v1:ChargeTotal>
<v1:Currency>AUD</v1:Currency>
</v1:Payment>
<v1:TransactionDetails>
<v1:TransactionTypeIdentifier>PERSON_TO_PERSON_CARD_ACCOUNT</v1:Tran
sactionTypeIdentifier>
</v1:TransactionDetails>
<v1:Sender>
<v1:Name>Sender name</v1:Name>
<v1:AccountNumber>1234567890</v1:AccountNumber>
<v1:AccountType>PHONE_NUMBER</v1:AccountType>
<v1:Address>1st Street</v1:Address>
<v1:City>CHENNAI</v1:City>
<v1:State>TN</v1:State>
<v1:Zip>41460</v1:Zip>
<v1:Phone>1234567890</v1:Phone>
<v1:Country>IND</v1:Country>
<v1:ReferenceNumber>20221207</v1:ReferenceNumber>
</v1:Sender>
<v1:Receiver>
<v1:Name>Receiver name</v1:Name>
<v1:AccountNumber>1234567891234</v1:AccountNumber>
<v1:AccountType>PHONE_NUMBER</v1:AccountType>
<v1:Country>AUS</v1:Country>
</v1:Receiver>
</v1:Transaction>
</ipgapi:IPGApiOrderRequest>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
22.8 RuPay

Rupay cards can be authenticated through 2 different methods.

• Redirection Flow – a payment page is redirected to the Issuer’s authentication page to
complete the authentication with an OTP (One Time Password)
• Seamless Flow – authentication is performed within your website

Which of above authentication methods can be used depends on its availability on the issuers’ side.
For card BINs supporting both methods a seamless authentication is usually preferred.

Rupay Authentication is initiated with a “Payerauth” request containing the following additional
mandatory fields.

• ‘AuthenticateTransaction’ parameter to be set to“true”

• ‘TermUrl’ parameter represents the URL to which the result of the authentication is
redirected.
• ‘CardHolderBrowserParameters’ containing “BrowserAcceptHeader”, “BrowserIP”,
“BrowserLanguage”, “BrowserUserAgent” are mandatory

API response you receive from the Gateway from a ‘payerauth’ request, will help you to identify
which authentication method has been selected and is supported by the issuer.

Redirection Flow
In case the issuer supports Redirection method only, the Gateway returns the parameter “AcsURL”
in the response.
You need to perform a redirect as a POST request to the “AcsURL” which is generally implemented
as auto-submit form. The cardholder will be redirected to the issuer’s ACS and presented with the UI
to collect the authentication details - to enter one-time-password (OTP).

In the first step you submit a ‘payerauth’ request including all mandatory parameters as highlighted
below.
The following XML document represents an example of a Payerauth transaction using the minimum
set of elements:

The following XML document represents an example of a response indicating, that the Redirection
Flow is supported by the issuer:

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<ipgapi:IPGApiOrderResponse
xmlns:a1="http://ipg-online.com/ipgapi/schemas/a1"
xmlns:ipgapi="http://ipg-online.com/ipgapi/schemas/ipgapi"
xmlns:v1="http://ipg-online.com/ipgapi/schemas/v1">
<ipgapi:ApprovalCode>?:waiting authentication</ipgapi:ApprovalCode>
<ipgapi:Brand>RUPAY</ipgapi:Brand>
<ipgapi:Country>IND</ipgapi:Country>
<ipgapi:CommercialServiceProvider>IMS</ipgapi:CommercialServiceProvider>
<ipgapi:OrderId>A-3a0bb646-430e-43bb-ad3a-2170c61597b0</ipgapi:OrderId>
<ipgapi:IpgTransactionId>84438910651</ipgapi:IpgTransactionId>
<ipgapi:PaymentType>CREDITCARD</ipgapi:PaymentType>
<ipgapi:TDate>1685187954</ipgapi:TDate>
<ipgapi:TDateFormatted>2023.05.27 13:45:54 (CEST)</ipgapi:TDateFormatted>
<ipgapi:TransactionTime>1685187954</ipgapi:TransactionTime>
<ipgapi:Secure3DResponse>
<v1:Secure3DVerificationResponse>
<v1:VerificationRedirectResponse>
<v1:AcsURL>https://test/gateway/processing?rupayId=84438910651</v1:AcsURL>
<v1:TermUrl> https://test/webshop/receiveAndProcess/validate</v1:TermUrl>
</v1:VerificationRedirectResponse>
</v1:Secure3DVerificationResponse>
</ipgapi:Secure3DResponse>
</ipgapi:IPGApiOrderResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

The parameter “AcsURL” in the “VerificationRedirectResponse” represents the URL you need to
redirect your consumers to, so that they are able to perform an authentication.

In the next step you need to POST data to the indicated “AcsURL” usually implemented as an auto-
submit form. This needs to be implemented within your website. The cardholder will be redirected to
the ACS and presented with the UI to collect the authentication details - enter one-time-password
(OTP). After successful authentication the consumer is redirected back the URL you provided within
“TermUrl” parameter.

It is recommended to perform the extended hash validation on the fields received in the response and
inquiry order status, to ensure there were no data tampering in place.

In the next step you need to submit a “sale” request and include “ipgTransactionId” you have
received in the first API response from out Gateway.
The following XML document represents an example of a “SALE” transaction using the minimum set
of elements:

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header />
<SOAP-ENV:Body>
<ipgapi:IPGApiOrderRequest
xmlns:ipgapi="http://ipg-online.com/ipgapi/schemas/ipgapi"
xmlns:v1="http://ipg-online.com/ipgapi/schemas/v1">
<v1:Transaction>
<v1:CreditCardTxType>
<v1:StoreId>{{storeid}}</v1:StoreId>
<v1:Type>sale</v1:Type>
</v1:CreditCardTxType>
<v1:CreditCardData>
<v1:CardCodeValue>{{rupay.cvv}}</v1:CardCodeValue>
</v1:CreditCardData>
<v1:Payment>
<v1:ChargeTotal>15</v1:ChargeTotal>
<v1:Currency>356</v1:Currency>
</v1:Payment>
<v1:TransactionDetails>
<v1:IpgTransactionId>84438910651</v1:IpgTransactionId>
</v1:TransactionDetails>
</v1:Transaction>
</ipgapi:IPGApiOrderRequest>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

The following XML document represents an example of a response:

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<SOAP-ENV:Fault>
<faultcode>SOAP-ENV:Client</faultcode>
<faultstring xml:lang="en">ProcessingException</faultstring>
<detail>
<ipgapi:IPGApiOrderResponse
xmlns:a1="http://ipg-online.com/ipgapi/schemas/a1"
xmlns:ipgapi="http://ipg-online.com/ipgapi/schemas/ipgapi"
xmlns:v1="http://ipg-online.com/ipgapi/schemas/v1">
<ipgapi:ApprovalCode>Y:095120:4438510496:PPX :314609510495</ipgapi:ApprovalCode>
<ipgapi:AVSResponse>PPX</ipgapi:AVSResponse>
<ipgapi:Brand>RUPAY</ipgapi:Brand>
<ipgapi:Country>IND</ipgapi:Country>
<ipgapi:CommercialServiceProvider>IMS</ipgapi:CommercialServiceProvider>
<ipgapi:ErrorMessage>SGS-030052: Communication Error</ipgapi:ErrorMessage>
<ipgapi:OrderId>A-3a0bb646-430e-43bb-ad3a-2170c61597b0</ipgapi:OrderId>
<ipgapi:IpgTransactionId>84438910652</ipgapi:IpgTransactionId>
<ipgapi:PaymentType>CREDITCARD</ipgapi:PaymentType>
<ipgapi:ProcessorApprovalCode>095120</ipgapi:ProcessorApprovalCode>
<ipgapi:ProcessorReferenceNumber>314717910651</ipgapi:ProcessorReferenceNumber>
ipgapi:ProcessorResponseCode>00</ipgapi:ProcessorResponseCode>
<ipgapi:ProcessorResponseMessage>success</ipgapi:ProcessorResponseMessage>
<ipgapi:SchemeTransactionId>100112023052600000000000220467</ipgapi:SchemeTransactio
nId>
<ipgapi:TDate>1685190028</ipgapi:TDate>
<ipgapi:TDateFormatted>2023.05.27 14:20:28 (CEST)</ipgapi:TDateFormatted>
<ipgapi:TerminalID>00001113</ipgapi:TerminalID>
<ipgapi:TransactionResult>APPROVED</ipgapi:TransactionResult>
<ipgapi:TransactionTime>1685190028</ipgapi:TransactionTime>
</ipgapi:IPGApiOrderResponse>
</detail>
</SOAP-ENV:Fault>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Seamless Flow
In case the issuer supports Seamless flow, the Gateway returns the “OtpVerificationResponse”
parameter after payerAuth request.
During the seamless flow, the cardholder’s authentication (OTP) is captured within your webside and
OTP must be submitted to the Gateway in the next API request.

In the first step you submit a ‘payerauth’ request including all mandatory parameters, e.g.
‘AuthenticateTransaction’, ‘TermUrl’, ‘CardHolderBrowserParameters’.

The following XML document represents an example of a Payerauth transaction using the minimum
set of elements:

The following XML document represents an example of a response containing parameter

‘OtpVerificationResponse’ indicating, that the Seamless Flow is supported by the issuer:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<ipgapi:IPGApiOrderResponse
xmlns:a1="http://ipg-online.com/ipgapi/schemas/a1"
xmlns:ipgapi="http://ipg-online.com/ipgapi/schemas/ipgapi"
xmlns:v1="http://ipg-online.com/ipgapi/schemas/v1">
<ipgapi:ApprovalCode>?:waiting authentication</ipgapi:ApprovalCode>
<ipgapi:Brand>RUPAY</ipgapi:Brand>
<ipgapi:Country>IND</ipgapi:Country>
<ipgapi:CommercialServiceProvider>IMS</ipgapi:CommercialServiceProvider>
<ipgapi:OrderId>A-7263bcdf-b2b7-4797-a5a6-691181cf0510</ipgapi:OrderId>
<ipgapi:IpgTransactionId>84439794295</ipgapi:IpgTransactionId>
<ipgapi:PaymentType>CREDITCARD</ipgapi:PaymentType>
<ipgapi:TDate>1685864722</ipgapi:TDate>
<ipgapi:TDateFormatted>2023.06.04 09:45:22 (CEST)</ipgapi:TDateFormatted>
<ipgapi:TransactionTime>1685864722</ipgapi:TransactionTime>
<ipgapi:Secure3DResponse>
<v1:OtpVerificationResponse>
<v1:OtpValidityInMinutes>1</v1:OtpValidityInMinutes>
</v1:OtpVerificationResponse>
</ipgapi:Secure3DResponse>
</ipgapi:IPGApiOrderResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

While receiving the ‘OtpVerificationResponse’, you must provide an option for your carholders to
collect the authentication details, such as One-Time Password.

While capturing the OTP within your website, you must submit a ‘payerauth’ request to the Gateway
and include a parameter “VerifyOtp”.

The following XML document represents an example of a ‘payerauth’ transaction using the minimum
set of elements:

In the response you receive a confirmation, if the OTP has been verified successfully.
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<ipgapi:IPGApiOrderResponse xmlns:a1="http://ipg-
online.com/ipgapi/schemas/a1" xmlns:ipgapi="http://ipg-
online.com/ipgapi/schemas/ipgapi" xmlns:v1="http://ipg-
online.com/ipgapi/schemas/v1">
<ipgapi:ApprovalCode>Y:00:OTP verified successfully.</ipgapi:ApprovalCode>
<ipgapi:Brand>RUPAY</ipgapi:Brand>
<ipgapi:Country>IND</ipgapi:Country>
<ipgapi:CommercialServiceProvider>IMS</ipgapi:CommercialServiceProvider>
<ipgapi:OrderId>A-7263bcdf-b2b7-4797-a5a6-691181cf0510</ipgapi:OrderId>
<ipgapi:IpgTransactionId>84439794295</ipgapi:IpgTransactionId>
<ipgapi:PaymentType>CREDITCARD</ipgapi:PaymentType>
<ipgapi:TDate>1685864722</ipgapi:TDate>
<ipgapi:TDateFormatted>2023.06.04 09:45:22 (CEST)</ipgapi:TDateFormatted>
<ipgapi:TransactionResult>APPROVED</ipgapi:TransactionResult>
<ipgapi:TransactionTime>1685864722</ipgapi:TransactionTime>
<ipgapi:Secure3DResponse>
<v1:OtpVerificationResponse>
<v1:ResponseCode>00</v1:ResponseCode>
<v1:ResponseDescription>OTP verified successfully.</v1:ResponseDescription>
</v1:OtpVerificationResponse>
</ipgapi:Secure3DResponse>
</ipgapi:IPGApiOrderResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

It is possible to regenerate OTP within your website with submitting the parameter “RegenerateOtp”
for “IpgTransactionId”. The Gateway will perform a call to NPCI in the background.

Please note, that “OtpVerificationRequest” may be used for both OTP verification and regeneration.
In cases you need to regenerate OTP, it is mandated to include your card details and CVV.

The following XML document represents an example of a Payerauth transaction using the minimum
set of elements:

The following XML document represents an example of a response including OTP validity time:

It is recommended to perform an inquiry call to ensure the authentication has been successful. In the
next step you need to submit a “sale” request and include “IpgTransactionId” you have received in
the first API response from the Gateway.

The following XML document represents an example of a ‘sale’ transaction using the minimum set of
elements:

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header />
<SOAP-ENV:Body>
<ipgapi:IPGApiOrderRequest
xmlns:ipgapi="http://ipg-online.com/ipgapi/schemas/ipgapi"
xmlns:v1="http://ipg-online.com/ipgapi/schemas/v1">
<v1:Transaction>
<v1:CreditCardTxType>
<v1:StoreId>{{storeid}}</v1:StoreId>
<v1:Type>sale</v1:Type>
</v1:CreditCardTxType>
<v1:CreditCardData>
<v1:CardCodeValue>{{rupay.cvv}}</v1:CardCodeValue>
</v1:CreditCardData>
<v1:Payment>
<v1:ChargeTotal>15</v1:ChargeTotal>
<v1:Currency>356</v1:Currency>
</v1:Payment>
<v1:TransactionDetails>
<v1:IpgTransactionId>84439794295</v1:IpgTransactionId>
</v1:TransactionDetails>
</v1:Transaction>
</ipgapi:IPGApiOrderRequest>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

The following XML document represents an example of a response you receive from the Gateway:

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<ipgapi:IPGApiOrderResponse
xmlns:a1="http://ipg-online.com/ipgapi/schemas/a1"
xmlns:ipgapi="http://ipg-online.com/ipgapi/schemas/ipgapi"
xmlns:v1="http://ipg-online.com/ipgapi/schemas/v1">
<ipgapi:ApprovalCode>Y:131636:4439794296:PPX :315513794295</ipgapi:ApprovalCode>
<ipgapi:AVSResponse>PPX</ipgapi:AVSResponse>
<ipgapi:Brand>RUPAY</ipgapi:Brand>
<ipgapi:Country>IND</ipgapi:Country>
<ipgapi:CommercialServiceProvider>IMS</ipgapi:CommercialServiceProvider>
<ipgapi:OrderId>A-7263bcdf-b2b7-4797-a5a6-691181cf0510</ipgapi:OrderId>
<ipgapi:IpgTransactionId>84439794296</ipgapi:IpgTransactionId>
<ipgapi:PaymentType>CREDITCARD</ipgapi:PaymentType>
<ipgapi:ProcessorApprovalCode>131636</ipgapi:ProcessorApprovalCode>
<ipgapi:ProcessorReferenceNumber>315513794295</ipgapi:ProcessorReferenceNumber>
<ipgapi:ProcessorResponseCode>00</ipgapi:ProcessorResponseCode>
<ipgapi:ProcessorResponseMessage>success</ipgapi:ProcessorResponseMessage>
<ipgapi:SchemeTransactionId>100122023060400000000000222691</ipgapi:SchemeTransactio
nId>
<ipgapi:TDate>1685864791</ipgapi:TDate>
<ipgapi:TDateFormatted>2023.06.04 09:46:31 (CEST)</ipgapi:TDateFormatted>
<ipgapi:TerminalID>00001113</ipgapi:TerminalID>
<ipgapi:TransactionResult>APPROVED</ipgapi:TransactionResult>
<ipgapi:TransactionTime>1685864791</ipgapi:TransactionTime>
</ipgapi:IPGApiOrderResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

22.8.1 Rupay Network Token Provisioning with external Token Provider

This feature allows you to use your own token service provider and submit the token with cryptogram
to the Gateway without provisioning request. The token you obtained from external token provider
must be submitted in “Card number” element together with the token cryptogram.
The following XML document represents an example of a Sale transaction using the minimum set of
elements:

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

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<ipgapi:IPGApiOrderRequest xmlns:ipgapi="http://ipg-
online.com/ipgapi/schemas/ipgapi" xmlns:v1="http://ipg-
online.com/ipgapi/schemas/v1">
<v1:Transaction>
<v1:CreditCardTxType>
<v1:StoreId>330821</v1:StoreId>
<v1:Type>sale</v1:Type>
</v1:CreditCardTxType>
<v1:CreditCardData>
<v1:CardNumber>630562XXXXXX9484</v1:CardNumber>
<v1:ExpMonth>12</v1:ExpMonth>
<v1:ExpYear>26</v1:ExpYear>
<v1:CardCodeValue>XXX</v1:CardCodeValue>
</v1:CreditCardData>
<v1:TokenCryptogram>AJkBA2VzYAAgIwUVFDgTAAAAAAA=</v1:TokenCryptogram>
<v1:Payment>
<v1:ChargeTotal>65.50</v1:ChargeTotal>
<v1:Currency>356</v1:Currency>
</v1:Payment>
<v1:TransactionDetails>
<v1:IpgTransactionId>84486024295</v1:IpgTransactionId>
</v1:TransactionDetails>
</v1:Transaction>
</ipgapi:IPGApiOrderRequest>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
22.9 Guest Checkout Tokenization

As per Reserve Bank of India (RBI) compliance requirements, storing card on file data has been
limited. As an alternative solution, a guest checkout transaction token provided by schemes have
been introduced as Alternate IDs (Alt ID). In order to request Scheme Alt ID and cryptogram, you
need to send an action request to the Gateway. The call to retreive scheme ALT ID and cryptogram is
made by our system automatically.

Please note that this feature is applicable for Mastercard, Visa and Amex only.
The following XML document represents an example of a request with minimal set of elements:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:i

pg="http://ipg-online.com/ipgapi/schemas/ipgapi" xmlns:a1="http://ipg-
online.com/ipgapi/schemas/a1" xmlns:v1="http://ipg-online.com/ipgapi/schemas/v1">
<soapenv:Header/>
<soapenv:Body>
<ns4:IPGApiActionRequest
xmlns:ns4="http://ipg-online.com/ipgapi/schemas/ipgapi" xmlns:ns2="http://ipg-
online.com/ipgapi/schemas/a1" xmlns:ns3="http://ipg-online.com/ipgapi/schemas/v1">
<ns2:Action>
<ns2:GetGuestCheckoutTokenCryptogram>
<ns2:StoreId>331164004</ns2:StoreId>
<ns2:CreditCardData>
<ns3:CardNumber>4895********2363</ns3:CardNumber>
<ns3:ExpMonth>12</ns3:ExpMonth>
<ns3:ExpYear>24</ns3:ExpYear>
<ns3:CardCodeValue>123</ns3:CardCodeValue>
<ns3:Brand>VISA</ns3:Brand>
</ns2:CreditCardData>
<ns3:Payment>
<ns3:ChargeTotal>16.98</ns3:ChargeTotal>
<ns3:Currency>INR</ns3:Currency>
</ns3:Payment>
</ns2:GetGuestCheckoutTokenCryptogram>
</ns2:Action>
</ns4:IPGApiActionRequest>
</soapenv:Body>
</soapenv:Envelope>

The following XML document represents an example of a response:

Path/Name XML Schema Description

type
v1:NetworkToken/ xs:string Guest checkout token number
v1:GuestCheckoutTokenData/ [0-9]{13,19}
v1: GuestCheckoutTokenNumber/
v1:NetworkToken/ xs:string Guest checkout token expiry month
v1:GuestCheckoutTokenData/ (0[1-9])|(1[0-
v1:ExpMonth 2])
v1:NetworkToken/ xs:string Guest checkout expiry year
v1:GuestCheckoutTokenData/ [0-9]{2}
v1:ExpYear
v1:NetworkToken/ xs:string Last four digits of the original Card Number
v1:GuestCheckoutTokenData/ \d{4} represented by the guest checkout token
v1:CardLast4
v1:NetworkToken/ xs:string Available values:
v1:GuestCheckoutTokenData/ "AMEX"
v1:Brand "MASTERCARD"
"VISA"
v1:NetworkToken/ xs:string Guest checkout token cryptogram as assigned
v1: GuestCheckoutTokenData/ minLength by a scheme.
v1: GuestCheckoutTokenCryptogram value="20
maxLength
value="255"
23 Troubleshooting - Merchant Exceptions

<detail>
XML is not wellformed: Premature end of message.
</detail>

Possible Explanation:
You have sent an absolutely empty message. The message contains neither a soap message nor an
IPG API message or any other characters in the http body.

<detail>
XML is not wellformed: Content is not allowed in prolog.
</detail>

Possible Explanation:
The message can’t be interpreted as an XML message.

<detail>
XML is not wellformed:
XML document structures must start and end within the same entity.
</detail>

Possible Explanation:
The message starts like an XML message but the end tag of the first open tag is missing.

<detail>
XML is not wellformed:
The element type "SOAP-ENV:Body" must be terminated
by the matching end-tag "</SOAP-ENV:Body>".
</detail>

Possible Explanation:
To an open internal tag (not the top level tag) the end tag is missing. In this example the end tag
</SOAP-ENV:Body> is missing.

<detail>
XML is not wellformed:
Element type "irgend" must be followed by either attribute specifications, ">" or "/>".
</detail>

Possible Explanation:
The message isn’t an XML message or a correct XML message. A “>” character is missing for the
tag irgend.

<detail>
XML is not wellformed:
Open quote is expected for attribute "xmlns:ns3"
associated with an element type "ns3:IPGApiOrderRequest".
</detail>
Possible Explanation:
The value of one attribute isn’t enclosed in quotation marks. In IPG API attributes are only used for
the name spaces.

<detail>
XML is not wellformed:
The prefix "ipgapi" for element "ipgapi:IPGApiOrderRequest"
is not bound.
</detail>

Possible Explanation:
The name space “ipgapi” isn’t declared. To declare a name space use the xmlns prefix. In this case
you should take
xmlns:ipgapi="http://ipg-online.com/ipgapi/schemas/ipgapi" as attribute in the top level tag of the IPG
API message (IPGApiOrderRequest or IPGApiActionRequest).

<detail>
XML is not wellformed:
The prefix "xmln" for attribute "xmln:ns2" associated
with an element type "ns3:IPGApiOrderRequest" is not bound.
</detail>

Possible Explanation:
To declare an own name space, only the predefined name space xmlns allowed. In this case the
prefix is written as xmln and not as xmlns.

<detail>
XML is not wellformed:
Unable to create envelope from given source
because the namespace was not recognized
</detail>

Possible Explanation:
The message could be interpreted as an XML message and the enclosing soap message is correct,
but the including IPG API message in the soap body has no name spaces or the name spaces are not
declared correctly. The correct name spaces are described in the xsd.

<detail>
XML is not wellformed:
The processing instruction target matching "[xX][mM][lL]"
is not allowed.
</detail>

Possible Explanation:
The whole message must be a correct XML message so that the including IPG API message must
not contains the xml declaration <?xml … ?>.

<detail>
Unexpected characters before XML declaration
</detail>

Possible Explanation:
The XML must start with “<?xml”. Please check, if you send an empty line or another white space
character in front of the xml and remove them.

<detail>
XML is not a SOAP message:
Unable to create envelope from given source
because the root element is not named "Envelope"
</detail>

Possible Explanation:
The message seems to be a correct XML message but only soap messages are accepted. This
message must be enclosed by a soap message.

<detail>
XML is not a valid SOAP message:
Error with the determination of the type.
Probably the envelope part is not correct.
</detail>

Possible Explanation:
The soap body tag is missing.

<detail>
Source object passed to ''{0}'' has no contents.
</detail>

Possible Explanation:
The soap body is empty. The including IPG API message is missing.

<detail>
Included XML is not a valid IPG API message:
unsupported top level {namespace}tag "irgendwas" in the soap body. Only one of [
{http://ipg-online.com/ipgapi/schemas/ipgapi}IPGApiActionRequest,
{http://ipg-online.com/ipgapi/schemas/ipgapi}IPGApiOrderRequest
] allowed.
</detail>

Possible Explanation:
The first tag in the including IPG API message must be one of IPGApiActionRequest or
IPGApiOrderRequest tag and not the tag irgendwas. In this case this tag has no namespace.

<detail>
Included XML is not a valid IPG API message:
unsupported top level {namespace}tag
"{http://firstdata.de/ipgapi/schemas/ipgapi}IPGApiOrderRequest" in the soap body. Only one of
[
{http://ipg-online.com/ipgapi/schemas/ipgapi}IPGApiActionRequest,
{http://ipg-online.com/ipgapi/schemas/ipgapi}IPGApiOrderRequest
] allowed.
</detail>

Possible Explanation:
The top level tag of the included IPG API message no allowed tag. In this case the name space is
wrong.

<detail>
cvc-pattern-valid:
Value '1.234' is not facet-valid with respect to pattern
'([1-9]([0-9]{0,12}))?[0-9](\.[0-9]{1,2})?' for type
'#AnonType_ChargeTotalAmount'
cvc-type.3.1.3:
The value '1.234' of element 'ns3:ChargeTotal' is not valid.
</detail>

Possible Explanation:
The value of a tag does not correspond with the declaration in the xsd. The value has three decimal
places but the xsd only allows two.

<detail>
cvc-complex-type.2.4.a:
Invalid content was found starting with element 'ns2:ExpYear'.
One of '{"http://ipg-online.com/ipgapi/schemas/v1":ExpMonth}'
is expected.
</detail>

Possible Explanation:
The occurrences of the tags must be corresponding to the xsd. We recommend to use the tags in the
same sequence as they are declared in the xsd. In this case the tag ExpMonth is expected and not
ExpYear.
23.1 Troubleshooting - Processing Exceptions

<detail>
<ipgapi:IPGApiOrderResponse
xmlns:ipgapi="http://ipg-online.com/ipgapi/schemas/ipgapi">
<ipgapi:CommercialServiceProvider />
<ipgapi:TransactionTime>1233656751183</ipgapi:TransactionTime>
<ipgapi:ProcessorReferenceNumber />
<ipgapi:ProcessorResponseMessage />
<ipgapi:ErrorMessage>
SGS-C: 000003:
illegal combination of values for the 3DSecure:
(VerificationResponse, PayerAuthenticationResponse,
PayerAuthenticationCode) N Y null
</ipgapi:ErrorMessage>
<ipgapi:OrderId />
<ipgapi:ApprovalCode />
<ipgapi:AVSResponse />
<ipgapi:TDate />
<ipgapi:TransactionResult>FAILED</ipgapi:TransactionResult>
<ipgapi:TerminalID />
<ipgapi:ProcessorResponseCode />
<ipgapi:ProcessorApprovalCode />
<ipgapi:ProcessorReceiptNumber />
<ipgapi:ProcessorTraceNumber />
</ipgapi:IPGApiOrderResponse>
</detail>

Explanation:
The combination of the three values VerificationResponse, PayerAuthenticationResponse and
AuthenticationValue for 3-D Secure version 1 is wrong. Allowed combinations are:

Verification- Payer- AuthenticationV

Response Authentication- alue IPG 3dsecure
Response response code Comments
null null null n/a Transaction will be passed to auth
system without any 3dsecure
information
No MC ECI, Visa ECI = 7
N null null Cardholder not enrolled
7 No MC ECI, Visa ECI = 7
N N null Cardholder not enrolled
7 No MC ECI, Visa ECI = 7
U null null Unable to authenticate (DS not
accessible)
5 No MC ECI, Visa ECI = 7
Y A null Attempt (ACS cannot tell result of
authentication)
4 MC ECI = 1, Visa ECI = 6
Y A x Attempt (ACS cannot tell result of
authentication)
4 MC ECI = 1, Visa ECI = 6
Y U null Unable to authenticate (ACS not
accessible)
6 No MC ECI, Visa ECI = 7
Y Y null Auth Success (no CAAV / UCAF)
2 MC ECI = 2, Visa ECI = 5
Y Y x Auth Success
1 MC ECI = 2, Visa ECI = 5
Y N null Auth Failure (Signature verification
incorrect) - IPG declines the transaction
( "N:-5101:3D Secure authentication
failed" )
3 No MC or Visa ECI

Other combinations not listed above will be declined by IPG with a IPG 3dsecure response code of 8
and "N:-5100:Invalid 3D Secure values".

XID (created by MPI before sending Verification request) needs to be set for VISA transactions.
The payer authentication code x means, that the value is not null.

<detail>
<ipgapi:IPGApiOrderResponse
xmlns:ipgapi="http://ipg-online.com/ipgapi/schemas/ipgapi">
<ipgapi:CommercialServiceProvider />
<ipgapi:TransactionTime>1233659493267</ipgapi:TransactionTime>
<ipgapi:ProcessorReferenceNumber />
<ipgapi:ProcessorResponseMessage />
<ipgapi:ErrorMessage>
SGS-005002:
The merchant is not setup to support the requested service.
</ipgapi:ErrorMessage>
<ipgapi:OrderId>
IPGAPI-REQUEST-9c555d62-3850-4726-8589-5a2444c98c5d
</ipgapi:OrderId>
<ipgapi:ApprovalCode />
<ipgapi:AVSResponse />
<ipgapi:TDate />
<ipgapi:TransactionResult>FAILED</ipgapi:TransactionResult>
<ipgapi:TerminalID />
<ipgapi:ProcessorResponseCode />
<ipgapi:ProcessorApprovalCode />
<ipgapi:ProcessorReceiptNumber />
<ipgapi:ProcessorTraceNumber />
</ipgapi:IPGApiOrderResponse>
</detail>

Explanation:
This is an example with a German Direct Debit transaction, which is not supported for the merchant.
If you should receive this result for a transaction type which is included in your agreement, please
contact our technical support team.

Explanation:
After a transaction further transactions with the same data blocked are for a configurable time span.
See User Guide Virtual Terminal for details about the fraud settings.

Explanation:
This is an example with US Dollar, which is no allowed currency for this store.

<detail>
<ipgapi:IPGApiOrderResponse
xmlns:ipgapi="http://ipg-online.com/ipgapi/schemas/ipgapi">
<ipgapi:CommercialServiceProvider />
<ipgapi:TransactionTime>1234346305732</ipgapi:TransactionTime>
<ipgapi:ProcessorReferenceNumber />
<ipgapi:ProcessorResponseMessage />
<ipgapi:ErrorMessage>
SGS-032000: Unknown processor error occured.
</ipgapi:ErrorMessage>
<ipgapi:OrderId>
IPGAPI-REQUEST-b3223ee5-156b-4d22-bc3f-910709d59202
</ipgapi:OrderId>
<ipgapi:ApprovalCode />
<ipgapi:AVSResponse />
<ipgapi:TDate>1234346284</ipgapi:TDate>
<ipgapi:TransactionResult>DECLINED</ipgapi:TransactionResult>
<ipgapi:TerminalID />
<ipgapi:ProcessorResponseCode />
<ipgapi:ProcessorApprovalCode />
<ipgapi:ProcessorReceiptNumber />
<ipgapi:ProcessorTraceNumber />
</ipgapi:IPGApiOrderResponse>
</detail>
Explanation:
If your transactions are normally executed, one possible explanation is that the number of Terminal
IDs assigned to your store are not sufficient for your transaction volume. Please contact our Sales
team to order further Terminal IDs for load balancing.
23.2 Troubleshooting - Login error messages when using cURL

* About to connect() to test.ipg-online.com port 443 (#0)

* Trying 217.73.32.55... connected
* Connected to test.ipg-online.com (217.73.32.55) port 443 (#0)
* unable to set private key file: 'C:\API\config\WS120666668._.1.key' type PEM
* Closing connection #0
curl: (58) unable to set private key file: 'C:\API\config\WS120666668._.1.key' type PEM

Explanation:
Keystore and password do not fit. Check if you used the right keystore and password. Please check if
you used the WS<storeId>._.1.pem file. If you append .cer to the file name you can open the
certificate with a double click. The certificate must be exposed for your store. Please remove the
extension .cer after the check.

* SSL certificate problem, verify that the CA cert is OK. Details:

error:14090086:SSL routines:SSL3_GET_SERVER_CERTIFICATE:certificate verify failed
* Closing connection #0
curl: (60) SSL certificate problem, verify that the CA cert is OK. Details:
error:14090086:SSL routines:SSL3_GET_SERVER_CERTIFICATE:certificate verify failed
More details here: http://curl.haxx.se/docs/sslcerts.html

curl performs SSL certificate verification by default, using a "bundle" of Certificate Authority (CA)
public keys (CA certs). The default bundle is named curl-ca-bundle.crt; you can specify an alternate file
using the --cacert option.
If this HTTPS server uses a certificate signed by a CA represented in the bundle, the certificate
verification probably failed due to a problem with the certificate (it might be expired, or the name
might not match the domain name in the URL).
If you'd like to turn off curl's verification of the certificate, use the -k (or --insecure) option

Explanation:
The truststore certificate is wrong. Please verify the trustore: Open the file tlstrust.pem and check
that one of them matched the root of the server certificate of the Gateway.

<html>
<head>
<title>Apache Tomcat/5.5.20 - Error report</title>
<style>

</style>
</head>
<body>
<h1>HTTP Status 401 - </h1>
<HR size="1" noshade="noshade">
<p><b>type</b> Status report</p><p><b>message</b>
<u></u></p><p><b>description</b>
<u>This request requires HTTP authentication ().</u></p>
<HR size="1" noshade="noshade">
<h3>Apache Tomcat/5.5.20</h3>
</body>
</html>

Explanation:
Your certificates are OK and accepted but your password or your user is wrong.
23.3 Troubleshooting - Login error messages when using the Java Client

java.io.IOException: Keystore was tampered with, or password was incorrect

Explanation:
Your keystore password doesn’t fit to the keystore or the truststore password to the truststore. You
can check the password with the keytool which is a component of the JDK. You can find it in the bin
directory of the JDK. For testing the password call
c:\Programme\Java\jdk1.6.0_07\bin\keytool.exe -list -v -keystore <your keystore or truststore> -
storepass <your keystore or truststore password>

javax.net.ssl.SSLHandshakeException: sun.security.validator.ValidatorException: No trusted certificate

found

Explanation:
Your truststore is wrong. You can inspect your truststore with keytool, a component of the JDK. Call
c:\Programme\Java\jdk1.6.0_07\bin\keytool.exe -list -v -keystore <your truststore> -storepass <your
truststore password>
and you must find the issuer Equifax
OU=Equifax Secure Certificate Authority, O=Equifax, C=US in the output. Check the MD5 and SHA1
values too.

<html>
<head>
<title>Apache Tomcat/5.5.20 - Error report</title>
<style><!--H1 {font-family:Tahoma,Arial,sans-serif;color:white;background-color:#525D76;font-
size:22px;} H2 {font-family:Tahoma,Arial,sans-serif;color:white;background-color:#525D76;font-size:16px;} H3
{font-family:Tahoma,Arial,sans-serif;color:white;background-color:#525D76;font-size:14px;} BODY {font-
family:Tahoma,Arial,sans-serif;color:black;background-color:white;} B {font-family:Tahoma,Arial,sans-
serif;color:white;background-color:#525D76;} P {font-family:Tahoma,Arial,sans-
serif;background:white;color:black;font-size:12px;}A {color : black;}A.name {color : black;}HR {color : #525D76;}--
></style>
</head>
<body>
<h1>HTTP Status 401 -</h1>
<HR size="1" noshade="noshade">
<p>
<b>type</b>
Status report
</p>
<p>
<b>message</b>
<u></u>
</p>
<p>
<b>description</b>
<u>This request requires HTTP authentication ().</u>
</p>
<HR size="1" noshade="noshade">
<h3>Apache Tomcat/5.5.20</h3>
</body>
</html>

Explanation: Your user id or password is wrong.

IPG IntegrationGuide API 2023-1
No ratings yet
IPG IntegrationGuide API 2023-1
162 pages
Web Service API: Integration Guide
No ratings yet
Web Service API: Integration Guide
124 pages
IPG IntegrationGuide API NBD
No ratings yet
IPG IntegrationGuide API NBD
103 pages
ICICI API Specification V1.2
No ratings yet
ICICI API Specification V1.2
42 pages
FDGG Web Service API
No ratings yet
FDGG Web Service API
109 pages
Documentation Paymob
No ratings yet
Documentation Paymob
58 pages
eCommercePaymentSolutions sg246177
No ratings yet
eCommercePaymentSolutions sg246177
352 pages
Example Api Documentation by Mindtrans
No ratings yet
Example Api Documentation by Mindtrans
60 pages
SV Epg-202306.1-Api-Spec en Core 20230914
No ratings yet
SV Epg-202306.1-Api-Spec en Core 20230914
541 pages
Iveri Client Developers Guide 4
No ratings yet
Iveri Client Developers Guide 4
170 pages
PayWay API Developers Guide
No ratings yet
PayWay API Developers Guide
48 pages
PayflowGateway Guide
No ratings yet
PayflowGateway Guide
238 pages
Midtrans Documentation
No ratings yet
Midtrans Documentation
95 pages
IPG IntegrationGuide API-Soap 2020-3
No ratings yet
IPG IntegrationGuide API-Soap 2020-3
99 pages
Merchant Payment Integration Guide
100% (1)
Merchant Payment Integration Guide
137 pages
HDFC API Document
100% (1)
HDFC API Document
160 pages
UMS Banking Gateway-Direct-Post-API
No ratings yet
UMS Banking Gateway-Direct-Post-API
46 pages
Integrate Payments Direct Post API
No ratings yet
Integrate Payments Direct Post API
31 pages
SequelPay API Manual
No ratings yet
SequelPay API Manual
121 pages
PP Pay Flow Pro Guide
No ratings yet
PP Pay Flow Pro Guide
176 pages
Customer Service & E-Payment Guide
No ratings yet
Customer Service & E-Payment Guide
10 pages
HyperPay Developer Slides Explanation
No ratings yet
HyperPay Developer Slides Explanation
2 pages
SAP Payment Engine 90 EN PDF
100% (1)
SAP Payment Engine 90 EN PDF
432 pages
PayPal NVP API Developer Guide
100% (1)
PayPal NVP API Developer Guide
165 pages
Youth Payment Trends in Mumbai
No ratings yet
Youth Payment Trends in Mumbai
51 pages
PHP Readme
No ratings yet
PHP Readme
3 pages
SAP Payment Engine 90 en
No ratings yet
SAP Payment Engine 90 en
480 pages
Website Payments Pro Payflow Edition Developer's Guide
No ratings yet
Website Payments Pro Payflow Edition Developer's Guide
70 pages
EPG REST Integration V17
No ratings yet
EPG REST Integration V17
48 pages
PP API Reference
No ratings yet
PP API Reference
272 pages
Payflowgateway Guide
No ratings yet
Payflowgateway Guide
256 pages
PayflowPro Guide
No ratings yet
PayflowPro Guide
198 pages
Credit Card Services
100% (4)
Credit Card Services
338 pages
Mobile Push Payment Program Implementation Guide
No ratings yet
Mobile Push Payment Program Implementation Guide
105 pages
Vishal Payment
No ratings yet
Vishal Payment
5 pages
E-commerce Payment Essentials
No ratings yet
E-commerce Payment Essentials
8 pages
Gateway Integration Guide Connect
No ratings yet
Gateway Integration Guide Connect
53 pages
PayPal API Reference
No ratings yet
PayPal API Reference
350 pages
API Documentation October 18, 2016
No ratings yet
API Documentation October 18, 2016
37 pages
HDFC API Doc v1.3
No ratings yet
HDFC API Doc v1.3
172 pages
Payment Gateway Design Guide
No ratings yet
Payment Gateway Design Guide
8 pages
Express Checkout Integration Guide
No ratings yet
Express Checkout Integration Guide
110 pages
SecureFrame Integration Guide v.1.13
No ratings yet
SecureFrame Integration Guide v.1.13
35 pages
Merchant Integration Guide
No ratings yet
Merchant Integration Guide
46 pages
Switch Developer Guide
No ratings yet
Switch Developer Guide
14 pages
Payment GatewayTesting
100% (1)
Payment GatewayTesting
8 pages
Payment Gateway PP T
No ratings yet
Payment Gateway PP T
24 pages
Payment Receipt
No ratings yet
Payment Receipt
68 pages
Google Pay: Documentation
No ratings yet
Google Pay: Documentation
5 pages
Akurateco Presentation - WLPG
No ratings yet
Akurateco Presentation - WLPG
20 pages
PP WebsitePaymentsPro IntegrationGuide
No ratings yet
PP WebsitePaymentsPro IntegrationGuide
68 pages
Beanstream API Integration Original
No ratings yet
Beanstream API Integration Original
92 pages
Manual Webpay en Ingles
No ratings yet
Manual Webpay en Ingles
64 pages
Quicksilver P2P API Integration Manual v1.0.4
No ratings yet
Quicksilver P2P API Integration Manual v1.0.4
22 pages
Payment Gatway Final
No ratings yet
Payment Gatway Final
13 pages
Refund API Documentation Guide
No ratings yet
Refund API Documentation Guide
12 pages
Digital Payment System
No ratings yet
Digital Payment System
5 pages
The Whole Process of E-Commerce Security Management System: Ronggang Zhang Lijuan Fang Xiaoping He Chuan Wei
No ratings yet
The Whole Process of E-Commerce Security Management System: Ronggang Zhang Lijuan Fang Xiaoping He Chuan Wei
301 pages
Aleksander v. Chichurin, Elena M. Ovsiyuk, Viktor M. Red'Kov - Problems in Quantum Mechanics and Field Theory With Mathematical Modelling-CRC Press (2025)
No ratings yet
Aleksander v. Chichurin, Elena M. Ovsiyuk, Viktor M. Red'Kov - Problems in Quantum Mechanics and Field Theory With Mathematical Modelling-CRC Press (2025)
374 pages
Dhiman Deb Chowdhury - Future of Networks - Modern Communication Infrastructure (2025)
No ratings yet
Dhiman Deb Chowdhury - Future of Networks - Modern Communication Infrastructure (2025)
502 pages
Emine E. Abali, Roy Carman, Douglas B. Spicer - Biochemistry Behind The Symptoms-Wolters Kluwer (2024)
No ratings yet
Emine E. Abali, Roy Carman, Douglas B. Spicer - Biochemistry Behind The Symptoms-Wolters Kluwer (2024)
992 pages
Subrata Pandey - MATLAB Model of An Optimized Battery Charge Controller-Self Published (2022)
No ratings yet
Subrata Pandey - MATLAB Model of An Optimized Battery Charge Controller-Self Published (2022)
67 pages
Ahmed Ibrahim Fathelrahman, Mohamed Izham Mohamed Ibrahim, Albert I. Wertheimer - Medical Devices For Pharmacy and Other Healthcare Professions-CRC Press (2021)
No ratings yet
Ahmed Ibrahim Fathelrahman, Mohamed Izham Mohamed Ibrahim, Albert I. Wertheimer - Medical Devices For Pharmacy and Other Healthcare Professions-CRC Press (2021)
419 pages
PassThru Protocol Log Analysis
No ratings yet
PassThru Protocol Log Analysis
2 pages
Computer Planner 2025 9th
No ratings yet
Computer Planner 2025 9th
4 pages
Training Report Deepak
No ratings yet
Training Report Deepak
36 pages
CPFR Roadmap
No ratings yet
CPFR Roadmap
142 pages
Top-Down Programming Explained
No ratings yet
Top-Down Programming Explained
2 pages
Rk-Mcu HN-PTT - Master Control Unit Rk-Mcu
No ratings yet
Rk-Mcu HN-PTT - Master Control Unit Rk-Mcu
1 page
Lesson 10
No ratings yet
Lesson 10
7 pages
Low Capacitance TVS Diode Array Guide
No ratings yet
Low Capacitance TVS Diode Array Guide
1 page
Speedtronic® Mark V Turbine Control System
100% (2)
Speedtronic® Mark V Turbine Control System
67 pages
Intelligent Document Processing Guide
No ratings yet
Intelligent Document Processing Guide
26 pages
Life Vision Int Wordlist Ukrainian
100% (1)
Life Vision Int Wordlist Ukrainian
112 pages
Grade 10 - Algebra Worksheet 2020
100% (1)
Grade 10 - Algebra Worksheet 2020
15 pages
Data Science & AI Certification Program For Managers & Leaders Learnbay
100% (1)
Data Science & AI Certification Program For Managers & Leaders Learnbay
41 pages
Dell EMC VDI Complete Solutions Brief
No ratings yet
Dell EMC VDI Complete Solutions Brief
3 pages
Automatic Payment Program: Configuration Document
No ratings yet
Automatic Payment Program: Configuration Document
56 pages
NG Pháp
No ratings yet
NG Pháp
31 pages
Raghavi Resume
No ratings yet
Raghavi Resume
1 page
Interface
No ratings yet
Interface
7 pages
Bresenham Line Drawing Algorithm
No ratings yet
Bresenham Line Drawing Algorithm
14 pages
Prisoner Face Detecting System A Java Project.
100% (2)
Prisoner Face Detecting System A Java Project.
138 pages
1X-F4-xx: Product Data Sheet
No ratings yet
1X-F4-xx: Product Data Sheet
2 pages
Significant Figure Rules: Determining Number of Significant Figures (Sig Figs)
No ratings yet
Significant Figure Rules: Determining Number of Significant Figures (Sig Figs)
4 pages
ATM Class Diagram Guide
No ratings yet
ATM Class Diagram Guide
5 pages
Google Glass Technical Seminar Report
No ratings yet
Google Glass Technical Seminar Report
30 pages
BEV Datasheet En-Gb
No ratings yet
BEV Datasheet En-Gb
12 pages
RIMS ISACA Bridging The Digital Risk Gap - Res - Eng - 0919
No ratings yet
RIMS ISACA Bridging The Digital Risk Gap - Res - Eng - 0919
18 pages
Blue Light Blue Color Blocks Flight Attendant CV
No ratings yet
Blue Light Blue Color Blocks Flight Attendant CV
2 pages
CV - Ahmed - Abbassi - Python-Data Engineer Senior - EN
No ratings yet
CV - Ahmed - Abbassi - Python-Data Engineer Senior - EN
3 pages
Open Packet Tracer Scenario: Telnet-CDP Lab-1 Scenario - Pkt. Before Proceeding, Save As Telnet-CDP Lab-1 Scenario-Working - PKT
No ratings yet
Open Packet Tracer Scenario: Telnet-CDP Lab-1 Scenario - Pkt. Before Proceeding, Save As Telnet-CDP Lab-1 Scenario-Working - PKT
3 pages
Report ...
No ratings yet
Report ...
54 pages