The API at a glance
Choose an operation, check its result and open an example. The full guide follows below.
https://restapi.imaginaits.com/x-auth-token: YOUR_TOKEN| Method | Endpoint and example | Purpose | What to check |
|---|---|---|---|
| POST | /puttransaction.phpView cURL example | Create a payment or refundFull details → | status=ok registers the transaction; query its state afterwards. |
| GET | /statustransaction.phpView cURL example | Query a transactionFull details → | PENDING, PAID, CANCELLED or ERROR in Cloud. |
| GET | /listtransactions.phpView cURL example | List transactionsFull details → | Filter by status and continue with the returned cursor. |
| GET | /transactioncashflow.phpView cURL example | Query cash in, cash out and breakdownFull details → | Amounts and denominations reported for this transaction. |
| GET | /inventory.phpView cURL example | Query the reported inventoryFull details → | currency, recyclable, stacker and updated_at, when available. |
| POST | /canceltransaction.phpView cURL example | Compatible original cancellationFull details → | ok or CANCELLED alone does not confirm cancellation on the machine. |
| POST | /canceltransactionv2.phpView cURL example | CancelTransactionV2: request tracked cancellationFull details → | Keep operation_id. 202 means pending; retain Idempotency-Key. |
| GET | /v2.php?action=capabilitiesView cURL example | Discover available featuresFull details → | cancellation_tracking indicates whether tracking is enabled. |
| GET | /v2.php?action=transactionView cURL example | Query transaction and tracking togetherFull details → | Separates cloud_status from execution_confirmation. |
| GET | /v2.php?action=operationView cURL example | Query the cancellation requestFull details → | confirmed, execution_state, cash_flow and requires_review. |
Basic workflow
- Create the paymentamount: 2100 = EUR 21.00. Keep transaction_id.
- Check the resultQuery the same reference; HTTP 200 is not enough.
- Cancel if still pendingCancelTransactionV2 returns operation_id; query until confirmed=true.
202 = request registered. V1 CANCELLED = Cloud state. confirmed=true with CONFIRMED_BY_IMACASH = complete final ImaCash report.
Compatibility
POST /v2.php?action=cancel continues to work with the same contract. New integrations should use CancelTransactionV2: /canceltransactionv2.php. Existing integrations do not need changing.
Before you start
Select REST API Imagina in ImaCash Configuration > Integration. Cloud must authorize the licence for REST and accept its maintenance or trial entitlement. Copy that licence token; do not use the administrator password or the connector internal secret. If no token appears, note the version and numerical licence reference and contact support; do not create another sale or demo to diagnose it.
Connection, token and scope
The base URL is https://restapi.imaginaits.com/. Send x-auth-token with every request, over HTTPS. Each token is scoped to its licence. Keep it out of URLs, screenshots, logs, repositories and email. Examples use YOUR_TOKEN and fictional references. The documentation does not execute operations.
References and amounts
transaction_id is a stable reference for an operation in your application and licence: reuse exactly the same value after a timeout. user and terminal are business references for operator and workstation, not credentials or ImaCash permissions. amount uses minor units: 2100 means EUR 21.00 and -2100 a EUR 21.00 refund. method=1 means cash and method=0 card; recording a card transaction does not prove a bank payment.
Create and query a payment
Send JSON containing transaction_id, amount, user, terminal and method. status=ok confirms Cloud registration, not completed payment. Query the same reference and check both HTTP and JSON. A 409 on creation may mean the reference exists: query it and compare its data; do not submit another ID.
Example · POST /puttransaction.php
curl --request POST 'https://restapi.imaginaits.com/puttransaction.php' \
--header 'x-auth-token: YOUR_TOKEN' \
--header 'Content-Type: application/json' \
--data '{"transaction_id":"TX-DEMO-20261029-001","amount":2100,"user":"OPERATOR-01","terminal":"DESK-01","method":1}'Example · GET /statustransaction.php
curl 'https://restapi.imaginaits.com/statustransaction.php?transaction_id=TX-DEMO-20261029-001' --header 'x-auth-token: YOUR_TOKEN'Example · GET /transactioncashflow.php
curl 'https://restapi.imaginaits.com/transactioncashflow.php?transaction_id=TX-DEMO-20261029-001' --header 'x-auth-token: YOUR_TOKEN'Compatible V1 cancellation
V1 keeps POST /canceltransaction.php with transaction_id in the query or form, not JSON. Its ok response and CANCELLED state describe the Cloud record, not confirmation from the machine. Some rejections return HTTP 200 with status=error. Reading statustransaction or transactioncashflow afterwards does not turn that marker into physical proof. If money has already been received, ImaCash may defer cancellation and require its configured local authorization.
Example · POST /canceltransaction.php
curl --request POST 'https://restapi.imaginaits.com/canceltransaction.php?transaction_id=TX-DEMO-20261029-001' --header 'x-auth-token: YOUR_TOKEN'V2 cancellation tracking
Check cancellation_tracking in capabilities. Send a JSON cancellation request with Idempotency-Key, save operation_id and query it every two seconds, respecting Retry-After. HTTP 202 and REQUESTED only mean registration. Only confirmed=true with CONFIRMED_BY_IMACASH means an authenticated final ImaCash report was received with completion, currency and complete equal incoming/outgoing amounts. This is not independent hardware certification. An integrator token, progress report or Cloud state alone cannot confirm it.
| execution_state | Meaning and next action |
|---|---|
REQUESTED | Registered in Cloud; awaiting an ImaCash report. |
CONFIRMED_BY_IMACASH | ImaCash reports cancellation with completion and complete coherent cash flows. |
REJECTED_ALREADY_PAID | ImaCash reports a paid sale; cancellation is not confirmed. |
REPORTED_UNVERIFIED | An incomplete cancellation report was received; do not consider it confirmed. |
REVIEW_REQUIRED | Conflicting result or error; local review and support are required. |
Example · GET /v2.php?action=capabilities
curl 'https://restapi.imaginaits.com/v2.php?action=capabilities' --header 'x-auth-token: YOUR_TOKEN'Example · POST /canceltransactionv2.php
curl --request POST 'https://restapi.imaginaits.com/canceltransactionv2.php' \
--header 'x-auth-token: YOUR_TOKEN' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: cancel-DEMO-20261029-001' \
--header 'X-Request-ID: request-DEMO-001' \
--data '{"transaction_id":"TX-DEMO-20261029-001"}'Example · HTTP 202
{
"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
}
}Example · GET /v2.php?action=operation
curl 'https://restapi.imaginaits.com/v2.php?action=operation&operation_id=OPERATION_ID_FROM_RESPONSE' --header 'x-auth-token: YOUR_TOKEN'Example · HTTP 200
{
"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
}
}Example · GET /v2.php?action=transaction
curl 'https://restapi.imaginaits.com/v2.php?action=transaction&transaction_id=TX-DEMO-20261029-001' --header 'x-auth-token: YOUR_TOKEN'Retries, disconnections and authorization
Reuse the same key and reference when repeating a V2 request to recover its tracking. Reusing a key for another reference is rejected. A new key for a transaction with an existing cancellation request is also rejected; query the transaction for operation_id. If ImaCash is closed, cannot report or lacks detail, the request remains unconfirmed. After a reasonable wait, display pending review and retain the reference; do not repeat payments, refunds or restarts. V2 does not remove local passwords, permissions or protections.
Refund a paid sale
A PAID sale cannot be cancelled through this flow. Where a refund is required, create a new refund with its own reference and a negative amount, keeping the link to the original sale in your application. Registering the refund does not confirm cash dispensed: wait for ImaCash and check the amounts. Do not reuse the sale ID or simulate cancellation.
Example · POST /puttransaction.php
curl --request POST 'https://restapi.imaginaits.com/puttransaction.php' \
--header 'x-auth-token: YOUR_TOKEN' --header 'Content-Type: application/json' \
--data '{"transaction_id":"REFUND-DEMO-20261029-001","amount":-2100,"user":"OPERATOR-01","terminal":"DESK-01","method":1}'Errors and support
401: missing token. 403: unauthorized token or licence, possibly REST or maintenance entitlement. V2 404: missing or out-of-scope resource. 409: key, reference or state conflict; inspect error.code. 400: invalid parameters or JSON. 405: wrong method. 413: oversized body. 503: service or tracking unavailable, not proof of machine failure. A timeout or 5xx does not prove non-delivery. Give support request_id, operation_id, reference, time and HTTP code, without credentials.
Compatibility and published limits
V1 routes, authentication, fields and states remain. V2 adds a route without requiring migration or adding new values to V1 transaction_status. Its *_at_utc timestamps use UTC; created_at keeps its legacy format. device_state=not_observed does not mean disconnected. This extension provides no direct device commands or generic outbound webhooks; check capabilities. Missing amounts are null, not confirmed zeros. Some earlier clients omit zero amounts in their report: even after local completion, V2 keeps REPORTED_UNVERIFIED when that explicit value is missing.
Test before production
In an authorized test environment, check creation, querying, duplicate references, cancellation before and after cash insertion, rejected local authorization, offline ImaCash and a lost response. Ensure your application does not consider a payment cancelled on a 200/202 alone. Validate each device model and software version with its provider; an HTTP example is not a physical test.