API v1.2.1 Objects

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/

1. CheckoutInvoice

Object contains checkout invoice data.

Field	Type	Mandatory	Description
orderId	String	Yes	Invoice ID in merchant's system (up to 36 characters).
totalAmount	Number	Yes	Total amount in kopecks (10 characters — only digits, non-negative number).
currency	Enum	No	Currency code in Alpha-3 ISO-4217: RUB — default value if parameter is omitted or empty. Values other than RUB will return reject with message that only RUB is expected.
discountAmount	Number	No	Discount amount in kopecks (10 characters — only digits, non-negative number).
subTotalAmount	Number	No	Total amount excluding discount in kopecks. (10 characters — only digits, non-negative number).
items	Array of Item	Yes	Array of Item objects describing commodity items.

2. Item

Object defines a particular commodity item to be paid with Koshelek Pay.

Object defines particular commodity item to be paid with Koshelek Pay.

Field	Type	Mandatory	Description
name	String	Yes	Item name.
article	String	Yes	Item article.
price	Number	Yes	Price for one item in kopecks.
currency	String	No	Currency code in Alpha-3 ISO-4217: RUB — default value if parameter is omitted or empty. Values other than RUB will return reject with message that only RUB is expected.
quantity	Number	Yes	Item count: Number with floating point and 1 symbol after decimal point. Fractional numbers are disallowed. ✅ Correct: measure = GRAM quantity = 1125.0 OR quantity = 1125 ❌ Incorrect: measure = KILOGRAM quantity = 1.125
measure	Enum	No	Item measure: PIECE — item pieces (default value if parameter is omitted or empty.) GRAM KILOGRAM TON CENTIMETER DECIMETER METER SQUARE_CENTIMETER SQUARE_DECIMETER SQUARE_METER MILLILITER LITER KILOWATT_HOUR GIGACALORIE DAY HOUR MINUTE SECOND KILOBYTE MEGABYTE GIGABYTE TERABYTE OTHER — other item measure.
totalAmount	Number	Yes	Total amount in kopecks.
discountAmount	Number	No	Discount amount in kopecks.
subTotalAmount	Number	No	Total amount excluding discount in kopecks.
tax	Enum	Yes	Tax rate: none — no VAT. vat0 — VAT at 0% rate. vat10 — VAT at 10% rate. vat20 — VAT at 20% rate. vat110 — VAT at estimated tax rate of 10/110. vat120 — VAT at estimated tax rate of 20/120.

3. User

Object describes a loyalty program user (customer).

Field	Type	Mandatory	Description
loyaltyId	String	Yes	Customer loyalty ID (e.g., presented loyalty card number) (up to 36 characters).

4. PaymentTypeAvailabilityInfo

Object containing available payment method info.

Field	Type	Mandatory	Description
paymentType	String	Yes	Payment method name available for customer (up to 36 characters).
available	Boolean	Yes	Indicates payment method availability: true — available; false — unavailable.
message	String	No	Additional information on payment method.

5. Slip

Object contains information about a completed transaction.

Object contains information about completed transaction.

Field	Type	Mandatory	Description
id	String	Yes	Slip object ID in Koshelek Pay.
paymentType	Enum	Yes	Payment mechanism selected by customer: SBP — SBP. DOLYAME — Dolyame.
storeId	String	Yes	Store ID (see API Connection).
terminalId	String	Yes	Terminal ID.
orderId	String	Yes	Invoice ID in merchant's system.
paymentTransactionId	String	Yes	Payment transaction ID in Koshelek Pay.
refundTransactionId	String	No	Refund transaction ID.
merchantId	String	Yes (for paymentType = SBP)	Merchant ID presented by recipient bank. Mandatory for SBP transactions.
kzo	String	No	Control operation value that may be returned for successful SBP transaction.
operationDateTime	Date	Yes	Date in format: yyyy-MM-dd'T'HH:mm:ss.SSSZ Time zone always equals Z (+0).
operationId	String	No	Unique return ID assigned by payment provider (use trxId obtained from SBP or refundId from Dolyame.)
qrcId	String	Yes (for paymentType = SBP)	Transaction ID assigned by Faster Payments System. Mandatory for SBP transactions.
totalAmount	Number	Yes	Paid amount in kopecks.
currency	Enum	Yes	Currency code in Alpha-3 ISO-4217: RUB — default value if parameter is omitted or empty. Values other than RUB will return reject with message that only RUB is expected.

6. PaymentMethod

Object defines payment method used in transaction.

Field	Type	Mandatory	Description
type	Enum	Yes	Payment mechanism supported by POS: SBP — SBP. DOLYAME — Dolyame.
meta	Object	No	Object for extra fields (e.g. discounts, bonuses etc.) in a "key-value" format.
paymentPurpose	String	No	"Payment purpose" value applicable to SBP transactions. When returned, this value will override any other paymentPurpose value agreed by default between merchant and Cardsmobile.

7. Invoice

Object describes an invoice (receipt).

Field	Type	Mandatory	Description
orderId	String	Yes	Invoice number (up to 36 characters).
receiptId	String	Yes	Receipt number (up to 36 characters).
merchantName	String	Yes	Merchant full name (up to 999 characters).
merchantAddress	String	Yes	Merchant address (up to 999 characters).
inn	String	Yes	Merchant TIN (12 digits, opening with 2 zeroes for legal entities.
dateTime	Datetime	Yes	Date in format: YYYY-MM-DDTHH24:MI:SS+GMT
shift	String	Yes	Work shift (up to 32 characters).
cashier	String	Yes	Checkout operator number or name (up to 256 characters).
taxation	Enum	No	Taxation system (TS): osn — general TS. usn_income — simplified TS (income). usn_income_outcome — simplified TS (net income). envd — unified tax on imputed income. esn — unified agricultural tax. patent — patent TS.
kktRegNumber	String	No	Cash register number (up to 64 characters).
fnNumber	String	No	Fiscal memory device number (up to 64 characters).
fpd	String	No	Fiscal attribute of document (up to 64 characters).
fdNumber	String	No	Fiscal document number (up to 64 characters).
website	String	No	Web site for receipt verification (e.g. nalog.ru) (up to 64 characters).
receiptType	Enum	Yes	Receipt type: debit credit refund
totalAmount	Number	Yes	Total amount in kopecks (up to 10 digits, non-negative integer).
currency	Number	No	Currency code in Alpha-3 ISO-4217: RUB — default value if parameter is omitted or empty. Values other than RUB will return reject with message that only RUB is expected.
discountAmount	Number	No	Discount amount in kopecks (up to 10 digits, non-negative integer).
subTotalAmount	Number	No	Total amount excluding discount in kopecks (10 digits, non-negative integer).
taxAmount	Number	No	Tax amount in kopecks (up to 10 characters — only digits, non-negative integer).
qr	String	No	QR for receipt in digital (up to 999 characters).
items	Array of Item	Yes	Array of Item objects describing purchased items.