Instructions on Payment Plug-In
Integration with TWEC PG
Contents
1
Revision
History
.......................................................................................................
4
2
Introduction
....................................................................................................... 6
3
Glossary
....................................................................................................... 7
4
Abbreviations
....................................................................................................... 8
5
Overview
....................................................................................................... 9
6
5.1
Interaction
Scheme
..................................................................................................
9
5.2
Order
Lifecycle
..................................................................................................
11
Format
of Payment Plug-In Interaction with TWEC PG
.......................................................................................................
13
6.1
7
8
Message
Exchange Using Administrative Operations
..................................................................................................
13
6.1.1
Exec
................................................................................................ 13
6.1.2
ExecPasswordAuth
................................................................................................ 13
6.2
Redirecting
Customer to TWEC PG Payment Page
..................................................................................................
15
6.3
Notifying
Internet Shop of Authorization Result
..................................................................................................
15
6.4
Notifying
Internet Shop of Order Status Change
..................................................................................................
15
Message
Format and Structure
.......................................................................................................
16
7.1
Structure
of TKKPG/Request XML Message
..................................................................................................
16
7.2
Structure
of TKKPG/Response XML Message
..................................................................................................
18
7.3
Data ..................................................................................................
Types
19
7.3.1
enumOperation
Operation Type
................................................................................................
20
7.3.2
enumOrderType
Order Type
................................................................................................
20
7.3.3
enumStatusOperation
Operation Status
................................................................................................
20
7.3.4
enumOrderStatus
Order Status
................................................................................................
21
Operation
Groups
.......................................................................................................
22
8.1
Financial
Operations
..................................................................................................
22
8.1.1
Create
Order
................................................................................................
22
8.1.2
Postauthorization
................................................................................................ 25
COMPASS PLUS
Public, v.1.08e, 25.12.2020.
Copyright © 1998-2020 Compass Plus Ltd.
2
8.1.3
Payment
Reversal
................................................................................................
26
8.1.4
Refund
................................................................................................ 27
8.2
9
Information
Operations
..................................................................................................
28
8.2.1
Get................................................................................................
Order Status
28
8.2.2
Get................................................................................................
Order Information
29
8.2.3
Get................................................................................................
Orders List
34
Appendixes
....................................................................................................... 38
9.1
Standard
Procedures for Executing TWEC PG Operations
..................................................................................................
38
9.1.1
Purchasing
................................................................................................ 38
9.1.2
Purchasing
with Preauthorization
................................................................................................
41
9.1.3
Automatic
Recurring Payment
................................................................................................
44
9.2
Example
Implementation of Payment Plug-In
..................................................................................................
47
9.3
Example
Implementation of Administrative Operations in PHP
..................................................................................................
48
9.4
XSD Schema
of TWEC PG Protocol
..................................................................................................
49
9.5
XMLOut
Message Parameters
..................................................................................................
49
9.6
TWEC
PG Test Server Connection Settings
..................................................................................................
53
9.7
Recommendations
on Generating Encrypted Payment Data
..................................................................................................
55
COMPASS PLUS
Public, v.1.08e, 25.12.2020.
Copyright © 1998-2020 Compass Plus Ltd.
3
Revision History
1
Revision History
Version
Revision Date
1.08
25.12.2020
Where to Look
Revised the document.
Corrected the description of the MITAttributes and
Purchase.Recur.removeOnDecline parameters.
Added
the
description
XmlOut.NotificationURL parameter.
of
the
Updated section Create Order
1.08
16.10.2020
Supported the facility to work with Diners Club
International.
Updated section XMLOut Message Parameters
1.07
18.08.2020
Changed the EMV 3-D Secure protocol version.
Updated section Create Order
1.06
25.06.2020
1.05
02.05.2020
Updated section ExecPasswordAuth
For the Status parameter in the response to the
Refund / Reverse request, added the 95 available
value used in case the respective transaction ID is
missing from the authorization system response.
Added the facility to leave the Language
parameter undefined when creating an order. In
this case, the EN parameter value will be used by
default.
Added the facility to leave the Fee parameter value
unspecified when creating an order.
Added the facility to specify the terminal ID when
creating an order.
Updated sections:
Structure of TKKPG/Request XML Message
enumStatusOperation Operation Status
Create Order
1.04
28.10.2019
Updated section Abbreviations
1.03
08.09.2019
Supported the facility to transfer encrypted payment
data to TWEC PG.
Updated sections:
Structure of TKKPG/Request XML Message
Postauthorization
Payment Reversal
Refund
Get Orders List
Added section Recommendations on Generating
Encrypted Payment Data
1.02
20.06.2019
Added information on mandatory use of Contenttype: text/xml in the requests sent to the Exec
access point.
Updated section Exec
COMPASS PLUS
Public, v.1.08e, 25.12.2020.
Copyright © 1998-2020 Compass Plus Ltd.
4
Revision History
Version
Revision Date
Where to Look
Updated parameters included in TKKPG/Request
XML message.
Updated section Structure of TKKPG/Request
XML Message
Updated additional order parameters.
Updated section Create Order
Updated parameters of TWEC PG response to the
GetOrderInformation operation.
Updated section Get Order Information
1.01
24.04.2019
Updated parameters of TWEC PG response to the
GetOrderInformation operation.
Updated section Get Order Information
1.00
01.02.2019
COMPASS PLUS
Public, v.1.08e, 25.12.2020.
Copyright © 1998-2020 Compass Plus Ltd.
Original version
5
Introduction
2
Introduction
The document hereunder provides instructions on integrating the Internet shop with
TranzWare e-Commerce Payment Gateway (hereinafter, TWEC PG).
The document is intended for technicians responsible for integration.
COMPASS PLUS
Public, v.1.08e, 25.12.2020.
Copyright © 1998-2020 Compass Plus Ltd.
6
Glossary
3
Glossary
Term
Definition
3D Secure
Technology designed to enhance the security of operations performed on the
Internet using bank cards
3DS Method
3DS Method is a scenario or set of commands invoked in the cardholder
browser. 3DS Method can be used to obtain additional information on the
cardholder browser to facilitate the cardholder authentication.
Acquirer
1.Acquiring bank: a financial institution that maintains contractual relationship
with the commercial and service enterprises
2.A licenced member of an international payment system servicing the
commercial and service enterprises
ACS (Access
Server)
Control Hardware and software complex used to verify the card enrollment in 3-D
Secure and to authenticate the cardholder using 3-D Secure, located in the
domain of the issuer or an organization authorized by the issuer and used by
them
AReq
(Authentication Message sent from 3DS Server to ACS via DS to request for cardholder
Request)
authentication. AReq can contain:
Payment data
Card and cardholder details
Data on the cardholder browser/device
Additional information on the purchase
Data on the cardholder authentication in the Internet shop
Data on the cardholder account created in the Internet shop
ARes
(Authentication Message that represents ACS response to AReq.
Response)
ARes contains the cardholder authentication result or the request for additional
information required to complete authentication.
Domain
Area of responsibility and location of software/hardware complexes of the data
exchange participant according to the 3D Secure standards
DS (Directory Server)
Software-hardware complex designed to route
requests and located in the Interoperability domain
Issuer
1.Financial institution that issues payment cards, receives data of the card
transactions performed by the cardholders, performs authorization, ensures
the payment for valid transactions, and posts transaction amounts to
cardholder accounts
cardholder
authentication
2.Credit organization (or its agent) that issues bank cards
Refund
Voluntary return of the transaction amount by the merchant to a purchaser who
previously made a purchase transaction by card
Reversal
Transaction cancellation that results in annulment of its result
COMPASS PLUS
Public, v.1.08e, 25.12.2020.
Copyright © 1998-2020 Compass Plus Ltd.
7
Abbreviations
4
Abbreviations
4DBC
4-Digit Batch Code
AAV
Accountholder Authentication Value (Mastercard SecureCode, Mastercard
Identity Check)
AEVV
American Express Verification Value
ACS
Access Control Server
CAVV
Cardholder Authentication Verification Value (Visa Secure – for Visa, J/
Secure – for JCB)
CVC2
Card Validation Code 2
CVV2
Card Verification Value 2
DB
Database
DSRP
Digital Secure Remote Payment
IPS
International Payment System
PAReq
Payer Authentication Request
PARes
Payer Authentication Response
PS
Payment System
TLS
Transport Layer Security
URL
Uniform Resource Locator
VEReq
Verification Enrollment Request
VERes
Verification Enrollment Response
XML
Extensible Markup Language
COMPASS PLUS
Public, v.1.08e, 25.12.2020.
Copyright © 1998-2020 Compass Plus Ltd.
8
Overview
5
Overview
TWEC PG is a module of the TranzWare e-Commerce system implementing the 3D
Secure acquiring functionality according to the 3D Secure v1.0 and EMV 3D Secure
v22 standards.
TWEC PG is a software complex designed to accept, process and manage purchases
made on the Internet using bank cards.
The complex ensures processing of purchases and order payment: from order creation to
dispute maintenance, purchase stats analysis, etc.
TWEC PG supports interface with an authorization system to manage the entire order
lifecycle (order payment, reversal, refund).
5.1
Interaction Scheme
When processing transactions, TWEC PG and payment plug-in interact as on the scheme
below:
COMPASS PLUS
Public, v.1.08e, 25.12.2020.
Copyright © 1998-2020 Compass Plus Ltd.
9
Overview
Interaction Scheme
1.Customer (cardholder) visits the Internet shop website, specifies the desired items and
places an order.
2.Payment plug-in of the Internet shop (merchant) sends to TWEC PG the CreateOrder
request with the order attributes (amount, currency, interface language, order
description, three URLs of return for cases when the operation is approved, declined
and cancelled). In the response, the Internet shop receives the unique order number,
session ID and URL to redirect the customer to work with TWEC PG.
3.Internet shop redirects the customer to the respective TWEC PG page to pay for the
order. Customer is authenticated by ACS according to the 3D Secure standards, and
the transaction gets authorized by the card issuer via the payment system.
4.Depending on the transaction authorization result, TWEC PG assigns the PREAUTHAPPROVED / APPROVED / CANCELED / DECLINED status to the order and redirects
the customer to the respective page of the Internet shop payment plug-in (at the
address specified in the ApproveURL / CancelURL / DeclineURL parameter). TWEC
PG sends the XMLOut message to the customer containing the order details.
5.When the customer goes to the respective Internet shop payment plug-in URL or when
the timeout expires (if the customer has not gone to this URL), the Internet shop
payment plug-in requests for the order status from TWEC PG (by executing the
GetOrderStatus operation).
6,7.Internet shop payment plug-in receives the order status in the response to the
GetOrderStatus operation and executes the GetOrderInformation operation.
Otherwise, TWEC PG sends a notification of the order status change (GET request with
the OrderID, SessionID, Status parameters) to the Internet shop payment plug-in
via HTTPS/HTTP.
8.Order details are displayed on the Internet shop website.
The channel of communication between the Internet shop payment plug-in and TWEC
PG can be used to transmit administrative operations (payment reversal, refund, etc.
with reference to the order number and session ID).
COMPASS PLUS
Public, v.1.08e, 25.12.2020.
Copyright © 1998-2020 Compass Plus Ltd.
10
Overview
Order Lifecycle
5.2
Order Lifecycle
The order can have the following statuses:
CREATED (assigned after the OrderID and SessionID parameters are generated and
remains unchanged until the order is paid)
ON-LOCK (assigned to avoid duplicate payment)
Attention!
o ON-LOCK status is assigned to the order when the PayOrder procedure is initiated
and remains unchanged until the authorization process is completed. After that, it is
changed either to APPROVED or to DECLINED.
o ON-LOCK status is assigned to the order with the PREAUTH-APPROVED status
when the Completion administrative operation is initiated and remains unchanged
until the postauthorization is completed. After that, it is changed either to
APPROVED or to the original order status (in case the operation is not successful).
ON-PAYMENT (order payment is in process)
Attention! The ON-PAYMENT status is assigned to the order after the card data is
entered.
APPROVED (payment is successful)
CANCELED (operation is interrupted by the customer)
DECLINED (payment is declined, e.g. the Prefix not found error has occurred during
the order execution)
COMPASS PLUS
Public, v.1.08e, 25.12.2020.
Copyright © 1998-2020 Compass Plus Ltd.
11
Overview
Order Lifecycle
REVERSED
ON-REFUND (status remains unchanged until the refund is completed to avoid
duplicate refund)
Attention! The ON-REFUND status is assigned to the order when the Refund
administrative operation is initiated and remains unchanged until it is completed. After
that, it is changed either to REFUNDED or to the original order status (if the operation
is not successful).
REFUNDED
PREAUTH-APPROVED (purchase with preauthorization is approved, i.e. funds are put
on hold in the account to execute the operation)
EXPIRED (order lifetime has expired)
ERROR (error connecting to TWEC PG DB, POS driver or TPTP terminal)
COMPASS PLUS
Public, v.1.08e, 25.12.2020.
Copyright © 1998-2020 Compass Plus Ltd.
12
Format of Payment Plug-In Interaction with TWEC PG
6
Format of Payment Plug-In Interaction with
TWEC PG
TWEC PG offers several access points distinguished by the communication format,
direction and purpose.
6.1
Message Exchange Using Administrative
Operations
Payment plug-in of the Internet shop communicates with the TWEC PG payment
gateway by means of the HTTP requests sent to the payment gateway address provided
by the acquirer bank when setting up the Internet shop. The following access points are
available:
Exec
ExecPasswordAuth
6.1.1
Exec
Authentication is based on the bi-directional TLS protocol (with the client and server
certificates). The payment gateway server matches the Internet shop ID (MerchantID)
against the CN value (Common Name) of the client certificate.
URL
https://<payment gateway host>/Exec
Method
POST
Headers
Content-type: text/xml
Attention! Content-type: text/xml is mandatory in the requests sent to the Exec
access point.
Request/
response
format
XML according to the xsd schema of the TWEC PG internal protocol (tkkpg.xsd)
Encoding
UTF-8
6.1.2
ExecPasswordAuth
Authentication is based on using the TLS protocol (server certificate) and verifying the
authentication token transmitted in the request.
URL
https://<payment gateway host>/ExecPasswordAuth
Method
POST
Request header Content-Type: application/x-www-form-urlencoded;
COMPASS PLUS
Public, v.1.08e, 25.12.2020.
Copyright © 1998-2020 Compass Plus Ltd.
13
Format of Payment Plug-In Interaction with TWEC PG
Message Exchange Using Administrative Operations
Request
parameters
xmlRequest – XML according to the xsd schema of the TWEC PG internal protocol
(tkkpg.xsd)
authData – authentication token
Response
header
Content-type: text/xml
Response
format
XML according to the xsd schema of the TWEC PG internal protocol (tkkpg.xsd)
Encoding
UTF-8
Authentication token is calculated as follows:
authData = sha256(sha256(xmlRequest) + "/" + sha256(merchant + "/" + password))
Where:
sha256 – data hash calculation according to the SHA-256 algorithm and its conversion
to HEX in the upper case
xmlRequest – line with the operation execution request in the XML format created
according to the administrative protocol
merchant – Internet shop ID in TWEC PG (MerchantID parameter)
password – merchant password specified in the TWEC PG settings
Example of token calculation:
Source data:
xmlRequest
<?xml version="1.0" encoding="UTF-8"?>
<TKKPG><Request><Operation>TransactionLog</Operation><Language>EN</
Language><Merchant>TEST</Merchant></Request></TKKPG>
merchant – TEST
password – 123456
Result:
authData
960C6BC22FE2F6FCE7C725967A14CD07874F15D2501C1FB60154C9B0C45364D3
-
COMPASS PLUS
14
Public, v.1.08e, 25.12.2020.
Copyright © 1998-2020 Compass Plus Ltd.
Format of Payment Plug-In Interaction with TWEC PG
Message Exchange Using Administrative Operations
6.2
Redirecting Customer to TWEC PG Payment Page
Payment plug-in of the Internet shop redirects the customer to pay the order at the
address received in the TKKPG/Response/Order/URL parameter of the response to
the order creation request.
URL
https://<payment gateway host>
Method
POST or GET
Request
header
Content-Type: application/x-www-form-urlencoded;
Request
parameters
6.3
OrderID – order ID received in the TKKPG/Response/Order/OrderID response
SessionID – session ID received in the TKKPG/Response/Order/SessionID
response
Notifying Internet Shop of Authorization Result
After the order is paid (successfully/unsuccessfully) or payment is cancelled, the TWEC
PG payment gateway redirects the customer to the Internet shop address defined in the
payment gateway settings at the merchant registration or to the respective address
specified in the ApproveURL / CancelURL / DeclineURL parameter at the order
creation.
URL
https://<merchant host>
Method
POST
Request header Content-Type: application/x-www-form-urlencoded;
Request
parameters
6.4
Version – version of TWEC PG communication protocol. Current version is 1.0.
Message – XMLOut message informing about the transaction authorization result. For
details, refer to XMLOut Message Parameters.
Notifying Internet Shop of Order Status Change
Throughout the order lifecycle, the TWEC PG payment gateway notifies the Internet
shop of the order status changes. Notifications are sent in the HTTP requests to the
dedicated Internet shop address specified in the TWEC PG settings (ChangeStatusURL
parameter) at the merchant registration or in the additional order parameter (TKKPG/
Request/Order/AddParams/ChangeStatusURL) at the order creation.
URL
https://<merchant host>
Method
GET
Request
parameters
OrderID – order ID received in the TKKPG/Response/Order/OrderID response
SessionID – session ID received in the TKKPG/Response/Order/SessionID
response
Status – order status
COMPASS PLUS
Public, v.1.08e, 25.12.2020.
Copyright © 1998-2020 Compass Plus Ltd.
15
Message Format and Structure
7
Message Format and Structure
XML messages must be structured according to the XSD schema of the TWEC PG
internal protocol.
XML message comprises the prolog and the TKKPG root element that includes either the
Request or Response element depending on the data exchange direction.
7.1
Structure of TKKPG/Request XML Message
Request structure description contains only basic parameters and elements that are filled
in most operations. For the specific request parameters, refer to Operation Groups.
Conventions:
R (Required) – element is mandatory
C (Conditional) – element presence is conditional and depends on the operation type or
on other elements in the request
O (Optional) – element is optional
Parameter
Data Type
Mandatory
Desription
Operation
xs:string
R
Operation type. For the available values, refer to the
description of the enumOperation enumerated type.
Language
xs:string
O
Interface language. Filled with the two-letter code of
the interface language compliant with RFC 1766
(e.g. RU – Russian language, EN –
English
language).
SessionID
xs:string
O
Session ID used together with the order number to
cancel the operation, get order status, etc.
Merchant
xs:string
O
Internet shop ID in TWEC PG. Used in the
GetOrders operation.
EncryptedPayload
xs:string
O
Encrypted payload data
Attention! The facility to transfer encrypted
payment data is available if the respective settings
are defined in TWEC PG. For rules of generating
encrypted
payment
data,
refer
to
Recommendations on Generating Encrypted
Payment Data.
Order
xs:complexType
C
Order information. The element contains the order
parameters.
Order/OrderID
xs:integer
C
Order ID. The parameter is used in certain types of
operations on the order.
Order/OrderType
xs:string
O
Order type. The financial transaction to be created.
The parameter is defined at the order creation. For
the available values, refer to the description of the
enumOrderType enumerated type.
Order/Merchant
xs:string
C
Internet shop ID in TWEC PG. The parameter is
mandatory in the CreateOrder operation and in
certain financial operations.
COMPASS PLUS
Public, v.1.08e, 25.12.2020.
Copyright © 1998-2020 Compass Plus Ltd.
16
Message Format and Structure
Structure of TKKPG/Request XML Message
Parameter
Data Type
Mandatory
Desription
Order/Amount
xs:integer
C
Transaction amount in the minimum units of the
transaction currency. The parameter is mandatory in
the CreateOrder operation and in certain financial
operations.
Order/Currency
xs:integer
C
Numeric code of the order currency. The parameter
is mandatory in the CreateOrder operation and in
certain financial operations.
Order/Description xs:string
O
Text description of the order. Can be displayed in
the interface on the page used to make payment.
Order/ApproveURL xs:anyURI
O
URL to redirect the customer to if the operation is
approved
Order/CancelURL
xs:anyURI
O
URL to redirect the customer to if the purchase is
cancelled
Order/DeclineURL xs:anyURI
O
URL to redirect the customer to if the payment is
not successful
Order/phone
xs:integer
O
Customer phone number (additional parameter) that
will be saved to the TWEC PG DB
Order/AddParams
xs:complexType
O
Element containing additional order parameters. The
set of parameters depends on the type of operation
and order. For details, refer to Create Order.
Fee
xs:integer
O
Acquiring fee in the minimum currency units (e.g.
cents, kopecks). If the parameter is set to a
negative number, the Bank Discount field will be
displayed on the payment page instead of the Bank
Fee field. The Bank Discount field contains the
number of bonuses (bank discount) made available
to the customer for the order. If the parameter
value is not defined, it is set to 0 by default.
Description
xs:string
O
Text description of the transaction. Can be displayed
in the interface.
Refund
xs:complexType
O
Element containing parameters for the Refund
operation
Refund/Amount
xs:integer
C
Refund amount in the minimum currency units.
Mandatory for the Refund operation.
Refund/Currency
xs:integer
C
Refund currency. Contains the currency numeric
code. Mandatory for the Refund operation.
Refund/WithFee
xs:boolean
O
Indicator of the acquiring fee refund.
Available values:
false (by default) – acquiring fee amount is not
refunded.
true – acquiring fee amount is refunded.
Example of the request:
<?xml version="1.0" encoding="UTF-8"?>
<TKKPG>
<Request>
<Operation>CreateOrder</Operation>
<Language>RU</Language>
<Order>
<OrderType>Purchase</OrderType>
<Merchant>POS_IKEA_2</Merchant>
<Amount>123456</Amount>
COMPASS PLUS
Public, v.1.08e, 25.12.2020.
Copyright © 1998-2020 Compass Plus Ltd.
17
Message Format and Structure
Structure of TKKPG/Request XML Message
<Currency>840</Currency>
<Description>xxxxxxxx</Description>
<ApproveURL>http://merchant.ru/testshopPageReturn.jsp</ApproveURL>
<CancelURL>http://merchant.ru/testshopPageReturn.jsp</CancelURL>
<DeclineURL>http://merchant.ru/testshopPageReturn.jsp</DeclineURL>
<phone>+79000000011</phone>
</Order>
</Request>
</TKKPG>
7.2
Structure of TKKPG/Response XML Message
Response structure description contains only basic parameters and elements that are
filled in most operations. For the specific response parameters, refer to Operation
Groups.
Conventions:
R (Required) – element is mandatory
C (Conditional) – element presence is conditional and depends on the operation type or
on other elements in the request
O (Optional) – element is optional
Parameter
Data Type
Mandatory
Desription
Operation
xs:string
R
Operation type. For the available values, refer to the
description of the enumOperation enumerated type.
Status
xs:string
R
Request execution result. For the available values,
refer to the description of the enumStatusOperation
enumerated type.
Order
xs:complexType
C
Order information. The element contains the order
parameters.
Order/OrderID
xs:integer
C
Order ID or number. The parameter is madatory in
the operations of the following types:
CreateOrder
Reverse
GetOrderStatus
Order/SessionID
xs:string
C
Session ID used together with the order number.
The parameter is mandatory in the CreateOrder
operation.
Order/OrderStatus xs:string
C
Order status. For the available values, refer to the
description of the enumOrderStatus enumerated
type. The parameter is madatory in the operations
of the following types:
GetOrderStatus
GetOrderInformation
Order/URL
xs:anyURI
C
URL to redirect the customer to. The customer is
redirected by the GET/POST method to the URL
address specified in the response and supplemented
with the values of the SessionID and OrderID
parameters.
AdditionalInfo
xs:complexType
O
Element containing additional information about the
order
COMPASS PLUS
Public, v.1.08e, 25.12.2020.
Copyright © 1998-2020 Compass Plus Ltd.
18
Message Format and Structure
Structure of TKKPG/Response XML Message
Parameter
Data Type
Mandatory
Desription
AdditionalInfo/
Receipt
xs:string
O
Signed receipt (bank guarantee)
authorization (BASE64-encoded)
confirming
Reversal
xs:complexType
O
Element
containing
parameters
operation
Reversal/
RespCode
xs:string
C
Code of the authorization system response to the
Reverse operation
Reversal/
RespMessage
xs:string
C
Text response of the authorization system
XMLOut
xs:complexType
O
Element containing parameters of the authorization
result notification provided to the Internet shop. For
details, refer to XMLOut Message Parameters.
the
Reverse
Example of the response:
<?xml version="1.0" encoding="UTF-8"?>
<TKKPG>
<Response>
<Operation>CreateOrder</Operation>
<Status>00</Status>
<Order>
<OrderID>828</OrderID>
<SessionID>ECDE79578768ECFBF2897A0F44CC0CEF</SessionID>
<URL>https://payment.gateway/url</URL>
</Order>
</Response>
</TKKPG>
7.3
Data Types
Section describes values of the following enumerated types of data used in XML
messages in terms of communication with TWEC PG:
enumOperation operation type
enumOrderType order type
enumStatusOperation operation status
enumOrderStatus order status
COMPASS PLUS
Public, v.1.08e, 25.12.2020.
Copyright © 1998-2020 Compass Plus Ltd.
19
Message Format and Structure
Data Types
7.3.1
enumOperation Operation Type
Value
Definition
CreateOrder
Order creation
Completion
Postauthorization
Reverse
Payment reversal
Refund
Refund
GetOrderStatus
Getting order status
GetOrderInformation
Getting order information
GetOrders
Getting list of orders
7.3.2
enumOrderType Order Type
Value
Definition
Purchase
Purchase
PreAuth
Preauthorization
7.3.3
enumStatusOperation Operation Status
Value
Definition
00
Successfully
10
Operation is not allowed. Internet shop has no access to the order creation
operation (or the Internet shop is not registered).
11
Error using UPOP service
30
Invalid message format (no mandatory parameters, etc.)
54
Invalid operation
55
Invalid parameters provided
72
Empty POS driver response
95
No transaction ID in the authorization system response
96
System error
97
POS driver connection error
98
MobiCash connection error
COMPASS PLUS
Public, v.1.08e, 25.12.2020.
Copyright © 1998-2020 Compass Plus Ltd.
20
Message Format and Structure
Data Types
7.3.4
enumOrderStatus Order Status
Value
Definition
CREATED
Order has been created
APPROVED
Payment is successful
PREAUTH-APPROVED
Preauthorization is completed (funds are put on hold in the account to execute
the operation)
EXPIRED
Order lifetime has expired
ERROR
Error
CANCELED
Operation is interrupted by the customer
DECLINED
Payment is declined
ON-PAYMENT
Payment procedure is in process
ON-LOCK
Status is locked (to avoid duplicate payment)
ON-REFUND
Status is locked until the refund is completed (to avoid duplicate refund)
REFUNDED
Refunded
REVERSED
Payment is reversed
COMPASS PLUS
Public, v.1.08e, 25.12.2020.
Copyright © 1998-2020 Compass Plus Ltd.
21
Operation Groups
8
Operation Groups
Operations supported by the TWEC PG payment gateway can be divided in two groups:
Financial operations
Information operations
8.1
Financial Operations
Section describes financial operations used to work with orders:
Create Order (CreateOrder)
Postauthorization (Completion)
Payment Reversal (Reverse)
Refund (Refund)
8.1.1
Create Order
Order creation is the initial step indispensible for further work. When creating an order,
specify the OrderType parameter value that defines which financial transaction will be
created. A financial transaction implies payment, actual debiting of funds. Available
OrderType values:
Purchase (by default). If specified, the request for purchase will be created.
PreAuth. If specified, the request for purchase with preauthorization will be created.
Purchase with preauthorization includes two stages:
1.Authorization transaction. It puts the operation amount on hold in the customer
account; the parameters of the original transaction (InvoiceNumber,
SequenceNumber, ApprovalCode) are saved to the reservation table.
2.Completion administrative operation
XML request format:
<?xml version="1.0" encoding="UTF-8"?>
<TKKPG>
<Request>
<Operation>CreateOrder</Operation>
<Language></Language>
<Order>
<OrderType></OrderType>
<Merchant></Merchant>
<Amount></Amount>
<Currency></Currency>
<Description></Description>
<ApproveURL></ApproveURL>
<CancelURL></CancelURL>
<DeclineURL></DeclineURL>
<phone></phone>
<AddParams></AddParams>
<Fee></Fee>
</Order>
</Request>
</TKKPG>
COMPASS PLUS
Public, v.1.08e, 25.12.2020.
Copyright © 1998-2020 Compass Plus Ltd.
22
Operation Groups
Financial Operations
For the description of the Fee, OrigCurrency, OrigAmount, DeclineURL, CancelURL,
ApproveURL, Description, Currency, Amount, Merchant, phone, OrderType and
Language parameters, refer to Structure of TKKPG/Request XML Message.
As a result of executing the CreateOrder operation, an order is created in TWEC PG.
The order status is set to CREATED. In the response, TWEC PG transmits the following
parameters to the payment plug-in:
OrderID (unique order number)
SessionID (session ID)
TWEC PG response format:
<?xml version="1.0" encoding="UTF-8"?>
<TKKPG>
<Response>
<Operation>CreateOrder</Operation>
<Status></Status>
<Order>
<OrderID></OrderID>
<SessionID></SessionID>
<URL></URL>
</Order>
</Response>
</TKKPG>
For the description of the response parameters, refer to Structure of TKKPG/
Response XML Message.
When creating an order, it is possible to specify additional order parameters in the
Order/AddParams element (optional).
The set of additional parameters can include any of those in the table below:
Parameter
Description
OrigAmount
Original amount of the transaction in the minimum units of the
transaction original currency
OrigCurrency
Transaction original currency. Contains the currency numeric code.
UserEmail
Customer e-mail address (additional parameter) that will be saved to the
Email field in the TWEC PG DB
AcctType
Cardholder account type.
Available values:
1 – Checking
2 – Savings
4 – Credit
8 – Bonus
OrderExpirationPeriod
Order lifetime (min). If the specified period expires while the order with
the CREATED, ON-LOCK or ON-PAYMENT status is checked, the order
status will change to EXPIRED and the customer making the payment
will be redirected to DeclineURL.
Attention!
If the parameter is not defined at the order creation, the value of the
analogous parameter defined in the TWEC PG settings will be used.
If the value contains a syntax error or is not specified, the parameter
will be set to its default value (30 minutes).
COMPASS PLUS
Public, v.1.08e, 25.12.2020.
Copyright © 1998-2020 Compass Plus Ltd.
23
Operation Groups
Financial Operations
Parameter
Description
If the parameter value is negative or 0, the order expiration time will
not be checked.
XmlOut.NotificationURL
Alternative address the XMLOut message is sent to. If the parameter is
not specified, the value of the analogous parameter defined in the TWEC
PG settings will be used.
TerminalID
Terminal identifier
Parameters for Recurring Payments
Purchase.Recur.frequency
Minimum count of days between recurring payments. The parameter
value is numeric and must be 1-4 characters long.
Attention! The parameter will not be used if the customer making
recurring payments is authenticated using EMV 3D Secure v2.
Purchase.Recur.endRecur
End date after which authorization will not be performed. The parameter
value format is YYYYMMDD. TWEC PG fills this parameter with the card
expiration date when PAReq is sent to ACS, if:
Format of the parameter value received from the payment plug-in
does not comply with that of the parameter (e.g. 0 or -1).
Card expiration date occurs before the date specified by the payment
plug-in in the Purchase.Recur.endRecur parameter
Attention!
The parameter value is verified when the order for an automatic
recurring payment is created. If the date specified in the parameter
occurs before the order creation date, the CreateOrder operation will
not be performed.
The parameter will not be used if the customer making recurring
payments is authenticated using EMV 3D Secure v2.
Purchase.Recur.period
Time period after which the next recurring payment will be made. The
parameter format is MI-H-D-M-Y. The minimum value is 1 minute, the
maximum – 1 year.
Attention! The parameter is
payments.
mandatory
for automatic
recurring
Purchase.Recur.removeOnDecline Indicator of a repeated attempt to pay the order if it was assigned the
DECLINED status. Available values:
true – no other attempt to pay the order is made and the order is
deleted from the list of recurring payments.
false (by default) – another attempt is made to pay the order.
Attention! The parameter is optional and used for automatic recurring
payments.
MITAttributes
Indicators of the transaction initiated with entering the card data (or its
analog) from the merchant data storage. The parameter is used to
specify a decimal number corresponding to a binary number generated
according to the bit mask in the following format:
bit 1 – Merchant Initiated Transaction, Credential on file entry mode.
Indicator of the transaction initiated by the merchant with entering the
card data (or its analog) from the merchant data storage.
bit 2 – Customer Initiated Transaction, Credential on file entry mode.
Indicator of the transaction initiated by the cardholder with entering
the card data (or its analog) from the merchant data storage.
bit 3 – Credential on file Initial transaction. Indicator of the initial
transaction for which the merchant saves the card data (or its analog)
to be used in possible subsequent transactions.
COMPASS PLUS
Public, v.1.08e, 25.12.2020.
Copyright © 1998-2020 Compass Plus Ltd.
24
Operation Groups
Financial Operations
Parameter
Description
bit 4 – Deferred operation. Indicator of the deferred operation.
bit 5 – Terminated. Indicator of the cancelled subscription.
For example, to indicate the initial transaction, in the MITAttributes
parameter specify the number 4 in the decimal representation that
corresponds to the binary number 00100.
Attention! The parameter should be defined by merchants that use
recurring payments.
Parameters for Internet Shop Notification of Order Status Change
ChangeStatusURL
URL to which the GET request is sent via HTTPS / HTTP upon the order status change. T
%ORDERID% – macro is replaced by the order ID upon URL generation.
%SESSIONID% – macro is replaced by the session ID upon URL generation.
%STATUS% – macro is replaced by the order status upon URL generation.
8.1.2
Postauthorization
Completion operation is used to complete preauthorization to the specified amount.
Attention! The preauthorization completion amount must not exceed that of the original
transaction. However, in some cases, it can do so depending on the authorization system
settings.
When the operation is initiated, the order status is checked. If it is not PREAUTHAPPROVED, the operation is not executed and the error 30 (invalid message format) is
returned. If the Completion operation is successful, the order status is set to
APPROVED. This is how the order status is changed.
XML request format:
<?xml version="1.0" encoding="UTF-8"?>
<TKKPG>
<Request>
<Operation>Completion</Operation>
<Language></Language>
<Order>
<Merchant></Merchant>
<OrderID></OrderID>
<AddParams></AddParams>
</Order>
<SessionID></SessionID>
<Amount></Amount>
<Currency></Currency>
<Description></Description>
<Fee></Fee>
<EncryptedPayload></EncryptedPayload>
</Request
</TKKPG>
For the request parameters description, refer to Structure of TKKPG/Request XML
Message.
TWEC PG response format:
<?xml version="1.0" encoding="UTF-8"?>
<TKKPG>
<Response>
<Operation>Completion</Operation>
COMPASS PLUS
Public, v.1.08e, 25.12.2020.
Copyright © 1998-2020 Compass Plus Ltd.
25
Operation Groups
Financial Operations
<Status>00</Status>
<POSResponse>
<l name="ResponseCode" value="001"/>
<f name="F" value="491385 A"/>
<f name="R" value="D"/>
<f name="a" value="&F1000#&C643#&R01#"/>
<f name="h" value="0010010090"/> <f name="t" value="4634791"/>
</POSResponse>
</Response>
</TKKPG>
Response parameters definition:
Parameter
Data Type
Mandatory
Description
Status
xs:string
R
For the parameter description, refer to
Structure of TKKPG/Response XML
Message.
POSResponse/
ResponseCode
xs:integer
R
POS driver response code
8.1.3
Payment Reversal
Reverse operation is used to reverse (cancel) the payment if the funds to the amount of
the operation were put on hold in the account and the order status was set to
APPROVED or PREAUTH-APPROVED.
XML request format:
<?xml version="1.0" encoding="UTF-8"?>
<TKKPG>
<Request>
<Operation>Reverse</Operation>
<Language></Language>
<Order>
<Merchant></Merchant>
<OrderID></OrderID>
</Order>
<Amount></Amount>
<Description></Description>
<SessionID></SessionID>
<EncryptedPayload></EncryptedPayload>
</Request>
</TKKPG>
For the description of the SessionID, Description, Amount, Language, Merchant,
EncryptedPayload and OrderID parameters, refer to Structure of TKKPG/Request
XML Message.
TWEC PG response format:
<?xml version="1.0" encoding="UTF-8"?>
<TKKPG>
<Response>
<Operation>Reverse</Operation>
<Status></Status>
<Order>
<OrderID></OrderID>
</Order>
<Reversal>
<RespCode></RespCode>
<RespMessage></RespMessage>
</Reversal>
COMPASS PLUS
Public, v.1.08e, 25.12.2020.
Copyright © 1998-2020 Compass Plus Ltd.
26
Operation Groups
Financial Operations
</Response>
</TKKPG>
For the description of the response parameters, refer to Structure of TKKPG/
Response XML Message.
8.1.4
Refund
Refund operation is used to cancel and refund the payment made in terms of a
particular order provided that the order was successfully paid, its status was set to
APPROVED and the funds were actually debited from the account.
XML request format:
<?xml version="1.0" encoding="UTF-8"?>
<TKKPG>
<Request>
<Operation>Refund</Operation>
<Language></Language>
<Order>
<Merchant></Merchant>
<OrderID></OrderID>
<AddParams></AddParams>
</Order>
<Description></Description>
<SessionID></SessionID>
<Refund>
<Amount></Amount>
<Currency></Currency>
<WithFee></WithFee>
</Refund>
<EncryptedPayload></EncryptedPayload>
</Request>
</TKKPG>
For the description of the Language, Merchant, Currency, WithFee, OrderID,
Description, SessionID, EncryptedPayload and Amount parameters, refer to
Structure of TKKPG/Request XML Message.
It is possible to use the Order/AddParams element in the request to define additional
order parameters. For the parameters description, refer to Create Order.
TWEC PG response format:
<?xml version="1.0" encoding="UTF-8"?>
<TKKPG>
<Response>
<Operation>Refund</Operation>
<Status></Status>
</Response>
</TKKPG>
For the Status parameter description, refer to Structure of TKKPG/Response XML
Message.
COMPASS PLUS
Public, v.1.08e, 25.12.2020.
Copyright © 1998-2020 Compass Plus Ltd.
27
Operation Groups
Financial Operations
8.2
Information Operations
Section describes operations used to obtain order-related information:
Get Order Status (GetOrderStatus)
Get Order Information (GetOrderInformation)
Get Orders List (GetOrders)
8.2.1
Get Order Status
GetOrderStatus operation is used to get the order status.
XML request format:
<?xml version="1.0" encoding="UTF-8"?>
<TKKPG>
<Request>
<Operation>GetOrderStatus</Operation>
<Language></Language>
<Order>
<Merchant></Merchant>
<OrderID></OrderID>
</Order>
<SessionID></SessionID>
</Request>
</TKKPG>
For the description of the request parameters, refer to Structure of TKKPG/Request
XML Message.
TWEC PG response format:
<?xml version="1.0" encoding="UTF-8"?>
<TKKPG>
<Response>
<Operation>GetOrderStatus</Operation>
<Status></Status>
<Order>
<OrderID></OrderID>
<OrderStatus></OrderStatus>
</Order>
<AdditionalInfo>
<Receipt></Receipt>
</AdditionalInfo>
</Response>
</TKKPG>
For the description of the request parameters, refer to Structure of TKKPG/Response
XML Message.
COMPASS PLUS
Public, v.1.08e, 25.12.2020.
Copyright © 1998-2020 Compass Plus Ltd.
28
Operation Groups
Information Operations
8.2.2
Get Order Information
GetOrderInformation operation is used to get full information on the order and view all
the additional parameters and executed operations.
XML request format:
<?xml version="1.0" encoding="UTF-8"?>
<TKKPG>
<Request>
<Operation>GetOrderInformation</Operation>
<Language></Language>
<Order>
<Merchant></Merchant>
<OrderID></OrderID>
</Order>
<SessionID></SessionID>
<ShowParams></ShowParams>
<ShowOperations></ShowOperations>
<ClassicView></ClassicView>
</Request>
</TKKPG>
Request parameters definition:
Parameter
ShowParams
Data Type
xs:complexType
Mandatory
O
Description
Facility to view the additional
parameters. Available values:
order
true – response will include the
OrderParams element containing the
names and values of additional order
parameters.
false (by default) –
include values of
parameters.
ShowOperations
xs:complexType
O
response will not
additional order
Facility to view the full list of operations on
the order. Available values:
true – response will include the
OrderOperations element containing
the list of operations on the order.
false (by default) – response will not
include the OrderOperations element.
ClassicView
xs:string
O
Display of the response in the standard
format. Available values:
true – response will be displayed in the
standard format (i. e. the TKKPG/
Response element containing other
response parameters will be present).
false (by default) – response will be
displayed
without
the
TKKPG/
Response element (i. e. all the
response parameters will be in the
Order element).
For the description of the SessionID, OrderID, Merchant and Language parameters,
refer to Structure of TKKPG/Request XML Message.
COMPASS PLUS
Public, v.1.08e, 25.12.2020.
Copyright © 1998-2020 Compass Plus Ltd.
29
Operation Groups
Information Operations
TWEC PG response format depends on the ClassicView parameter value in the request:
If the ClassicView value is not specified or is false:
<?xml version="1.0" encoding="UTF-8"?>
<Order>
<row>
<id></id>
<SessionID></SessionID>
<createDate></createDate>
<lastUpdateDate></lastUpdateDate>
<payDate></payDate>
<MerchantID></MerchantID>
<Amount></Amount>
<Currency></Currency>
<OrderLanguage></OrderLanguage>
<Description></Description>
<ApproveURL></ApproveURL>
<CancelURL></CancelURL>
<DeclineURL></DeclineURL>
<Orderstatus></Orderstatus>
<Receipt></Receipt>
<twoId></twoId>
<RefundAmount></RefundAmount>
<RefundCurrency></RefundCurrency>
<ExtSystemProcess></ExtSystemProcess>
<OrderType></OrderType>
<Fee></Fee>
<Email></Email>
<RefundDate></RefundDate>
<TWODate></TWODate>
<TWOTime></TWOTime>
<OrderParams>
<row>
<PARAMNAME>TranAddendums</PARAMNAME>
<VAL>PFRyYW5BZGRlbmR1bXM+DQogIDxFeHQ
+dGV4dDwvRXh0Pg0KPC9UcmFuQWRkZW5kdW1zPg0K</VAL>
</row>
</OrderParams>
<OrderOperations>
<row>
<id></id>
<PackageId></PackageId>
<createDate></createDate>
<MerchantID></MerchantID>
<OperType></OperType>
<OperName></OperName>
<OrderId></OrderId>
<Amount></Amount>
<Currency></Currency>
<Approval></Approval>
<twoId></twoId>
<twoRC></twoRC>
<Source>1</Source>
<REVERSED>0</REVERSED>
</row>
<row>
<id></id>
<PackageId></PackageId>
<createDate></createDate>
<MerchantID></MerchantID>
<TERMINALID/>
<OperType></OperType>
<OperName></OperName>
<OrderId></OrderId>
<Amount></Amount>
<Currency></Currency>
COMPASS PLUS
Public, v.1.08e, 25.12.2020.
Copyright © 1998-2020 Compass Plus Ltd.
30
Operation Groups
Information Operations
<Approval></Approval>
<twoId></twoId>
<twoRC></twoRC>
<Source>1</Source>
<REVERSED>0</REVERSED>
<row>
</OrderOperations>
</row>
</Order>
If the ClassicView value is true:
<?xml version="1.0" encoding="UTF-8"?>
<TKKPG>
<Response>
<Operation>GetOrderInformation</Operation>
<Status></Status>
<Order>
<row>
<id></id>
<SessionID></SessionID>
<createDate></createDate>
<lastUpdateDate></lastUpdateDate>
<payDate></payDate>
<MerchantID></MerchantID>
<Amount></Amount>
<Currency></Currency>
<OrderLanguage></OrderLanguage>
<Description></Description>
<ApproveURL></ApproveURL>
<CancelURL></CancelURL>
<DeclineURL></DeclineURL>
<Orderstatus></Orderstatus>
<Receipt/>
<twoId/>
<RefundAmount></RefundAmount>
<RefundCurrency></RefundCurrency>
<ExtSystemProcess></ExtSystemProcess>
<OrderType></OrderType>
<Fee></Fee>
<Email></Email>
<RefundDate></RefundDate>
<TWODate></TWODate>
<TWOTime></TWOTime>
<OrderParams>
<row>
<PARAMNAME></PARAMNAME>
<VAL></VAL>
</row>
</OrderParams>
<OrderOperations>
<row>
<id></id>
<PackageId></PackageId>
<createDate></createDate>
<MerchantID></MerchantID>
<TERMINALID/>
<OperType></OperType>
<OperName></OperName>
<OrderId></OrderId>
<Amount></Amount>
<Currency/>
<Approval/>
<twoRC/>
<Source/>
<twoId/>
<REVERSED/>
COMPASS PLUS
Public, v.1.08e, 25.12.2020.
Copyright © 1998-2020 Compass Plus Ltd.
31
Operation Groups
Information Operations
</row>
</OrderOperations>
</row>
</Order>
</Response>
</TKKPG>
Response parameters definition:
Parameter
Data Type
Mandatory
Description
Order/row/id
xs:integer
R
Unique order number
Order/row/
createDate
xs:integer
C
Order creation date
Order/row/
lastUpdateDate
xs:integer
C
Date of the order last modification
Order/row/payDate
xs:integer
C
Date of the first payment in terms of the
order
Order/row/
MerchantID
xs:string
C
Merchant ID in TWEC PG
Order/row/Amount
xs:integer
C
Order amount
Order/row/Currency xs:integer
C
Order currency
Order/row/
OrderLanguage
xs:string
C
Interface language for the order. Filled
with the two-letter code of the interface
language compliant with RFC 1766 (e.g.
RU – Russian language, EN – English
language, UK – Ukrainian language, etc.).
Order/row/
Description
xs:string
C
Order description
Order/row/
ApproveURL
xs:anyURI
C
URL to redirect the customer to if the
operation is approved.
If the parameter is not defined in the
CreateOrder operation, its value will be
taken from the TWEC PG settings.
Order/row/
CancelURL
xs:anyURI
C
URL to redirect the customer to if the
operation is cancelled (by clicking the
Cancel button).
If the parameter is not defined in the
CreateOrder operation, its value will be
taken from the TWEC PG settings.
Order/row/
DeclineURL
xs:anyURI
C
URL to redirect the customer to if the
payment operation is declined.
If the parameter is not defined in the
CreateOrder operation, its value will be
taken from the TWEC PG settings.
Order/row/twoid
xs:integer
C
ID of the transaction in the authorization
system executed based on the last
operation in terms of the order
Order/row/
RefundAmount
xs:integer
C
Total amount of refund operations
Order/row/
RefundCurrency
xs:integer
C
Currency of refund operations
COMPASS PLUS
Public, v.1.08e, 25.12.2020.
Copyright © 1998-2020 Compass Plus Ltd.
32
Operation Groups
Information Operations
Parameter
Data Type
Mandatory
Description
Order/row/
ExtSystemProcess
xs:integer
C
Indicator of whether an external system is
used to process transactions
Order/row/
OrderType
xs:string
C
Order type
Order/row/Fee
xs:integer
O
Acquiring fee
Order/row/Email
xs:string
O
Customer e-mail address
Order/row/
RefundDate
xs:integer
C
Refund date
Order/row/TWODate xs:integer
C
Date on the receipt
Order/row/TWOTime xs:integer
C
Time on the receipt
Order/row/
OrderParams
xs:complexType
O
Names and values of the additional order
parameters
Order/row/
OrderOperations
xs:complexType
O
Entire list of operations in terms of the
order
Order/row/
OrderOperations/id
xs:integer
R
Operation ID
Order/row/
OrderOperations/
PackageId
xs:integer
O
Order package ID
Order/row/
OrderOperations/
createDate
xs:string
R
Operation creation date
Order/row/
OrderOperations/
MerchantID
xs:integer
R
Merchant ID in TWEC PG
Order/row/
OrderOperations/
TERMINALID
xs:integer
R
ID of the terminal the operation was
performed on
Order/row/
OrderOperations/
OperType
xs:integer
R
Operation type code
Order/row/
OrderOperations/
OperName
xs:string
R
Operation name
Order/row/
OrderOperations/
OrderId
xs:integer
R
Order ID
Order/row/
OrderOperations/
Amount
xs:integer
O
Amount of operation performed in terms of
the order
Order/row/
OrderOperations/
Currency
xs:integer
O
Currency code (e.g. 643 – Russian Rouble,
840 – US Dollar)
Order/row/
OrderOperations/
Approval
xs:integer
O
Approval code (receipt number)
COMPASS PLUS
Public, v.1.08e, 25.12.2020.
Copyright © 1998-2020 Compass Plus Ltd.
33
Operation Groups
Information Operations
Parameter
Data Type
Mandatory
Description
Order/row/
OrderOperations/
twoId
xs:integer
O
ID of the operation assigned to it in the
authorization system
Order/row/
OrderOperations/
twoRC
xs:integer
O
Authorization system response code
Order/row/
OrderOperations/
Source
xs:integer
O
Operation source
Order/row/
OrderOperations/
REVERSED
xs:complexType
O
Indicator of payment reversal
For the description of the Receipt, OrderStatus and SessionID parameters, refer to
Structure of TKKPG/Response XML Message.
8.2.3
Get Orders List
GetOrders operation is used to filter and sort the merchant orders.
XML request format:
<?xml version="1.0" encoding="UTF-8"?>
<TKKPG>
<Request>
<Operation>GetOrders</Operation>
<Language></Language>
<Merchant></Merchant>
<EncryptedPayload></EncryptedPayload>
<OrdersFilter>
<Period>
<Start></Start>
<End></End>
</Period>
<LastCount></LastCount>
<StartFrom></StartFrom>
<Status></Status>
<Amount>
<Min></Min>
<Max></Max>
</Amount>
<Currency></Currency>
<Description></Description>
<AddParams>
<Item id='' val='' />
</AddParams>
<OrderBy></OrderBy>
<OrderingDirection></OrderingDirection>
<OrderId></OrderId>
</OrdersFilter
</Request>
</TKKPG>
COMPASS PLUS
Public, v.1.08e, 25.12.2020.
Copyright © 1998-2020 Compass Plus Ltd.
34
Operation Groups
Information Operations
Request parameters definition:
Parameter
Data Type
Mandatory
Description
OrdersFilter/Period
xs:integer
R
Order creation period
OrdersFilter/Period/Start
xs:integer
C
Order start date.
The parameter is optional if the
OrdersFilter/LastCount
parameter is defined.
OrdersFilter/Period/End
xs:integer
O
Order end date
OrdersFilter/LastCount
xs:integer
C
Number of records to
displayed after filtering.
be
The parameter is optional if the
OrdersFilter/Period/Start
parameter is defined.
Attention!
If
the
OrdersFilter.LastCount value
is not specified or exceeds that
of the respective parameter in
TWEC PG used to define the
number of operations returned
in
the
response
to
the
GetOrders operation request,
the latter value will be used.
OrdersFilter/StartFrom
xs:integer
O
Item starting from which the
records are displayed
OrdersFilter/Status
xs:string
O
Order status
OrdersFilter/Amount
xs:integer
O
Transaction amount in
minimum
units
of
transaction currency
OrdersFilter/Amount/Min
xs:integer
O
Minimum transaction amount
OrdersFilter/Amount/Max
xs:integer
O
Maximum transaction amount
OrdersFilter/Currency
xs:integer
O
Transaction currency
(e.g. 840 – US Dollar)
OrdersFilter/Description
xs:string
O
Text description of the order
OrdersFilter/AddParams
xs:complexType
O
Additional order parameters
OrdersFilter/OrderBy
xs:string
O
Sorting of orders by one of the
following parameters:
the
the
code
id
SessionID
createDate
lastUpdateDate
payDate
MerchantID
Amount
Currency
OrderLanguage
Description
ApproveURL
CancelURL
DeclineURL
COMPASS PLUS
Public, v.1.08e, 25.12.2020.
Copyright © 1998-2020 Compass Plus Ltd.
35
Operation Groups
Information Operations
Parameter
Data Type
Mandatory
Description
Orderstatus
Receipt
RefundAmount
RefundCurrency
RefundDate
Fee
Attention! Sorting by several
parameters is not supported.
OrdersFilter/
OrderingDirection
xs:string
O
Sorting order.
Available values:
ACS (by default) – ascending
sorting
DESC – descending sorting
OrdersFilter/OrderId
xs:integer
O
Order number
For the description of the Merchant, EncryptedPayload and Language parameters,
refer to Structure of TKKPG/Request XML Message.
TWEC PG response format:
<?xml version="1.0" encoding="UTF-8"?>
<Orders>
<row>
<id></id>
<SessionID></SessionID>
<createDate></createDate>
<lastUpdateDate></lastUpdateDate>
<payDate></payDate>
<MerchantID></MerchantID>
<Amount></Amount>
<Currency></Currency>
<OrderLanguage></OrderLanguage>
<Description></Description>
<ApproveURL></ApproveURL>
<CancelURL></CancelURL>
<DeclineURL></DeclineURL>
<Orderstatus></Orderstatus>
<Receipt/>
<twoId/>
<RefundAmount></RefundAmount>
<RefundCurrency></RefundCurrency>
<PaidWithMobicash></PaidWithMobicash>
<RefundDate></RefundDate>
<ExtSystemProcess></ExtSystemProcess>
<OrderType/>
<Fee></Fee>
</row>
<row>
<id></id>
<SessionID></SessionID>
<createDate></createDate>
<lastUpdateDate></lastUpdateDate>
<payDate></payDate>
<MerchantID></MerchantID>
<Amount></Amount>
<Currency></Currency>
<OrderLanguage></OrderLanguage>
<Description></Description>
COMPASS PLUS
Public, v.1.08e, 25.12.2020.
Copyright © 1998-2020 Compass Plus Ltd.
36
Operation Groups
Information Operations
<ApproveURL></ApproveURL>
<CancelURL></CancelURL>
<DeclineURL></DeclineURL>
<Orderstatus></Orderstatus>
<Receipt/>
<twoId/>
<RefundAmount></RefundAmount>
<RefundCurrency></RefundCurrency>
<PaidWithMobicash></PaidWithMobicash>
<RefundDate></RefundDate>
<ExtSystemProcess></ExtSystemProcess>
<OrderType/>
<Fee></Fee>
</row>
</Orders>
For the detailed description of the parameters, refer to Get Order Information. The
response can also contain the PaidWithMobicash parameter indicating that the order
was paid via the MobiCash service.
COMPASS PLUS
Public, v.1.08e, 25.12.2020.
Copyright © 1998-2020 Compass Plus Ltd.
37
Appendixes
Standard Procedures for Executing TWEC PG Operations
9
Appendixes
9.1
Standard Procedures for Executing TWEC PG
Operations
Section describes standard procedures for executing the following operations:
Purchasing
Purchasing with Preauthorization
Automatic Recurring Payment / Transfer
9.1.1
Purchasing
Purchase includes the following steps:
1.Payment plug-in of the Internet shop initiates the CreateOrder operation (with the
OrderType parameter set to Purchase) in TWEC PG.
Example of XML request:
<?xml version="1.0" encoding="UTF-8"?>
<TKKPG>
<Request>
<Operation>CreateOrder</Operation>
<Language>RU</Language>
<Order>
<OrderType>Purchase</OrderType>
<Merchant>test</Merchant>
<Amount>2500</Amount>
<Currency>840</Currency>
<Description>xxxxxxxx</Description>
<ApproveURL>/testPaymentModulePageReturn.jsp</ApproveURL>
<CancelURL>/testPaymentModulePageReturn.jsp</CancelURL>
<DeclineURL>/testPaymentModulePageReturn.jsp</DeclineURL>
<AddParams>
<ChangeStatusURL>http://127.0.0.1:5000/testPaymentModuleChangeStatus.jsp</ChangeStatusURL>
</AddParams>
</Order>
</Request>
</TKKPG>
2.TWEC PG generates the order ID and session ID; creates an XML response containing
the generated data and URL the payment plug-in will redirect the customer to.
Example of XML response provided by TWEC PG:
<?xml version="1.0" encoding="UTF-8"?>
<TKKPG>
<Response>
<Operation>CreateOrder</Operation>
<Status>00</Status>
<Order>
<OrderID>828</OrderID>
<SessionID>ECDE79578768ECFBF2897A0F44CC0CEF</SessionID>
<URL>https://TWPG.bank.com/index.jsp</URL>
</Order>
</Response>
</TKKPG>
COMPASS PLUS
Public, v.1.08e, 25.12.2020.
Copyright © 1998-2020 Compass Plus Ltd.
38
Appendixes
Standard Procedures for Executing TWEC PG Operations
3.Payment plug-in receives an XML response to the CreateOrder operation and
redirects the customer browser to the TWEC PG page whose address is specified in
the URL parameter to make payment. At the redirection to the specified URL, the
following parameters must be transmitted:
OrderID – order ID received in the OrderID parameter
SessionID – session ID received in the SessionID parameter
Example of call by GET method:
https://TWPG.bank.com/index.jsp?ORDERID=828&SESSIONID=ECDE79578768ECFBF2897A0F44CC0CEFF
4.TWEC PG notifies the Internet shop of the order status change using the HTTP
request that contains the OrderID, SessionID and Status parameters. The request is
sent to the Internet shop address specified in the additional order parameter at the
order creation.
Example of call by GET method:
http://127.0.0.1:5000/testPaymentModuleChangeStatus.jsp?
ORDERID=828&SESSIONID=ECDE79578768ECFBF2897A0F44CC0CEFF&STATUS=ON-PAYMENT
Otherwise, the payment plug-in requests the order status by executing the
GetOrderStatus operation every 3-5 seconds.
Example of XML request:
<?xml version="1.0" encoding="UTF-8"?>
<TKKPG>
<Request>
<Operation>GetOrderStatus</Operation>
<Language>RU</Language>
<Order>
<Merchant>test</Merchant>
<OrderID>828</OrderID>
</Order>
<SessionID>ECDE79578768ECFBF2897A0F44CC0CEF</SessionID>
</Request>
</TKKPG>
Example of XML response provided by TWEC PG:
<?xml version="1.0" encoding="UTF-8"?>
<TKKPG>
<Response>
<Operation>GetOrderStatus</Operation>
<Status>00</Status>
<Order>
<OrderID>828</OrderID>
<OrderStatus>ON-PAYMENT</OrderStatus>
</Order>
<AdditionalInfo>
<Receipt>BASE64-encode-info</Receipt>
</AdditionalInfo>
</Response>
</TKKPG>
5.If 3D Secure authentication is used, TWEC PG sends user authentication requests to
ACS and gets the transaction authorized by the issuer via the payment system.
6.Depending on the transaction authorization result, TWEC PG assigns the
APPROVED / CANCELED / DECLINED status to the order and redirects the
customer to the payment plug-in page of the Internet shop at the respective URL
(ApproveURL / CancelURL / DeclineURL).
COMPASS PLUS
Public, v.1.08e, 25.12.2020.
Copyright © 1998-2020 Compass Plus Ltd.
39
Appendixes
Standard Procedures for Executing TWEC PG Operations
7.TWEC PG sends the authorization result notification to the Internet shop.
8.Payment plug-in gets the order status from the response to the GetOrderStatus
operation or from the order status change notification and executes the
GetOrderInformation operation.
Example of XML request:
<?xml version="1.0" encoding="UTF-8"?>
<TKKPG>
<Request>
<Operation>GetOrderInformation</Operation>
<Language>RU</Language>
<Order>
<Merchant>test</Merchant>
<OrderID>828</OrderID>
</Order>
<SessionID>ECDE79578768ECFBF2897A0F44CC0CEF</SessionID>
<ShowParams>true</ShowParams>
<ShowOperations>false</ShowOperations>
<ClassicView>true</ClassicView>
</Request>
</TKKPG>
Example of XML response provided by TWEC PG:
<?xml version="1.0" encoding="UTF-8"?>
<TKKPG>
<Response>
<Operation>GetOrderInformation</Operation>
<Status>00</Status>
<Order>
<row>
<id>828</id>
<SessionID>ECDE79578768ECFBF2897A0F44CC0CEF</SessionID>
<createDate>2018-02-14 14:15:37</createDate>
<lastUpdateDate>2018-02-14 14:33:26</lastUpdateDate>
<payDate>null</payDate>
<MerchantID>test</MerchantID>
<Amount>2500</Amount>
<Currency>840</Currency>
<OrderLanguage>RU</OrderLanguage>
<Description>xxxxxxxx</Description>
<ApproveURL>/testPaymentModulePageReturn.jsp</ApproveURL>
<CancelURL>/testPaymentModulePageReturn.jsp</CancelURL>
<DeclineURL>/testPaymentModulePageReturn.jsp</DeclineURL>
<Orderstatus>APPROVED</Orderstatus>
<RefundAmount>0</RefundAmount>
<RefundCurrency>null</RefundCurrency>
<ExtSystemProcess>0</ExtSystemProcess>
<OrderType>Purchase</OrderType>
<Fee>0</Fee>
<RefundDate>0000-00-00 00:00:00</RefundDate>
<TWOTime>null</TWOTime>
<OrderParams>
<row>
<PARAMNAME>AcctType</PARAMNAME>
<VAL>4</VAL>
</row>
</OrderParams>
</row>
</Order>
</Response>
</TKKPG>
COMPASS PLUS
Public, v.1.08e, 25.12.2020.
Copyright © 1998-2020 Compass Plus Ltd.
40
Appendixes
Standard Procedures for Executing TWEC PG Operations
9.Payment plug-in displays the order information (received in the response to the
GetOrderInformation operation) on the website.
For further actions on the order, such operations
GetOrderInformation, GetOrderStatus can be used.
9.1.2
as
Refund,
Reverse,
Purchasing with Preauthorization
Purchase with preauthorization includes the following steps:
1.Preauthorization:
1.1.Payment plug-in of the Internet shop initiates the CreateOrder operation (with
the OrderType parameter set to PreAuth) in TWEC PG.
Example of XML request:
<?xml version="1.0" encoding="UTF-8"?>
<TKKPG>
<Request>
<Operation>CreateOrder</Operation>
<Language>RU</Language>
<Order>
<OrderType>PreAuth</OrderType>
<Merchant>test</Merchant>
<Amount>2500</Amount>
<Currency>840</Currency>
<Description>xxxxxxxx</Description>
<ApproveURL>/testPaymentModulePageReturn.jsp</ApproveURL>
<CancelURL>/testPaymentModulePageReturn.jsp</CancelURL>
<DeclineURL>/testPaymentModulePageReturn.jsp</DeclineURL>
<AddParams>
<ChangeStatusURL>http://127.0.0.1:5000/testPaymentModuleChangeStatus.jsp</
ChangeStatusURL>
</AddParams>
</Order>
</Request>
</TKKPG>
1.2.TWEC PG generates the order ID and session ID; creates an XML response
containing the generated data and URL the payment plug-in will redirect the
customer to.
Example of XML response provided by TWEC PG:
<?xml version="1.0" encoding="UTF-8"?>
<TKKPG>
<Response>
<Operation>CreateOrder</Operation>
<Status>00</Status>
<Order>
<OrderID>828</OrderID>
<SessionID>ECDE79578768ECFBF2897A0F44CC0CEF</SessionID>
<URL>https://TWPG.bank.com/index.jsp</URL>
</Order>
</Response>
</TKKPG>
COMPASS PLUS
Public, v.1.08e, 25.12.2020.
Copyright © 1998-2020 Compass Plus Ltd.
41
Appendixes
Standard Procedures for Executing TWEC PG Operations
1.3.Payment plug-in receives an XML response to the CreateOrder operation and
redirects the customer browser to the TWEC PG page whose address is specified in
the URL parameter to make payment. At the redirection to the specified URL, the
following parameters must be transmitted:
OrderID – order ID received in the OrderID parameter
SessionID – session ID received in the SessionID parameter
Example of call by GET method:
https://TWPG.bank.com/index.jsp?
ORDERID=828&SESSIONID=ECDE79578768ECFBF2897A0F44CC0CEFF
1.4.TWEC PG notifies the Internet shop of the order status change using the HTTP
request that contains the OrderID, SessionID and Status parameters. The request
is sent to the Internet shop address specified in the additional order parameter at
the order creation.
Example of call by GET method:
http://127.0.0.1:5000/testPaymentModuleChangeStatus.jsp?
ORDERID=828&SESSIONID=ECDE79578768ECFBF2897A0F44CC0CEFF&STATUS=ON-PAYMENT
Otherwise, the payment plug-in requests the order status by executing the
GetOrderStatus operation every 3-5 seconds.
Example of XML request:
<?xml version="1.0" encoding="UTF-8"?>
<TKKPG>
<Request>
<Operation>GetOrderStatus</Operation>
<Language>RU</Language>
<Order>
<Merchant>test</Merchant>
<OrderID>828</OrderID>
</Order>
<SessionID>ECDE79578768ECFBF2897A0F44CC0CEF</SessionID>
</Request>
</TKKPG>
Example of XML response provided by TWEC PG:
<?xml version="1.0" encoding="UTF-8"?>
<TKKPG>
<Response>
<Operation>GetOrderStatus</Operation>
<Status>00</Status>
<Order>
<OrderID>828</OrderID>
<OrderStatus>ON-PAYMENT</OrderStatus>
</Order>
<AdditionalInfo>
<Receipt>BASE64-encode-info</Receipt>
</AdditionalInfo>
</Response>
</TKKPG>
1.5.If 3D Secure authentication is used, TWEC PG sends user authentication requests
to ACS and gets the transaction authorized by the issuer via the payment system.
1.6.Depending on the transaction authorization result, TWEC PG assigns the
PREAUTH-APPROVED/DECLINED/CANCELED status to the order and redirects
the customer to the payment plug-in page of the Internet shop located at the
respective URL (ApproveURL / CancelURL / DeclineURL).
1.7.TWEC PG sends the authorization result notification to the Internet shop.
COMPASS PLUS
Public, v.1.08e, 25.12.2020.
Copyright © 1998-2020 Compass Plus Ltd.
42
Appendixes
Standard Procedures for Executing TWEC PG Operations
1.8.Payment plug-in gets the order status from the response to the GetOrderStatus
operation or from the order status change notification and executes the
GetOrderInformation operation.
Example of XML request:
<?xml version="1.0" encoding="UTF-8"?>
<TKKPG>
<Request>
<Operation>GetOrderInformation</Operation>
<Language>RU</Language>
<Order>
<Merchant>test</Merchant>
<OrderID>828</OrderID>
</Order>
<SessionID>ECDE79578768ECFBF2897A0F44CC0CEF</SessionID>
<ShowParams>true</ShowParams>
<ShowOperations>false</ShowOperations>
<ClassicView>true</ClassicView>
</Request>
</TKKPG>
Example of XML response provided by TWEC PG:
<?xml version="1.0" encoding="UTF-8"?>
<TKKPG>
<Response>
<Operation>GetOrderInformation</Operation>
<Status>00</Status>
<Order>
<row>
<id>828</id>
<SessionID>ECDE79578768ECFBF2897A0F44CC0CEF</SessionID>
<createDate>2018-02-14 14:15:37</createDate>
<lastUpdateDate>2018-02-14 14:33:26</lastUpdateDate>
<payDate>null</payDate>
<MerchantID>test</MerchantID>
<Amount>2500</Amount>
<Currency>840</Currency>
<OrderLanguage>RU</OrderLanguage>
<Description>xxxxxxxx</Description>
<ApproveURL>/testPaymentModulePageReturn.jsp</ApproveURL>
<CancelURL>/testPaymentModulePageReturn.jsp</CancelURL>
<DeclineURL>/testPaymentModulePageReturn.jsp</DeclineURL>
<Orderstatus>PREAUTH-APPROVED</Orderstatus>
<RefundAmount>0</RefundAmount>
<RefundCurrency>null</RefundCurrency>
<ExtSystemProcess>0</ExtSystemProcess>
<OrderType>PreAuth</OrderType>
<Fee>0</Fee>
<RefundDate>0000-00-00 00:00:00</RefundDate>
<TWOTime>null</TWOTime>
<OrderParams>
<row>
<PARAMNAME>AcctType</PARAMNAME>
<VAL>4</VAL>
</row>
</OrderParams>
</row>
</Order>
</Response>
</TKKPG>
1.9.Payment plug-in displays the order information (received in the response to the
GetOrderInformation operation) on the website.
COMPASS PLUS
Public, v.1.08e, 25.12.2020.
Copyright © 1998-2020 Compass Plus Ltd.
43
Appendixes
Standard Procedures for Executing TWEC PG Operations
2.Postauthorization:
2.1.Payment plug-in initiates in TWEC PG the Completion operation specifying the
values of the OrderID and SessionID parameters received in the response to the
preauthorization operation.
Example of XML request:
<?xml version="1.0" encoding="UTF-8"?>
<TKKPG>
<Request>
<Operation>Completion</Operation>
<Language>RU</Language>
<Order>
<Merchant>test</Merchant>
<OrderID>828</OrderID>
</Order>
<SessionID>ECDE79578768ECFBF2897A0F44CC0CEF</SessionID>
<Description>xxxxxx</Description>
</Request>
</TKKPG>
Example of XML response provided by TWEC PG:
<?xml version="1.0" encoding="UTF-8"?>
<TKKPG>
<Response>
<Operation>Completion</Operation>
<Status>00</Status>
<POSResponse>
<l name="ResponseCode" value="001"/>
<f name="F" value="491385 A"/>
<f name="R" value="D"/>
<f name="a" value="&F1000#&C643#&R01#"/>
<f name="h" value="0010010090"/>
<f name="t" value="4634791"/>
</POSResponse>
</Response>
</TKKPG>
2.2.TWEC PG sends the Completion transaction to the authorization system.
2.3.Depending on the authorization system response, TWEC PG assigns the
APPROVED/DECLINED/CANCELED status to the order.
For further actions on the order, such operations
GetOrderInformation, GetOrderStatus can be used.
9.1.3
as
Refund,
Reverse,
Automatic Recurring Payment
First payment in terms of the order includes the following steps:
1.Payment plug-in initiates in TWEC PG the CreateOrder operation with the
OrderType parameter set to Purchase and the OrderExpirationPeriod,
Purchase.Recur.frequency, Purchase.Recur.endRecur, Purchase.Recur.period
and Purchase.Recur.removeOnDecline additional parameters defined in the
AddParams element (for the parameters description, refer to CreateOrder).
Example of XML request:
<?xml version="1.0" encoding="UTF-8"?>
<TKKPG>
<Request>
<Operation>CreateOrder</Operation>
<Language>RU</Language>
COMPASS PLUS
Public, v.1.08e, 25.12.2020.
Copyright © 1998-2020 Compass Plus Ltd.
44
Appendixes
Standard Procedures for Executing TWEC PG Operations
<Order>
<OrderType>Purchase</OrderType>
<Merchant>test</Merchant>
<Amount>2500</Amount>
<Currency>840</Currency>
<Description>xxxxxxxx</Description>
<ApproveURL>/testPaymentModulePageReturn.jsp</ApproveURL>
<CancelURL>/testPaymentModulePageReturn.jsp</CancelURL>
<DeclineURL>/testPaymentModulePageReturn.jsp</DeclineURL>
<AddParams>
<ChangeStatusURL>http://127.0.0.1:5000/testPaymentModuleChangeStatus.jsp</
ChangeStatusURL>
<Purchase.Recur.frequency>0</Purchase.Recur.frequency>
<Purchase.Recur.endRecur>20181014</Purchase.Recur.endRecur>
<Purchase.Recur.period>2-0-2-0-0</Purchase.Recur.period>
<Purchase.Recur.removeOnDecline>true</Purchase.Recur.removeOnDecline>
</AddParams>
</Order>
</Request>
</TKKPG>
2.TWEC PG generates the order ID and session ID; creates an XML response containing
the generated data and URL the payment plug-in will redirect the customer to.
Example of XML response provided by TWEC PG:
<?xml version="1.0" encoding="UTF-8"?>
<TKKPG>
<Response>
<Operation>CreateOrder</Operation>
<Status>00</Status>
<Order>
<OrderID>828</OrderID>
<SessionID>ECDE79578768ECFBF2897A0F44CC0CEF</SessionID>
<URL>https://TWPG.bank.com/index.jsp</URL>
</Order>
</Response>
</TKKPG>
3.Payment plug-in receives an XML response to the CreateOrder operation and
redirects the customer browser to the TWEC PG page whose address is specified in
the URL parameter to make payment. At the redirection to the specified URL, the
following parameters must be transmitted:
OrderID – order ID received in the OrderID parameter
SessionID – session ID received in the SessionID parameter
Example of call by GET method:
https://TWPG.bank.com/index.jsp?ORDERID=828&SESSIONID=ECDE79578768ECFBF2897A0F44CC0CEFF
4.TWEC PG notifies the Internet shop of the order status change using the HTTP
request that contains the OrderID, SessionID and Status parameters. The request is
sent to the Internet shop address specified in the additional order parameter at the
order creation.
Example of call by GET method:
http://127.0.0.1:5000/testPaymentModuleChangeStatus.jsp?
ORDERID=828&SESSIONID=ECDE79578768ECFBF2897A0F44CC0CEFF&STATUS=ON-PAYMENT
Otherwise, the payment plug-in requests the order status by executing the
GetOrderStatus operation every 3-5 seconds.
COMPASS PLUS
Public, v.1.08e, 25.12.2020.
Copyright © 1998-2020 Compass Plus Ltd.
45
Appendixes
Standard Procedures for Executing TWEC PG Operations
Example of XML request:
<?xml version="1.0" encoding="UTF-8"?>
<TKKPG>
<Request>
<Operation>GetOrderStatus</Operation>
<Language>RU</Language>
<Order>
<Merchant>test</Merchant>
<OrderID>828</OrderID>
</Order>
<SessionID>ECDE79578768ECFBF2897A0F44CC0CEF</SessionID>
</Request>
</TKKPG>
Example of XML response provided by TWEC PG:
<?xml version="1.0" encoding="UTF-8"?>
<TKKPG>
<Response>
<Operation>GetOrderStatus</Operation>
<Status>00</Status>
<Order>
<OrderID>828</OrderID>
<OrderStatus>ON-PAYMENT</OrderStatus>
</Order>
<AdditionalInfo>
<Receipt>BASE64-encode-info</Receipt>
</AdditionalInfo>
</Response>
</TKKPG>
5.If 3D Secure authentication is used, TWEC PG sends user authentication requests to
ACS and gets the transaction authorized by the issuer via the payment system.
6.Depending on the transaction authorization result, TWEC PG assigns the
APPROVED / CANCELED / DECLINED status to the order and redirects the
customer to the payment plug-in page of the Internet shop located at the respective
URL (ApproveURL / CancelURL / DeclineURL).
7.TWEC PG sends the authorization result notification to the Internet shop.
8.Payment plug-in gets the order status from the response to the GetOrderStatus
operation or from the order status change notification and executes the
GetOrderInformation operation.
Example of XML request:
<?xml version="1.0" encoding="UTF-8"?>
<TKKPG>
<Request>
<Operation>GetOrderInformation</Operation>
<Language>RU</Language>
<Order>
<Merchant>test</Merchant>
<OrderID>828</OrderID>
</Order>
<SessionID>ECDE79578768ECFBF2897A0F44CC0CEF</SessionID>
<ShowParams>true</ShowParams>
<ShowOperations>false</ShowOperations>
<ClassicView>true</ClassicView>
</Request>
</TKKPG>
COMPASS PLUS
Public, v.1.08e, 25.12.2020.
Copyright © 1998-2020 Compass Plus Ltd.
46
Appendixes
Standard Procedures for Executing TWEC PG Operations
Example of XML response provided by TWEC PG:
<?xml version="1.0" encoding="UTF-8"?>
<TKKPG>
<Response>
<Operation>GetOrderInformation</Operation>
<Status>00</Status>
<Order>
<row>
<id>828</id>
<SessionID>ECDE79578768ECFBF2897A0F44CC0CEF</SessionID>
<createDate>2018-02-14 14:15:37</createDate>
<lastUpdateDate>2018-02-14 14:33:26</lastUpdateDate>
<payDate>null</payDate>
<MerchantID>test</MerchantID>
<Amount>2500</Amount>
<Currency>840</Currency>
<OrderLanguage>RU</OrderLanguage>
<Description>xxxxxxxx</Description>
<ApproveURL>/testPaymentModulePageReturn.jsp</ApproveURL>
<CancelURL>/testPaymentModulePageReturn.jsp</CancelURL>
<DeclineURL>/testPaymentModulePageReturn.jsp</DeclineURL>
<Orderstatus>APPROVED</Orderstatus>
<RefundAmount>0</RefundAmount>
<RefundCurrency>null</RefundCurrency>
<ExtSystemProcess>0</ExtSystemProcess>
<OrderType>Purchase</OrderType>
<Fee>0</Fee>
<RefundDate>0000-00-00 00:00:00</RefundDate>
<TWOTime>null</TWOTime>
<OrderParams>
<row>
<PARAMNAME>AcctType</PARAMNAME>
<VAL>4</VAL>
</row>
</OrderParams>
</row>
</Order>
</Response>
</TKKPG>
9.Payment plug-in displays the order information (received in the response to the
GetOrderInformation operation) on the website.
Every next payment in terms of the order will be made automatically, upon expiration of
the period specified in the Purchase.Recur.period additional parameter of the
AddParams element at the order creation.
9.2
Example Implementation of Payment Plug-In
Example implementation of the standard payment plug-in that enables the merchant to
initiate the CreateOrder administrative operation in TWEC PG is available at https://
compassplus.com/solutions/plug-play/processing-hub/tranzware-payment-gatewaypayment-module-integration-guide.
COMPASS PLUS
Public, v.1.08e, 25.12.2020.
Copyright © 1998-2020 Compass Plus Ltd.
47
Appendixes
Example Implementation of Payment Plug-In
9.3
Example Implementation of Administrative
Operations in PHP
Example implementation of the CreateOrder and GetOrderStatus administrative
operations (sent to the Exec access point) in the PHP programming language:
<?php
//
// Post can be placed to a separate function that uses sockets (the third-party libraries are not required)
// The function returns a simplexml object containing a parsed xml.
//
function PostQW($hostname,$port,$data){
$path = '/Exec';
$content = '';
// Establish a connection to the $hostname server
$fp = fsockopen($hostname, $port, $errno, $errstr, 30);
// Check if the connection is successfully established
if (!$fp) die('<p>'.$errstr.' ('.$errno.')</p>');
// HTTPS request header
$headers = 'POST '.$path." HTTPS/1.0\r\n";
$headers .= 'Host: '.$hostname."\r\n";
$headers .= "Content-type: text/xml\r\n";
$headers .= 'Content-Length: '.strlen($data)."\r\n\r\n";
// Send HTTPS request to the server
fwrite($fp, $headers.$data);
// Receive response
while ( !feof($fp) ){
$inStr= fgets($fp, 1024);
// Cut the HTTPS response headers. The string can be commented out if it is necessary to parse the header
// In this case it is necessary to cut the response
if (substr($inStr,0,7)!=="<TKKPG>") continue;
//Disconnect
$content .= $inStr;
}
//
fclose($fp);
//
// To parse the response, use the simplexml library
// Documentation on simplexml - https://us3.php.net/manual/ru/book.simplexml.php
$xml = simplexml_load_string($content); // Load data from the string
return ($xml);
}
// Create Xml order to describe the order parameters:
$data='<?xml version="1.0" encoding="UTF-8"?>';
$data.="<TKKPG>";
$data.="<Request>";
$data.="<Operation>CreateOrder</Operation>";
$data.="<Language>RU</Language>";
$data.="<Order>";
$data.="<OrderType>Purchase</OrderType>";
$data.="<Merchant>POS_1</Merchant>";
$data.="<Amount>2500</Amount>";
$data.="<Currency>840</Currency>";
$data.="<Description>xxxxxxxx</Description>";
$data.="<ApproveURL>/testshopPageReturn.jsp</ApproveURL>";
$data.="<CancelURL>/testshopPageReturn.jsp</CancelURL>";
$data.="<DeclineURL>/testshopPageReturn.jsp</DeclineURL>";
$data.="</Order></Request></TKKPG>";
//
// Create Order $hostname = '10.7.2.60'; // Address of the server with servlet used to work with orders
$port="5556"; // Port
// Information on the result of the order creation in the Response object
COMPASS PLUS
Public, v.1.08e, 25.12.2020.
Copyright © 1998-2020 Compass Plus Ltd.
48
Appendixes
Example Implementation of Administrative Operations
in PHP
// Examples of obtaining required fields:
$xml=PostQW($hostname,$port,$data);
$Status=$xml->Response->Status;
$OrderID=$xml->Response->Order->OrderID;
$SessionID=$xml->Response->Order->SessionID;
// Request status of the order just received
$data='<?xml version="1.0" encoding="UTF-8"?>';
$data.="<TKKPG>";
$data.="<Request>";
$data.="<Operation>GetOrderStatus</Operation>";
$data.="<Order>";
$data.="<Merchant>POS_1</Merchant>";
$data.="<OrderID>".$OrderID."</OrderID>";
$data.="</Order>";
$data.="<SessionID>".$SessionID."</SessionID>";
$data.="</Request></TKKPG>";
$xml=PostQW($hostname,$port,$data);
$OrderStatus=$xml->Response->Order->OrderStatus;
?>
XSD Schema of TWEC PG Protocol
9.4
XSD schema of the internal protocol (TKKPG) is available at available at https://
compassplus.com/solutions/plug-play/processing-hub/tranzware-payment-gatewaypayment-module-integration-guide.
XMLOut Message Parameters
9.5
Table below lists the parameters of the XMLOut message containing transaction
authorization results:
Parameter
Mandatory
Example
Description
OrderID
Yes
4584-87854
Unique order number
OrderIDEncrypted
No
@encrypted@1@039F750 Encrypted order number
B64668D86
TransactionType
Yes
Purchase
Operation type
OrderStatus
Yes
APPROVED or DECLINED
Order status
OrderStatusScr
Yes
APPROVED or DECLINED
Order
status
description
PAN
Yes
455555XXXXXX5487
Masked card number
Brand
Yes
Visa
Payment system
text
MC
AmEx
JCB
Discover
Language
No
COMPASS PLUS
Public, v.1.08e, 25.12.2020.
Copyright © 1998-2020 Compass Plus Ltd.
RU – Russian, EN – Customer
interface
English, UK – Ukrainian, language. Filled with the
etc.
two-letter code of the
interface
language
compliant with RFC 1766.
49
Appendixes
XMLOut Message Parameters
Parameter
Mandatory
Example
Description
PurchaseAmount
Yes
15210
Transaction
amount
(transmitted
by
the
payment plug-in) in the
minimum units of the
transaction currency (RUR
– kopecks, USD – cents,
etc.). For the transaction
adjustment, it is the
adjusted
transaction
amount.
PurchaseAmountScr
Yes
152,10
Transaction
amount
formatted for display to
the customer
Fee
No
100
Fee
amount
in
the
minimum
units
of
transaction currency (RUR
– kopecks, USD – cents,
etc.)
FeeScr
No
1,00
Fee amount formatted for
display to the customer
(RUR – Russian Rouble,
USD – United States
Dollar, etc.)
Currency
Yes
840 – US Dollar
Transaction currency code
643 – Russian Rouble
CurrencyScr
Yes
US
Dollar,
Rouble, etc.
Name
No
John Smith
Customer name
TranDateTime
Yes
15/02/2003 15:37
Transaction date and time
ApprovalCode
Yes
548789
Approval
number)
ApprovalCodeScr
Yes
548789
Approval code
ThreeDSVerificaion and
Yes
Y, N, U, A
Indicator
of
card
verification
using
3D
Secure technology. The
transactions
execution
status
("U"/"A")
is
contained in the PARes
message.
Attention!
The parameter will not
be not present in the
XML message if EMV
3D
Secure
v2
authentication is used.
ThreeDSVerification
Russian Transaction currency text
description
code
(receipt
To ensure compatibility
with v.3.1.20.x and
older
versions,
the
indicator
of
card
verification using 3-D
Secure is retained in
the
ThreeDSVerificaion
and
COMPASS PLUS
Public, v.1.08e, 25.12.2020.
Copyright © 1998-2020 Compass Plus Ltd.
50
Appendixes
XMLOut Message Parameters
Parameter
Mandatory
Example
Description
ThreeDSVerification
parameters.
RezultOperation
Yes
Operation result
Operation execution result
ThreeDSStatus
No
APPROVED or DECLINED
Status
of
verification
using
3D
Secure
technology. It is defined if
verification is required.
Attention!
The
parameter will not be not
present
in
the
XML
message if EMV 3D
Secure v2 authentication
is used.
ResponseCode
No
0402
Transaction
execution
result code. If the system
cannot
establish
connection
to
the
authorization system, the
ResponseCode=001
parameter
value
is
returned.
ResponseDescription
No
Insufficient funds
Description
of
the
authorization decline (in
the customer interface
language). Specified if the
transaction is declined.
Response_g
No
Russia
Text field where the
additional information is
displayed (e.g. account
currency and number,
cardholder country, etc.).
The value is received
from the authorization
system.
AcqFee
No
100
Acquiring fee amount in
the minimum units of
transaction currency (RUR
– kopecks, USD – cents,
etc.)
AcqFeeScr
No
1,00
Acquiring
fee
amount
formatted for display to
the customer (RUR –
Russian Rouble, USD –
United States Dollar, etc.)
MerchantTranID
No
31333435373837393038 Unique
transaction
37343030303030303030 number (generated by
TWEC PG)
OrderDescription
No
Purchase
Order text description
Response_f
Yes
123456
Prepaid code
ShopOrderId
No
87854
Number assigned to the
order by the payment
plug-in
AuthorizationResponse
Yes
1
Authorization
response code
Code
COMPASS PLUS
Public, v.1.08e, 25.12.2020.
Copyright © 1998-2020 Compass Plus Ltd.
host
51
Appendixes
XMLOut Message Parameters
Parameter
Mandatory
Example
Description
TotalAmount
No
150000
Total of the order amount
and the acquiring fee in
the minimum currency
units
TotalAmountScr
No
1500.00
Total of the order amount
and the acquiring fee
formatted for display to
the customer
BankName
No
Bank LLC
Bank name
ShopName
No
Internet Shop LLC
Merchant name
whiteListStatus
No
Y
Merchant status in the
trusted list of merchants
N
E
P
R
U
The document is signed by the Bank certificate (depending on the settings).
Example of the final XML message notifying the shops of the transaction authorization
result:
<Message date="25/01/2017 10:15:58">
<Version>1.0</Version>
<OrderID>5973</OrderID>
<TransactionType>Purchase</TransactionType>
<RRN>713091</RRN>
<PAN>4555XXXXXX1903</PAN>
<PurchaseAmount>5000</PurchaseAmount>
<Fee>100</Fee>
<FeeScr>1,00</FeeScr>
<Currency>840</Currency>
<TranDateTime>25/01/2017 10:15:58</TranDateTime>
<ResponseCode>001</ResponseCode>
<ResponseDescription>Transaction is successful</ResponseDescription>
<Brand>VISA</Brand>
<OrderStatus>APPROVED</OrderStatus>
<ApprovalCode>340623 A</ApprovalCode>
<AcqFee>0</AcqFee>
<AcqFeeScr>0</AcqFeeScr>
<RezultOperation>Operation result</RezultOperation>
<MerchantTranID>3133343537383739303837343030303030303030</MerchantTranID>
<OrderDescription>xxxxxxxx</OrderDescription>
<ApprovalCodeScr>340623</ApprovalCodeScr>
<PurchaseAmountScr>50,00</PurchaseAmountScr>
<CurrencyScr>US Dollar</CurrencyScr>
<OrderStatusScr>Approved</OrderStatusScr>
<ThreeDSVerification>Y</ThreeDSVerification>
<ThreeDSStatus>Approved</ThreeDSStatus>
<Name>John Smith</Name>
<ShopOrderId>40727</ShopOrderId>
<OrderIDEncrypted>@encrypted@1@039F750B64668D86</OrderIDEncrypted>
<AuthorizationResponseCode>1</AuthorizationResponseCode>
<TotalAmount>150000</TotalAmount>
<TotalAmountScr>1500.00</TotalAmountScr>
<BankName>Bank LLC</BankName>
<ShopName>Internet Shop LLC</ShopName>
<whiteListStatus>Y</whiteListStatus>
<CardRegistrationResponse>
COMPASS PLUS
Public, v.1.08e, 25.12.2020.
Copyright © 1998-2020 Compass Plus Ltd.
52
Appendixes
XMLOut Message Parameters
...
</CardRegistrationResponse>
</Message>
Attention! If the facility to add an external card to the authorization system DB (upon
successful completion of the transaction) is used, the CardRegistrationResponse
element will be added to the final XML message:
<CardRegistrationResponse>
<MaskedPAN>123456******3452</MaskedPAN>
<CardUID>9215EA569F97E711842****5056B3006F</CardUID>
<Brand>MC</Brand>
</CardRegistrationResponse>
where:
MaskedPAN – masked number of the payer/transfer sender card
CardUID – payer/transfer sender card ID
Brand – name of the payer/transfer sender card payment system
9.6
TWEC PG Test Server Connection Settings
Connection Parameters
URL addresses at which the test payment gateway can be accessed:
Test Server
URL
Address of the payment gateway page to which the https://pg.compassplus.com:3464/index.j sp
customer is redirected to pay for the order
Address of the payment gateway access point https://pg.compassplus.com:3444/Exec
intended to execute administrative requests by the
client certificate
Address of the payment gateway access point https://pg.compassplus.com:3464/ExecPasswordAuth
intended to execute administrative requests by
password
Test Cards
Card Number
Expiration Date
(YYMM)
CVV2/CVC2
Test Scenario
7777770000000020
1907
729
Card is not enrolled in 3-D
Secure
7777770000000038
1907
475
Card is not enrolled in 3-D
Secure
7777770000000046
1907
158
Insufficient funds to perform
the operation
7777770000000053
1908
423
Insufficient funds to perform
the operation
7777770000000061
1907
843
Available
exceeded
limit
has
been
7777770000000079
1907
357
Available
exceeded
limit
has
been
COMPASS PLUS
Public, v.1.08e, 25.12.2020.
Copyright © 1998-2020 Compass Plus Ltd.
53
Appendixes
TWEC PG Test Server Connection Settings
Card Number
Expiration Date
(YYMM)
CVV2/CVC2
Test Scenario
7777770000000087
1908
135
Authorization
unavailable
host
is
7777770000000095
1907
376
Authorization
unavailable
host
is
7777770000000004
1907
151
Card is enrolled in
Secure,
operation
successful
3-D
is
7777770000000012
1907
409
Card is enrolled in
Secure,
operation
successful
3-D
is
Additional information on test cards:
Card brand is Visa.
Financial approval is not required for the transaction.
CVV2 / CVC2 is not verified.
3-D Secure authentication is required.
Transactions with the "A" (Attempt) status are declined; the order status is set to
DECLINED.
Purchase operation is prohibited if the card is not enrolled in 3-D Secure.
Purchase operation is prohibited if 3-D Secure authentication fails.
Purchase operation is prohibited if no response is received from IPS.
Static authentication by card password is used (password is test).
Test Merchants
Merchants (MerchantID) whose
pg.compassplus.com:3444/Exec:
requests
should
be
posted
to
https://
test
test1
test2
test3
test4
Attention! If a request is transmitted to the Exec access point, the merchant is
authenticated by the client certificate. Certificates for merchants and keys to them are
available at https://compassplus.com/solutions/plug-play/processing-hub/tranzwarepayment-gateway-payment-module-integration-guide.
COMPASS PLUS
Public, v.1.08e, 25.12.2020.
Copyright © 1998-2020 Compass Plus Ltd.
54
Appendixes
TWEC PG Test Server Connection Settings
Merchants (MerchantID) whose requests
pg.compassplus.com:3464/ExecPasswordAuth:
should
be
posted
to
https://
test5
test6
test7
test8
test9
Attention! If a request is transmitted to the ExecPasswordAuth access point, the
merchant is authenticated by the password 12345.
9.7
Recommendations on Generating Encrypted
Payment Data
To ensure correct transfer of encrypted payment data to TWEC PG via the payment /
transfer page (index.j sp), transfer service (transferindexnew.j sp), service of adding a
card to the TWO DB (cardregistrationindex.j sp) or in administrative operations,
encrypted payment data must be generated according to the rules described below.
The data must be transferred in the following fields in the JSON format:
amount – transaction amount in the minimum units of the transaction currency. The
field can be used only when transferring data in administrative operations or via the
transfer service page (transferindexnew.j sp).
currency – transaction currency code. The field can be used only when transferring
data
in
administrative
operations
or
via
the
transfer
service
page
(transferindexnew.j sp).
eci – TWEC indicator code (e field of the TPTP protocol). The field can be used only
when transferring data in administrative operations.
sender object:
o pan – payer / transfer sender card number
o reference – payer / transfer sender card ID (cardUID)
o expDate – card expiration date
o name – cardholder name
o cryptogram – cryptogram generated by ACS and providing a method of verifying
the 3-D Secure authentication integrity and its result during the authorization
procedure. The field can be used only when transferring data in administrative
operations.
o code – card verification code
receiver object:
o pan – payment / transfer recipient card number
o reference – recipient card ID (cardUID)
COMPASS PLUS
Public, v.1.08e, 25.12.2020.
Copyright © 1998-2020 Compass Plus Ltd.
55
Appendixes
Recommendations on Generating Encrypted Payment
Data
Example of the JSON-formatted object populated with the fields listed above:
{
"amount": "100000",
"currency": "643",
"eci": "82",
"sender": {
"pan": "1111000000000003",
"reference": "uid1000",
"expDate": "2205",
"name": "CARDHOLDER NAME",
"cryptogram": "D08FABD095C2B73D",
"code": "845"
},
"receiver": {
"pan": "2220000000000001",
"reference": "uid1001"
}
}
To generate the encrypted data, the merchant generates the secret AES key that will be
used to encrypt the JWE object with the payment data corresponding to the JSON object.
Next, the AES key is encrypted using the public key from the certificate received from
the processing centre (TWEC PG).
The encrypted AES key should be added to the encrypted_key header of the JWS object
whose payment data contains the serialized-to-string JWE object with encrypted data.
Next, the merchant signs the JWS object with the RSA key.
Example of the encrypted data generation in Java using the nimbus-jose library:
Security.addProvider(new BouncyCastleProvider());
AsymmetricCryptography cryptography = new AsymmetricCryptography();
String keystorePath = "c:\\keys\\emv\\acs\\merchant.jks";
char[] keystorePassword = "123456".toCharArray();
String keyAlias = "merch";
char[] keyPassword = "123456".toCharArray();
String rootAlias = "root";
Path path = Paths.get(keystorePath);
KeyStore keyStore;
try (FileInputStream is = new FileInputStream(path.toFile())) {
keyStore = KeyStore.getInstance(KeyStore.getDefaultType());
keyStore.load(is, keystorePassword);
}
KeyPairWithCertificates keyPair = KeystoreUtils.loadKeystore(keystorePath, keystorePassword, keyAlias,
keyPassword, rootAlias, null);
TransactionData data = new TransactionData();
data.setAmount("233");
data.setCurrency("810");
data.setEci("86");
SenderData sData = new SenderData();
sData.setPan("5777773124760440");
sData.setExpDate("2011");
sData.setCode("141");
sData.setName("CARDHOLDER NAME");
data.setSender(sData);
ReceiverData rData = new ReceiverData();
rData.setPan("577777795792544");
rData.setPhone("1234567890");
rData.setEmail("test@test.ru");
data.setReceiver(rData);
ObjectMapper objectMapper = new ObjectMapper();
String json = objectMapper.writeValueAsString(data);
System.out.println(json);
COMPASS PLUS
Public, v.1.08e, 25.12.2020.
Copyright © 1998-2020 Compass Plus Ltd.
56
Appendixes
Recommendations on Generating Encrypted Payment
Data
int keyBitLength = EncryptionMethod.A128GCM.cekBitLength();
KeyGenerator keyGenerator = KeyGenerator.getInstance("AES");
keyGenerator.init(keyBitLength);
SecretKey key = keyGenerator.generateKey();
// 1. Encrypt
SecureRandom random = new SecureRandom();
byte[] bytes = new byte[16];
random.nextBytes(bytes);
Base64URL iv = Base64URL.encode(bytes);
JWEHeader header = new JWEHeader.Builder(JWEAlgorithm.DIR, EncryptionMethod.A128GCM)
.customParam("spccty", "PP")
.customParam("encrypted_key", cryptography.encryptText(
Base64.getEncoder().encodeToString(key.getEncoded()),
keyPair.getKeyPair().getPublic()
))
.iv(iv)
.build();
Payload payload = new Payload(json);
JWEObject jweObject = new JWEObject(header, payload);
jweObject.encrypt(new DirectEncrypter(key));
// 2. Sign
JWSSigner signer = new RSASSASigner(keyPair.getKeyPair().getPrivate());
List<Base64> chain = new ArrayList();
chain.add(Base64.encode(keyPair.getCertificate().getEncoded()));
if (keyPair.getIntermediateCertificate() != null) {
chain.add(Base64.encode(keyPair.getIntermediateCertificate().getEncoded()));
}
if (keyPair.getRootCertificate() != null) {
chain.add(Base64.encode(keyPair.getRootCertificate().getEncoded()));
}
JWSObject jwsObject = new JWSObject((new
com.nimbusds.jose.JWSHeader.Builder(JWSAlgorithm.PS256)).x509CertChain(chain).build(), new
Payload(jweObject.serialize()));
jwsObject.sign(signer);
Example of the received payment data:
eyJ4NWMiOlsiTUlJRmhUQ0NBMjJnQXdJQkFnSUdBV1ZDRVNpTk1BMEdDU3FHU0liM0RRRUJDd1VBTUh3eEN6QU
pCZ05WQkFZVEFrNU1NU2t3SndZRFZRUUtEQ0JWVENCVWNtRnVjMkZqZEdsdmJpQlRaV04xY21sMGVTQmthWF
pwYzJsdmJqRWdNQjRHQTFVRUN3d1hWVXdnVkZNZ00wUXRVMlZqZFhKbElGSlBUMVFnUTBFeElEQWVCZ05WQ
kFNTUYxVk1JRlJUSURORUxWTmxZM1Z5WlNCU1QwOVVJRU5CTUI0WERURTRNRGd4TmpBNU1qa3dOVm9YRF
RFNU1EZ3hOakE1TWprd05Wb3dlREVMTUFrR0ExVUVCaE1DVWxVeEZEQVNCZ05WQkFnTUMwTm9aV3g1WVdK
cGJuTnJNUlV3RXdZRFZRUUhEQXhOWVdkdWFYUnZaMjl5YzJzeEZUQVRCZ05WQkFvTURFTnZiWEJoYzNNZ1VHe
DFjekVNTUFvR0ExVUVDd3dEU1VGRU1SY3dGUVlEVlFRRERBNDVNUzR5TWpjdU1qUTBMakl3TXpDQ0FTSXdEUVl
KS29aSWh2Y05BUUVCQlFBRGdnRVBBRENDQVFvQ2dnRUJBTCtFcjdWckFwWDdzZnl3MHNZc0I2cjhjR2tcL2piaH
FlenROaDQ5UUphRmM1dWV6a3F4Z1NVNlZ3R2tpamFFTldrRzl2RXY3MGxsTGh3K1liTDgySmZXNURmZWF3bnN
RbjMyV0hkVUtvejJiQktZM2RoQUVaK2JzalJlVXdEaksxdlk1MG9KVHFhZyt4UkpFV2dKNVwvS2RiMVdsTUFRczZ5V
Et2TTJKVGxSRHpWZzNsbG5MUlNURm1kbkZlYTdSdFFwKzFYdXhnRFN4OGxiM1FTWUt6a1l2SXpGV1pMaXhNMk
5BNzdyQkZ1dzREa2NKVEwwT3JCbjY5WUxUS1hkR1NNbVVqSTlQMGYwb2d3b1NJVk9EclFKdTkwOHJ3ZXBGK3F
HQ3NSMVZiOUZNUWdlMnhaVDNBbnJFZjBLYkNEbUo2RG16WWtFUlh0WTRUaTlpc2dzdE8ydFVDQXdFQUFhT0NB
UTh3Z2dFTE1JR3ZCZ05WSFNNRWdhY3dnYVNBRkpoMmE0YUxnbXpBWURPYkFJZ3g3OUx3RzN2eW9ZR0FwSD
R3ZkRFTE1Ba0dBMVVFQmhNQ1Rrd3hLVEFuQmdOVkJBb01JRlZNSUZSeVlXNXpZV04wYVc5dUlGTmxZM1Z5YV
hSNUlHUnBkbWx6YVc5dU1TQXdIZ1lEVlFRTERCZFZUQ0JVVXlBelJDMVRaV04xY21VZ1VrOVBWQ0JEUVRFZ01C
NEdBMVVFQXd3WFZVd2dWRk1nTTBRdFUyVmpkWEpsSUZKUFQxUWdRMEdDQ1FDVEw3M3JJNWc4b1RBZEJnTl
ZIUTRFRmdRVXBcL3ZTV1c1VTUwWE5GVnpnbjhoY3RjV3FncXd3Q1FZRFZSMFRCQUl3QURBT0JnTlZIUThCQWY
4RUJBTUNCZUF3SFFZRFZSMGxCQll3RkFZSUt3WUJCUVVIQXdFR0NDc0dBUVVGQndNQ01BMEdDU3FHU0liM0R
RRUJDd1VBQTRJQ0FRQlFKajFTNFwvckxEKzJyRmROK3BhcVluRTFQNUIyXC82clVnOXhGXC9MdFZ1dGYrVFA3O
G1xOEUxTHFsYlNqbDVlNWhaZHd4MkZmTWZyUDFZRDNmbnAyaXRCRkhjWWh4Yk5CMlFmejVYWmNWUjhVZXY
1VUp3SnZKdlBvQkVyWDU0cWtkNmUxdE5KUTVXQzRvc1wvZ3E3STZxZ2Zuc3JFQlhzUlBrRTVEODduZ090ZVJyQ
UR1VU84WncrSjErQzRqdEN2WlJSQXdOUXV1bE5xcGcyaVFsaFlvdFZGYTRyeXdKUXNicFRZcUpsS2NSVHZmdDIx
Z1V2RnFcL0g3SWM3elVkNU5oZFwvMVwvOVJvWFpDSTVENkNTRHF5aVducVFoUnhNcHBobVJ3VnUrOUN6all1S
1lIZGxcLzV5OFRnYWlPakI4bUtTckpaSDltSXB1XC9JVnRnVU0rR042RGVxQXdMZHFpS2R4QWM3U3cwSWhqNEh
ZYzlzTVF2RzlpNDFINGR2MnV2WXVobjJmRnpVa1dxXC9RQWZLRUdNdUQ4bGdFeEhJQTQ0NjBMaHFROFJFUzhqc
2l0TXZkK0N0MFZSaFBZbVlJRDBMTDh3Z3doMGVcL05WM3Q2TTA2NlptVWdONFNRbkFBSEpJYjl3b0t1RmtkclhH
cXdWaXJaejllS1dpNXhMMDU1MHdUa3NiUmRRU2JDUHlFMEpodFhkVFBSRzBhc3JRMDhFYmkwVmlTK2lrbm8yV1
BYWHFyWW5HbFhpME1BYzFyM2pQSlwvOThQNzVGVWZGUmg4NzNTUkxhNjN3M1B0RWJQVDhvekJSVld3XC9s
COMPASS PLUS
Public, v.1.08e, 25.12.2020.
Copyright © 1998-2020 Compass Plus Ltd.
57
Appendixes
Recommendations on Generating Encrypted Payment
Data
WDZUaVJNeGpNMHpLSjFPYnhINjN6aUJSMnIrN0p2MVRPc3RKd0d4UXFmNFY1MURWSHd2SDM4VUtVamxUNlJr
YVFBU1VsUT09IiwiTUlJRjNqQ0NBOGFnQXdJQkFnSUpBSk12dmVzam1EeWhNQTBHQ1NxR1NJYjNEUUVCQ3dVQ
U1Id3hDekFKQmdOVkJBWVRBazVNTVNrd0p3WURWUVFLRENCVlRDQlVjbUZ1YzJGamRHbHZiaUJUWldOMWNtb
DBlU0JrYVhacGMybHZiakVnTUI0R0ExVUVDd3dYVlV3Z1ZGTWdNMFF0VTJWamRYSmxJRkpQVDFRZ1EwRXhJRE
FlQmdOVkJBTU1GMVZNSUZSVElETkVMVk5sWTNWeVpTQlNUMDlVSUVOQk1CNFhEVEUyTVRJeU1ERXpOVEF3Tl
ZvWERUTTJNVEl4TlRFek5UQXdOVm93ZkRFTE1Ba0dBMVVFQmhNQ1Rrd3hLVEFuQmdOVkJBb01JRlZNSUZSeVl
XNXpZV04wYVc5dUlGTmxZM1Z5YVhSNUlHUnBkbWx6YVc5dU1TQXdIZ1lEVlFRTERCZFZUQ0JVVXlBelJDMVRaV
04xY21VZ1VrOVBWQ0JEUVRFZ01CNEdBMVVFQXd3WFZVd2dWRk1nTTBRdFUyVmpkWEpsSUZKUFQxUWdRME
V3Z2dJaU1BMEdDU3FHU0liM0RRRUJBUVVBQTRJQ0R3QXdnZ0lLQW9JQ0FRREVmWTJ4dUxOak04XC8zeHJHNn
pkN0ZidVhIZkNGaWVCRVJSdUdRU0xZTW1FUzVraGdqWnRlTjU5TmVvRGJJdTNYTkZDbTRUUjJUVHBUZGptU0Z
VOGVEMUUzK0NYVzlNNlFjekNvVHU1T1poK2g2eU9ZVE1Fa3Qrd0RmM0MwaFplXC83amp5MlBvZGlISGZ1ZTBTU
1pJSlE1Vm00c1VrbUVEYkRiY1NkUmxGbXhVZTJheVgzdGxZeXh6bWVoWlNHUThqbVZoblcwWFdnMzZtUUpOc3Z
YMm5MbkJCNThFRTJHdEdkWDlibktkWE5mWlRBUFNyZFNPblhNUDk3R2grUnAxdWQzWUFuY0tPNFJPemlOU1dq
ekRvYTBPZnduYUpXc3gySTZkYldCUFM1UUhRWnRuXC93MGlIYXlwWG9UTWVaVWpJVlNyS0h4MFpBSHIzdjZwV
Ug2b3krUTlCOTM5RWxPZmxPcmFGeWRhbFBrMzNpK3R4QjZCenlMd2xzREdaYWVJbTRKYmxycWx4MFF5elFaXC
9UMGJhZmJmbG1Gem9kbDZadkFnU0Q0T25QbzVBUTdEbDRFOVhpSWE4NWwwamxiNzFzK1h5XC85cE5CdnNw
ZDNLSFR0MGJcL0o1ajdzelJrT2J0bmlrckZzRXU1NUhjUjloejVmRW9mb3ZjYmtMQkx2TkNMY1pyem1pREpoTDZX
c3JwbzA3VW1ZXC85VFwvREJtak5PVGlES2szY3lcL045c1BqV2VvYXV5Q2Zmc242eUxuTkxaNGhzRCtIN3ZDcG9Q
TXh5RnhKYU5PYXd2MDhaRisxN3JxQ2N1UnBmUFU2VVdMTkNtQ0ExZlNNWWJjdE8yOFN0UzJvNmFjV0YzbllkcW
duVlpDZzBcL0gyTTNiNVRPZVZtQXVDUVdEVkFjb3hnUUlEQVFBQm8yTXdZVEFkQmdOVkhRNEVGZ1FVbUhacmh
vdUNiTUJnTTVzQWlESHYwdkFiZVwvSXdId1lEVlIwakJCZ3dGb0FVbUhacmhvdUNiTUJnTTVzQWlESHYwdkFiZVwv
SXdEd1lEVlIwVEFRSFwvQkFVd0F3RUJcL3pBT0JnTlZIUThCQWY4RUJBTUNBWVl3RFFZSktvWklodmNOQVFFTEJR
QURnZ0lCQUtSczVWb2VieHU0eXpUTUljMm5id3NveGUwWmRBaVJVNDRBbjNqNGd6d3VxQ2ljODBLNFlsb2lET0l
BZlJXRzdIYkYxYkczN29TZlFCaFIwWDJ6dkhcL1I4QlZsU2ZhcW92cjc4ckdPeWVqTkFzdGZHcG1JYVlUMHp1RTJqd
mplUitZS21GQ29ybmhCb2ptQUx6WU5RQmJGcExVQzQ1SGU4ejVnQjJqc252N2wwSFJzWEpHTjExYVVRdkpnd2p
RVGJjNEZiQW5XSVd2QUtjVXR5ZVdpQ0J2RndcL0ZUeDIzWldNVVc4ak1yamR5aVJhbjdkWGM2bjV2RFwvRFYzdH
VNNXJNV0VBNXgwN0Q5N0RWXC93dnNcL004SThETDZtSTJ0RVBmd1ZmXC9RSVc0VU9OcG5sQWg2aTlEZXZCK
3NLcnFyaWxYRTkxcFBPQ21CWFlYQnhiQVBXOE0zR2g3azJWVldcL2pMNGtxb0I0SGZIMElESHFJVmVTWGlyU0h4
b3ZLXC9mR0lxakV1ZWRMV3pNTUtUY0VjWWk3TFZTcUZ2RllWXC9raGltdW1BbDhTRlZwSFFzUTdMdnNLaW0xQ
3N1cGtPK2ZVYjQ0ZGthVXVtNlFDXC9pSW5rNzhLUmdHVjhYWkEyNXl3NHdcL0ZKYVdlazBqbnVDSms3Vis3N042
UEdLMEZ4bVNkckhSTnpOU29Ua21hNFB0WklUbkdOVEdxWGVUVjBIdnI4Q2xiUWZCV3BxYVp0S0I4ZFRraFJDVF
VQYXNZWlpMRnRqMlkyV2NYc2hNQkFoRW5CaUNzb2FJR3oxeHhjeUZINElvaUMyR0tiZmk1cGpYckhmUnJ0UElyM
UI0XC91V01IeEl0dEVGSzNxS1wvM1ZjMWJqZFg2SDRJVVdOVjYyUDUya3dkc01YTm9RNTVqdyJdLCJhbGciOiJQU
zI1NiJ9.ZXlKbGJtTWlPaUpCTVRJNFIwTk5JaXdpYzNCalkzUjVJam9pVUZBaUxDSmhiR2NpT2lKa2FYSWlMQ0pwZG
lJNklsbE1VRGN4UmxGWVJFTmFXVFZXT1VkNlVWbE9UMUVpTENKbGJtTnllWEIwWldSZmEyVjVJam9pUTBKMk1V
SnFibUYwWTB4eE4zWTNSR0pNT0hKSVFtYzVOWEkwTjFoeWIxWk1NV1ZTYW5KeFVXNWlPRmhjTDFGSVlUZHdT
RE54WVRKWk1WZGhkR1Y0UjJsVlpXRm9hVFZSZVhod1prVklUVmxrTXprck1VZFNVRXA1WjA1UU9XVjNiMnQzV
UZ3dlRsaHFSWE52TkZOU1VUQlBaa2wyVkc1Vk1FZEdUMUZ2UVZ3dmFtczBWRU5JTW5wNFN6UkNha3BDUTBwc
VNrRjJOMjFHYjNoWVdWbHdWakp5VTBwSE9GSTJOR3B6ZVRoRE4wZGFXaXRFYlRobk0wcFlPVnd2TjBkS1RYUTB
ibVJtWkdwRVpFMHhSMk5QVDJwM1ZYTXhTM1ZLWWxkcVNtTTBNemhzZFdwdlEwaFZXa0pCVEVaWFQzSTVXVU
5XUm1ab2RuTktibEJIVnl0cE4wMDFjbGxtTUhCWUsxVnRkV0kxVEhWb056RjJTV0pYYkRsdlUwSnllRzFrZFRWck9
UaERRMHB3UnpWbFkxaHNkekZNZFV4T2RWd3ZjRVpDYVhoclhDOUhSa0owYmxBd2VWVklUM1J3VDJkdk1uTXlR
bUpPWTJWM2JGQlJQVDBpZlEuLlduSzBaZkRDRWNwUzRSeVAuRXRtN1RZeThkaGdpVVdQUE53OTlEbEJaX01FS1
NJV3BKaTIyYWxfSXZ6QUU0bzlWcUFvN1RzNUh3ZnczN3N3Wi04eHFXNE9jdHY1WlU1SGtwczVKdFp6R3haZEp4R
UJuZWVWNEVzb2x2V0JJcU1XeUk2UTgxeklVNEJaR0I5UkxRUHk5ZWt3YUMtbjZFN3d1STlGU0hva0lOdGJhUEtQd
Vd3clhFZk9GRDNhbXNJWHdrQi1ad2pBNWJsOFV3S0ZCSS1BdUJSbWxwc1hrYUFrcHZrQmtqX2doY0ROOWc1RF
pXRUprUm1pQ0dDV1ROTEd0VTNlY2lEZVFFVjBfc0d2T0t2S0UwYk9JYXBnSjR1UDBiaFlHR2JCRDFKeXRuMUNMLk
JwTC12WTE1OTBPMDhxUEdEcnBqOGc.nEgfQKXyS9N_CVQd2LQix5pQu0S8wMbF5n8OU_e88bfoyhdqQhKLQCjr
ma39oc18ticP9zOSg8XxBkbKOKnoq3e55jhEqbA8Uu5Tio240Ikx_q1VxHIcGjEvmCgVwMvWtCA79mjlofhn78ZBW8DQzK8IqiKR6f8-K6-hmKjWpPY35JCYePEUYxdJvgN2PyxyGiRd9key4QOKyUfgP2G_4nISpxcVugPCPuzbgO8EpR3guvPiH8ccTMXmqpUB9hEoaZu_aNStT2ZGVNBqn
g9pGMbnbzyNV3TNMKj8BtPuI0rJ8PK3YfE-A8XMwqukZcJyP-DhPhMGSqvz5JfXLyg
COMPASS PLUS
Public, v.1.08e, 25.12.2020.
Copyright © 1998-2020 Compass Plus Ltd.
58