Connect your software through Cloud REST
This page helps you prepare your integration. Cloud REST exchanges operations with ImaCash over HTTPS; it is separate from local ImaApi. The manual explains the contract and examples step by step.
Open the English manual · Download examples
Postman · cURL · Python · C# · JavaScript · OpenAPI reference in English
Requirements and your own token
In ImaCash Configuration > Integration select REST API Imagina. The licence needs Cloud authorisation for REST and eligible maintenance or trial access. Copy its own token and send it over HTTPS in x-auth-token; contact support if it is missing. It is not the administrator password and must stay out of URLs, screenshots, logs and repositories.
References and amounts
transaction_id identifies an operation from your software within the licence. user and terminal are business references for the operator and workstation, not credentials or local permissions. amount uses minor units: 2100 represents EUR 21.00. Recording a card does not prove a bank payment.
Create, query and collect payment
Create the operation and keep its reference. Successful registration in Cloud does not confirm payment. Query the same operation and check the ImaCash result and amounts before closing the sale. The manual provides the complete fields, methods and examples.
Request and confirm cancellation
V1 keeps its contract: CANCELLED describes Cloud. In V2, REQUESTED and HTTP 202 only register the request. Only CONFIRMED_BY_IMACASH with confirmed=true indicates a complete, consistent final report from ImaCash; it is not independent device certification. REJECTED_ALREADY_PAID means ImaCash reports that the sale was paid.
Refund a paid sale
This flow does not cancel a PAID sale. If a refund is due, create a refund with a new reference and a negative amount, retaining its link to the original sale. Wait for the ImaCash result and cash payout; recording the refund does not prove cash was returned.
Retries and uncertain results
Keep transaction_id and, in V2, the same Idempotency-Key. Store operation_id and check tracking before resending. A timeout does not prove the request failed to arrive. When tracking requires review, local checks and support are needed; resending does not clear it. Do not repeat payments or refunds or restart to resolve uncertainty.
Errors and support references
Check the JSON as well as HTTP: V1 may return 200 with status=error. The manual explains 400, 401, 403, 404, 405, 409, 413 and 503. For support retain request_id, operation_id, reference, time and HTTP code, excluding credentials and customer data.
V1, V2 and actual scope
V1 remains available and V2 is optional. An incomplete report, including an older client omitting zero amounts, may remain REPORTED_UNVERIFIED. device_state=not_observed proves neither connectivity nor disconnection. There are no direct device commands or general outgoing webhooks, and local permissions remain required. Validate the model and version with the supplier before live use.
What is the ImaCash REST API?
The REST API is the bridge that connects your POS system to ImaCash and cash control devices. It works with simple HTTP requests in JSON format, and all access is token protected to maintain security.
When to use this integration?
This API is intended for when your POS cannot connect directly with ImaCash due to differences in platform, architecture or technology. Instead of modifying your system, you use our API to communicate.
What are the requirements to integrate a POS to the ImaCash Rest API?
Validate that your software meets the technical standards necessary to seamlessly integrate with ImaCash using the API REST. There are only 6 requirements, check them out here.
Important
For direct physical operations with the machine (such as manual counting, emptying or maintenance), you will have to work with the ImaCash interface directly. The API manages data communication, not physical control of the hardware.
Configuration

IMPORTANT NOTE: Para que el POS pueda vincularse a ImaCash mediante la REST API de Imagina, necesitarás un token de autenticación que deberás solicitar a nuestro equipo.
POS Communication Flow - ImaCash using REST API
The following image illustrates how the communication between the POS system and ImaCash works through the REST API:

- The POS creates a transaction using POST /PutTransaction.php
- ImaCash waits and processes the transaction using GET /statusTransaction.php
- ImaCash updates the status after the process is completed
- The POS receives confirmation of the transaction status
Para más información sobre la implementación técnica y documentación completa de la API pulsa a continuación:
Review all the complete documentation here