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

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

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

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": "[email protected]",
  "store_id": "123",
  "shipping_sku": "SHIP-SKU-001"
}