XML Integrator (Queries)

Quick links

• Introduction

• Request Message

• Response Message

• Typical Example Requests and Responses

Introduction

This document describes the interface for retrieving transaction data from the PPRO system. It has been designed in a way that the retrieval and processing of the data can be fully automated and there is no need for manual intervention.

URL

In order to retrieve the requested data from the PPRO system an XML message has to be sent via HTTP- POST within a parameter called "load“ to the following URL:

• Test-URL: https://test.ctpe.net/payment/query

• Live-URL: https://ctpe.net/payment/query

As a result of this request you will get an XML stream including all of the transactions that fulfil your filter criteria.

Request Description

The Request version must be specified and is “1.0” always.

Query describes the mode for which you want to receive transaction data and for which entity. You can query for any defined entity that exists in your account. Please be aware that if you define for example the level to be CHANNEL the ID of the entity must be a channel ID.

The element Type describes which transaction types you can query from the gateway. It is possible to query all available payment types. However, for some payment types a time limitation may apply, ie they can only be queried over a period of one day.

At the moment three types are available for searches over a maximum period of one month:

• Chargeback (CB)

• Chargeback Reversal (CR)

• Receipt (RC)

In those cases the difference between “from” and “to” in the Period tag must be lower than or equal to one month.

All other types can only be queried over a period of one day, meaning “from” and “to” in the Period tag must be the same.

IMPORTANT: The maximum number of transactions per query is limited depending on the types and period you are querying for:

• The maximum number of results per query in general is 10.000.

• In case you query for a longer period than one week or you do not specify a period at all the maximum number is 2.000.

• In case you query for a type other than CB, CR or RC, the maximum number is 2.000.

• In case you search for “TransactionID”, the maximum number is 200.

• Queries for ShortID and UniqueID do not require any time period or other additional query parameters

• If the time period is lower than ten minutes, the query can be executed without any limiting query parameters

For system stability and security reasons PPRO reserves the right to block the query interface for single merchants in case the query API should be receiving e.g. a massive number of automated queries beyond tolerable limits. See chapter 4 for typical use cases and recommended queries.

Simple Request Example

<Request version="1.0">
    <Header>
        <Security sender="ff80808109c5bcc00109c5bce9f1003a" />
    </Header>
    <Query entity="ff80808109c5bcc00109c5bce9f50056" level="CHANNEL" mode="INTEGRATOR_TEST" type="STANDARD">
        <User login="ff80808109c5bcc00109c5bce9f20042" pwd="geheim" />
        <Period from="2006-03-04" to="2006-03-04" />
        <Types>
            <Type code="RF" />
            <Type code="PA" />
            <Type code="RV" />
        </Types>
    </Query>
</Request>

Simple Response Example 1

<Response version="1.0">
<Result response='SYNC' type="LIST">
<Transaction .../>
<Transaction .../>
<Transaction .../>
...
</Result>
</Response>

Simple Response Example 2

<Response>
<Error>
<Timestamp>2006-03-04 15:50:35</Timestamp>
<Return code="100.200.101">invalid period, if searching for non-backchannel-types
(CB, RC) from and to must be on the same day</Return>
</Error>
</Response>

Request Message

Request Encoding:

For all payment requests containing shopping and possibly payment data, the request header must contain the Content-Type / charset parameter with the charset encoding set to “UTF-8”. The actual content type may differ; the decisive information is the charset value.

Accordingly, all request data must be encoded using the UTF-8-character set.

For XML data, please use the following Content-Type: application/x-www-form-urlencoded;charset=UTF-8 Examples:

Integration via PHP/cURL: http://php.net/manual/de/book.curl.php

$ch = curl_init();
curl_setopt($ch, CURLINFO_HEADER_OUT, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
"Content-Type: application/x-www-form-urlencoded;charset=UTF-8"
));
// attach parameter curl_exec($ch);

Integration via Java:

UrlRequest req = new UrlRequest(UrlRequest.POST, CORE_URL );
// attach parameter to request
req.addHeaderParam("Content-Type", "application/x-www-form-urlencoded;charset=UTF-8");
req.send();

Header Group

The header group of the XML request holds transmission and security related information.

<Header>
    <Security sender="123a456b789c123d456e789f012g345”/>
</Header>

Value for sender	Description
Alphanumeric 32	Each entity (PSP, Division, Merchant, Channel) which sends requests to the system has an own sender unique ID. The sender UID is no logical business orientated subdivision like the channel ID, but refers to physical installations of software. Please provide here the value you have received from the customer support department.

Query Group

<Query mode="LIVE" level="CHANNEL" entity="678a456b789c123d456e789f012g432" 
type="STANDARD" maxCount=”5”>

The query tag has three attributes which determine the processing of the query.

Value for mode	Description
INTEGRATOR_TEST	Transaction gets just sent to the Integrator and not to the Validator (Risk Management) or Connector modules. Used to test compliance against the Integrator module.
CONNECTOR_TEST	Transaction enters the Integrator module, accesses the Validator modules (Risk Management) and then goes to the Connector. The Connector operates in test mode.
LIVE	Transaction enters the Integrator module, accesses the Validator modules (Risk Management) and then goes to the Connector. The Connector operates in live mode.

Value for level	Description
CHANNEL	Transactions are queried on channel level (ID specified with entity is a channel ID)
MERCHANT	Transactions are queried on merchant level (ID specified with entity is a merchant ID)

Value for type	Description
STANDARD	This is the default type. No special behavior activated.
ACTIVE_TRANSACTIONS	Queries all transactions which match the given query parameters and which are active transactions of their sessions.
LINKED_TRANSACTIONS	Queries all transactions which are linked directly or indirectly to one specific transaction. For this type the ID or ShortID of one transaction must be specified.
AVAILABLE_TRANSACTIONS	Queries all transactions which match the given query parameters and which are available transactions of their sessions. The difference between ACTIVE_TRANSACTIONS and AVAILABLE_TRANSACTIONS applies to registrations only: “active” are only confirmed registrations, “available” are not confirmed registrations also.
ACTIVE_LINKED_TRANSACTIONS	Queries all transactions which are linked directly or indirectly to one specific transaction and which are active transactions in their session. For this type the ID or ShortID of one transaction must be specified.
AVAILABLE_LINKED_TRANSACTIONS	Queries all transactions which are linked directly or indirectly to one specific transaction and which are active transactions in their session. For this type the ID or ShortID of one transaction must be specified. The difference between ACTIVELINKED TRANSACTIONS and AVAILABLE_LINKED_TRANSACTIONS applies to registrations only: “active” are only confirmed registrations, “available” are not confirmed registrations also.

Value for maxCount	Description
Number	Maximum number of returned transactions by the query. Especially helpful if you want to get the last 10 transaction only for an overview or similar to speedup your application.

Value for entity	Description
Alphanumeric 32	ID of the entity specified in level. The entity ID is a unique key for the identification of the unit which sends transactions into the system.

User Group

The User tag group contains security related information. Check the document “Technical Quickstart” for information on how to retrieve this login data for your test account. Contact your account manager for the live account data.

<User login="421a456b789c123d456e789f012g098" pwd="56b789c123d456e789f"/>

Value for login	Description
Alphanumeric 32	The login is a unique ID for each human or system user. Each merchant or payment service provider can have several logins for system users and human users. It is not recommended to share one login between several human users.

Value for pwd	Description
Alphanumeric 3..32	A password which fits the login UID has to be provided. It is distributed together with the login UID.

Identification Group

The identification group contains IDs which are used for the identification of the transaction:

• Unique ID • Short ID • TransactionID

<Identification>
    <UniqueID>12345678901234567890123456789012</UniqueID>
    <ShortID>1234.1234.1234</ShortID>
    <TransactionID>Merchant_Defined_ID_For_A_Transaction</TransactionID>
</Identification>

Search for UniqueID or ShortID: This group allows the user to query for specific transactions if the ShortId or the UniqueId is known. Both IDs are part of each XML Transaction Response. Only one of the two IDs is required. If either UniqueID or ShortID is present, Period and Types are optional.

Identification Tag	Data Type	Length	Mandatory / Optional	Description
UniqueID	Alphanumeric	32	Conditionally Mandatory	Only ID where the uniqueness within the system is absolutely guaranteed. Has to be used for al automated matching and reference purposes.
ShortID	Numeric / Dots	14	Conditionally Mandatory	ID which is used for manual entry and search purposes. The likelihood for uniqueness is very high, but no guaranteed.

Search for more than one UniqueID at the same time: This group allows the user to query for specific transactions the UniqueIds are known and return them all at once. Period and Types are optional.

Identification Tag	Data Type	Length	Mandatory / Optional	Description
UniqueID	Alphanumeric	32	Conditionally Mandatory	Contains a list of ID sub elements
ID	Alphanumeric	32	Conditionally Mandatory	Only ID where the uniqueness within the system is absolutely guaranteed. Has to be used for all automated matching and reference purposes.

<Identification>
    <UniqueIDs>
        <ID>1234567890123456789012bb3456789012</ID>
        <ID>ff8081811bfa5356011bfbe22a2800b4</ID>
    </UniqueIDs>
</Identification>

Search for TransactionID: This group also allows the user to query for specific transactions by the TransactionID. This is the ID the merchant has assigned to a specific payment transaction.

Identification Tag	Data Type	Length	Mandatory / Optional	Description
TransactionID	Alphanumeric	32	Optional	ID the merchant has assigned to a specific payment transaction and submitted with the origina payment transaction.

This ID does not necessarily have to be unique when it gets submitted the payment system with a payment transaction. Nevertheless, it is highly recommended to use unique (or at least selective) ones. For safety and stability reasons of the query interface, this query allows you to retrieve a maximum of 200 transactions per TransactionID.

TransactionType Group

The TransactionType group contains an alternative and/or extension to the Methods group. It allows you to define what types of transactions your query result should contain.

<TransactionType>PAYMENT</TransactionType>

Value of TransactionType	Description
PAYMENT	Payment Transaction Types. Those are CB, CR, DB, CP, PA, RC, RF and RV
REGISTER	Registration Transaction Types. Those are CF, DR and RG
RISKMANAGEMENT	Risk Management Transaction Types. Those are EA, RI, 3D, SA, and IC. This list is always extending as new features are implemented.

Period Group

This tag group specifies the date period of the query. The “from” date is always extended with the time 00:00:00 and the “to” date with 23:59:59. All times are UTC only. For the following payment types the “from” and “to” date can be any day:

• Chargeback (CB)

• Chargeback Reversal (CR)

• Receipt (RC)

For all other payment types the “from” and “to” date have to be on the same day. This means only one day can be queried within one XML query request.

<Period from="2018-09-01" to="2018-09-15 12:00:00"/>

Value for [from]	Description	Value for [to]	Description
Date, format yyyy-MM-dd [HH:mm:ss]	Date from when the query starts.	Date, format yyyy-MM-dd [HH:mm:ss]	Date when the query ends.

Methods Group

The Methods tag group contains information about the payment methods you want to retrieve.

<Methods>
<Method code="CC"/>
</Methods>

Value for code	Description
Alpha(2)	A valid payment method.

Types Group

The Types tag group contains information about the payment types you want to retrieve.

<Types>
    <Type code="CB" />
    <Type code="PA" />
</Types>

Value for code	Description
Alpha(2)	A valid payment type.

ProcessingResult Group

The ProcessingResult tag group contains information if you want to query for successful of failed transactions only. It is the same tag you would receive in an XML payment response as part of the Processing Tag Group (See document “XML Transactions”).

<ProcessingResult>ACK</ProcessingResult>

Value for ProcessingResult	Description
ACK	Get successful Transactions only
NOK	Get failed (rejected) Transactions only

Account Group

The account group allows you to search for user account. This tag group is only needed if you search for registered user accounts.

<Account>
    <Id>[email protected]</Id>
    <Password>pwd12345</Password>
    <Brand>TESTWALLET</Brand>
</Account>

Identification Tag	Data Type	Length	Mandatory / Optional	Description
Id	Alphanumeric	128	Mandatory	ID of the user with the User Account
Brand	Alphanumeric	32	Mandatory	Brand of the User Account
Password	Password	32	Mandatory	Password of the registered user

Response Message

The result to a query request message is – like the response to an XML transaction request – surrounded by a tag. The response tag contains either a Result Group or, in case of an invalid request, an Error Group.

Result Group

<Result response='SYNC' type="LIST">

Value for response	Description	Value for response	Description
SYNC	All requested transactions are part of this request and are nested inside the Result Group	LIST	Specifies that the transactions are provided as a list inside the Result group

Error Group

<Error>
    <Timestamp>2004-11-11 11:11:11</Timestamp>
    <Return code="100.100.101">invalid entity type</Return>
</Error>

Tag of Error	Description
Timestamp	Date and Time of the request, format is “yyyy-MM-dd hh:mm:ss”
Return	Contains error information describing the occurred error as text

Value for code	Description
Alphanumeric, format is nnn.nnn.nnn	Return code identifying the error that occurred. For a list of all error codes check: https://test.ctpe.net/payment/codes/queryErrorCodes.jsp

Typical Example Requests and Responses

Chargebacks (CB)

For retrieving chargebacks for a certain period, a request has to be sent to the query engine at:

Test-URL: https://test.ctpe.net/payment/query Live-URL: https://ctpe.net/payment/query

Typical Use Case: Automatically retrieve chargebacks from the payment system. Depending on the acquirer or bank new Chargebacks usually appear once a day in the system. For details, please, contact your account manager. Therefore, it does not make sense to query the system for new Chargebacks every five minutes or so.

Please note: For system safety and stability reasons the merchant query access may be blocked in case of receiving too many automated requests from this account within a short timeframe.

This request will retrieve the chargebacks for the channel identified by the ID 8a8294174e918ca6014e9c6f5ae12a9c for the week of the 27th of March to the 2nd of April. Let’s assume 3 chargebacks have been issued during that period. The result might look something like the Response sample tab.

Request sample

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Request version="1.0">
    <Header>
        <Security sender="8a829417281b8ee30128299066f50cd7" />
    </Header>
    <Query entity="8a8294174e918ca6014e9c6f5ae12a9c" level="CHANNEL" mode="CONNECTOR_TEST" type="STANDARD">
        <User pwd="demo" login="8a829417281b8ee30128299066f50cdb" />
        <Period from="2019-03-27" to="2019-04-02" />
        <Types>
            <Type code="CB" />
        </Types>
    </Query>
</Request>

Response sample

<Response>
    <Result response="SYNC" count="3">
        <Transaction mode="CONNECTOR_TEST" channel="8a8294174e918ca6014e9c6f5ae12a9c" response="SYNC" source="BIP">
            <Identification>
                <ShortID>6210.1105.3145</ShortID>
                <UniqueID>8ac7a4a269d942dc0169dfe4b03941dd</UniqueID>
                <TransactionID>Order Number 123</TransactionID>
                <ShopperID>12345678909</ShopperID>
                <BulkID>2019-03-29</BulkID>
                <ReferenceID>8ac7a4a169c855450169cb2d27680f90</ReferenceID>
            </Identification>
            <Payment code="CC.CB">
                <Clearing>
                    <Amount>1.00</Amount>
                    <Currency>BRL</Currency>
                    <Descriptor>123 Usage</Descriptor>
                    <FxRate>1.0</FxRate>
                    <FxSource>INTERN</FxSource>
                    <FxDate>2019-04-02 21:11:40</FxDate>
                </Clearing>
                <Memo />
                <Presentation>
                    <Amount>1.00</Amount>
                    <Currency>BRL</Currency>
                    <Usage>123 Usage</Usage>
                    <ValueTimestamp>2019-04-02 21:11:40</ValueTimestamp>
                </Presentation>
            </Payment>
            <Account>
                <Number>******1111</Number>
                <Holder>Leandro</Holder>
                <Brand>VISA</Brand>
                <Year>2019</Year>
                <Month>10</Month>
                <Bin>411111</Bin>
                <Expiry month="10" year="2019" />
            </Account>
            <Customer>
                <Name>
                    <Family>da Silva</Family>
                    <Given>Jose</Given>
                </Name>
                <Contact>
                    <Email>[email protected]</Email>
                    <Ip>123.123.123.123</Ip>
                </Contact>
                <Address>
                    <City>Sao Paulo</City>
                    <Country>BR</Country>
                    <State>SP</State>
                    <Street>Rua Itapeva 547</Street>
                    <Zip>01332000</Zip>
                </Address>
                <Details />
            </Customer>
            <Processing code="CC.CB.90.00">
                <Timestamp>2019-04-02 21:11:40</Timestamp>
                <Result>ACK</Result>
                <Status code="90">NEW</Status>
                <Reason code="00">Successful Processing</Reason>
                <Return code="000.100.200">Reason not Specified</Return>
                <ConnectorDetails />
            </Processing>
            <RequestTimestamp>2019-04-02 21:11:40</RequestTimestamp>
            <Analysis>
                <Criterion name="INFO_matchingAlgorithm">MANUAL_MATCH</Criterion>
            </Analysis>
        </Transaction>
        <Transaction mode="CONNECTOR_TEST" channel="8a8294174e918ca6014e9c6f5ae12a9c" response="SYNC" source="BIP">
            <Identification>
                <ShortID>0605.1782.0929</ShortID>
                <UniqueID>8ac7a4a069d942db0169dfe4efe045e3</UniqueID>
                <TransactionID>Order Number 123</TransactionID>
                <ShopperID>12345678909</ShopperID>
                <BulkID>2019-03-28</BulkID>
                <ReferenceID>8ac7a4a069c3549d0169c5f4a508215b</ReferenceID>
            </Identification>
            <Payment code="CC.CB">
                <Clearing>
                    <Amount>1.00</Amount>
                    <Currency>BRL</Currency>
                    <Descriptor>123 Usage</Descriptor>
                    <FxRate>1.0</FxRate>
                    <FxSource>INTERN</FxSource>
                    <FxDate>2019-04-02 21:11:56</FxDate>
                </Clearing>
                <Memo />
                <Presentation>
                    <Amount>1.00</Amount>
                    <Currency>BRL</Currency>
                    <Usage>123 Usage</Usage>
                    <ValueTimestamp>2019-04-02 21:11:56</ValueTimestamp>
                </Presentation>
            </Payment>
            <Account>
                <Number>******1111</Number>
                <Holder>Leanndro Teste23</Holder>
                <Brand>VISA</Brand>
                <Year>2019</Year>
                <Month>10</Month>
                <Bin>411111</Bin>
                <Expiry month="10" year="2019" />
                <RegistrationId>8ac7a4a269c3eab00169c5f4a3726f0c</RegistrationId>
            </Account>
            <Customer>
                <Name>
                    <Family>da Silva</Family>
                    <Given>Jose</Given>
                </Name>
                <Contact>
                    <Email>[email protected]</Email>
                    <Ip>123.123.123.123</Ip>
                </Contact>
                <Address>
                    <City>Sao Paulo</City>
                    <Country>BR</Country>
                    <State>SP</State>
                    <Street>Rua Itapeva 547</Street>
                    <Zip>01332000</Zip>
                </Address>
                <Details />
            </Customer>
            <Processing code="CC.CB.90.00">
                <Timestamp>2019-04-02 21:11:56</Timestamp>
                <Result>ACK</Result>
                <Status code="90">NEW</Status>
                <Reason code="00">Successful Processing</Reason>
                <Return code="000.100.200">Reason not Specified</Return>
                <ConnectorDetails />
            </Processing>
            <RequestTimestamp>2019-04-02 21:11:56</RequestTimestamp>
            <Analysis>
                <Criterion name="INFO_matchingAlgorithm">MANUAL_MATCH</Criterion>
            </Analysis>
        </Transaction>
        <Transaction mode="CONNECTOR_TEST" channel="8a8294174e918ca6014e9c6f5ae12a9c" response="SYNC" source="BIP">
            <Identification>
                <ShortID>4722.9781.0526</ShortID>
                <UniqueID>8ac7a49f69d940fa0169dfe52a424545</UniqueID>
                <TransactionID>Order Number 123</TransactionID>
                <ShopperID>12345678909</ShopperID>
                <BulkID>2019-03-28</BulkID>
                <ReferenceID>8ac7a4a169c31dca0169c5ef22ff69b9</ReferenceID>
            </Identification>
            <Payment code="CC.CB">
                <Clearing>
                    <Amount>1.00</Amount>
                    <Currency>BRL</Currency>
                    <Descriptor>123 Usage</Descriptor>
                    <FxRate>1.0</FxRate>
                    <FxSource>INTERN</FxSource>
                    <FxDate>2019-04-02 21:12:11</FxDate>
                </Clearing>
                <Memo />
                <Presentation>
                    <Amount>1.00</Amount>
                    <Currency>BRL</Currency>
                    <Usage>123 Usage</Usage>
                    <ValueTimestamp>2019-04-02 21:12:11</ValueTimestamp>
                </Presentation>
            </Payment>
            <Account>
                <Number>******1111</Number>
                <Holder>Leandro Teste</Holder>
                <Brand>VISA</Brand>
                <Year>2019</Year>
                <Month>10</Month>
                <Bin>411111</Bin>
                <Expiry month="10" year="2019" />
                <RegistrationId>8ac7a4a069c3549d0169c5ef21371cbf</RegistrationId>
            </Account>
            <Customer>
                <Name>
                    <Family>da Silva</Family>
                    <Given>Jose</Given>
                </Name>
                <Contact>
                    <Email>[email protected]</Email>
                    <Ip>123.123.123.123</Ip>
                </Contact>
                <Address>
                    <City>Sao Paulo</City>
                    <Country>BR</Country>
                    <State>SP</State>
                    <Street>Rua Itapeva 547</Street>
                    <Zip>01332000</Zip>
                </Address>
                <Details />
            </Customer>
            <Processing code="CC.CB.90.00">
                <Timestamp>2019-04-02 21:12:11</Timestamp>
                <Result>ACK</Result>
                <Status code="90">NEW</Status>
                <Reason code="00">Successful Processing</Reason>
                <Return code="000.100.200">Reason not Specified</Return>
                <ConnectorDetails />
            </Processing>
            <RequestTimestamp>2019-04-02 21:12:11</RequestTimestamp>
            <Analysis>
                <Criterion name="INFO_matchingAlgorithm">MANUAL_MATCH</Criterion>
            </Analysis>
        </Transaction>
    </Result>
</Response>

Receipts (RC)

Typical Use Case: Automatically retrieve if somebody has transferred money onto your bank account. In order to check if a prepayment (PP) has been fulfilled you have to retrieve receipts. Again, a request has to be sent to the query engine at:

Test-URL: https://test.ctpe.net/payment/query Live-URL: https://ctpe.net/payment/query

This request will retrieve the receipts for the channel identified by the ID 8a8294174e918ca6014e9c6e44672a96 for the week of the 27th of March to the 3rd of April. Let’s assume that one receipt has been issued during that period. The result will look like the Response sample tab.

Request sample

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Request version="1.0">
    <Header>
        <Security sender="8a829417281b8ee30128299066f50cd7" />
    </Header>
    <Query entity="8a8294174e918ca6014e9c6e44672a96" level="CHANNEL" mode="CONNECTOR_TEST" type="STANDARD">
        <User pwd="demo" login="8a829417281b8ee30128299066f50cdb" />
        <Period from="2019-03-27" to="2019-04-03" />
        <Types>
            <Type code="RC" />
        </Types>
    </Query>
</Request>

Response sample

<Response>
    <Result response="SYNC" count="1">
        <Transaction mode="CONNECTOR_TEST" channel="8a8294174e918ca6014e9c6e44672a96" response="SYNC" source="BIP">
            <Identification>
                <ShortID>9938.5741.5684</ShortID>
                <UniqueID>8ac7a4a169d940fc0169e468db810b13</UniqueID>
                <TransactionID>06121808</TransactionID>
                <BulkID>2019-04-03</BulkID>
                <InvoiceID>6000000557</InvoiceID>
                <ReferenceID>8ac7a4a069d942db0169e4684fa52239</ReferenceID>
            </Identification>
            <Payment code="PP.RC">
                <Clearing>
                    <Amount>161.69</Amount>
                    <Currency>BRL</Currency>
                    <Descriptor>Demo 1633.1811.4926 06121808</Descriptor>
                    <FxRate>1.0</FxRate>
                    <FxSource>INTERN</FxSource>
                    <FxDate>2019-04-03 18:14:31</FxDate>
                </Clearing>
                <Memo />
                <Presentation>
                    <Amount>161.69</Amount>
                    <Currency>BRL</Currency>
                    <Usage>Testando descriptor</Usage>
                    <ValueTimestamp>2019-04-03 18:14:30</ValueTimestamp>
                </Presentation>
            </Payment>
            <Account>
                <Country>BR</Country>
            </Account>
            <Customer>
                <Name>
                    <Family>Artem</Family>
                    <Given>Artem</Given>
                </Name>
                <Contact>
                    <Email>[email protected]</Email>
                    <Ip>127.0.0.1</Ip>
                </Contact>
                <Address>
                    <City>NorthPlatte</City>
                    <Country>BR</Country>
                    <State>AL</State>
                    <Street>516NDewey</Street>
                    <Zip>69101909</Zip>
                </Address>
                <Details />
            </Customer>
            <Processing code="PP.RC.90.00">
                <Timestamp>2019-04-03 18:14:31</Timestamp>
                <Result>ACK</Result>
                <Status code="90">NEW</Status>
                <Reason code="00">Successful Processing</Reason>
                <Return code="000.100.112">Request successfully processed in 'Merchant in Connector Test Mode'</Return>
                <ConnectorDetails />
            </Processing>
            <RequestTimestamp>2019-04-03 18:14:31</RequestTimestamp>
            <Analysis>
                <Criterion name="INFO_matchingAlgorithm">MANUAL_MATCH</Criterion>
            </Analysis>
        </Transaction>
    </Result>
</Response>

Query Specific Transactions by ID

Typical Use Case: Automatically retrieve transactions from the payment system where you only have an ID. In order to retrieve a transaction where the UniqueId or ShortId is known, only one transaction can be queried. For example, this can be particularly useful to retrieve a Registration of an user to be able to show the user the (masked) payment data or customer data he entered the last time he paid in the shop. This is very helpful in case you either do not have the UniqueID or ShortID anymore or you never received it (e.g. Timeout). In this case you are able to query the state of the transaction.

Request sample

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Request version="1.0">
    <Header>
        <Security sender="8a829417281b8ee30128299066f50cd7" />
    </Header>
    <Query entity="8a8294174e918ca6014e9c6e44672a96" level="CHANNEL" mode="CONNECTOR_TEST" type="STANDARD">
        <User pwd="demo" login="8a829417281b8ee30128299066f50cdb" />
        <Period from="2019-03-27" to="2019-04-03" />
        <Identification>
            <ShortID>1633.1811.4926</ShortID>
        </Identification>
    </Query>
</Request>

Response sample for RC (Receipt)

<Response>
    <Result response="SYNC" count="1">
        <Transaction mode="CONNECTOR_TEST" channel="8a8294174e918ca6014e9c6e44672a96" response="ASYNC" source="OPP">
            <Identification>
                <ShortID>1633.1811.4926</ShortID>
                <UniqueID>8ac7a4a069d942db0169e4684fa52239</UniqueID>
                <TransactionID>06121808</TransactionID>
                <BulkID>2019-04-03</BulkID>
                <InvoiceID>6000000557</InvoiceID>
            </Identification>
            <Payment code="PP.PA">
                <Clearing>
                    <Amount>161.69</Amount>
                    <Currency>BRL</Currency>
                    <Descriptor>Demo 1633.1811.4926 06121808</Descriptor>
                    <FxRate>1.0</FxRate>
                    <FxSource>INTERN</FxSource>
                    <FxDate>2019-04-03 18:13:55</FxDate>
                </Clearing>
                <Presentation>
                    <Amount>161.69</Amount>
                    <Currency>BRL</Currency>
                    <Usage>Testando descriptor</Usage>
                </Presentation>
            </Payment>
            <Account>
                <Country>BR</Country>
            </Account>
            <Customer>
                <Name>
                    <Family>Artem</Family>
                    <Given>Artem</Given>
                </Name>
                <Contact>
                    <Email>[email protected]</Email>
                    <Ip>127.0.0.1</Ip>
                </Contact>
                <Address>
                    <City>NorthPlatte</City>
                    <Country>BR</Country>
                    <State>AL</State>
                    <Street>516NDewey</Street>
                    <Zip>69101909</Zip>
                </Address>
                <Details />
            </Customer>
            <Processing code="PP.PA.90.00">
                <Timestamp>2019-04-03 18:13:55</Timestamp>
                <Result>ACK</Result>
                <Status code="90">NEW</Status>
                <Reason code="00">Successful Processing</Reason>
                <Return code="000.100.112">Request successfully processed in 'Merchant in Connector Test Mode'</Return>
                <ConnectorDetails>
                    <Result name="connectorInstanceId">10.2.3.225</Result>
                    <Result name="acquirerTxId2">16331811</Result>
                    <Result name="acquirerTxId1">1633.1811.4926</Result>
                    <Result name="acquirerReturnMessage">BOLETO LINK SUCCESSFULLY GENERATED</Result>
                    <Result name="acquirerReturnCode">0</Result>
                    <Result name="ExtendedDescription">User redirected to Itau</Result>
                    <Result name="merchantAccount">BR_Itau_ACON4_STAGING_AP</Result>
                    <Result name="EXTERNAL_SYSTEM_LINK">https://shopline.itau.com.br/shopline/itaubloqueto.asp?DC=L183R175W209L12Q238M104H153V172A232P63R165S217Q103D205B5Z138Z92F103O208R14B7H146L37X98U254Q251P62Y107W154X71Q47Y8Y60F226F195B163H172R72C162T222C162A99O219S128H225A27D148E140Y42A105U44O124I100H243P4K164U154T97Y250Y14M114C173L28B121H222T116W151C159D178C20T254M67H230B48V21K187E216I184Q103K64D209P89B101V226Q159P13W198Y215H150L100W182Z221D158D236R227L141H154E85W172X62O247H129U20U172O47O117K97T3F223H92E212B48O73T85Q249F20T11B2W176P216A90B120H117A236X60G76N213D18
6P150Y193F36Y224D123H182E70G112D228Y83K136X90G52I155A187K16A20X235K220B52Q14P72Y243L254T199B9N182P224D243U81P224D214Q39G141L6O9E136A112C91K54T62C171Y217X128Y28U128E201Q47L198D163B76V244U215E206K130J0L75P249T228C182S8N90U54G31V18L158N168I56G26B187X175I129Y22Q22I69L86R128X65N253J184S85W185O140W78I239I209E130J195Z207G108X6J194Y159M117Z230Z104U165I176V45E157P228L10J7N254W184A184J36G128B184D164P63B2R254C208U192N201A168M81Q44Z46S46Z79R112Q188L46S244L222T115C185G13P59H126C50I178C218X193D146O48C33L107N0R131C92C156H15Z2R173G164U43D87X49U142X48K3R194K86H180O93Z0Q65A21A106J210U123Y242U104J128C90C26X90P231J72B6J126H234S11F128H84D203E138H5Q156W223O154O47L41Z102A244Q67A253X196S195V144G90V30C229J84H92Z18Z240F104N226F105L53H95O35Y231N190O87P150R177Y182X47V92D206I191L12T210Z99A249J203K234T221J88Z94Y241B207D19T128Y111Q15O99S251S222U31I82A19M23B204X190X230J124D93T82S128J90N53U61M120E186G41D205X48G91M107K149U132H117O65A195U140K12H67X6P139Q129O131N198O9T71T70F221I67G40N14M211G61V179P217Z90J208M60Z170H183T255M111X55N82M163T137D11C7C145S141A84P74T80W144S198A82U42F82Z117M18G6C114G120I61P130O159Q198I109B160J200I100Y192R15W229L246D232Z160K199M26W29X204P192U213D5M67R66V</Result>
                    <Result name="connectorVersion">1.0.25</Result>
                    <Result name="ConnectorTxID1">8ac7a4a069d942db0169e4684fa52239</Result>
                    <Result name="connectorName">acon4-itau</Result>
                    <Result name="AcquirerResponse">000.000.000</Result>
                </ConnectorDetails>
                <ConnectorTxId>8ac7a4a069d942db0169e4684fa52239</ConnectorTxId>
            </Processing>
            <Recurrence mode="INITIAL" />
            <RequestTimestamp>2019-04-03 18:13:55</RequestTimestamp>
            <Analysis>
                <Criterion name="OPP_shopperResultUrl">http://loc/brazil_store_view/</Criterion>
                <Criterion name="SHOPPER_Publisher1">Produto1</Criterion>
                <Criterion name="OPP_cart.items[1].price">161.69</Criterion>
                <Criterion name="merchant_sitename">http://loc/brazil_store_view/</Criterion>
                <Criterion name="OPP_cart.items[1].type">Product</Criterion>
                <Criterion name="BRADESCO_instrucao1">Pedido6000000557-C\\u00f3digodedownload</Criterion>
                <Criterion name="BRADESCO_instrucao">https://store.com.br</Criterion>
                <Criterion name="CUSTOM_due_date">06/12/2018</Criterion>
                <Criterion name="OPP_cart.items[1].quantity">1</Criterion>
                <Criterion name="OPP_cart.items[1].currency">BRL</Criterion>
                <Criterion name="OPP_cart.items[1].merchantItemId">47</Criterion>
                <Criterion name="OPP_cart.items[1].originalPrice">161.69</Criterion>
                <Criterion name="BRADESCO_cpfsacado">012345678909</Criterion>
                <Criterion name="OPP_entityId">8a8294174e918ca6014e9c6e44672a96</Criterion>
                <Criterion name="OPP_paymentBrand">BOLETO</Criterion>
                <Criterion name="purchase_flow">INITIAL</Criterion>
                <Criterion name="MODEL_merchantSourceIp">177.102.143.190</Criterion>
            </Analysis>
        </Transaction>
    </Result>
</Response>

Response sample for DB (Debit)

<Response>
    <Result response="SYNC" count="1">
        <Transaction mode="CONNECTOR_TEST" channel="8a8294174e918ca6014e9c6f5ae12a9c" response="ASYNC" source="OPPUI">
            <Identification>
                <ShortID>2802.1703.7519</ShortID>
                <UniqueID>8ac7a4a169c855450169cb2d27680f90</UniqueID>
                <TransactionID>Order Number 123</TransactionID>
                <ShopperID>12345678909</ShopperID>
                <BulkID>2019-03-29</BulkID>
            </Identification>
            <Payment code="CC.DB">
                <Clearing>
                    <Amount>1.00</Amount>
                    <Currency>BRL</Currency>
                    <Descriptor>123 Usage</Descriptor>
                    <FxRate>1.0</FxRate>
                    <FxSource>INTERN</FxSource>
                    <FxDate>2019-03-29 20:38:48</FxDate>
                </Clearing>
                <Presentation>
                    <Amount>1.00</Amount>
                    <Currency>BRL</Currency>
                    <Usage>123 Usage</Usage>
                </Presentation>
            </Payment>
            <Account>
                <Number>******1111</Number>
                <Holder>Leandro</Holder>
                <Brand>VISA</Brand>
                <Year>2019</Year>
                <Month>10</Month>
                <Bin>411111</Bin>
                <Expiry month="10" year="2019" />
            </Account>
            <Customer>
                <Name>
                    <Family>da Silva</Family>
                    <Given>Jose</Given>
                </Name>
                <Contact>
                    <Email>[email protected]</Email>
                    <Ip>123.123.123.123</Ip>
                </Contact>
                <Address>
                    <City>Sao Paulo</City>
                    <Country>BR</Country>
                    <State>SP</State>
                    <Street>Rua Itapeva 547</Street>
                    <Zip>01332000</Zip>
                </Address>
                <Details />
            </Customer>
            <Processing code="CC.DB.90.00">
                <Timestamp>2019-03-29 20:38:48</Timestamp>
                <Result>ACK</Result>
                <Status code="90">NEW</Status>
                <Reason code="00">Successful Processing</Reason>
                <Return code="000.100.112">Request successfully processed in 'Merchant in Connector Test Mode'</Return>
                <ConnectorDetails>
                    <Result name="ExtendedDescription">Transaction succeeded</Result>
                    <Result name="acquirerResponse1">0329053848823</Result>
                    <Result name="acquirerInitialTxId">16f871fc-bfa1-471e-a42e-6a2e39680c01</Result>
                    <Result name="ConnectorTxID1">8ac7a4a169c855450169cb2d27680f90</Result>
                    <Result name="AcquirerResponse">000.000.000</Result>
                    <Result name="connectorVersion">3.1.12</Result>
                    <Result name="connectorName">Cielo</Result>
                    <Result name="merchantAccount">Cielo_ACON3_STAGING</Result>
                    <Result name="acquirerTxId2">0329053848823#APG@682276</Result>
                    <Result name="acquirerTxId1">16f871fc-bfa1-471e-a42e-6a2e39680c01</Result>
                    <Result name="connectorInstanceId">10.2.3.119</Result>
                    <Result name="acquirerTxId3">8ac7a4a169c855450169cb2d27680f90</Result>
                    <Result name="acquirerReturnCode">6</Result>
                    <Result name="acquirerResponse2">20190329053848823</Result>
                    <Result name="acquirerReturnMessage">Operation Successful</Result>
                </ConnectorDetails>
                <ConnectorTxId>8ac7a4a169c855450169cb2d27680f90</ConnectorTxId>
            </Processing>
            <Recurrence mode="INITIAL" />
            <RequestTimestamp>2019-03-29 20:38:47</RequestTimestamp>
            <Analysis>
                <Criterion name="OPP_shopperResultUrl">https://allpago.docs.oppwa.com/tutorials/integration-guide</Criterion>
                <Criterion name="product">1 month membership</Criterion>
                <Criterion name="SHOPPER_EndToEndIdentity">2a3b09579830ca2cf12f71e9e594657ab4f797b603e8cfcdd4dd122dad6da058</Criterion>
                <Criterion name="OPP_card.bin">411111</Criterion>
                <Criterion name="OPP_entityId">8a8294174e918ca6014e9c6f5ae12a9c</Criterion>
                <Criterion name="OPP_paymentBrand">VISA</Criterion>
                <Criterion name="merchant_website">www.store.com</Criterion>
                <Criterion name="OPP_shopOrigin">https://allpago.docs.oppwa.com</Criterion>
                <Criterion name="MODEL_merchantSourceIp">34.246.230.186</Criterion>
                <Criterion name="CTPE_DESCRIPTOR_TEMPLATE">${USAGE}</Criterion>
                <Criterion name="CTPE_MERCHANT_ACCOUNT_DATA_ID">8a8294174e918d17014e9c6f94fe4b11</Criterion>
            </Analysis>
        </Transaction>
    </Result>
</Response>

Error handling

If a query is rejected due to errors the Response will contain an Error-Tag. The following example shows a request that is declined because the type is unknown (please be aware that codes and messages are subject to changes):

Request sample

<Request version="1.0">
    <Header>
        <Security sender="123a456b789c123d456e789f012g345" />
    </Header>
    <Query mode="LIVE" level="MERCHANT" entity="678a456b789c123d456e789f012g432" type="STANDARD">
        <User login="peter" pwd="thewolf" />
        <Period from="2004-09-08 12:00:00" to="2004-09-08 13:00:00" />
        <Types type="LIST">
            <Type code="MM" />
        </Types>
    </Query>
</Request>

Error response sample

<Response version="1.0">
    <Error>
        <Timestamp>2004-11-11 11:11:11</Timestamp>
        <Return code="100.100.101">invalid entity type</Return>
    </Error>
</Response>

For a list of all possible return codes see https://test.ctpe.net/payment/codes/queryErrorCodes.jsp