API section

Payment terminal

Card and SBP payment, refund, cancellation, settlement, emergency reversal, reports and slip; a QR code image for SBP payment. A sale with a receipt is easier as one operation — POST /api/v1/checkouts.

POST	`/api/v1/terminals/{id}/settlements`	Settlement
POST	`/api/v1/terminals/{id}/reports`	Terminal report
POST	`/api/v1/terminals/{id}/refunds`	Refund to card
POST	`/api/v1/terminals/{id}/payments`	Card payment
POST	`/api/v1/terminals/{id}/emergency-reversals`	Emergency reversal of the last operation
POST	`/api/v1/terminals/{id}/cancellations`	Cancel a payment
GET	`/api/v1/terminals/{id}/last-slip`	Last terminal slip
GET	`/api/v1/qr`	QR code as a PNG image

Settlement#

POST/api/v1/terminals/{id}/settlements

Operation

End of day on the terminal; the slip is in the result

Parameters

Name	In	Type	Description
`id`required	path	integer int32	device number from `GET /api/v1/devices`
`Idempotency-Key`required	header	string
`Prefer`	header	string

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/terminals/1/settlements' \
  -H 'Idempotency-Key: $(uuidgen)' \
  -H 'Prefer: wait=30'

curl

curl -X POST 'https://cloud.hw-connector.ru/agent/api/v1/terminals/1/settlements' \
  -H 'X-Api-Key: hwk_…' \
  -H 'X-Device-Id: 42' \
  -H 'Idempotency-Key: $(uuidgen)' \
  -H 'Prefer: wait=30'

Terminal report#

POST/api/v1/terminals/{id}/reports

Operation

The shift's operations without settlement with the bank; full=true — for each operation. The slip is in the result

Parameters

Name	In	Type	Description
`id`required	path	integer int32	device number from `GET /api/v1/devices`
`Idempotency-Key`required	header	string
`Prefer`	header	string
`full`	query	boolean

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/terminals/1/reports' \
  -H 'Idempotency-Key: $(uuidgen)' \
  -H 'Prefer: wait=30'

curl

curl -X POST 'https://cloud.hw-connector.ru/agent/api/v1/terminals/1/reports' \
  -H 'X-Api-Key: hwk_…' \
  -H 'X-Device-Id: 42' \
  -H 'Idempotency-Key: $(uuidgen)' \
  -H 'Prefer: wait=30'

Refund to card#

POST/api/v1/terminals/{id}/refunds

Operation

For payments of previous days, after the settlement

Parameters

Name	In	Type	Description
`id`required	path	integer int32	device number from `GET /api/v1/devices`
`Idempotency-Key`required	header	string
`Prefer`	header	string

Request body application/json required

Fields · ReversalRequest

amountinteger int64
paymentRefstringrequired
from 1

JSON

{
  "amount": 1,
  "paymentRef": "string"
}

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/terminals/1/refunds' \
  -H 'Idempotency-Key: $(uuidgen)' \
  -H 'Prefer: wait=30' \
  -H 'Content-Type: application/json' \
  --data '{"amount":1,"paymentRef":"string"}'

curl

curl -X POST 'https://cloud.hw-connector.ru/agent/api/v1/terminals/1/refunds' \
  -H 'X-Api-Key: hwk_…' \
  -H 'X-Device-Id: 42' \
  -H 'Idempotency-Key: $(uuidgen)' \
  -H 'Prefer: wait=30' \
  -H 'Content-Type: application/json' \
  --data '{"amount":1,"paymentRef":"string"}'

Card payment#

POST/api/v1/terminals/{id}/payments

Operation

Parameters

Name	In	Type	Description
`id`required	path	integer int32	device number from `GET /api/v1/devices`
`Idempotency-Key`required	header	string
`Prefer`	header	string

Request body application/json required

Fields · PaymentRequest

amountinteger int64

JSON

{
  "amount": 1
}

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/terminals/1/payments' \
  -H 'Idempotency-Key: $(uuidgen)' \
  -H 'Prefer: wait=30' \
  -H 'Content-Type: application/json' \
  --data '{"amount":1}'

curl

curl -X POST 'https://cloud.hw-connector.ru/agent/api/v1/terminals/1/payments' \
  -H 'X-Api-Key: hwk_…' \
  -H 'X-Device-Id: 42' \
  -H 'Idempotency-Key: $(uuidgen)' \
  -H 'Prefer: wait=30' \
  -H 'Content-Type: application/json' \
  --data '{"amount":1}'

Emergency reversal of the last operation#

POST/api/v1/terminals/{id}/emergency-reversals

Operation

When the POS did not get the payment result (connection lost, hang): the terminal reverses its last operation

Parameters

Name	In	Type	Description
`id`required	path	integer int32	device number from `GET /api/v1/devices`
`Idempotency-Key`required	header	string
`Prefer`	header	string

Request body application/json required

Fields · EmergencyReversalRequest

amountinteger int64
paymentRefstring

JSON

{
  "amount": 1,
  "paymentRef": "string"
}

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/terminals/1/emergency-reversals' \
  -H 'Idempotency-Key: $(uuidgen)' \
  -H 'Prefer: wait=30' \
  -H 'Content-Type: application/json' \
  --data '{"amount":1,"paymentRef":"string"}'

curl

curl -X POST 'https://cloud.hw-connector.ru/agent/api/v1/terminals/1/emergency-reversals' \
  -H 'X-Api-Key: hwk_…' \
  -H 'X-Device-Id: 42' \
  -H 'Idempotency-Key: $(uuidgen)' \
  -H 'Prefer: wait=30' \
  -H 'Content-Type: application/json' \
  --data '{"amount":1,"paymentRef":"string"}'

Cancel a payment#

POST/api/v1/terminals/{id}/cancellations

Operation

The same day, before the settlement; the money is not charged

Parameters

Name	In	Type	Description
`id`required	path	integer int32	device number from `GET /api/v1/devices`
`Idempotency-Key`required	header	string
`Prefer`	header	string

Request body application/json required

Fields · ReversalRequest

amountinteger int64
paymentRefstringrequired
from 1

JSON

{
  "amount": 1,
  "paymentRef": "string"
}

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/terminals/1/cancellations' \
  -H 'Idempotency-Key: $(uuidgen)' \
  -H 'Prefer: wait=30' \
  -H 'Content-Type: application/json' \
  --data '{"amount":1,"paymentRef":"string"}'

curl

curl -X POST 'https://cloud.hw-connector.ru/agent/api/v1/terminals/1/cancellations' \
  -H 'X-Api-Key: hwk_…' \
  -H 'X-Device-Id: 42' \
  -H 'Idempotency-Key: $(uuidgen)' \
  -H 'Prefer: wait=30' \
  -H 'Content-Type: application/json' \
  --data '{"amount":1,"paymentRef":"string"}'

Last terminal slip#

GET/api/v1/terminals/{id}/last-slip

The slip of the last successful operation from the journal (payment, refund, cancellation, settlement, checkout) — to print it again

Parameters

Name	In	Type	Description
`id`required	path	integer int32	device number from `GET /api/v1/devices`

Response 200 application/json

Type: map → any value

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

Request example

curl

curl 'http://localhost:7790/api/v1/terminals/1/last-slip'

curl

curl 'https://cloud.hw-connector.ru/agent/api/v1/terminals/1/last-slip' \
  -H 'X-Api-Key: hwk_…' \
  -H 'X-Device-Id: 42'

QR code as a PNG image#

GET/api/v1/qr

text — what to encode, e.g. the payload from the qr event; size — side in pixels (100–1200)

Parameters

Name	In	Type	Description
`text`required	query	string
`size`	query	integer int32

Response 200

File.

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

Request example

curl

curl 'http://localhost:7790/api/v1/qr?text=text'

curl

curl 'https://cloud.hw-connector.ru/agent/api/v1/qr?text=text' \
  -H 'X-Api-Key: hwk_…' \
  -H 'X-Device-Id: 42'