Integration Requirements
Pay API
To enable payments with Koshelek Pay API, the following technical requirements apply to merchants and cash desk software developers.
All requirements are mandatory unless “optional” is stated explicitly.
1. Koshelek Pay scenarios requirements
Full list of scenarios that implement payment operations with Koshelek Pay is listed in Usage Scenarios.
Make sure to support:
- Basic flows
- Alternative flows
- Specific cases
- Error processing
2. POS receipt requirements
:information_source: 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 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 | Is 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 time frame 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 (see Scenario 3. Refund payment → Alternative refund flows and possible errors).
4. Additional APIs
4.1. Store API
:information_source: 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 specification page 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 specification page (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 - one-time TOTP password
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 requirements
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 | Description | 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. 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.2. TOTP configuration
For Koshelek TOTP module, make all parameters and IDs specified in Koshelek TOTP Module → Setup and Configuration → Configuration). All parameters are mandatory.