{ "openapi": "3.1.0", "info": { "title": "Imagina REST API", "description": "ImaCash REST API. V1 routes and payloads remain compatible. Read the integration guide at https://restapi.imaginaits.com/docs/. HTTP acceptance, Cloud status and an ImaCash execution report are distinct. Use x-auth-token for your own licence; user and terminal are business references, not credentials. Never resend money after an uncertain response.", "version": "1.1.1", "x-logo": { "url": "/docs/icon.png", "backgroundColor": "#FFFFFF", "altText": "Imagina IT Logo" }, "contact": { "name": "Imagina IT", "url": "https://imaginaits.com/contacto", "email": "info@imaginaits.com" } }, "servers": [ { "url": "https://restapi.imaginaits.com", "description": "" } ], "tags": [ { "name": "Transactions", "description": "Operations related to transaction management." }, { "name": "Machine related data", "description": "Endpoints to retrieve detailed data from cash drawer connected to Imagina IT applications." } ], "components": { "securitySchemes": { "ApiTokenAuth": { "type": "apiKey", "in": "header", "name": "x-auth-token", "description": "Include your authentication token in the header as follows:\n`x-auth-token: `" } }, "schemas": { "Status": { "type": "string", "enum": [ "PENDING", "PAID", "CANCELLED", "ERROR" ] }, "Method": { "type": "integer", "description": "Payment method. 1 = Cash, 0 = Card.", "enum": [ 0, 1 ], "example": 1 }, "DenominationEntry": { "type": "object", "description": "Normalized denomination line. Monetary values use minor units (cents): 1 = EUR 0.01, 100 = EUR 1.00, 500 = EUR 5.00.", "properties": { "denomination": { "type": "integer", "example": 100, "description": "Denomination value in minor units." }, "denomination_value": { "type": "string", "example": "1.00", "description": "Denomination value formatted in EUR." }, "type": { "type": "string", "enum": [ "coin", "banknote" ], "example": "coin" }, "quantity": { "type": "integer", "example": 1 }, "amount": { "type": "integer", "example": 100, "description": "denomination * quantity, in minor units." }, "amount_value": { "type": "string", "example": "1.00", "description": "Line amount formatted in EUR." } } }, "CashFlowEvent": { "type": "object", "description": "A cash movement event. If the machine sends denominations.events, the endpoint returns that stored sequence; otherwise it derives events from aggregated denominations.", "properties": { "type": { "type": "string", "enum": [ "inserted", "returned", "completed", "cancelled", "error" ], "example": "inserted" }, "denomination": { "type": [ "integer", "null" ], "example": 500 }, "denomination_value": { "type": [ "string", "null" ], "example": "5.00" }, "quantity": { "type": "integer", "example": 1 }, "amount": { "type": "integer", "example": 500 }, "amount_value": { "type": "string", "example": "5.00" }, "total_inserted": { "type": [ "integer", "null" ], "example": 601 }, "total_returned": { "type": [ "integer", "null" ], "example": 64 }, "elapsed_ms": { "type": [ "integer", "null" ], "example": 820 }, "at": { "type": [ "string", "null" ], "example": "2026-04-29T10:22:13Z" } } }, "CashFlowTimings": { "type": "object", "properties": { "started_at": { "type": [ "string", "null" ], "example": "2026-04-29T10:22:10Z" }, "completed_at": { "type": [ "string", "null" ], "example": "2026-04-29T10:22:18Z" }, "duration_ms": { "type": [ "integer", "null" ], "example": 8420 }, "change_return_started_at": { "type": [ "string", "null" ], "example": "2026-04-29T10:22:17Z" }, "change_return_completed_at": { "type": [ "string", "null" ], "example": "2026-04-29T10:22:18Z" }, "change_return_elapsed_ms": { "type": [ "integer", "null" ], "example": 930 } } }, "TransactionCashFlowResponse": { "type": "object", "properties": { "status": { "type": "string", "example": "ok" }, "data": { "type": "object", "properties": { "transaction_id": { "type": "string", "example": "TX-CASH-537" }, "currency": { "type": "string", "example": "EUR" }, "transaction_status": { "$ref": "#/components/schemas/Status" }, "operation_status": { "type": "string", "enum": [ "pending", "completed", "cancelled", "error" ], "example": "completed" }, "operation_message": { "type": "string", "example": "Operation completed" }, "target_amount": { "type": "integer", "example": 537 }, "target_amount_value": { "type": "string", "example": "5.37" }, "amount_inserted": { "type": "integer", "example": 601 }, "amount_inserted_value": { "type": "string", "example": "6.01" }, "amount_remaining": { "type": "integer", "example": 0 }, "amount_remaining_value": { "type": "string", "example": "0.00" }, "overpaid_amount": { "type": "integer", "example": 64 }, "overpaid_amount_value": { "type": "string", "example": "0.64" }, "change_returned": { "type": "object", "properties": { "amount": { "type": "integer", "example": 64 }, "amount_value": { "type": "string", "example": "0.64" }, "denominations": { "type": "array", "items": { "$ref": "#/components/schemas/DenominationEntry" } } } }, "inserted_denominations": { "type": "array", "items": { "$ref": "#/components/schemas/DenominationEntry" } }, "returned_denominations": { "type": "array", "items": { "$ref": "#/components/schemas/DenominationEntry" } }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/CashFlowEvent" } }, "event_source": { "type": "string", "enum": [ "stored", "derived", "none" ], "example": "stored" }, "timings": { "$ref": "#/components/schemas/CashFlowTimings" }, "user": { "type": "string", "example": "Operator1" }, "terminal": { "type": "string", "example": "Terminal1" }, "created_at": { "type": "string", "example": "2026-04-29 10:22:10" }, "raw_denominations": { "type": [ "object", "null" ], "description": "Original denominations JSON stored by the machine." } } } } }, "V2Operation": { "type": "object", "required": [ "operation_id", "transaction_id", "execution_state", "confirmed", "cash_flow", "requires_review" ], "properties": { "operation_id": { "type": "string", "pattern": "^[a-f0-9]{32}$" }, "transaction_id": { "type": "string" }, "execution_state": { "type": "string", "enum": [ "REQUESTED", "CONFIRMED_BY_IMACASH", "REJECTED_ALREADY_PAID", "REPORTED_UNVERIFIED", "REVIEW_REQUIRED" ] }, "confirmed": { "type": "boolean", "description": "True only after a complete, coherent authenticated final ImaCash cancellation report; never from Cloud status alone." }, "confirmation_source": { "type": "string", "nullable": true, "enum": [ "imacash_report", null ] }, "reported_state": { "type": "string", "nullable": true, "enum": [ "CANCELLED", "PAID", "ERROR", null ] }, "requested_at_utc": { "type": "string", "description": "UTC, YYYY-MM-DD HH:mm:ss.ffffff" }, "reported_at_utc": { "type": "string", "nullable": true, "description": "UTC server report-reception time, not the device clock." }, "cash_flow": { "type": "object", "required": [ "received_minor", "returned_minor", "currency" ], "properties": { "received_minor": { "type": "integer", "nullable": true, "minimum": 0, "maximum": 2147483647 }, "returned_minor": { "type": "integer", "nullable": true, "minimum": 0, "maximum": 2147483647 }, "currency": { "type": "string", "nullable": true, "pattern": "^[A-Z]{3}$" } } }, "requires_review": { "type": "boolean" } } }, "V2Capabilities": { "type": "object", "required": [ "api_version", "legacy_contract", "device_state", "cancellation_tracking", "idempotent_cancellation_requests", "imacash_report_required", "direct_device_commands", "outbound_webhooks" ], "properties": { "api_version": { "type": "string", "enum": [ "2.0" ] }, "legacy_contract": { "type": "string", "enum": [ "unchanged" ] }, "device_state": { "type": "string", "enum": [ "not_observed" ] }, "cancellation_tracking": { "type": "boolean" }, "idempotent_cancellation_requests": { "type": "boolean" }, "imacash_report_required": { "type": "boolean" }, "direct_device_commands": { "type": "boolean" }, "outbound_webhooks": { "type": "boolean" } } }, "V2Transaction": { "type": "object", "required": [ "transaction_id", "amount_minor", "cloud_status", "user", "terminal", "created_at", "device_state", "execution_confirmation", "cancellation" ], "properties": { "transaction_id": { "type": "string" }, "amount_minor": { "type": "integer", "nullable": true, "description": "Signed minor units; null if legacy storage is ambiguous." }, "cloud_status": { "type": "string", "enum": [ "PENDING", "PAID", "CANCELLED", "ERROR" ] }, "user": { "type": "string", "nullable": true }, "terminal": { "type": "string", "nullable": true }, "created_at": { "type": "string", "nullable": true }, "device_state": { "type": "string", "enum": [ "not_observed" ] }, "execution_confirmation": { "type": "string", "enum": [ "imacash_report", "not_available" ] }, "cancellation": { "oneOf": [ { "$ref": "#/components/schemas/V2Operation" }, { "type": "object", "nullable": true, "enum": [ null ] } ] } } }, "V2Envelope": { "type": "object", "required": [ "status", "api_version", "request_id", "data" ], "properties": { "status": { "type": "string", "enum": [ "ok" ] }, "api_version": { "type": "string", "enum": [ "2.0" ] }, "request_id": { "type": "string" }, "data": { "oneOf": [ { "$ref": "#/components/schemas/V2Capabilities" }, { "$ref": "#/components/schemas/V2Operation" }, { "$ref": "#/components/schemas/V2Transaction" } ] } } }, "V2Error": { "type": "object", "required": [ "status", "api_version", "request_id", "error" ], "properties": { "status": { "type": "string", "enum": [ "error" ] }, "api_version": { "type": "string", "enum": [ "2.0" ] }, "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine code. Do not parse human messages." } } } } } } }, "security": [ { "ApiTokenAuth": [] } ], "paths": { "/listtransactions.php": { "get": { "summary": "List transactions", "description": "This endpoint is used to list transactions within a specified date range.", "tags": [ "Transactions" ], "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/Status" } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time", "example": "2025-08-01 00:00:00" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time", "example": "2025-08-31 23:59:59" } }, { "name": "cursor", "in": "query", "required": false, "description": "Cursor used for pagination. The response may include a next cursor value to retrieve subsequent results.", "schema": { "type": "string", "example": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJwYWdpbmF0aW9uIiwiaWF0IjoxNzYyODc3ODg3LCJleHAiOjE3NjI4NzgxODcsImlzcyI6InJlc3RhcGkuaW1hZ2luYWl0cy5jb20iLCJwb3NpdGlvbiI6MTB9.2rvIRR-zHYFKRNZMcUy49afI19Z2B7ox9x6bnCt7paU" } } ], "x-code-samples": { "lang": "cURL", "label": "Example", "source": "curl -X GET \"https://restapi.imaginaits.com/listtransactions.php?from=2025-08-01%2000:00:00&to=2025-08-31%2023:59:59\" -H \"x-auth-token: YOUR_TOKEN\"" }, "responses": { "200": { "description": "Transactions listed successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "ok" }, "data": { "type": "array", "items": { "type": "object", "properties": { "transaction_id": { "type": "string", "example": "TX123456789" }, "amount": { "type": "integer", "example": 4999 }, "status": { "$ref": "#/components/schemas/Status" }, "user": { "type": "string", "example": "Operator1" }, "terminal": { "type": "string", "example": "Terminal1" }, "method": { "type": "string", "description": "Payment method. 1 = Cash, 0 = Card.", "example": "1" }, "denominations": { "type": "object", "example": null }, "created_at": { "type": "string", "example": "2025-08-07 12:39:16" } } } }, "next_cursor": { "type": "string", "nullable": true, "example": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJwYWdpbmF0aW9uIiwiaWF0IjoxNzYyODc3ODg3LCJleHAiOjE3NjI4NzgxODcsImlzcyI6InJlc3RhcGkuaW1hZ2luYWl0cy5jb20iLCJwb3NpdGlvbiI6MjB9.tjQ0ce3Zq9mIYK1q9kYKexYj1cj2j0QvVtKLnYcG1X8" } } } } } }, "401": { "description": "Unauthorized - Invalid or missing authentication token", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Invalid or missing authentication token" } } } } } } } } }, "/statustransaction.php": { "get": { "summary": "Get transaction status", "description": "This endpoint is used to retrieve the status of a transaction.", "tags": [ "Transactions" ], "parameters": [ { "name": "transaction_id", "in": "query", "required": true, "schema": { "type": "string", "example": "TX123456789" }, "description": "Transaction ID to query." } ], "responses": { "200": { "description": "Transaction status retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "ok" }, "data": { "type": "object", "properties": { "transaction_id": { "type": "string", "example": "TX123456789" }, "amount": { "type": "integer", "example": 4999 }, "user": { "type": "string", "example": "Operator1" }, "terminal": { "type": "string", "example": "Terminal1" }, "created_at": { "type": "string", "example": "2025-08-07 12:39:16" }, "transaction_status": { "type": "string", "enum": [ "PENDING", "PAID", "CANCELLED", "ERROR" ] }, "denominations": { "type": "object", "example": null } } } } } } } }, "400": { "description": "Missing transaction_id parameter", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "transaction_id is required and cannot be empty" } } } } } }, "401": { "description": "Unauthorized - Invalid or missing authentication token", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Invalid or missing authentication token" } } } } } }, "404": { "description": "Transaction ID does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "This transaction does not exist" } } } } } } } } }, "/puttransaction.php": { "post": { "summary": "Create a transaction", "description": "This endpoint is used to create a new transaction.", "tags": [ "Transactions" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "transaction_id": { "type": "string", "example": "TX123456789" }, "amount": { "type": "integer", "example": 4999 }, "user": { "type": "string", "example": "Operator1" }, "terminal": { "type": "string", "example": "Terminal1" }, "method": { "type": "integer", "description": "Payment method. 1 = Cash, 0 = Card.", "example": 1 } }, "required": [ "transaction_id", "amount", "user", "terminal", "method" ] } } } }, "responses": { "200": { "description": "Transaction created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "message": { "type": "string", "example": "Transaction created successfully" } } } } } }, "401": { "description": "Unauthorized - Invalid or missing authentication token", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Invalid or missing authentication token" } } } } } }, "409": { "description": "Transaction ID already exists", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Transaction already exists" } } } } } } } } }, "/canceltransaction.php": { "post": { "summary": "Cancel a transaction", "description": "V1 compatibility: changes the Cloud transaction marker to CANCELLED. This does NOT confirm cancellation on the device. transaction_id is a query/form parameter, not JSON. Some business rejections return HTTP 200 with status=error. For opt-in tracking use POST /canceltransactionv2.php (CancelTransactionV2), then GET /v2.php?action=operation.", "tags": [ "Transactions" ], "parameters": [ { "name": "transaction_id", "in": "query", "schema": { "type": "string", "example": "TX123456789" }, "description": "Transaction ID to cancel." } ], "responses": { "200": { "description": "Transaction cancelled successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "ok" }, "message": { "type": "string", "example": "Transaction cancelled successfully" } } } } } }, "400": { "description": "Missing transaction_id parameter", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "transaction_id not provided" } } } } } }, "403": { "description": "Transaction not found or not authorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Transaction not found or not authorized" } } } } } }, "409": { "description": "Transaction cannot be cancelled because it is already processed", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Transaction cannot be cancelled because it is already processed" }, "current_status": { "type": "string", "example": "PAID" } } } } } }, "500": { "description": "Database error while cancelling transaction", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Database error while cancelling transaction" } } } } } } } } }, "/inventory.php": { "get": { "summary": "Retrieve machine inventory", "description": "Returns the latest stored inventory (coins and banknotes) associated with the provided authentication token.", "tags": [ "Machine related data" ], "responses": { "200": { "description": "Inventory retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "ok" }, "data": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer", "example": 15 }, "token": { "type": "string", "example": "SAMPLE_TOKEN_123" }, "recyclable": { "type": [ "object", "null" ], "example": { "1": 10, "2": 5, "100": 12 } }, "stacker": { "type": [ "object", "null" ], "example": { "5": 3, "10": 1, "20": 0 } }, "datetime": { "type": "string", "example": "2025-08-07 12:39:16" } } } } } } } }, "401": { "description": "Unauthorized - Invalid or missing authentication token", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Invalid or missing authentication token" } } } } } }, "500": { "description": "Database error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Error de base de datos" } } } } } } } } }, "/transactioncashflow.php": { "get": { "summary": "Get transaction cash flow", "description": "Returns the detailed cash flow for one transaction: inserted denominations, running cash events, final total, returned change, returned denominations and timing information. Amounts are expressed in minor units (cents): 1 = EUR 0.01, 100 = EUR 1.00, 500 = EUR 5.00. The endpoint reads the denominations JSON stored for the transaction. ImaCash can populate it through its internal status update with keys such as inserted, returned, amount_paid, target_amount, events, completed_at and change_return_elapsed_ms.", "tags": [ "Transactions" ], "parameters": [ { "name": "transaction_id", "in": "query", "required": true, "schema": { "type": "string", "example": "TX-CASH-537" }, "description": "Transaction ID to inspect." } ], "x-code-samples": { "lang": "cURL", "label": "Example", "source": "curl -X GET \"https://restapi.imaginaits.com/transactioncashflow.php?transaction_id=TX-CASH-537\" -H \"x-auth-token: YOUR_TOKEN\"" }, "responses": { "200": { "description": "Transaction cash flow retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionCashFlowResponse" }, "example": { "status": "ok", "data": { "transaction_id": "TX-CASH-537", "currency": "EUR", "transaction_status": "PAID", "operation_status": "completed", "operation_message": "Operation completed", "target_amount": 537, "target_amount_value": "5.37", "amount_inserted": 601, "amount_inserted_value": "6.01", "amount_remaining": 0, "amount_remaining_value": "0.00", "overpaid_amount": 64, "overpaid_amount_value": "0.64", "change_returned": { "amount": 64, "amount_value": "0.64", "denominations": [ { "denomination": 50, "denomination_value": "0.50", "type": "coin", "quantity": 1, "amount": 50, "amount_value": "0.50" }, { "denomination": 10, "denomination_value": "0.10", "type": "coin", "quantity": 1, "amount": 10, "amount_value": "0.10" }, { "denomination": 2, "denomination_value": "0.02", "type": "coin", "quantity": 2, "amount": 4, "amount_value": "0.04" } ] }, "inserted_denominations": [ { "denomination": 1, "denomination_value": "0.01", "type": "coin", "quantity": 1, "amount": 1, "amount_value": "0.01" }, { "denomination": 100, "denomination_value": "1.00", "type": "coin", "quantity": 1, "amount": 100, "amount_value": "1.00" }, { "denomination": 500, "denomination_value": "5.00", "type": "banknote", "quantity": 1, "amount": 500, "amount_value": "5.00" } ], "returned_denominations": [ { "denomination": 50, "denomination_value": "0.50", "type": "coin", "quantity": 1, "amount": 50, "amount_value": "0.50" }, { "denomination": 10, "denomination_value": "0.10", "type": "coin", "quantity": 1, "amount": 10, "amount_value": "0.10" }, { "denomination": 2, "denomination_value": "0.02", "type": "coin", "quantity": 2, "amount": 4, "amount_value": "0.04" } ], "events": [ { "type": "inserted", "denomination": 1, "denomination_value": "0.01", "quantity": 1, "amount": 1, "amount_value": "0.01", "total_inserted": 1, "total_returned": null, "elapsed_ms": 210, "at": "2026-04-29T10:22:11Z" }, { "type": "inserted", "denomination": 100, "denomination_value": "1.00", "quantity": 1, "amount": 100, "amount_value": "1.00", "total_inserted": 101, "total_returned": null, "elapsed_ms": 1420, "at": "2026-04-29T10:22:12Z" }, { "type": "inserted", "denomination": 500, "denomination_value": "5.00", "quantity": 1, "amount": 500, "amount_value": "5.00", "total_inserted": 601, "total_returned": null, "elapsed_ms": 2980, "at": "2026-04-29T10:22:13Z" }, { "type": "returned", "denomination": 50, "denomination_value": "0.50", "quantity": 1, "amount": 50, "amount_value": "0.50", "total_inserted": 601, "total_returned": 50, "elapsed_ms": 7900, "at": "2026-04-29T10:22:18Z" }, { "type": "completed", "denomination": null, "denomination_value": null, "quantity": 0, "amount": 0, "amount_value": "0.00", "total_inserted": 601, "total_returned": 64, "elapsed_ms": 8420, "at": "2026-04-29T10:22:18Z" } ], "event_source": "stored", "timings": { "started_at": "2026-04-29T10:22:10Z", "completed_at": "2026-04-29T10:22:18Z", "duration_ms": 8420, "change_return_started_at": "2026-04-29T10:22:17Z", "change_return_completed_at": "2026-04-29T10:22:18Z", "change_return_elapsed_ms": 930 }, "user": "Operator1", "terminal": "Terminal1", "created_at": "2026-04-29 10:22:10", "raw_denominations": { "target_amount": 537, "amount_paid": 601, "inserted": { "1": 1, "100": 1, "500": 1 }, "returned": { "50": 1, "10": 1, "2": 2 }, "change_return_elapsed_ms": 930 } } } } } }, "400": { "description": "Missing transaction_id parameter" }, "401": { "description": "Unauthorized - missing authentication token" }, "403": { "description": "Forbidden - invalid or unauthorized authentication token" }, "404": { "description": "Transaction ID does not exist for the authenticated license" }, "500": { "description": "Database error" } } } }, "/v2.php": { "get": { "tags": [ "Transactions" ], "summary": "Optional V2 discovery and tracking", "description": "capabilities reports implemented Cloud features, not device connectivity. transaction returns Cloud status separately from cancellation tracking. operation returns an own operation; only confirmed=true with CONFIRMED_BY_IMACASH confirms a complete coherent authenticated ImaCash final report. Missing amounts remain null. No general outbound webhooks or direct device commands are provided.", "parameters": [ { "name": "action", "in": "query", "schema": { "type": "string", "enum": [ "capabilities", "transaction", "operation" ], "default": "capabilities" } }, { "name": "transaction_id", "in": "query", "schema": { "type": "string" } }, { "name": "operation_id", "in": "query", "schema": { "type": "string", "pattern": "^[a-f0-9]{32}$" } }, { "name": "X-Request-ID", "in": "header", "schema": { "type": "string", "minLength": 8, "maxLength": 64 } } ], "responses": { "200": { "description": "Scoped data; inspect confirmation fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2Envelope" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" } } } }, "400": { "description": "Invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2Error" } } } }, "401": { "description": "Missing token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2Error" } } } }, "403": { "description": "Licence not authorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2Error" } } } }, "404": { "description": "Resource absent or outside scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2Error" } } } }, "503": { "description": "Tracking unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2Error" } } } } }, "x-codeSamples": [ { "lang": "Shell", "source": "curl 'https://restapi.imaginaits.com/v2.php?action=capabilities' --header 'x-auth-token: YOUR_TOKEN'" }, { "lang": "Shell", "source": "curl 'https://restapi.imaginaits.com/v2.php?action=operation&operation_id=OPERATION_ID_FROM_RESPONSE' --header 'x-auth-token: YOUR_TOKEN'" } ] }, "post": { "tags": [ "Transactions" ], "summary": "Compatibility alias for CancelTransactionV2", "description": "Existing alias retained: POST /v2.php?action=cancel. New integrations should use POST /canceltransactionv2.php. New optional contract. Requires action=cancel, JSON and Idempotency-Key (8-128 ASCII letters, numbers, dot, underscore, colon or hyphen). Reuse the same key and transaction reference after a timeout. HTTP 202 means REQUESTED, never physical confirmation. Keep operation_id and poll every two seconds. Existing local authorization and cash protections remain. A PAID transaction requires a separate refund flow.", "parameters": [ { "name": "action", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "cancel" ] } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 128 } }, { "name": "X-Request-ID", "in": "header", "schema": { "type": "string", "minLength": 8, "maxLength": 64 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "transaction_id" ], "properties": { "transaction_id": { "type": "string", "maxLength": 100 } } }, "example": { "transaction_id": "TX-DEMO-20261029-001" } } } }, "responses": { "202": { "description": "Request registered, confirmation pending", "content": { "application/json": { "example": { "status": "ok", "api_version": "2.0", "request_id": "request-DEMO-001", "data": { "operation_id": "0123456789abcdef0123456789abcdef", "transaction_id": "TX-DEMO-20261029-001", "execution_state": "REQUESTED", "confirmed": false, "confirmation_source": null, "reported_state": null, "requested_at_utc": "2026-10-29 09:00:00.000000", "reported_at_utc": null, "cash_flow": { "received_minor": null, "returned_minor": null, "currency": null }, "requires_review": false } }, "schema": { "$ref": "#/components/schemas/V2Envelope" } } } }, "200": { "description": "A repeated request already has a complete ImaCash confirmation", "content": { "application/json": { "example": { "status": "ok", "api_version": "2.0", "request_id": "request-DEMO-002", "data": { "operation_id": "0123456789abcdef0123456789abcdef", "transaction_id": "TX-DEMO-20261029-001", "execution_state": "CONFIRMED_BY_IMACASH", "confirmed": true, "confirmation_source": "imacash_report", "reported_state": "CANCELLED", "requested_at_utc": "2026-10-29 09:00:00.000000", "reported_at_utc": "2026-10-29 09:00:02.000000", "cash_flow": { "received_minor": 100, "returned_minor": 100, "currency": "EUR" }, "requires_review": false } }, "schema": { "$ref": "#/components/schemas/V2Envelope" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" } } } }, "400": { "description": "Invalid JSON, reference or idempotency key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2Error" } } } }, "401": { "description": "Missing token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2Error" } } } }, "403": { "description": "Licence not authorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2Error" } } } }, "404": { "description": "Transaction absent or ambiguous", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2Error" } } } }, "405": { "description": "Wrong method", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2Error" } } } }, "409": { "description": "idempotency_conflict, transaction_has_cancellation_request, transaction_not_pending or transaction_state_changed / operation_conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2Error" } } } }, "413": { "description": "Body exceeds 16384 bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2Error" } } } }, "503": { "description": "Tracking unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2Error" } } } } }, "x-codeSamples": [ { "lang": "Shell", "source": "curl --request POST 'https://restapi.imaginaits.com/canceltransactionv2.php' \\\n --header 'x-auth-token: YOUR_TOKEN' \\\n --header 'Content-Type: application/json' \\\n --header 'Idempotency-Key: cancel-DEMO-20261029-001' \\\n --header 'X-Request-ID: request-DEMO-001' \\\n --data '{\"transaction_id\":\"TX-DEMO-20261029-001\"}'" } ] } }, "/canceltransactionv2.php": { "post": { "tags": [ "Transactions" ], "summary": "CancelTransactionV2 — request cancellation with tracking", "description": "New optional contract. Requires JSON and Idempotency-Key (8-128 ASCII letters, numbers, dot, underscore, colon or hyphen). Reuse the same key and transaction reference after a timeout. HTTP 202 means REQUESTED, never physical confirmation. Keep operation_id and poll every two seconds. Existing local authorization and cash protections remain. A PAID transaction requires a separate refund flow.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 128 } }, { "name": "X-Request-ID", "in": "header", "schema": { "type": "string", "minLength": 8, "maxLength": 64 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "transaction_id" ], "properties": { "transaction_id": { "type": "string", "maxLength": 100 } } }, "example": { "transaction_id": "TX-DEMO-20261029-001" } } } }, "responses": { "202": { "description": "Request registered, confirmation pending", "content": { "application/json": { "example": { "status": "ok", "api_version": "2.0", "request_id": "request-DEMO-001", "data": { "operation_id": "0123456789abcdef0123456789abcdef", "transaction_id": "TX-DEMO-20261029-001", "execution_state": "REQUESTED", "confirmed": false, "confirmation_source": null, "reported_state": null, "requested_at_utc": "2026-10-29 09:00:00.000000", "reported_at_utc": null, "cash_flow": { "received_minor": null, "returned_minor": null, "currency": null }, "requires_review": false } }, "schema": { "$ref": "#/components/schemas/V2Envelope" } } } }, "200": { "description": "A repeated request already has a complete ImaCash confirmation", "content": { "application/json": { "example": { "status": "ok", "api_version": "2.0", "request_id": "request-DEMO-002", "data": { "operation_id": "0123456789abcdef0123456789abcdef", "transaction_id": "TX-DEMO-20261029-001", "execution_state": "CONFIRMED_BY_IMACASH", "confirmed": true, "confirmation_source": "imacash_report", "reported_state": "CANCELLED", "requested_at_utc": "2026-10-29 09:00:00.000000", "reported_at_utc": "2026-10-29 09:00:02.000000", "cash_flow": { "received_minor": 100, "returned_minor": 100, "currency": "EUR" }, "requires_review": false } }, "schema": { "$ref": "#/components/schemas/V2Envelope" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string" } } } }, "400": { "description": "Invalid JSON, reference or idempotency key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2Error" } } } }, "401": { "description": "Missing token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2Error" } } } }, "403": { "description": "Licence not authorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2Error" } } } }, "404": { "description": "Transaction absent or ambiguous", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2Error" } } } }, "405": { "description": "Wrong method", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2Error" } } } }, "409": { "description": "idempotency_conflict, transaction_has_cancellation_request, transaction_not_pending or transaction_state_changed / operation_conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2Error" } } } }, "413": { "description": "Body exceeds 16384 bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2Error" } } } }, "503": { "description": "Tracking unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2Error" } } } } }, "x-codeSamples": [ { "lang": "Shell", "source": "curl --request POST 'https://restapi.imaginaits.com/canceltransactionv2.php' \\\n --header 'x-auth-token: YOUR_TOKEN' \\\n --header 'Content-Type: application/json' \\\n --header 'Idempotency-Key: cancel-DEMO-20261029-001' \\\n --header 'X-Request-ID: request-DEMO-001' \\\n --data '{\"transaction_id\":\"TX-DEMO-20261029-001\"}'" } ], "operationId": "CancelTransactionV2" } } } }