Scenario 1. Payment

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/

Payment scenario: basic flow

The Koshelek Pay payment scenario can be split into 2 parts. Please keep in mind that this is a continuous process.

It is essential for payments via Koshelek Pay that the loyalty card barcode scanning is done only once (a single scan should cover both loyalty card processing and payment).

1. Barcode processing and checkout

(for full resolution, open image in new tab)

Step #	Description
[01]-[03]	Customer selects a loyalty card in the Koshelek app. The app displays the card and the TOTP-enabled card barcode (see Koshelek TOTP Module).
[04]	Checkout operator scans the TOTP-enabled card barcode with a scanner. Cash desk software reads out the full barcode value, checks if payment via Koshelek Pay is available (indicated by cardSession presence in the barcode value), validates TOTP password (as described in Koshelek TOTP Module), identifies customer loyalty ID and calculates total amount.
[05]-[10]	Merchant requests a list of payment providers (refer to API v1.2.1 Requests). The response contains a list of available payment providers along with the koshelekPayIsDefault value, which indicates if Koshelek Pay is set as default payment method in customer's Koshelek app.
[11]	If Koshelek Pay is not enabled in customer's account, a fallback to alternate payment methods is triggered. End of scenario.
[12]-[14]	(Optional steps) Cash desk contacts the merchant's datacenter to calculate discounts and bonuses for different payment methods (traditional and for received payment providers). The merchant's datacenter performs the calculation and returns a marketing message for each provider to the cash desk to be shown in customer's Koshelek app. The cash desk software generates the final value of the payment amount and discounts in the receipt for each payment method. The total amount and the discount amount must be the same for all payment providers (including via the Koshelek app). Only marketing messages and subsequent bonuses from the merchant may differ after payment through a certain payment provider.

2. Payment

(for full resolution, open image in new tab)

Further scenario execution is determined by the koshelekPayIsDefault value.

koshelekPayIsDefault = true:

Step #	Description
[01]-[05]	Merchant automatically requests payment checkout (refer to API v1.2.1 Requests). As a result, the total amount is displayed in customer's Koshelek app.
[06]	Customer confirms payment in the app.
[07-11]	Koshelek server processes payment and informs merchant of transaction status. The status is also displayed on customer's Koshelek app screen.
[12]-[14]	Merchant sends transaction receipt to the Koshelek server (refer to API v1.2.1 Requests). The receipt is transferred to the Koshelek app screen for customer's notice. End of scenario.

koshelekPayIsDefault = false and at least one payment provider is available:

Step #	Description
[15]-[22]	Checkout operator informs the customer that the Koshelek Pay payment method is available. If the customer confirms to pay with Koshelek Pay, the operator triggers payment checkout request (refer to API v1.2.1 Requests). As a result, the total amount is displayed in customer's Koshelek app.
[23]	Customer confirms payment in the app.
[24]-[28]	Koshelek server processes the payment and informs merchant of transaction status. The status is also displayed on customer's Koshelek app screen.
[29]-[31]	Merchant sends transaction receipt to the Koshelek server (refer to API v1.2.1 Requests). The receipt is transferred to the Koshelek app screen for customer's notice. End of scenario.

No payment providers are available:

Step #	Description
[32]	Cash desk software displays the reason for payment provider unavailability (see message parameter per each provider). End of scenario.

Payment transaction states

The diagram shows transaction status transitions during payment operation initiated via Koshelek Pay API.

• Green color indicates successful statuses.

• Red indicates unsuccessful statuses.

• Yellow indicates transit statuses.

(for full resolution, open image in new tab)

Specific payment cases

1. Non-piece purchases

Non-piece goods (e.g. those sold by weight) require proper processing in Pay API. Specify such item details by using the following fields:

• measure: measure units

• quantity: item count in measure units (use only integer numbers)

• price: price for 1 measure unit

Example

Today's price for bananas: 100 rubles / kg.

Case 1: customer buys 1.0 kg of bananas

The following Pay API fields should be used to specify this purchase:

• measure: GRAM or KILOGRAM

• quantity:

  • 1 (if measure = KILOGRAM)

  • 1000 (if measure = GRAM)

• price:

  • 10000 kopecks (if measure = KILOGRAM)

  • 10 kopecks (if measure = GRAM)

Case 2: customer buys 0.5 kg of bananas

The following Pay API fields should be used to specify this purchase:

• measure: GRAM

• quantity: 500

• price: 10 kopecks per GRAM

2. Buying more than 1 identical item

When customer buys multiple number of the same item, it is important to pass exact number of such items.

This is crucial for partial refunds, as payment provider Dolyame verifies number of items for particular article during refund processing. If payment transaction specifies item quantity = 1, then partial refund won't go through.

Example

Customer buys two pencils of article = 12345.

In this case, you have 2 options to properly specify this purchase:

Option 1: pass pencils as 1 item

• name: pencil

• quantity: 2

• article: 12345

Option 2: pass pencils as 2 items

item 1:

• name: pencil

• quantity: 1

• article: 12345

item 2:

• name: pencil

• quantity: 1

• article: 12345

3. Discounts, rewards, advance payments, mixed payments

If some part of purchase amount is paid differently (i.e. is paid by cash, advance payment or any other way different from Koshelek Pay), then you should specify this part of amount in field discountAmount.

Example

Case 1: advance payment

Customer arranges for the "car repair" service (total cost: 10 000 rubles). Some spare parts must be purchased and delivered to the service station in advance. According to service conditions, it is necessary to make an advance payment of 2 000 rubles.

Customer paid an advance by cash and now wants to complete payment with Koshelek Pay. In this case, use the following fields to complete purchase:

• discountAmount: 200000 kopecks (equals 2 000 rubles)

• totalAmount: 800000 kopecks (equals 8 000 rubles)

Case 2: partial payment with rewards

Customer buys some goods of total value 1 000 rubles. Customer wants to break the payment in a way so that 300 rubles would be paid with reward points, and remaining 700 rubles with Koshelek Pay. In this case, use the following fields to complete purchase:

• discountAmount: 30000 kopecks (equals 300 rubles)

• totalAmount: 70000 kopecks (equals 700 rubles)

Alternative payment flows

Sometimes basic payment flow can be extended as described below.

1. Customer updates checkout positions after the /checkout request is issued

Your actions:

1. Tell customer not to confirm payment in the Koshelek app (otherwise, payment can go through and you won't be able to cancel it).

2. Initiate payment cancel (refer to Scenario 2. Cancel payment).

3. Send an updated checkout invoice with a new requestId but the same cardSession (refer to API v1.2.1 Requests).

2. Customer cancels purchase (in full or in part) after payment is confirmed in the app

Your actions:

• If transaction result is not yet received:

  1. Initiate payment cancellation (refer to Scenario 2. Cancel payment). If cancellation is initiated before the bank receives the payment request, no funds will be withdrawn and no receipt slip will be issued.

  2. If the customer asks to update the checkout: update checkout positions as required and send an updated checkout invoice with a new requestId but the same cardSession (refer to API v1.2.1 Requests).

• If transaction result is already received (it may be received even after cancellation request as the bank will likely receive payment request before we get cancellation request from you):

  1. If the transaction result is unsuccessful (payment declined): you may update checkout positions as required and send an updated checkout invoice with a new requestId but the same cardSession (refer to API v1.2.1 Requests).

  2. If the transaction is completed successfully and customer wants to cancel payment: initiate payment cancellation (refer to Scenario 3. Refund payment). After refund is completed, new transaction for the same customer and the same loyalty card is done from scratch — i.e. you should scan TOTP barcode and receive a new cardSession.

3. Customer cancels payment in the app by mistake

That is: customer cancels payment on the Koshelek app screen accidentally or by mistake.

Your actions:

1. Send an updated checkout invoice with a new requestId but the same cardSession (refer to API v1.2.1 Requests).

4. Bank declines transaction for some reason

That is: transaction status is rejected, transaction is declined.

Your actions:

• If the reason is insufficient funds and the customer has solved it:

  1. Retry sending checkout invoice with a new requestId but the same cardSession (refer to API v1.2.1 Requests).

• Other reasons:

  1. Among possible reasons, it might be technical issues with the acquirer or the Faster Payment System (FPS). You may want to retry sending checkout invoice, likewise in insufficient funds case — or, suggest another payment option to the customer. If retry doesn't help, fall back to a different payment option.

5. POST /checkout request returns: "cardSession unavailable or invalid"

Your actions:

1. Refresh cardSession by re-reading the loyalty card TOTP barcode (or asking a customer to re-scan QR at the cash desk if this method is implemented.)

2. Send an updated checkout invoice with new requestId and cardSession (refer to API v1.2.1 Requests).

6. Can't issue POST /status request due to no response received on POST /checkout (transactionId missing)

Your actions:

1. It is allowable to retry the same request with the same requestId и cardSession (API methods are idempotent).