Session-Active Methods (Hardware)

These endpoints require a Session Token (the JWT obtained from the /api/session/start endpoint).

💵 Bill Reader (Cash In)

Open Bill Reader

POST [host]/api/session/bill-reader/open

Description: Enables the bill reader to start accepting cash. Once a bill is inserted, you have a 90-second window to either accept or reject it while it is held in the intermediate channel (escrow).

Security

Type	Header	Value
Session Token	`Authorization`	`Bearer <your_session_token>`

Body (JSON)

{
  "amount": 10,
  "callback": "[https://your-api.com/callback](https://your-api.com/callback)" // Optional
}

💳 TPV (Card Payments)

Prepare Payment

POST [host]/api/session/tpv/prepare

Description: Activates the PIN pad to initiate a card payment. The terminal will remain active for a maximum of 2 minutes.

Security

Type	Header	Value
Session Token	`Authorization`	`Bearer <your_session_token>`

Body (JSON)

{
  "amount": 10,
  "callback": "[https://your-api.com/callback](https://your-api.com/callback)" // Optional
}

🗂️ Card Dispenser

Prepare Card

POST [host]/api/session/dispenser/prepare

Description: Retrieves a card from the hopper and moves it to the internal reader position. Once the card is "prepared," it can be read, dispensed, or discarded.

Security

Type	Header	Value
Session Token	`Authorization`	`Bearer <your_session_token>`

Read Card Barcode

GET [host]/api/session/barcode-reader/read

Description: Reads the barcode of the card that is currently in the "prepared" position inside the dispenser.

Response Example (200)

{
    "success": true,
    "barcode": "8412345678901",
    "request_id": "e1f4f2b962b400714301bd3dcb143f7"
}

🖨️ Printer

Print PDF

POST [host]/api/session/printer/print-pdf

Description: Sends a PDF document to the kiosk's thermal printer.

Security

Type	Header	Value
Session Token	`Authorization`	`Bearer <your_session_token>`

Body (JSON)

Field	Type	Description
`pdf`	`string`	The document encoded in Base64. Must include the prefix `data:application/pdf;base64,`.

Request Body Example

{
  "pdf": "data:application/pdf;base64,JVBERi0xLjQKJ..."
}

📸 Cameras & Scanner (Base64 Images)

These endpoints allow you to capture images from the different optical devices installed in the kiosk. All images are returned as Base64 strings.

Scan Document

GET [host]/api/session/scanner/scan

Description: Triggers the document scanner to capture an image of the placed ID or document.

Response Example (200)

{
    "success": true,
    "message": "Scan done",
    "image": "data:image/jpeg;base64,/9j/4QAYRXhpZg...",
    "request_id": "g1f4f2b962b400714301bd3dcb143f9"
}