Print

The Kushki ONE Print API lets your POS system control the thermal printer built into Sunmi SmartPOS terminals. You send an ordered array of print commands describing the receipt layout — text lines, item columns, QR codes, barcodes, logos — and the terminal executes them in sequence.

The Print API is available in two modes matching the payment integration:

Mode	Connection	Auth required
Cloud	`cloudt.kushkipagos.com` → terminal	✅ HMAC-SHA256
Local Network	Direct to terminal IP	❌

Beta — Early Access

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

How it works

Print jobs are asynchronous — the terminal queues the job and returns 202 Accepted immediately. The final result is delivered via:

Webhook: supply a webhookUrl in the request body. The terminal POSTs the result to your URL when the job completes.

Polling: call the Get Print Job Status endpoint periodically until status is COMPLETED or FAILED.

1. POST .../print/[job|]        → 202 Accepted, PENDING
2. Terminal prints asynchronously
3. Terminal POSTs to webhookUrl (or you poll job_status)
   → status: COMPLETED | FAILED

Available operations

Create Print Job (Cloud)

Queue a print job via Kushki's cloud relay. Terminal identified by serial number in the URL.

Create Print Job (Local)

Queue a print job directly over LAN/Wi-Fi. No authentication required.

Get Print Job Status (Cloud)

Poll job status via cloud using print_job_id.

Get Print Job Status (Local)

Poll job status directly on the terminal using print_job_id.

Print Job Webhook (Local)

Endpoint in your POS that receives the async result from the terminal. Implement to avoid polling.

Command types

Every print job is an ordered commands array. The type field on each object determines how it renders on paper.

`type`	Description
`text`	Text line — configurable size, alignment, bold, italic, underline
`columns`	Multi-column row with proportional widths — ideal for item/price lines
`divider`	Full-width separator: `SOLID`, `DOTTED`, or `EMPTY`
`feed`	Advance paper N blank lines
`space`	Insert pixel-precise vertical whitespace
`cut`	Trigger the auto-cutter (silently ignored on cutterless terminals)
`image`	Print a Base64-encoded PNG/JPG — typically for merchant logos (max 384 px wide)
`qr`	Generate a QR code natively in hardware — faster and sharper than a pre-rendered image
`barcode`	Generate a CODE128 barcode natively in hardware

Example — Full payment receipt

{
  "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": "2x Producto A", "weight": 2, "align": "LEFT" },
        { "text": "$ 300.00",      "weight": 1, "align": "RIGHT" }
      ]
    },
    {
      "type": "columns",
      "columns": [
        { "text": "1x Producto B", "weight": 2, "align": "LEFT" },
        { "text": "$ 200.00",      "weight": 1, "align": "RIGHT" }
      ]
    },
    {
      "type": "divider",
      "dividerType": "SOLID"
    },
    {
      "type": "columns",
      "columns": [
        { "text": "TOTAL", "weight": 2, "align": "LEFT" },
        { "text": "$ 500.00", "weight": 1, "align": "RIGHT" }
      ]
    },
    {
      "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"
    }
  ]
}

Print webhook payload

When the job finishes, the terminal POSTs to your webhookUrl:

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

On 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.

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 silently 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
Set HTTP timeout ≥ 15 s for Cloud requests	Cloud relay adds latency before the terminal responds

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
`OFFLINE`	Terminal unreachable (Cloud)	Check terminal connectivity
`UNKNOWN_ERROR`	Unclassified error	Check logs
`BAD_FORMAT`	Malformed JSON or command	Fix the request

Got a suggestion on this documentation? Contact us.

How it works#

Available operations#

Command types#

Example — Full payment receipt#

Print webhook payload#

Best practices#

Printer error codes#

How it works

Available operations

Command types

Example — Full payment receipt

Print webhook payload

Best practices

Printer error codes