UNLIMITED

THE USE OF
BANKART’S
PAYMENT GATEWAY
– INSTRUCTIONS
FOR MERCHANTS

Jun 2023

1
 UNLIMITED

Table of contents
1. GLOSSARY ........................................................................................................................................ 3
2. INTRODUCTION ................................................................................................................................ 4
2.1. Online transaction flow .........................................................................................................................4
3. TECHNICAL INTEGRATION OF THE CARD PAYMENT METHOD (INSTRUCTIONS FOR DEVELOPERS)........ 6
3.1. Main steps in the implementation of support ......................................................................................6
3.2. Technical documentation and requirements ........................................................................................6
3.3. Merchant-side transaction processing support ....................................................................................6
3.4. Obtaining card details from the customer ............................................................................................7
3.4.1. Designing a payment page with an input mask .............................................................................7
3.4.2. Custom payment page ...................................................................................................................7
3.5. Types of transactions supported on Payment Gateway .......................................................................8
3.5.1. Basic types of transactions supported: ..........................................................................................8
3.5.2. Types of supported transactions with card-storing capability .......................................................9
3.5.3. Card storing ................................................................................................................................. 10
3.6. Support for online instalment payments ........................................................................................... 18
4. TESTING GUIDELINES ...................................................................................................................... 20
4.1. Basic information ............................................................................................................................... 20
4.2. Obtaining data for connection to Payment Gateway ........................................................................ 20
4.3. Test cards ........................................................................................................................................... 23
4.4. Testing with the simulation connector .............................................................................................. 23
4.5. Transition to a production environment ............................................................................................ 25
5. BANKART PAYMENT GATEWAY: USER INTERFACE OVERVIEW .......................................................... 26
5.2.1. Reviewing the details (logs) of each transaction ......................................................................... 28
5.2.2. Captures and voids of transactions ............................................................................................. 28
5.2.3. Refund of the amount of transactions ........................................................................................ 29
5.2.4. Exporting the list of executed transactions ................................................................................. 30

2
 UNLIMITED

1. GLOSSARY
Authentication (3DS): The process of verifying a user's identity to ensure that the user has the right
to carry out a transaction.
Authorization: The process of verifying card details, limits and whether the customer has sufficient
funds in their bank account to make the purchase they wish to make, etc. This process generally
occurs after authentication has been successfully completed, but in certain exceptions even without
successful authentication.
Payment Gateway: A system that enables or simplifies the acceptance of card payments or instant
payments (Flik, etc.) to merchants. It is a system that connects websites (stores) with issuers and
acquirers of payment methods. Payment Gateway also provides a connection to the customer
authentication systems. In addition, Payment Gateway has a web interface to facilitate the review of
transactions made.
Access Control Server (ACS): A system used by the card-issuing banks for authentication of
cardholders using several different methods.

3
 UNLIMITED

2. INTRODUCTION
This document is intended for merchants who use Bankart's Payment Gateway to accept card
payments. The document provides the information necessary for the integration of Payment
Gateway, in addition to general information on card transactions and testing instructions.

2.1. Online transaction flow

Below is a schematic diagram of an indicative online transaction flow, with a description of each step of
the online transaction underneath for clarity.

Figure 1: Online transaction flow

Online transaction flow steps:

1. A customer browses an online shop looking for products:
a. adds products to the basket;
b. selects a payment method, which in this case is a payment card, and confirms the
purchase;
c. the merchant makes an API call to Bankart's Payment Gateway and an input mask
appears to enter the customer's card details.
2. After entering the card details, their authenticity is verified (Card Enrollment):
a. Payment Gateway connects to the card scheme to obtain data about the card, the
version of the 3DS protocol and data on whether the card is even included in the
3DS system;
b. the card scheme forwards the data back to Payment Gateway.
3. Payment Gateway connects to the payment authentication system:
a. if the transaction is a transaction for which strong customer authentication is not
required, the transaction is executed without strong customer authentication;
b. if strong authentication is required, the ACS sends an authentication request to the

4
 UNLIMITED
customer's payment confirmation app (usually in the form of a push notification) or
a unique password (OTP) is sent to the phone number;
c. the customer performs authentication;
d. the authentication system transmits the authentication result information to the ACS
system;
e. The ACS forwards the authentication result information to Payment Gateway.
4. In the next step, the authorization process starts:
a. Payment Gateway sends an authorization request to the card scheme;
b. the latter forwards the request to the customer's bank, where the purchase is authorized;
c. the customer's bank returns the response to the card scheme, and at the same time
the process is initiated for sending a security text message (if the service is activated)
and an instalment text message (if it is an instalment purchase) to the customer;
d. the card scheme returns a response to Payment Gateway.
5. Payment Gateway calls the URL to display the transaction success screen:
a. Payment Gateway returns the transaction result to the merchant;
b. the merchant acknowledges the receipt of the result;
c. the customer is presented with the transaction success/failure screen.

5
 UNLIMITED

3. TECHNICAL INTEGRATION OF THE CARD PAYMENT

METHOD (INSTRUCTIONS FOR DEVELOPERS)
3.1. Main steps in the implementation of support
1. Signing a contract between the merchant and the bank;
2. Transmission of data from the bank to Bankart, where the merchant is entered into the
online business support system;
3. Forwarding of the data for the purposes of implementing support to the merchant's contact
mobile phone number and email address (passwords for access to the Payment Gateway
portal and API/WEB connection of the user);
4. Merchant's developers perform integration with Payment Gateway;
5. Performance of tests covering the agreed scope of business operations (authorization,
capture, void, instalments, correct display of notifications when a transaction is authorized
and declined, etc.);
6. The bank registers the merchant via MasterCard Connect in the EMV 3D Secure system. No
registration is required in the case of Visa, as the data is already automatically sent to the
Bankart systems upon login;
7. The merchant notifies Bankart of the successful completion of the tests, Bankart further verifies the
results in terms of
process centre support;
8. Forwarding the data for accessing the production environment to the merchant.

3.2. Technical documentation and requirements

General documentation on Payment Gateway is available at:
https://gateway.bankart.si/documentation/gateway
API documentation on connecting and integration is available at:
https://gateway.bankart.si/documentation/apiv3?php#transaction-api-v3-0 (JSON)

All API calls must contain a signature that is generated based on the content sent and the secret
shared. Callbacks are also signed so you can verify the authenticity of the received content. API calls
can be modified on the Payment Gateway side in some of the optional fields. Merchant-side support
must be done in such a way that the change does not affect the functioning.

Sample code in programming languages PHP, Java, C# (.NET Framework) and plugins for the latest
versions of WooCommerce and Wordpress (v4 and v5), Prestashop (v1.7 – previous versions are not
supported), Magento (v2) and Opencart (v3 – v2 is not supported) platforms is available at: link.

3.3. Merchant-side transaction processing support

SSL communication is used for communication between the merchant's website and Payment
Gateway. For this purpose, the merchant must obtain a suitable, generally supported server
certificate on their side.

IMPORTANT: the merchant or their IT support must ensure that the server certificate is replaced on
time before expiry, as proper support is not possible without a valid certificate. Monitoring

6
 UNLIMITED
production after the change is made on the side of the merchant is required. If the merchant does
not obtain the same processing results at the time of monitoring as before the change was made, the
merchant should revert their system to the previous state and inform Bankart
([email protected]).

3.4. Obtaining card details from the customer

Payment Gateway supports different ways of retrieving card details from the customer. The
merchant can use a pre-prepared payment page with an input mask or integrate it into their own
website. It is also possible to store payment card data, whereby sensitive card data is stored on the
Payment Gateway site and the merchant handles only the token of the individual card. A more
detailed description is given below.
For the authentication and authorization process of the transaction, the customer's details listed
below are important and are obtained by the merchant from the user account or upon entering
contact details before entering the card details. It is recommended that the merchant verifies
whether the customer has entered the details in the correct format, as this makes the transaction
more likely to be successful.
Name of field Description
billAddrCity Place of residence.
Format: variable length, 50 characters maximum
billAddrCountry Country of residence.
Format: 3 characters maximum, JSON Data Type: String, necessary to fill in with a
numerical 3-digit code according to the ISO 3166-1 standard (exceptions are provided in
Table A.5 in the EMV 3DS specification)
billAddrLine1 Address.
Format: variable length, 50 characters maximum, Data Type: String
billAddrPostCode Postal code of residence.
Format: variable length, 16 characters maximum, Data Type: String
email Email address of the payer.
Format: variable length, 254 characters maximum, necessary to fill in with data meeting the
requirements provided in the table in Section 3.4 of document IETF RFC 5322.
cardholderName Name of the cardholder.
Format: variable length, 2–45 characters (verified by Bankart)

3.4.1. Designing a payment page with an input mask

We can add the merchant's logo to the Hosted Payment Page (HPP), which displays an input mask
for the card details and is displayed in case of a redirect from the merchant's page. This should be
submitted by the merchant in .png format to [email protected] prior to inclusion in the
production. The maximum image size is 500px x 130px. Please contact your bank for logos of the
payment schemes involved.
Currently, the HPP site can be displayed in 19 different languages. These languages are Slovenian,
English, German, Italian, Bulgarian, Bosnian, Czech, Slovak, Spanish, Croatian, Hungarian,
Montenegrin, Macedonian, Polish, Romanian, Russian, Albanian, Serbian and Turkish. For additional
language options, please contact your bank.

3.4.2. Custom payment page

For merchants who want a customized payment page, we suggest the payment.js integration,
which is described in the API documentation freely available to developers on the website:
https://bankart.paymentsandbox.cloud/documentation/gateway#payment-js-javascript-
integration.

7
 UNLIMITED
3.5. Types of transactions supported on Payment Gateway

3.5.1. Basic types of transactions supported:

- DEBIT (normal online purchase):
This type of one-step transaction is typically used by merchants selling digital goods, tickets
and other items that are available to customers immediately after payment is completed.
The merchant cannot void these (final) authorizations of amounts that are marked to be
included in the end-of-day clearing and settlement processing.
- REFUND (money back for online purchases):
If a merchant wants to make a refund due to customer dissatisfaction or other issues, they
must initiate this type of transaction. Refund transactions must always have a reference to a
financial transaction (debit, capture) and must not exceed the amount of the original
transaction.

DEBIT + REFUND scheme:

Figure 2: Display of the DEBIT+REFUND flow

- PREAUTHORIZE + CAPTURE and VOID + REFUND:

A merchant selling physical goods may first want to check their stock before confirming
payment. If the merchant finds that they cannot fulfil the order, they can cancel the
authorization and release the reserved funds in the cardholder's account (perform a VOID).
This is why we call it a two-step transaction.
The transaction is thus split into two parts, the (pre)authorization and the subsequent
CAPTURE command, which indicates that the transaction should be included in the end-of-
day clearing and settlement processing. The capture should be done within one week
(depending on the card scheme) to avoid a higher risk of chargebacks. Once a transaction has
been captured, it cannot be voided, but a REFUND (money back) can be made.

PREAUTHORIZE + CAPTURE/VOID + REFUND scheme:

8
 UNLIMITED

Figure 3: Display of the PREAUTH+VOID/CAPTURE flow

3.5.2. Types of supported transactions with card-storing capability

These transaction types allow merchants to reuse card details for future transactions (COF or Card
on File) without requiring the cardholder to re-enter the card number and expiry date. Both
transactions are initiated by the cardholder, with the cardholder performing strong authentication
upon data entry. The merchant must first sign a contract with the bank, by means of which the bank
enables them to carry out transactions with the stored card in the first place. Only once the legal
formalities are in place can the merchant mark, test and offer transactions with a stored card.
- CARDHOLDER INITIATED TRANSACTIONS (CIT):
The merchant offers the cardholder the option of payment with the stored card. The
merchant receives a masked PAN in the original transaction when the card was stored and
can use it to display and offer the stored payment credentials to the cardholder.
These transactions are the same as normal transactions, except that in subsequent
transactions the cardholder does not manually enter the card number but retrieves it from
the secure storage system. The cardholder is prompted for authentication via EMV 3DS for
the initial transaction, as for any other online purchase.
- MERCHANT INITIATED TRANSACTIONS (MIT):
In the context of e-commerce, RECURRING transactions are meant as, e.g. periodic charges
for magazine subscriptions. In recurring transactions, the amount is the same each time.
Another type of MIT transaction is the UNSCHEDULED Card on File (COF) transaction, which
means non-periodic payments that are made with a variable amount by default, unless the
merchant sends an additional indicator in the message to request the same amount.

Figure 4: Scheme of division of recurring payments

9
 UNLIMITED

3.5.3. Card storing

A card can be stored in a number of ways:
- REGISTER (storing a card without a purchase):
The customer enters the card details at the online store, which offers the option to store the
card. First, the customer is authenticated and then a request for confirmation of the card
activity is sent to the card issuer. After confirmation, a reference of this transaction is stored
for further use of the card.
- DEBIT with the “withRegister” flag (normal online purchase with an additional indicator):
A classic online purchase, where the customer chooses to save the card for future purchases
at the time of payment. The customer has to authenticate themselves and the card details
are stored in Bankart's Payment Gateway, as is the reference to this first transaction.
- PREAUTHORIZE with the “withRegister” flag (preauthorization with an additional
indicator): A merchant selling physical goods may first want to check stock before confirming
payment. When entering the card details, the customer also selects the option to save the
selected card for future purchases. The customer has to authenticate themselves and the
card details and the reference to the first transaction are stored in Bankart’s Payment
Gateway.
- DEREGISTER (removal of a stored card)
This transaction can be executed by either the merchant or the customer. This type of
transaction removes a card already stored with a merchant. The customer can remove the
card if they no longer wish to use the card at the merchant, and the merchant can remove
the card if the customer stores a new card without deleting the old card that they no longer
use. The merchant is responsible for deleting all card data that is no longer needed (also in
the event of the business ceasing its activities). In order to perform this transaction, a
reference to the first transaction in the series must be sent within the API call (the UUID
reference field mentioned in the next subsection).

The following shows how the different types of transactions that have the possibility of storing a card
(CoF, MiT and recurring) should be indicated. Tables indicating the main indicators are enclosed, as
well as examples of JSON calls.

3.5.3.1. Indicating CoF (Card on File) transactions:

10
 UNLIMITED

Figure 5: Table with indicators for CoF transactions

Within CoF transactions, there are 3 types of possible implementations of these transactions:
- Initial, where the amount equals 0:
It is a customer-initiated transaction (CIT) where card details have to be entered.
o In the “transaction Type” field, the transaction should be marked as REGISTER, which
will only save the card. Alternatively, PREAUTHORIZE can be selected, where the
indicators then differ from the REGISTER transaction.
o In the case of a REGISTER transaction, the “withRegister” field is empty. In the case
of a PREAUTHORIZE transaction, the value in the “withRegister” field is TRUE.
o The field “authenticationIndicator” is set to 04 in the case of a PREAUTHORIZE
transaction. In the case of a REGISTER transaction, the field is left empty. The value
of “04” means that the card is only added, without setting up a recurring/MIT series.
o The field “challengeIndicator” is populated with the value “04”, which means that
strong authentication (SCA) is required by the card schemes for each initial
transaction.
o Other fields marked above do not need to be filled in.

- Initial, where the amount is different from 0:

It is a customer-initiated transaction (CIT) where card details have to be entered.
o The “transaction Type” field is marked as DEBIT or PREAUTHORIZE, depending on
which transaction type the merchant supports or wishes to perform.
o In the “transaction Indicator” field, the transaction should be marked as SINGLE. This
is to note that it is a stand-alone transaction or purchase (no series is created), but
also to store the card details. This is marked TRUE in the “withRegister” field.
o The “authenticationIndicator” field is set to 04 for this type of transaction implementation,
as it is linked to the “transaction Type” field.
o The field “challengeIndicator” is populated with the value “04”, which means that
strong authentication (SCA) is required by the card schemes for each initial
transaction.
o Other fields marked above do not need to be filled in.

- Subsequent transactions with the stored card:

It is a transaction initiated by the customer (CIT) using a previously stored card.
o In the “transaction Type” field, the transaction needs to be marked as DEBIT or
PREAUTHORIZE, depending on which transaction type the merchant supports or
wishes to perform.
o In the “transaction Indicator” field, the transaction should be marked as CARDONFILE, thus

11
 UNLIMITED
indicating that it is a subsequent transaction, but linked to the first one.
▪ Therefore, the field “referenceTransactionId” should be filled with the UUID
(unique indicator) of the Register or the initial transaction, because the
system thus knows that strong authentication has already been performed
on the first transaction and does not need to be performed here.

Example of a code for INITIAL (first) transactions, in JSON format:

{
"merchantTransactionId": "D-2022-04-07-624eb695e63d3",
"extraData": {
"userField1": "00",
},
"threeDSecureData":{
"authenticationIndicator":"04"
}
"merchantMetaData": "Transaction:Debit;Description:test",
"amount": "1.99",
"currency": "EUR",
"successUrl": " https://mydomain.com/PHPPaymentGatewayJson/examples/PaymentOK.php",
"cancelUrl": " https://mydomain.com/PHPPaymentGatewayJson/examples/PaymentCancel.php",
"errorUrl": " https://mydomain.com/PHPPaymentGatewayJson/examples/PaymentNOK.php",
"callbackUrl": " https://mydomain.com/PHPPaymentGatewayJson/examples/Callback.php",
"description": "One pair of shoes",
"withRegister": true,
"transactionIndicator": "SINGLE",
"customer": {
"firstName": "Janez",
"lastName": "Novak",
"billingAddress1": "Street 1",
"billingCity": "City",
"billingPostcode": "1000",
"billingCountry": "SI",
"email": "[email protected]",
"ipAddress": "91.208.168.48"
},
"language": "sl"
}
Example of a code for SUBSEQUENT (further) transactions, in JSON format:

12
 UNLIMITED
{
"merchantTransactionId": "D-2022-04-07-624ebfa95f6d9",
"extraData": {
"userField1": "00"
},
"merchantMetaData": "Transaction:Debit;Description:test",
"referenceUuid": "a4189ed3a0ea2546826a",
"amount": "1.99",
"currency": "EUR",
"successUrl": https://mydomain.com/PHPPaymentGatewayJson/examples/PaymentOK.php",
"cancelUrl": " https://mydomain.com/PHPPaymentGatewayJson/examples/PaymentCancel.php",
"errorUrl": " https://mydomain.com/PHPPaymentGatewayJson/examples/PaymentNOK.php",
"callbackUrl": "https://mydomain.com/PHPPaymentGatewayJson/examples/Callback.php",
"description": "One pair of shoes",
"withRegister": false,
"transactionIndicator": "CARDONFILE",
"customer": {
"firstName": "Janez",
"lastName": "Novak",
"billingAddress1": "Street 1",
"billingCity": "City",
"billingPostcode": "1000",
"billingCountry": "SI",
"email": "[email protected]",
"ipAddress": "91.208.168.48"
},
"language": "sl"
}

3.5.3.2. Indicating MIT (Merchant Initiated Transactions) transactions:

Figure 6: Table with indicators for MIT transactions

Within MIT transactions, there are 3 types of possible implementations of these transactions:
- Initial, where the amount equals 0 – MIT establish:
With this transaction, the merchant obtains consent to initiate further transactions without
the customer being present. It is a Merchant Initiated Transaction (MIT) where card details
need to be entered or the card is already stored with a Register transaction from before. In
both cases the fields are filled in the same way.
o In the “transaction Type” field, the transaction is marked PREAUTHORIZE.
o In the “transactionIndicator” field, the transaction needs to be marked INITIAL, as it
is the first transaction in the series.
o The “withRegister” field should be marked TRUE, which means that the card is stored
for subsequent payments.
o The “authenticationIndicator” field is automatically set to 02 for this type of

13
 UNLIMITED
transaction, as it is linked to the “transaction Type” field. The value “02” means that
the card is also stored when the MIT series is created.
o The field “recurringFrequency” is populated by default with the value “1” because,
according to the strict rules of the card schemes, it is not a recurring transaction, as
the amount can be different each month for MIT transactions. The desired number
of payments in the series can be entered here.
o If the transaction is one where the card is already stored, the
“referenceTransactionId” field should be used and populated with the UUID (unique
indicator) of the Register or the initial transaction in the series, as the system thus
knows that strong authentication has already been performed on the first
transaction and does not need to be performed here.
o The field “challengeIndicator” is populated with the value “04”, which means that
strong authentication (SCA) is required by the card schemes for each initial
transaction.

- Initial, where the amount is different from 0 – MIT establish:

It is a Merchant Initiated Transaction (MIT) where card details either need to be entered or
the card is already stored with a Register transaction from before.
In both cases the following fields are filled in the same way.
o This transaction sets up a series of MIT transactions and actually purchases goods at
the same time, so the “transaction Type” field is marked as DEBIT or PREAUTHORIZE,
depending on which transaction type the merchant supports or wants to perform.
For the other fields the same rules apply as for the initial transaction where the amount is 0.

- Subsequent MIT transactions:

It is a Merchant Initiated Transaction (MIT) using a previously stored card.
o The “transaction Type” field is marked DEBIT because it is a single-phase transaction.
o In the “transaction Indicator” field, the transaction should be marked as
CARDONFILE-MIT, thus indicating that it is a subsequent transaction, but linked to
the first one.
▪ Therefore, the field “referenceTransactionId” should be filled with the UUID
(unique indicator) of the Initial transaction, because the system thus knows
that strong authentication has already been performed on the first
transaction and does not need to be performed here.
o Other fields marked above do not need to be filled in.

Example of a code for INITIAL (first) transactions, in JSON format:

14
 UNLIMITED

Example of a code for SUBSEQUENT (further) transactions, in JSON format:

{
"merchantTransactionId": "D-2022-04-07-624ebdc06bed2",
"extraData": {
"userField1": "00"
},
"merchantMetaData": "Transaction:Debit;Description:test",
"referenceUuid": "2a06c2a09b69c8eced14",
"amount": "1.99",
"currency": "EUR",
"successUrl": https://mydomain.com/PHPPaymentGatewayJson/examples/PaymentOK.php",
"cancelUrl": " https://mydomain.com/PHPPaymentGatewayJson/examples/PaymentCancel.php",
"errorUrl": " https://mydomain.com/PHPPaymentGatewayJson/examples/PaymentNOK.php",

15
 UNLIMITED
"callbackUrl": "https://mydomain.com/PHPPaymentGatewayJson/examples/Callback.php",
"description": "One pair of shoes",
"withRegister": false,
"transactionIndicator": "CARDONFILE-MERCHANT-INITIATED",
"customer": {
"firstName": "Janez",
"lastName": "Novak",
"billingAddress1": "Street 1",
"billingCity": "City",
"billingPostcode": "1000",
"billingCountry": "SI",
"email": "[email protected]",
"ipAddress": "91.208.168.48"
},
"language": "sl"
}

3.5.3.3. Indicating Recurring transactions:

Figure 7: Table with indicators for Recurring transactions

Within Recurring transactions we again have 3 types of possible implementations of these transactions:
- Initial, where the amount equals 0 – Recurring establish:
This transaction sets up a series of MIT transactions. It is a Merchant Initiated Transaction
(MIT) where card details need to be entered or the card is already stored with a Register
transaction from before.
In both cases the following fields are filled in the same way.
o In the “transaction Type” field, the transaction is marked PREAUTHORIZE.
o In the “transactionIndicator” field, the transaction needs to be marked INITIAL, as it
is the first transaction in the series.
o The “withRegister” field is marked TRUE, which means that the card is kept stored.
o The “authenticationIndicator” field is automatically set to 02 for this type of
transaction, as it is linked to the “transaction Type” field. The value “02” means that
the card is also stored when the MIT series is created.
o The “recurringFrequency” field is populated by default with a value different from 1
or with the number of transactions to be executed in this series. The desired number
of payments in the series can be entered here.
o If the transaction is one where the card is already stored, the
“referenceTransactionId” field should be used and populated with the UUID (unique
indicator) of the Register or the initial transaction in the series, as the system thus
knows that strong authentication has already been performed on the first
transaction and does not need to be performed here.

16
 UNLIMITED
o The field “challengeIndicator” is populated with the value “04”, which means that
strong authentication (SCA) is required by the card schemes for each initial
transaction.

- Initial, where the amount is different from 0 – Recurring establish:

It is a Merchant Initiated Transaction (MIT) where card details either need to be entered or
the card is already stored with a Register transaction from before. In both cases the following
fields are filled in the same way.
o This transaction sets up a series of MIT transactions and actually purchases goods at
the same time, so the “transaction Type” field is marked as DEBIT or PREAUTHORIZE,
depending on which transaction type the merchant supports or wants to perform.
For the other fields the same rules apply as for the initial transaction where the amount is 0.

- Subsequent Recurring transactions:

It is a Merchant Initiated Transaction (MIT) using a previously stored card.
o The “transaction Type” field is marked DEBIT because it is a single-phase transaction.
o In the “transaction Indicator” field, the transaction should be marked as
RECURRING, thus indicating that it is a subsequent transaction, but linked to the
first one.
▪ Therefore, the field “referenceTransactionId” should be filled with the UUID
(unique indicator) of the Initial transaction, because the system thus knows
that strong authentication has already been performed on the first
transaction and does not need to be performed here.
o Other fields marked above do not need to be filled in.

Example of a code for INITIAL (first) transactions, in JSON format:

{
"merchantTransactionId": "D-2022-04-07-624eb9951e2ac",
"extraData": {
"userField1": "05",
"threeDSecureData":{
"authenticationIndicator": "02",
"recurringFrequency": "2"
},
"merchantMetaData": "Transaction:Debit;Description:test",
"amount": "1.99",
"currency": "EUR",
"successUrl": https://mydomain.com/PHPPaymentGatewayJson/examples/PaymentOK.php",
"cancelUrl": " https://mydomain.com/PHPPaymentGatewayJson/examples/PaymentCancel.php",
"errorUrl": " https://mydomain.com/PHPPaymentGatewayJson/examples/PaymentNOK.php",
"callbackUrl": "https://mydomain.com/PHPPaymentGatewayJson/examples/Callback.php",
"description": "One pair of shoes",
"withRegister": true,
"transactionIndicator": "INITIAL",
"customer": {
"firstName": "Janez",
"lastName": "Novak",
"billingAddress1": "Street 1",
"billingCity": "City",
"billingPostcode": "1000",
"billingCountry": "SI",
"email": "[email protected]",
"ipAddress": "91.208.168.48"
},

17
 UNLIMITED
"language": "sl"
}

Example of a code for SUBSEQUENT (further) transactions, in JSON format:

{
"merchantTransactionId": "D-2022-04-07-624ebf19af16d",
"extraData": {
"userField1": "00"
},
"merchantMetaData": "Transaction:Debit;Description:test",
"referenceUuid": "4a58b83ad5794fa66041",
"amount": "1.99",
"currency": "EUR",
"successUrl": https://mydomain.com/PHPPaymentGatewayJson/examples/PaymentOK.php",
"cancelUrl": " https://mydomain.com/PHPPaymentGatewayJson/examples/PaymentCancel.php",
"errorUrl": " https://mydomain.com/PHPPaymentGatewayJson/examples/PaymentNOK.php",
"callbackUrl": "https://mydomain.com/PHPPaymentGatewayJson/examples/Callback.php",
"description": "One pair of shoes",
"withRegister": false,
"transactionIndicator": "RECURRING",
"customer": {
"firstName": "Janez",
"lastName": "Novak",
"billingAddress1": "Street 1",
"billingCity": "City",
"billingPostcode": "1000",
"billingCountry": "SI",
"email": "[email protected]",
"ipAddress": "91.208.168.48"
},
"language": "sl"

3.6. Support for online instalment payments

As part of the online payment support, it is also possible to introduce instalment payments. This service is
available to merchants who have a contract with a bank that specifies this service in its offer.
The contract includes support on the Bankart systems side (Payment Gateway, authorization system,
posting data preparation system), but at the same time support must be put in place on the merchant's side
to offer this service as a whole to the customer. Below is a description of the support and how to implement
the support on the merchant’s side.
The basis for processing instalments is that the merchant sends the desired number of instalments in which
payment will be made by the buyer in the API call. Upon purchase, the authorization to the card will be
made based on the total amount of the purchase.

The process of introducing online instalment payment support is as follows:

- The merchant enters into an agreement with the bank to introduce online instalment payment
support.
- The bank communicates to Bankart the merchant code of the merchant with whom the instalment
payment contract is concluded.
Based on this information, the instalment payment option is opened in the authorization system. In
addition to the authorization to carry out instalment payments, the following controls are made as
part of the authorization system control:
o The number of instalments is specified in the contract concluded with the bank. If a request
is sent with a value of 0 or 1 in the field for the number of instalments, the purchase is
considered as a purchase without instalments.

18
 UNLIMITED
o If unauthorized characters are received (only numeric characters are allowed), the
transaction is rejected.
o If the merchant does not have the option to allow instalment payments selected, the
value in the received instalment field is ignored by the merchant and the transaction
is executed without instalments.
- An existing field in Payment Gateway called “userField1” is used to forward instalments to the
authorization system (visible in the above examples of the JSON call for card storing). Until now,
this field has not been used (the value entered had no impact on the processing of
transactions). If the merchant has a signed instalment payment support contract and a solution
in place, the value in the “userField1” field has an impact on the processing.
- The number of instalments is entered by the user. To avoid problems with inappropriate data
entry by the customer, we recommend the use of drop-down menus, radio buttons, etc., and
thus limiting the possible values entered to only the number specified in the contract
concluded with the bank. The merchant may introduce additional instalment controls on their
site and, after the customer has entered the number of instalments they wish to make in
relation to the items purchased or the amount, either allow such a transaction (forward it for
further processing) or not allow the customer's choice (e.g. prevent a purchase of EUR 10 in 5
instalments, which would incur excessive costs in terms of bank charges).
- In the process of displaying the possible payment methods, the merchant must give the
customer the choice of a method that covers instalment payments with the cards for which
the merchant has a contract in place. If the customer selects the instalment payment method,
the merchant enables the customer to select or (less preferably) enter the desired number of
instalments. The number of instalments selected/entered by the customer is sent by the
merchant in the request in the “userField1” field.
- Once the request has been forwarded, it will be handled in line with the regular production
procedures with the addition of an instalment field control. Authorization is made for the full
amount of the purchase.
- The merchant carries out a CAPTURE in accordance with the dynamics of the dispatch of the
goods, whether or not payment by instalments has been selected.
- If the merchant carries out CAPTURE of the purchase in several parts, each part will be deemed
charged in line with the number of instalments selected.
- If the merchant has instalment payment support in place (based on a contract with the bank)
and also provides the number of instalments in the request, the merchant may consider, in the
event of a positive response, that the customer will be debited by the bank within the amounts
of the individual instalments. In such a case, the merchant should note in the receipt to the
customer that the purchase has been made in instalments, in the number sent in the request.
- The number of instalments is visible to the merchant in the instalment display field of the
online store (depending on the way the developer has implemented it) and on the website
https://tebank.bankart.si/Testgw31/Merchant/index.jsp under the Transactions menu.
- The bank charges for instalment transactions are covered as agreed with the bank.

19
 UNLIMITED

4. TESTING GUIDELINES
4.1. Basic information
Before moving to a production environment for the use of online payments, we at Bankart require the
successful completion of a few tests to confirm the correct functioning of the merchant's system and
connection to Bankart's Payment Gateway . Before starting the testing, the Bankart customer support team
([email protected]) will provide you with some the credentials to connect to the Bankart
Payment Gateway and start the testing. Here are the main credentials and in the next subsection you will
be shown how to obtain all of them.
Name Description
API username API access – the developer uses this in the code.
API password Access to API
API Key Payment method key.
Shared Secret Shared secret for signing and authenticating the content of API calls.
Public Integration Key (PKI) Key to integrate payment.jst element in your store.
Web access:
URL Web address for accessing the portal and viewing transactions (refers to the following
section)
Username Username assigned for accessing the portal
Password Password assigned for first login (to be changed after first login!)

4.2. Obtaining data for connection to Payment Gateway

The data to enter the Payment Gateway portal is sent via two channels:
- the email address provided at your registration at the bank (This is in use only for Slovenian
merchants). For merchants that are part of NLB Skopje, NLB Sarajevo, NLB Banja Luka, NLB
Podgorica, NLB Priština, we will send two emails to the banks’ department for e-commerce, who
will then forward this information to you the merchant. In the first email we will send the
integration instructions and the password to access the portal, which must be changed immediately
upon login. And in the second email we will send you the username to access the portal.
- Text message to the number provided upon merchant registration. The username to access
the portal will be sent via this channel. (This is in use only for Slovenian merchants)

Once you have received the login details for the portal, you will then be able to collect the terminal
connection/integration details, as shown in the step-by-step instructions below:
Step 1: After logging in to the Payment Gateway portal, select the “Connectors” tab (highlighted
in green) on the left.

Figure 8: Selecting the “Connectors” tab in Payment Gateway

Step 2: A list of all terminals or connectors is displayed. For each of the connectors, click on the

20
 UNLIMITED
“Show” button on the right to access the information relevant for the integration or connection to
Payment Gateway (in the next step). Connectors that have “Sim” at the end are simulation
connectors and are used to test the integration before the merchant goes into production.
More about the actual testing with simulation connectors is provided later in the document.

Figure 9: Display of connectors in Payment Gateway

Step 3: Click on the “Show” button to see more detailed information about the connector.
The merchant requires the following information to connect to Gateway:
a. API Key
b. Shared Secret (click on “show” to display the information)
c. Public Integration Key (needed in case of payment.js integration for card payments – if the
merchant doesn't want to redirect to Bankart's input mask, but wants an implementation
on their own site to make it look like the customer never leaves the site/store.)

Figure 10: Display of connector data that needs to be copied into the merchant's systems

Step 4: After the data for each of the desired connectors has been copied into the merchant's
system, select the “Users” tab (highlighted in green) from the menu on the left.

Figure 11: Display of the selection of the "Users" tab in Payment Gateway

21
 UNLIMITED

Step 5: A list of all the merchant's users will be displayed. There can be more than one WEB type
user, as these are the users for whom the merchant enables access to the Payment Gateway portal
and transaction review (we suggest up to a maximum of 3, created by Bankart). There is usually
only one API type user, as this is the one through which the connection to Payment Gateway is
enabled.
The data for the main WEB user has already been sent to the merchant. The merchant has already
taken over the connector data. Finally, the API user data still needs to be obtained. For this part,
the merchant has to copy the API username (highlighted in green) to their system, and for this same
API user the “Reset Password” button (highlighted in red) has to be clicked in Payment Gateway on
the right side of the page.

Figure 12: Displaying users in Payment Gateway with a focus on API users

Step 6: The menu for generating the API password will appear. Clicking on the “Generate” option
(highlighted in green) under the Password field will generate the password. You have to copy this
password into the merchant's systems, then click on the “Reset Password” button (highlighted in
yellow) on the bottom right. This saves the password in the Payment Gateway system.

Figure 13: Display of a password change for an API user

IMPORTANT: The API password generation should be done only once or at the first login. Before the
password generation process is completed, the password should be saved and copied to the merchant's
back-office systems so that the merchant can connect to Payment Gateway. If the API password is changed
after the merchant has been in production for a long time and uses the API password generated upon initial
login, the connection between the merchant and Payment Gateway will BREAK after a subsequent
password change and transactions will NOT be able to be run and executed correctly.

22
 UNLIMITED

4.3. Test cards

Testing must be done with the test cards listed on
the right. In the event of unexpected responses,
please contact [email protected].
Enclosed are the details of the cards that can be used
to test the correct functioning of the transactions for
each card scheme.
First, the test card numbers for VISA and
Mastercard (see figure on the right). Depending on
the desired result (which is written next to the card
number), select one of the card numbers. In the field
where the CVC code is checked, you can enter any
three-digit combination, and the same applies to the
Figure 14: VISA and Mastercard test cards
validity date, where any (valid) date can be entered.

Below are the Diners test card numbers in case you have a contract with Diners or Erste Card
Slovenia:
3800 0000 0000 06 – the expected response is transaction approved
3614 8900 6479 13 – the expected response is transaction rejected

As above, select one of the card numbers according to the desired result if the integration is correct.
You can enter any three-digit combination in the field where the CVC code is checked, and the same
applies to the validity date, where any (valid) date can be entered.
Test cards are for testing purposes only and may NOT be used in production.
Production cards issued by banks are NOT to be used for testing in the test system, but
only test cards agreed with Bankart.

4.4. Testing with the simulation connector

For testing purposes, we will define your test merchant to verify the functioning of your system. The
response will be simulated on the payer's side.
After you initiate the transaction, an input mask will be displayed (shown in the figure) if you are
using the HPP redirect, or an integrated input mask will be displayed in your online store if you are
using the payment.js integration. In both cases, you need to enter the test card details provided to
you by Bankart or your bank.

23
 UNLIMITED

Figure 15: Bankart’s new input mask

Podatki o nakupu Purchase information
Trgovec Merchant
Bankart Test Merchant Bankart Test Merchant
Spletna stran Website
https://www.testni-trgovec.si https://www.testni-trgovec.si
Znesek Amount
9,99 EUR EUR 9.99
Podatki o kartici Card details
Ime in priimek Name and surname
Številka kartice Card number
XXXX XXXX XXXX XXXX XXXX XXXX XXXX XXXX
Datum zapadlosti Expiry date
MM/LL MM/YYYY
CVV2/CVC2 CVV2/CVC2
XXX XXX
Prekliči Cancel
Plačaj Pay

After entering your details and clicking the “Pay” button, you will be presented with a 3D Secure
authentication simulation screen and the option to select the authentication result. The card schemes use
an ECI value of 05 as an indicator that a strong authentication (SCA) has been performed, so in most cases
you will either select this option or the “Failed” option.

24
 UNLIMITED
Figure 16: Choice of authentication result for the simulation connector

- ECI 05: Transaction is authenticated

- ECI 06: Failed authentication attempt in the transaction
- ECI 07: Transaction was not authenticated
- Failed: Authentication is not performed, transaction is terminated

After clicking on the submit button, the transaction is executed to the end, where a screen with the
transaction success result is then displayed.

4.5. Transition to a production environment

- Bankart's customer support checks the integration status via the Payment Gateway logs:
Before granting production access, our customer support checks the Payment Gateway logs
to see if the payment flows are correctly executed on the simulation adapter. If everything is
in order or the transactions are correctly executed and marked, Bankart's customer support
team will manually enable the option to use the production terminal.
- Technical support during working hours only:
An important reminder that we always send out in our merchant onboarding emails is that
technical support is only available during working hours (08:00–15:00) on business days, as
freelance developers may also work outside regular working hours or over the weekend.
- Merchants should NOT conduct testing in a production environment!
It is important that merchants do not make changes to the production instance of their
connection to Payment Gateway. To this end, we provide merchants with a test environment
in which to confirm the functioning and then enable the same configuration in the production
environment. In this way we ensure that the moment a merchant receives production access,
their integration with Payment Gateway is working. If changes are subsequently made to the
production environment WITHOUT further testing, the merchant assumes responsibility for
any problems in the execution of individual transactions. If the merchant makes any
significant changes to the settings in the production environment, particularly outside of
working hours, we cannot provide you with immediate technical assistance.

25
 UNLIMITED

5. BANKART PAYMENT GATEWAY: USER

INTERFACE OVERVIEW
5.1. Access to the portal
The web interface is available at:
https://gateway.bankart.si/en/login
The username and password for online access are
separate from the API access. You will also provide an
email address when you arrange formalities with the
bank, which will also be used in case you need to reset
your password.
You should handle any changes to your details with
your bank.
If you have any problems logging in, please contact
[email protected] for assistance. You can
also contact Customer Support if you are unclear about
Figure 17: Entry point for the Payment Gateway
or have any problems using the interface. portal

5.2. Overview of the graphical interface

After entering the data and signing in, the home page or dashboard of the portal appears.
On the left, in the dark grey area, there are different tabs where you can choose to display the desired
details. The most useful tabs for you are Dashboard & Summary and Transactions.

After a successful login, the first tab of the graphical interface, “Dashboard”, is displayed, where you
can see an overview of the statistics of your transactions. Here you can adjust the filters/parameters
by clicking on the top right “Customize” button (highlighted in red) and display the desired graphs
and figures according to your preferences.
When you log in for the first time, please also select the time zone set to Europe/Ljubljana
(highlighted in yellow) on the top left to ensure that the transaction times are displayed in
the correct time and that there are no problems when searching for transactions.

Figure 18: First page in the Payment Gateway portal

On the left, in the grey multi-tab menu, you can select the different functions offered by the user

26
 UNLIMITED
interface. As mentioned above, you will probably find the “Transactions” tab the most useful, where
you can access a list and information about the transactions activated through your online store.

In the upper part of the page you can use various parameters to search for a specific transaction,
which is then displayed in the lower part:

Figure 19: Display of filters for searching transactions in Payment Gateway

The bottom part basically shows a list of all the transactions activated, where the transactions are
sorted in terms of time, from the newer transactions activated to the older ones. In the figure below,
two buttons can be seen on the top right of the blue bar. Clicking on the left button (highlighted in
red in the figure below) will bring up a sub-menu where you can adjust the visibility of the individual
fields on the list according to your needs. If the field name is coloured blue, then this field is displayed,
and if it is coloured grey it is not displayed. Alternatively, you can right-click to quickly export a single
page of transactions in the .csv format.

Figure 20: Option to select the display of fields in the “Transactions” tab

The most important fields on the list of transactions are:

• Transaction ID: the transaction identifier, set by the merchant and fed into the system, which
must be unique for each transaction. The IDs must be different for preauthorization and
subsequent capture or void.
• Purchase ID/UUID: under this value you can pair preauthorization with capture or void. The
UUID is simply a unique transaction ID set by Payment Gateway itself.
• Type: type of transaction activated (debit, preauthorization, capture, void, etc.)
• Status: transaction success

27
 UNLIMITED
• Amount: transaction amount
• Method: card scheme and user authentication version

5.2.1. Reviewing the details (logs) of each transaction

In the list of transactions, clicking on the “Details” button (located at the far right of each transaction
on the list), or clicking on the number in the UUID field, will bring up an interface where you can view
the details and logs of each selected transaction.

Figure 21: Display of page with details on a transaction

Here, in the “Logs” section, developers can check the content of the messages exchanged between the
merchant's system and the Payment Gateway system (note: only successfully authenticated messages
are visible).

5.2.2. Captures and voids of transactions

In the case of a preauthorization type transaction, you are offered the option of manual capture or
void (highlighted in blue) within the user interface on the top right.

Figure 22: Display of the capture/void choice for an individual transaction

Once you have captured the transaction, or the preauthorization has been captured, this will be
visible in the “Transaction Status” field. A link to the captured transaction will also be provided. When
you click on the link, you will be redirected to that captured transaction.

28
 UNLIMITED

Figure 23: Display of the reference (captured, voided) transaction

Note: “fees” and “payout” amounts are not visible. For deposits and commissions, you need to log into
the merchant portal, where financial statements are visible.

5.2.3. Refund of the amount of transactions

If the customer is not satisfied with the purchased product or if the product does not reach the
customer in a satisfactory condition AND the merchant has the possibility to refund the cost, they
can activate this action via the graphical interface upon viewing the transaction details. The “Refund”
button will appear on the top right side (highlighted in dark grey).

Figure 24: Display of how to execute a refund within the Payment Gateway portal

When you initiate a refund via the user interface, a pop-up will open offering two options: “Refund
without Postback” and “Refund with Postback”.
The “Refund with Postback” option sends the new transaction status to the merchant's previously
defined Callback URL, and if this is not defined, the merchant will NOT receive a change of transaction
status when initiating a refund via the Payment Gateway user interface.

29
 UNLIMITED

Figure 25: Screen that appears when a refund is initiated via the portal

5.2.4. Exporting the list of executed transactions

In the Data Export subtab (highlighted in blue in the figure below) you can filter the transactions and
export them to a .cvs or .xlxs file (Excel format).

Figure 26: Transaction export screens

Upon clicking the subtab, all documents that have been generated for export up to a certain moment
will be displayed. For each export document, the date on which the transactions were exported, the
type of data in the export document, the status and the option to Delete or Download are visible.
To export a document, click the “New Transaction Export” button (highlighted in red in the figure above).

30
 UNLIMITED

Figure 27: Display of screen with filters in transaction export

When the new window (above) opens, select the desired filters and the file type to export and
confirm the selection by clicking the “Generate” button. You will be redirected to the previous page,
where you have to wait a few moments for the document to be generated, and the download/delete
option is then offered.
If these options are not displayed after 30 seconds, you can refresh the page yourself.

31