IVR Hooks

Interactive Voice Response (IVR) payment integration endpoints

Retrieve Pre-Order Details for IVR Payment

post

Returns the pre-order details for an order number, including the product list and total price, so that the IVR system can present order information to the customer during the payment call.

How It Works:

1. Validates the request structure and IVR credentials.

2. Validates that the order number is provided.

3. Retrieves the pre-order session from cache using the order number.

4. Validates the pre-order state: payment option must be set, must be of cash register type, and the basket must not have changed.

5. Returns the product list and total order price.

Authentication: IVR credentials are configured via the IVR_USERNAME and IVR_PASSWORD server settings.

Error Handling: All responses return HTTP 200. Check result.success to determine whether the request succeeded. On failure, productlist is empty and orderprice is 0.0.

Possible error messages (on failure):

Error Message	Cause
Input invalid	Missing or invalid request fields
User invalid	IVR credentials do not match
Order number invalid	The orderNumber field is empty
Order not found	Order number not found in the pre-order cache
Order Not Found	Pre-order session not found
PaymentOption is null	No payment option set on the pre-order
PaymentOption is not valid...	Payment option is not of cash register type
Basket Changed	Basket contents changed since the pre-order was created

Body

application/json

usernamestringRequired

IVR integration username.

Example: ivr_user

passwordstringRequired

IVR integration password.

Example: ivr_password

orderNumberstringRequired

The order number for which to retrieve pre-order details.

Example: ORD-2024-001234

Responses

200

Pre-order product list and total price on success, or an error result on failure. Check result.success to determine the outcome.

application/json

Returned for both successful and failed IVR pre-order lookups. Check result.success to determine the outcome.

orderpricenumberOptional

Total order price including discounts. 0.0 on failure.

Example: 389.97

post

/hooks/ivr/pre_order/

HTTPcURLJavaScriptPython

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

{
  "username": "ivr_user",
  "password": "ivr_password",
  "orderNumber": "ORD-2024-001234"
}

200

Pre-order product list and total price on success, or an error result on failure. Check result.success to determine the outcome.

{
  "result": {
    "success": true,
    "errortext": ""
  },
  "productlist": [
    {
      "productnumber": "SKU-001",
      "discountedprice": 149.99,
      "realprice": 149.99,
      "quantity": 2,
      "productname": "Cotton T-Shirt"
    },
    {
      "productnumber": "SKU-002",
      "discountedprice": 89.99,
      "realprice": 99.99,
      "quantity": 1,
      "productname": "Denim Jacket"
    }
  ],
  "orderprice": 389.97
}

Submit IVR Payment Result

post

Records the outcome of an IVR (Interactive Voice Response) payment and creates a transaction entry.

How It Works:

1. Validates the request structure and IVR credentials.

2. Verifies that the success flag is set to true.

3. Retrieves the pre-order session associated with the order number from cache.

4. Validates the pre-order state: payment option must be set, must be of cash register type, and the basket must not have changed.

5. Records the transaction with the reference number, staff ID, and payment amount.

Authentication: IVR credentials are configured via the IVR_USERNAME and IVR_PASSWORD server settings. These are separate from the standard cash register credentials.

Error Handling: All responses return HTTP 200. Check orderResultResponse.result.success to determine whether the request succeeded.

Possible error messages (on failure):

Error Message	Cause
Input invalid	Missing or invalid request fields
User invalid	IVR credentials do not match
Success must be true	The success field in the request was false
Order Not Found	Order number not found in the pre-order cache
Order Not Found	Pre-order session not found
PaymentOption is null	No payment option set on the pre-order
PaymentOption is not valid...	Payment option is not of cash register type
Basket Changed	Basket contents changed since the pre-order was created

Body

application/json

usernamestringRequired

IVR integration username.

Example: ivr_user

passwordstringRequired

IVR integration password.

Example: ivr_password

Responses

200

Response for both successful and failed IVR payment submissions. Check orderResultResponse.result.success to determine the outcome.

application/json

Returned for both successful and failed IVR payment result submissions. Check orderResultResponse.result.success to determine the outcome.

post

/hooks/ivr/complete/

HTTPcURLJavaScriptPython

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

{
  "username": "ivr_user",
  "password": "ivr_password",
  "orderResultRequest": {
    "orderNumber": "ORD-2024-001234",
    "referenceNumber": "REF-20240615-001",
    "staffId": "STAFF-42",
    "success": true
  }
}

200

Response for both successful and failed IVR payment submissions. Check orderResultResponse.result.success to determine the outcome.

{
  "orderResultResponse": {
    "result": {
      "success": true,
      "errortext": ""
    }
  }
}