Print

The Print API (Local Network) lets your POS control the terminal's thermal printer directly over your local network. No authentication headers are required — requests are trusted based on local network access.

Print jobs are asynchronous — the terminal returns 202 Accepted immediately and delivers the final status via webhook or polling.

Beta — Early Access

The Print API is in Beta for Mexico 🇲🇽. Do not deploy to production without coordinating with the Kushki integration team.

Base URL

http://{terminalIp}:6868

INFO

The Print API does not require Authorization or timestamp headers — unlike the Payment API.

Available operations

Operation	Endpoint	Description
Create Print Job	`POST /terminal/v1/print`	Queue a print job — returns `202 Accepted` immediately
Get Print Job Status	`GET /terminal/v1/print_job?print_job_id={id}`	Poll the current status of a queued job
Print Job Webhook	—	Inbound endpoint in your POS — receives completion events from the terminal

Create Print Job

Request

{
  "printJobId": "RECEIPT-20260101-001",
  "webhookUrl": "https://pos.micomercio.com.mx/webhooks/print",
  "skipIfBusy": false,
  "commands": [
    {
      "type": "text",
      "text": "MI COMERCIO MÉXICO\n",
      "align": "CENTER",
      "size": 32,
      "bold": true
    },
    {
      "type": "text",
      "text": "RFC: MCC800101HNG\n",
      "align": "CENTER",
      "size": 20
    },
    {
      "type": "divider",
      "dividerType": "SOLID"
    },
    {
      "type": "text",
      "text": "Fecha: 01/01/2026  Hora: 14:32\n",
      "align": "LEFT",
      "size": 20
    },
    {
      "type": "divider",
      "dividerType": "DOTTED"
    },
    {
      "type": "columns",
      "columns": [
        { "text": "Producto A", "weight": 2, "align": "LEFT" },
        { "text": "$ 500.00",   "weight": 1, "align": "RIGHT" }
      ]
    },
    {
      "type": "divider",
      "dividerType": "SOLID"
    },
    {
      "type": "columns",
      "columns": [
        { "text": "TOTAL",    "weight": 2, "align": "LEFT", "bold": true },
        { "text": "$ 500.00", "weight": 1, "align": "RIGHT", "bold": true }
      ]
    },
    {
      "type": "text",
      "text": "APROBADO\n",
      "align": "CENTER",
      "size": 28,
      "bold": true
    },
    {
      "type": "qr",
      "content": "https://micomercio.com.mx/recibo/001",
      "dotSize": 6,
      "errorLevel": "M",
      "align": "CENTER"
    },
    {
      "type": "feed",
      "lines": 4
    },
    {
      "type": "cut"
    }
  ]
}

Response

{
  "print_job_id": "RECEIPT-20260101-001",
  "status": "PENDING"
}

Get Print Job Status

GET /terminal/v1/print_job?print_job_id=RECEIPT-20260101-001

Response

{
  "print_job_id": "RECEIPT-20260101-001",
  "status": "COMPLETED"
}

Status	Description
`PENDING`	Job queued — not yet printed
`COMPLETED`	Printed successfully
`FAILED`	Printing failed — check `errorCode`

Print Job Webhook

Supply a webhookUrl in the Create Print Job request. When the job finishes, the terminal POSTs to your URL:

Success:

{
  "print_job_id": "RECEIPT-20260101-001",
  "print_job_status": "COMPLETED"
}

Failure:

{
  "print_job_id": "RECEIPT-20260101-001",
  "print_job_status": "FAILED",
  "errorCode": "OUT_OF_PAPER",
  "errorMessage": "The printer is out of paper. Insert a roll and try again."
}

Your webhook endpoint must return HTTP 2xx. If the webhook does not arrive within ~60 seconds, fall back to polling with Get Print Job Status.

Command types

`type`	Description
`text`	Text line — size, alignment, bold, italic, underline
`columns`	Multi-column row — proportional widths, ideal for item/price lines
`divider`	Full-width separator: `SOLID`, `DOTTED`, or `EMPTY`
`feed`	Advance paper N blank lines
`space`	Pixel-precise vertical whitespace
`cut`	Trigger the auto-cutter
`image`	Base64-encoded PNG/JPG — max 384 px wide
`qr`	QR code generated natively in hardware
`barcode`	CODE128 barcode generated natively in hardware

Best practices

Practice	Reason
Always end with `feed` (≥ 3 lines) + `cut`	Ensures content clears the tear edge before cutting
Always set `printJobId`	Enables idempotent retries — terminal deduplicates by this ID
Set `skipIfBusy: false` for payment receipts	Prevents a busy queue from discarding the receipt
Use `qr` / `barcode` over `image` for codes	Native hardware generation is faster and higher density
Use `BINARIZATION` algorithm for logos	Sharper edges on monochrome thermal paper
Max image width: 384 px	Hardware limit on Sunmi P3 / P2 SE

Printer error codes

Code	Cause	Action
`OUT_OF_PAPER`	No paper roll	Insert new roll
`COVER_OPEN`	Cover open	Close firmly
`COVER_INCOMPLETE`	Cover not latched	Re-open and close
`PAPER_JAM`	Paper jammed	Remove manually
`BUSY`	Queue busy + `skipIfBusy: true`	Retry after current job
`PRINTER_HOT`	Print head overheated	Wait 2–3 min
`MOTOR_HOT`	Motor overheated	Wait for cooling
`CUTTER_ERROR`	Cutter jammed	Technical service required
`UNKNOWN_ERROR`	Unclassified error	Check logs
`BAD_FORMAT`	Malformed JSON or command	Fix the request

Got a suggestion on this documentation? Contact us.

Base URL#

Available operations#

Create Print Job#

Request#

Response#

Get Print Job Status#

Response#

Print Job Webhook#

Command types#

Best practices#

Printer error codes#

Base URL

Available operations

Create Print Job

Request

Response

Get Print Job Status

Response

Print Job Webhook

Command types

Best practices

Printer error codes