API section

Checkout

A whole sale or refund: payment on the terminal → receipt on the register → slip. If the receipt fails, the agent cancels the payment itself (PAYMENT_CANCELLED).

POST /api/v1/checkouts Sale or refund with a receipt

Sale or refund with a receipt#

POST/api/v1/checkouts

Operation

Order: card operation on the terminal (if there is a CARD payment) → receipt on the register → slip on the register. If the receipt fails after a card payment, the payment is cancelled on the terminal (error PAYMENT_CANCELLED); if the cancellation also fails — PAYMENT_NOT_CANCELLED with the payment data in error.details. Result: { receipt: fiscal document, payment: card operation }.

Parameters

Name	In	Type	Description
`Idempotency-Key`required	header	string
`Prefer`	header	string

Request body application/json required

Fields · CheckoutRequest

registerIdinteger int32
terminalIdinteger int32
receiptReceiptrequired
11 fields · Receipt
- typestringrequired
  values: SELL SELL_RETURN BUY BUY_RETURN
- taxationstring
  values: OSN USN_INCOME USN_INCOME_OUTCOME ESHN PATENT
- operatorOperator
  2 fields · Operator
  - namestringrequired
    from 1
  - innstring
- customerCustomer
  3 fields · Customer
  - contactstring
  - namestring
  - innstring
- headerarray of TextLine
  4 fields · TextLine
  - kindstringrequired
    values: TEXT PAIR SEPARATOR
  - textstring
  - rightstring
  - alignstring
    values: LEFT CENTER RIGHT
- itemsarray of ReceiptItemrequired
  from 1
  9 fields · ReceiptItem
  - namestringrequired
    from 1
  - priceinteger int64
    from 0
  - quantitynumberrequired
  - amountinteger int64
    from 0
  - vatstringrequired
    values: NONE VAT0 VAT5 VAT7 VAT10 VAT20 VAT22 VAT105 VAT107 VAT110 VAT120 VAT122
  - paymentMethodstringrequired
    values: FULL_PREPAYMENT PREPAYMENT ADVANCE FULL_PAYMENT PARTIAL_PAYMENT CREDIT CREDIT_PAYMENT
  - paymentObjectstringrequired
    values: COMMODITY EXCISE JOB SERVICE GAMBLING_BET GAMBLING_PRIZE LOTTERY LOTTERY_PRIZE INTELLECTUAL_ACTIVITY PAYMENT AGENT_COMMISSION COMPOSITE ANOTHER
  - departmentinteger int32
  - markingMarking
    4 fields · Marking
    codestringrequired
    from 1
    fractionstring
    pattern: \d+/\d+
    measurestring
    values: PIECE GRAM KILOGRAM TON CENTIMETER DECIMETER METER SQUARE_CENTIMETER SQUARE_DECIMETER SQUARE_METER MILLILITER LITER CUBIC_METER KILOWATT_HOUR GKAL DAY HOUR MINUTE SECOND KILOBYTE MEGABYTE GIGABYTE TERABYTE OTHER
    industryPropsstring
- paymentsarray of ReceiptPaymentrequired
  from 1
  2 fields · ReceiptPayment
  - typestringrequired
    values: CASH CARD PREPAID CREDIT OTHER
  - amountinteger int64
- footerarray of TextLine
  4 fields · TextLine
  - kindstringrequired
    values: TEXT PAIR SEPARATOR
  - textstring
  - rightstring
  - alignstring
    values: LEFT CENTER RIGHT
- electronicboolean
- senderEmailstring
- settlementPlacestring
originalPaymentRefstring
printSlipboolean

JSON

{
  "registerId": 1,
  "terminalId": 1,
  "receipt": {
    "type": "SELL",
    "taxation": "OSN",
    "operator": {
      "name": "string",
      "inn": "string"
    },
    "customer": {
      "contact": "string",
      "name": "string",
      "inn": "string"
    },
    "header": [
      {}
    ],
    "items": [
      {}
    ],
    "payments": [
      {}
    ],
    "footer": [
      {}
    ],
    "electronic": false,
    "senderEmail": "string",
    "settlementPlace": "string"
  },
  "originalPaymentRef": "string",
  "printSlip": false
}

Response 200 application/json

Fields · Operation

idstring uuid
typestring
idempotencyKeystring
resourcesarray of string
statusstring
values: QUEUED RUNNING SUCCEEDED FAILED UNKNOWN
stagestring
createdAtstring date-time
startedAtstring date-time
finishedAtstring date-time
resultany value
errorOperationError
3 fields · OperationError
- codestring
- messagestring
- detailsany value
warningsarray of string

Errors — problem+json with a code field, see error codes.

Request example

curl

curl -X POST 'http://localhost:7790/api/v1/checkouts' \
  -H 'Idempotency-Key: $(uuidgen)' \
  -H 'Prefer: wait=30' \
  -H 'Content-Type: application/json' \
  --data '{"registerId":1,"terminalId":1,"receipt":{"type":"SELL","taxation":"OSN","operator":{"name":"string","inn":"string"},"customer":{"contact":"string","name":"string","inn":"string"},"header":[{}],"items":[{}],"payments":[{}],"footer":[{}],"electronic":false,"senderEmail":"string","settlementPlace":"string"},"originalPaymentRef":"string","printSlip":false}'

curl

curl -X POST 'https://cloud.hw-connector.ru/agent/api/v1/checkouts' \
  -H 'X-Api-Key: hwk_…' \
  -H 'X-Device-Id: 42' \
  -H 'Idempotency-Key: $(uuidgen)' \
  -H 'Prefer: wait=30' \
  -H 'Content-Type: application/json' \
  --data '{"registerId":1,"terminalId":1,"receipt":{"type":"SELL","taxation":"OSN","operator":{"name":"string","inn":"string"},"customer":{"contact":"string","name":"string","inn":"string"},"header":[{}],"items":[{}],"payments":[{}],"footer":[{}],"electronic":false,"senderEmail":"string","settlementPlace":"string"},"originalPaymentRef":"string","printSlip":false}'