Print - Kushki Developer Portal

Print operations queue a receipt on the terminal's thermal printer (Sunmi P3, Sunmi P2 SE) over your LAN, with no drivers or SDKs. You describe the receipt as an ordered commands array; array order is physical paper order.

Beta — Early Access

Kushki ONE Local Network is currently in Beta for Colombia 🇨🇴. Do not deploy to production without coordinating with the Kushki integration team.

Operations

Operation	Endpoint	Returns
Create Print Job	`POST /terminal/v1/print`	`202 Accepted` with status `PENDING`
Get Print Job Status	`GET /terminal/v1/print_job?print_job_id={id}`	`PENDING`, `IN_PROGRESS`, `COMPLETED` or `FAILED`
Print Job Webhook	`POST` to your `webhookUrl`	Implemented by your POS

Note the paths: print does not use the /sync/ and /async/ prefixes that payment operations do.

WARNING

Printing is asynchronous. The 202 means queued, not printed — the real outcome arrives by webhook or polling.

How a job resolves

POST /terminal/v1/print with your commands array → 202 and a printJobId.

The terminal prints. Then either:

Webhook — supply webhookUrl and the terminal POSTs the final state to it. Fire-and-forget, not retried.

Polling — GET /terminal/v1/print_job?print_job_id={id} every 2–3 seconds until COMPLETED or FAILED.

Field	Why it matters
`printJobId`	Your idempotency key. Reuse it on retries — the terminal deduplicates and will not print twice
`externalReference`	Free-form traceability. Echoed back in status and webhook responses
`skipIfBusy`	`true` returns `409` instead of queueing. Never set it to `true` for a payment receipt

DANGER

Do not treat the webhook as your only signal for a payment receipt. It is never retried, and a lost callback looks exactly like a failed print from your side. Poll to confirm.

Commands

Write type in lowercase. Every other enum value — align, dividerType, algorithm, errorLevel — is UPPERCASE.

`type`	What it prints
`text`	A line or paragraph, with size, alignment, bold, italic, underline
`columns`	Proportional columns on one line — item and price
`divider`	Full-width rule: `SOLID`, `DOTTED` or `EMPTY`
`feed`	N blank lines
`space`	Pixel-precise vertical whitespace
`cut`	The auto-cutter. Silently ignored on cutterless terminals
`image`	A Base64 PNG/JPG, typically the merchant logo
`qr`	A QR code generated in printer hardware
`barcode`	A CODE128 barcode generated in printer hardware

{
  "printJobId": "RECEIPT-20240317-001",
  "commands": [
    { "type": "text", "text": "MI COMERCIO COLOMBIA\n", "align": "CENTER", "size": 28, "bold": true },
    { "type": "text", "text": "NIT: 900.123.456-7\n", "align": "CENTER", "size": 20 },
    { "type": "divider", "dividerType": "SOLID", "offset": 8 },
    { "type": "columns", "columns": [
        { "text": "2x Combo Hamburguesa", "weight": 2, "align": "LEFT" },
        { "text": "$ 300.000", "weight": 1, "align": "RIGHT" }
    ]},
    { "type": "columns", "columns": [
        { "text": "TOTAL", "weight": 2, "align": "LEFT" },
        { "text": "$ 380.000", "weight": 1, "align": "RIGHT" }
    ]},
    { "type": "qr", "content": "https://facturacion.micomercio.co/ticket/4421", "dotSize": 6, "errorLevel": "M", "align": "CENTER" },
    { "type": "feed", "lines": 4 },
    { "type": "cut" }
  ]
}

Amounts are COP — print them with no decimals ($ 380.000), matching what the terminal charged.

Per-command parameters, defaults and examples live on Create Print Job.

Practical limits

Rule	Detail
Always end with `feed` + `cut`	Advance ≥ 3 lines, or the cut lands on printed content
Max image width	384 px on Sunmi hardware
Logos	Prefer `BINARIZATION` — sharper edges on monochrome art. `DITHERING` is for photos
Base64	Raw string only. The `data:image/png;base64,` prefix makes the image fail silently
Codes	Prefer `qr` and `barcode` over `image` — hardware generation is faster and denser

Hardware failures come back as errorCode: OUT_OF_PAPER, COVER_OPEN, PAPER_JAM, PRINTER_HOT, CUTTER_ERROR, OFFLINE and others. Surface them to the cashier — most are fixed by someone touching the device.

Got a suggestion on this documentation? Contact us.

Local Print Services

Operations#

How a job resolves#

Commands#

Practical limits#

Operations

How a job resolves

Commands

Practical limits