Перейти к содержанию

Scenario 1. Payment

Pay API

Basic flow

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

Warning

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

Barcode processing and checkout

Diagram description:

Step # Description
[01]-[03] Customer selects 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 Pay API). 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 data center to calculate discounts and bonuses for different payment methods (traditional and for received payment providers).
The merchant’s data center 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 made via the Koshelek app must be the same for all payment providers (only marketing messages and subsequent bonuses from the merchant may differ after payment through a certain payment provider).

Algorithm for obtaining the list of available payment providers:

Algorithm for obtaining the list of available payment providers

2. Payment

Payment

Further scenario execution is determined by the koshelekPayIsDefault value.

koshelekPayIsDefault = true:

Step # Description
[01]-[05] Merchant automatically requests payment checkout (refer to Pay API). 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 Pay API). 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 Pay API). 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 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 Pay API). 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 Pay API.

  • Green color indicates successful statuses.
  • Red indicates unsuccessful statuses.
  • Gray indicates transit statuses.

Payment transaction state

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×item

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

1. Customer updates checkout positions after POST /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 (see Scenario 2. Cancel payment).
  3. Send an updated checkout invoice with new requestId but the same cardSession.

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 (see 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 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.
  • If transaction result is already received (it may be received even after payment cancellation, 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.
    2. If the transaction is completed successfully and the 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 re-scan TOTP barcode to refresh cardSession.

3. Customer cancels payment in the app by mistake

That is: customer cancels payment on the Koshelek App screen accidentally or my mistake.

Your actions:

  1. Send an updated checkout invoice with new requestId but the same cardSession.

4. Bank declines transaction for some reason

There is a rejected status for a transaction, indicating transaction has been declined.

Your actions:

  • If the reason is insufficient funds and customer has solved it:
    1. Retry sending checkout invoice with a new requestId but the same cardSession.
  • Other reasons: (including technical issues on acquirer or SBP side):
    1. 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.
  2. Send an updated checkout invoice (POST /checkout) with new requestId and cardSession.

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 POST /checkout with the same requestId and cardSession (API methods are idempotent).