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>

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>joe.doe@email.net</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.

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