> For the complete documentation index, see [llms.txt](https://apidocs.akinon.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://apidocs.akinon.com/commerce-openapis/orders/ivr-hooks.md). # IVR Hooks Interactive Voice Response (IVR) payment integration endpoints ## Retrieve Pre-Order Details for IVR Payment > 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 | ```json {"openapi":"3.1.0","info":{"title":"Orders API","version":"1.0.0"},"tags":[{"name":"IVR Hooks","description":"Interactive Voice Response (IVR) payment integration endpoints"}],"servers":[{"description":"Server base URL","url":"https://{commerce_url}","variables":{"commerce_url":{"default":"sandbox.akinon.com","description":"Commerce server URL"}}}],"security":[],"paths":{"/hooks/ivr/pre_order/":{"post":{"tags":["IVR Hooks"],"summary":"Retrieve Pre-Order Details for IVR Payment","description":"Returns the pre-order details for an order number, including the product list and\ntotal price, so that the IVR system can present order information to the customer\nduring the payment call.\n\n**How It Works:**\n1. Validates the request structure and IVR credentials.\n2. Validates that the order number is provided.\n3. Retrieves the pre-order session from cache using the order number.\n4. Validates the pre-order state: payment option must be set, must be of cash register type,\n and the basket must not have changed.\n5. Returns the product list and total order price.\n\n**Authentication:**\nIVR credentials are configured via the `IVR_USERNAME` and `IVR_PASSWORD` server settings.\n\n**Error Handling:**\nAll responses return HTTP 200. Check `result.success` to determine whether the request succeeded.\nOn failure, `productlist` is empty and `orderprice` is `0.0`.\n\n**Possible error messages (on failure):**\n\n| Error Message | Cause |\n|---------------|-------|\n| Input invalid | Missing or invalid request fields |\n| User invalid | IVR credentials do not match |\n| Order number invalid | The `orderNumber` field is empty |\n| Order not found | Order number not found in the pre-order cache |\n| Order Not Found | Pre-order session not found |\n| PaymentOption is null | No payment option set on the pre-order |\n| PaymentOption is not valid... | Payment option is not of cash register type |\n| Basket Changed | Basket contents changed since the pre-order was created |","operationId":"getIVRPreOrder","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IVRPreOrderRequest"}}}},"responses":{"200":{"description":"Pre-order product list and total price on success, or an error result on failure.\nCheck `result.success` to determine the outcome.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IVRPreOrderResponse"}}}}}}}},"components":{"schemas":{"IVRPreOrderRequest":{"type":"object","required":["username","password","orderNumber"],"properties":{"username":{"type":"string","description":"IVR integration username."},"password":{"type":"string","description":"IVR integration password."},"orderNumber":{"type":"string","description":"The order number for which to retrieve pre-order details."}}},"IVRPreOrderResponse":{"type":"object","description":"Returned for both successful and failed IVR pre-order lookups.\nCheck `result.success` to determine the outcome.","properties":{"result":{"type":"object","properties":{"success":{"type":"boolean","description":"`true` if the pre-order was found and is valid; `false` on failure."},"errortext":{"type":"string","description":"Human-readable error description. Empty string on success."}}},"productlist":{"type":"array","description":"List of products in the basket. Empty array on failure.","items":{"$ref":"#/components/schemas/IVRProductListItem"}},"orderprice":{"type":"number","description":"Total order price including discounts. `0.0` on failure."}}},"IVRProductListItem":{"type":"object","description":"Summary of a basket item as presented to the IVR system.","properties":{"productnumber":{"type":"string","description":"Product SKU code."},"discountedprice":{"type":"number","description":"Item total after applying any discounts."},"realprice":{"type":"number","description":"Item total before discounts."},"quantity":{"type":"integer","description":"Quantity of this product in the basket."},"productname":{"type":"string","description":"Display name of the product."}}}}}} ``` ## Submit IVR Payment Result > 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 | ```json {"openapi":"3.1.0","info":{"title":"Orders API","version":"1.0.0"},"tags":[{"name":"IVR Hooks","description":"Interactive Voice Response (IVR) payment integration endpoints"}],"servers":[{"description":"Server base URL","url":"https://{commerce_url}","variables":{"commerce_url":{"default":"sandbox.akinon.com","description":"Commerce server URL"}}}],"security":[],"paths":{"/hooks/ivr/complete/":{"post":{"tags":["IVR Hooks"],"summary":"Submit IVR Payment Result","description":"Records the outcome of an IVR (Interactive Voice Response) payment and creates a transaction entry.\n\n**How It Works:**\n1. Validates the request structure and IVR credentials.\n2. Verifies that the `success` flag is set to `true`.\n3. Retrieves the pre-order session associated with the order number from cache.\n4. Validates the pre-order state: payment option must be set, must be of cash register type,\n and the basket must not have changed.\n5. Records the transaction with the reference number, staff ID, and payment amount.\n\n**Authentication:**\nIVR credentials are configured via the `IVR_USERNAME` and `IVR_PASSWORD` server settings.\nThese are separate from the standard cash register credentials.\n\n**Error Handling:**\nAll responses return HTTP 200. Check `orderResultResponse.result.success` to determine\nwhether the request succeeded.\n\n**Possible error messages (on failure):**\n\n| Error Message | Cause |\n|---------------|-------|\n| Input invalid | Missing or invalid request fields |\n| User invalid | IVR credentials do not match |\n| Success must be true | The `success` field in the request was `false` |\n| Order Not Found | Order number not found in the pre-order cache |\n| Order Not Found | Pre-order session not found |\n| PaymentOption is null | No payment option set on the pre-order |\n| PaymentOption is not valid... | Payment option is not of cash register type |\n| Basket Changed | Basket contents changed since the pre-order was created |","operationId":"submitIVRPaymentResult","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IVRCompleteRequest"}}}},"responses":{"200":{"description":"Response for both successful and failed IVR payment submissions.\nCheck `orderResultResponse.result.success` to determine the outcome.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IVRCompleteResponse"}}}}}}}},"components":{"schemas":{"IVRCompleteRequest":{"type":"object","required":["username","password","orderResultRequest"],"properties":{"username":{"type":"string","description":"IVR integration username."},"password":{"type":"string","description":"IVR integration password."},"orderResultRequest":{"$ref":"#/components/schemas/IVROrderResultRequest"}}},"IVROrderResultRequest":{"type":"object","required":["orderNumber","referenceNumber","staffId"],"properties":{"orderNumber":{"type":"string","description":"The order number associated with the pre-order session."},"referenceNumber":{"type":"string","description":"Unique payment reference number assigned by the IVR system. Used as the transaction identifier."},"staffId":{"type":"string","description":"Identifier of the staff member who processed the payment."},"success":{"type":"boolean","default":true,"description":"Payment success indicator. Must be `true` for the request to be accepted."}}},"IVRCompleteResponse":{"type":"object","description":"Returned for both successful and failed IVR payment result submissions.\nCheck `orderResultResponse.result.success` to determine the outcome.","properties":{"orderResultResponse":{"type":"object","properties":{"result":{"type":"object","properties":{"success":{"type":"boolean","description":"`true` if the payment result was accepted; `false` on failure."},"errortext":{"type":"string","description":"Human-readable error description. Empty string on success."}}}}}}}}}} ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://apidocs.akinon.com/commerce-openapis/orders/ivr-hooks.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.