Cash Register Hooks

In-store cash register integration hook endpoints

Retrieve Pre-Order Details for Cash Register

post

Returns the full pre-order data for an order number that was previously generated by the get_order_number endpoint.

How It Works:

1. Validates the request credentials.

2. Looks up the pre-order session using the provided order number from cache.

3. Verifies that the payment option is set and is of cash register type.

4. Verifies the basket has not changed since the pre-order was created.

5. Returns the full pre-order details including basket, addresses, shipping, and payment data.

Installment Support: When installment payments are enabled for the cash register integration and an installment plan is selected on the pre-order, an additional card object is included in the response with details about the selected card and issuing bank.

Authentication: Credentials are validated against the CASH_REGISTER_AUTH_CONF dynamic setting (configurable via Admin Panel → Dynamic Settings).

Error Handling: On failure, the response contains error_code and error_message. HTTP status is always 200.

Error Code	Meaning
"402"	Basket has changed since the pre-order was created
"403"	Invalid credentials
"407"	No payment option set on the pre-order
"408"	Payment option is not of cash register type
"409"	Order number is missing from the request
"410"	Order number not found in the active pre-order cache
"411"	Pre-order session not found

Body

application/json

order_numberstringRequired

Order number previously generated by the get_order_number endpoint.

Example: ORD-2024-001234

usernamestringRequired

Integration username for authenticating the cash register request.

Example: cashier01

passwordstringRequired

Integration password for authenticating the cash register request.

Example: secret

Responses

200

Pre-order details on success, or an error response if validation fails. Check for the presence of error_code to determine if the request succeeded.

application/json

On success, contains order_number and pre_order (plus optional card). On failure, contains error_code and error_message.

order_numberstringOptional

The order number from the request. Present on success only.

Example: ORD-2024-001234

error_codestringOptional

Error code when the request fails. Not present on success.

Example: 403

error_messagestringOptional

Human-readable error description. Not present on success.

Example: User invalid

post/hooks/cash_register/pre_order/

HTTPcURLJavaScriptPython

POST /hooks/cash_register/pre_order/ HTTP/1.1
Host: sandbox.akinon.com
Content-Type: application/json
Accept: */*
Content-Length: 77

{
  "order_number": "ORD-2024-001234",
  "username": "cashier01",
  "password": "secret"
}

200

Pre-order details on success, or an error response if validation fails. Check for the presence of error_code to determine if the request succeeded.

{
  "order_number": "ORD-2024-001234",
  "pre_order": {
    "basket": {
      "pk": 5001,
      "total_amount": "299.99"
    },
    "shipping_address": {
      "pk": 101,
      "title": "Home",
      "first_name": "John",
      "last_name": "Doe",
      "line": "123 Main St"
    },
    "billing_address": {
      "pk": 101,
      "title": "Home"
    },
    "payment_option": {
      "pk": 3,
      "payment_type": "cash_register"
    },
    "shipping_amount": "9.99",
    "total_amount": "309.98",
    "unpaid_amount": "309.98",
    "currency_type_label": "Turkish Lira"
  }
}

Generate Cash Register Order Number

get

Generates a unique order number for the active basket and registers it in the pre-order session cache for subsequent cash register payment steps.

How It Works:

1. Generates a unique order number.

2. Retrieves the pre-order session linked to the current basket.

3. Validates that a cash register payment option is selected on the pre-order.

4. Stores the order number to pre-order mapping in cache (valid for 24 hours).

5. Returns the generated order number for use in the pre_order and complete steps.

Error Handling: On error, an error_code field is included in the response alongside error_message. The HTTP status code is always 200 — check for the presence of error_code to detect failures.

Error Code	Meaning
"407"	No payment option is set on the pre-order
"408"	Payment option is not of cash register type

Responses

200

Order number generated and cached, or an error if the pre-order state is invalid. Check for the presence of error_code to determine if the request succeeded.

application/json

Response from the order number generation endpoint. On success, only order_number is present. On failure, error_code and error_message are present; order_number may or may not be included.

order_numberstringOptional

Generated unique order number. Present on success and on error_code 408.

Example: ORD-2024-001234

error_codestringOptional

Error code when the pre-order state is invalid.

• "407": No payment option set.
• "408": Payment option is not cash register type.

Example: 407

error_messagestringOptional

Human-readable error description. Only present on failure.

Example: PaymentOption is null

get/hooks/cash_register/get_order_number/

HTTPcURLJavaScriptPython

GET /hooks/cash_register/get_order_number/ HTTP/1.1
Host: sandbox.akinon.com
Accept: */*

200

Order number generated and cached, or an error if the pre-order state is invalid. Check for the presence of error_code to determine if the request succeeded.

{
  "order_number": "ORD-2024-001234"
}

Complete Cash Register Payment

post

Finalizes a cash register payment and schedules order creation.

How It Works:

1. Validates the request credentials and order number.

2. Retrieves the pre-order session associated with the order number.

3. Verifies that the selected payment option is of cash register type.

4. Optionally applies promotions to the basket before calculating the amount.

5. Confirms the submitted amount matches the outstanding balance on the pre-order.

6. Verifies the basket has not changed since the pre-order was created.

7. Records the transaction and schedules order completion in the background.

Promotions: If promotions is provided, discounts are applied to the basket and the discounted_amount field is used for balance validation instead of amount.

Authentication: The username and password fields are validated against the CASH_REGISTER_AUTH_CONF dynamic setting (configurable via Admin Panel → Dynamic Settings).

Result Codes:

Code	Meaning
"0"	Payment accepted, order creation scheduled
402	Invalid request payload or basket has changed since pre-order
403	Invalid credentials
404	Order number not found in the active pre-order cache
405	Submitted amount does not match the outstanding balance
407	No payment option is set on the pre-order
408	Payment option is not of cash register type
411	Pre-order session not found
412	Error occurred while applying offer:

Note: This endpoint always returns HTTP 200. Both success and failure responses share the same structure — use the result field to distinguish them.

Body

application/json

transaction_idstringRequired

Unique transaction identifier assigned by the cash register terminal.

Example: TXN-20240615-001

order_numberstringRequired

The order number associated with the active pre-order session.

Example: ORD-2024-001234

usernamestringRequired

Integration username for authenticating the cash register request.

Example: cashier01

passwordstringRequired

Integration password for authenticating the cash register request.

Example: secret

amountstring · decimalRequired

Total amount to be paid. Must match the outstanding balance on the pre-order. Used for validation unless promotions are provided, in which case discounted_amount is used instead.

Example: 299.99

discounted_amountstring · decimalOptional

Discounted total after promotions are applied. Required when promotions is provided. Used for balance validation instead of amount.

Example: 249.99

terminal_codestringOptional

Identifier of the cash register terminal. Optional.

Example: TERM-001

Responses

200

Response for both successful and failed transactions. Check the result field: "0" indicates success; any other value is an error code.

application/json

Returned for both successful and failed cash register payment completions. The result field indicates the outcome.

transaction_idstring · nullableOptional

Transaction identifier from the request. null on failure.

Example: TXN-20240615-001

order_numberstring · nullableOptional

Order number from the request. null when the order was not resolved.

Example: ORD-2024-001234

resultone ofOptional

"0" on success. Integer error code on failure: 402 (invalid input or basket changed), 403 (invalid credentials), 404 (order not found), 405 (amount mismatch), 407 (payment option not set), 408 (wrong payment option type), 411 (pre-order not found), 412 (offer application error).

Example: 0

stringOptional

or

integerOptional

error_messagestringOptional

Human-readable error description. Empty string on success.

amountstring · nullableOptional

Confirmed payment amount. null on failure.

Example: 299.99

staff_idinteger · nullableOptional

Staff member identifier from the pre-order. null on failure.

Example: 232

staff_emailstring · nullableOptional

Email of the staff member associated with the pre-order. null on failure.

Example: [e-mail]

store_idstring · nullableOptional

Store identifier from the pre-order. null on failure.

Example: 123

shipping_skustring · nullableOptional

SKU of the configured shipping product for cash register payments. null if not configured or on failure.

Example: SHIP-SKU-001

post/hooks/cash_register/complete/

HTTPcURLJavaScriptPython

POST /hooks/cash_register/complete/ HTTP/1.1
Host: sandbox.akinon.com
Content-Type: application/json
Accept: */*
Content-Length: 158

{
  "transaction_id": "TXN-20240615-001",
  "order_number": "ORD-2024-001234",
  "username": "cashier01",
  "password": "secret",
  "amount": "299.99",
  "terminal_code": "TERM-001"
}

Simple Payment (no promotions)Payment with Promotions Applied

200

Response for both successful and failed transactions. Check the result field: "0" indicates success; any other value is an error code.

{
  "transaction_id": "TXN-20240615-001",
  "order_number": "ORD-2024-001234",
  "result": "0",
  "error_message": "",
  "amount": "299.99",
  "staff_id": 232,
  "staff_email": "[e-mail]",
  "store_id": "123",
  "shipping_sku": "SHIP-SKU-001"
}