XML Integrator (Queries)

Quick links

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:

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.

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

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>

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.

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

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.

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

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>

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

Methods Group

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

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

Types Group

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

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

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>

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>joe.doe@email.net</Id>
    <Password>pwd12345</Password>
    <Brand>TESTWALLET</Brand>
</Account>

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

Error Group

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

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.

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

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.

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

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.

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

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

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

PreviousIntegration GuideNextOverview

Last updated