Integration Requirements

Koshelek Pay API

Documentation has moved

The information on this page is no longer updated and may be obsolete. The most current Koshelek documentation is now available at the new address:

https://developers.koshelek.app/en/

To enable payments with Koshelek Pay API, the following technical requirements apply to merchants and cash desk software developers.

All requiremens are mandatody unless "optional" is stated explicitly.

1. Koshelek Pay scenarios requirements

Full list of scenarios that implement payment operations with Koshelek Pay is published in Usage Scenarios section.

Make sure to support:

• Basic flows

• Alternative flows

• Specific cases

• Error processing

2. POS receipt requirements

ℹ️ optional

It is recommended to enhance customer's cash register receipt (slip) printed by POS — by adding a special area with technical information describing payment / refund operation made with Koshelek Pay.

This information can be of use for customer for making support inquiries, as well as for cash desk operator — for refunds.

Pay API parameter	Description	Comments
orderId	ID (number) of order for merchant.	Common for payment and refund scenarios.
paymentTransactionId	Payment transaction ID for Koshelek.	Unique for payment scenario.
refundTransactionId	Refund transaction ID for Koshelek.	Unique for refund scenario.
paymentType	Payment provider (SBP / Dolyame).	Common for payment and refund scenarios.
qrcId	Transaction ID for SBP.	For paymentType = SBP
kzo	Control operation value for SBP.	For paymentType = SBP

3. API contract requirements

Integration with Koshelek Pay services must be implemented by leveraging the most current Pay API version (refer to General Information → Changelog: the most current version is specified on top of the list). Below is the full list of Pay API calls indicating those mandatory for implementation:

Pay API request	Mandatory
Request list of available payment methods	Optional
Checkout	Mandatory
Request status	Mandatory
Send payment receipt	Optional
Cancel payment	Mandatory
Refund payment	Mandatory

3.1. Ensure minimum possible latency

Low latency is crucial for smooth transactions. A delay between pressing the UI button on the cash desk and starting transferring data to Koshelek server must not exceed 0.5 seconds.

Example: payment scenario

Right after payment via Koshelek Pay is triggered on the cash desk, your system must immediately (within a timeframe of 0.5 seconds) issue a corresponding request to Koshelek Pay API.

3.2. Mind API idempotency

Pay API methods are idempotent. You should take this into account when developing a service that will communicate with Pay API. Special attention should be paid to this when making a refund (refer to Scenario 3. Refund payment → Alternative refund scenarios and possible errors).

4. Additional APIs

4.1. Store API

ℹ️ optional

To simplify addition / update information about stores that support payments with Koshelek Pay, it is recommended to integrate with dedicated Store API.

5. Error handling

5.1. Processing API error codes

It is required to correctly process Pay API errors that may be returned during API communication. Refer to API Response Codes for full list of Pay API HTTP status codes including error codes.

5.2. Processing errors involving cash desk operator

For errors that require actions from cash desk operator, it is required to show up such errors on cash desk screen in clear and unambiguous way, with brief instructions / tips for cash desk operator. Refer to API Response Codes (see column "Tip for cash desk operator").

6. TOTP implementation requirements

6. 1. Enable support for TOTP barcodes

Koshelek Pay employs the TOTP mechanism to validate authenticity of loyalty cards presented by customers. In this respect, aside from the card number itself, the TOTP-enabled card barcode should also contain some verification data:

• one-time cardSession (refer to Connection to API);

• one-time TOTP password (refer to Koshelek TOTP Module).

6.1.1. Allowed TOTP barcodes

The following TOTP barcode formats are accepted:

• code128

• PDF417

• DataMatrix

• QR code

6.2. Deploy Koshelek TOTP module

TOTP enablement requires deployment of a special TOTP software module in your infrastructure. Refer to Koshelek TOTP Module to get an idea of how to deploy this module.

6.3. Ensure backward compatibility

Your TOTP barcode support must ensure backward compatibility with loyalty cards incapable of TOTP verification (cards issued before Koshelek Pay integration — i.e. those cards missing cardSession and TOTP password in barcode).

7. POS cash report requiments

7.1. Store slip parameters

All slip parameters emerged at Koshelek Pay transaction (contained in Pay API's slip object) must be accounted and stored in POS internal database.

7.2. Enhance cash reports

The following parameters specific to Koshelek Pay transactions must be included in POS internal cash reports:

Pay API parameter	Decription	Comments
orderId	ID (number) of order for merchant.	Common for payment and refund scenarios.
paymentTransactionId	Payment transaction ID for Koshelek.	Unique for payment and refund scenarios.
refundTransactionId	Refund transaction ID for Koshelek.	Unique for refund scenario.
requestId	Unique request ID from cash desk software.	Unique for any request independent of scenario.
paymentType	Payment provider in Koshelek Pay.	Defines purchase mechanism (Dolyame / SBP).
qrcId	Transaction ID for SBP.	For paymentType = SBP
kzo	Control operation value for SBP.	For paymentType = SBP

8. Configuration requirements

8.1. Cash desk configuration

Data exchange via Koshelek Pay API involves number of identifiers and technological parameters as described in Connection to API → API credentials, onboarding parameters and identifiers. When implementing a service that interacts with the Pay API, you must ensure the following parameters to be configurable (either through a dedicated configuration file or otherwise):

Parameter	To be configurable
login	Mandatory
password	Mandatory
store	Mandatory
API Base URL (test)	Mandatory
API Base URL (production)	Mandatory
terminal	Optional
paymentPurpose	Optional

8.2. Pay API configuration

For better request automation, a certain part of logic must be configurable through a dedicated configuration parameters, namely:

• Allowed inbound and outbound ENUM values. This way you will be able to add new payment providers without having to upgrade cash desk software.

• Cash desk automated actions for timeouts and request resending. This will improve user experience during cash desk operation.

8.3. TOTP configuration

For Koshelek TOTP module, make all parameters and IDs specified in Koshelek TOTP Module → Setup and Configuration → Configuration to be configurable. All parameters are mandatory.