ImaCash integration

REST API Imagina

Connect your POS or ERP to ImaCash through Cloud REST. Find requirements, payments, refunds, cancellation tracking and examples in your language.

REST API Imagina
ImaCash

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

Integration ready to move forward

If this integration matches your software, the next step is moving into real operation

We can help you validate the scope, confirm compatible hardware and prepare the next implementation step.