Printing on SmartPOS terminal

🚧 Early Release — Beta

This product is in early access. Parameters, response structures and behaviors may change without prior notice. Do not use this version in production without coordinating with the Kushki integrations team first.

The Print API gives you full control over the thermal printer built into Kushki ONE terminals. Print any content from your POS system — before, during or after a transaction, or with no transaction at all — without installing drivers, SDKs or configuring hardware on your side.

Requirements

Before you start

A Sunmi P3 or P2 SE terminal with a built-in thermal printer, linked to your merchant account.

Your Business-Code to sign the requests.

The device's terminalSerial if you integrate over Cloud.

How it works

The print cycle has two parts: a sync request that queues the job, and an async notification that tells you when it finished.

Your POS system builds a commands array with the receipt layout.

You send the job creation request. The terminal answers 202 Accepted right away.

Printing runs asynchronously on the hardware.

You learn the final result over webhook or by querying the status.

The payloads and the headers are identical across topologies. The routes are not: the base URL stops at the terminal, and each route carries its own prefix.

Topology	Base URL
Local Network (LAN / Wi-Fi)	`http://{TERMINAL_IP}:6868/terminal/v1` or `https://{TERMINAL_IP}:6869/terminal/v1`
Cloud (Internet) — UAT	`https://uat-cloudt.kushkipagos.com/terminal/v1/{terminalSerial}`
Cloud (Internet) — Production	`https://cloudt.kushkipagos.com/terminal/v1/{terminalSerial}`

Routes by topology

On Local Network you queue with POST /terminal/v1/print and query with GET /terminal/v1/print_job. On Cloud you queue with POST /sync/print and query with POST /sync/print_job. See Option B: query the status for the details of each method.

Authentication

Printing uses the same mechanism as the payment operations — hash + encryption, the only one Kushki ONE has:

Element	Value
`Authorization`	`Basic` followed by the SHA-512 hash. The `Basic` prefix is required
`timestamp`	Unix timestamp in seconds, within ±5 minutes of server time
Body	The encrypted envelope `{"data": "<iv_hex>:<ciphertext_hex>"}`

The commands array shown on this page is the plaintext you encrypt, not what travels on the wire. The full flow is on Authentication and request encryption.

Local Network and Localhost: send the encrypted_http_communication header

In Local Network and Localhost, every request also carries the header encrypted_http_communication: true, in UAT and in production. Cloud does not require it. Details in Authentication and request encryption.

The status query is a GET on the local network

On the local network you query the status with GET, so the encrypted value travels as the data query parameter and no other parameter may be sent: the print_job_id goes inside the encrypted payload.

Use cases

The API is not limited to payment receipts. Any content your business needs to hand over on paper can be triggered from your POS system.

Use case	Description
Payment receipt	Direct sale, pre-authorization capture, refund or void
Discount coupon	A code for the customer's next purchase
QR code	Wi-Fi password, loyalty link, digital receipt, product information
Loyalty and promotions	Point balance, reward tiers, special offers
Pre-check or order summary	Kitchen ticket or table summary before the final charge
Reversal record	A printed record of a cancellation or refund
Reprint	Print a previous receipt again with the same `printJobId`
Free content	Text, image, QR or barcode, with no transaction involved

The commands array is a blank canvas

You are not limited to any template or predefined format. Combine text, images, QR codes, barcodes, columns and dividers in whatever order your business needs.

Anatomy of a receipt

Each visual section of the receipt maps to a command type inside the commands array.

Request structure

Field	Type	Required	Description
`commands`	array	✅	Ordered list of print commands
`printJobId`	string	—	Idempotency key. If you leave it out, a UUID is generated
`externalReference`	string	—	Your own free-form reference, for example `Table-14`
`webhookUrl`	string	—	URL that will receive the result when the job finishes
`skipIfBusy`	boolean	—	With `true`, returns `409` immediately if the queue is busy. Defaults to `false`

Command types

Type	Description
`text`	A line of text with size, alignment, bold, italic and underline
`columns`	A multi-column row with proportional widths, ideal for product and price
`divider`	A full-width separator line: `SOLID`, `DOTTED` or `EMPTY`
`feed`	Advances the paper N blank lines
`space`	Inserts precise vertical space in pixels
`cut`	Triggers the cutter. Safely ignored on terminals without one
`image`	Prints a PNG or JPG image in Base64. Use `algorithm: BINARIZATION` for logos
`qr`	Generates a QR code on the printer hardware
`barcode`	Generates a CODE128 barcode on the hardware

Command rules

The type property is mandatory on every command: it is the discriminator that defines its structure.

Enumerated values (align, dividerType, errorLevel, algorithm) always go in uppercase.

Images are sent as pure Base64, without the data:image/png;base64, prefix.

Full example

This request builds a receipt with a logo, header, line items, total, QR code and an automatic cut.

{
  "printJobId": "TICKET-190209",
  "externalReference": "Table-14",
  "webhookUrl": "https://api.yourbusiness.com/webhook/print-events",
  "skipIfBusy": false,
  "commands": [
    { "type": "image", "base64Image": "iVBORw0KGgoAAAANSUhEUg...", "align": "CENTER", "width": 300, "algorithm": "BINARIZATION" },
    { "type": "text", "text": "EL BUEN SABOR RESTAURANT\n", "align": "CENTER", "size": 32, "bold": true },
    { "type": "text", "text": "Tax ID: 900.123.456-7\n", "align": "CENTER", "size": 22 },
    { "type": "divider", "dividerType": "DOTTED" },
    { "type": "columns", "columns": [
        { "text": "2x Burger Combo", "weight": 2, "align": "LEFT" },
        { "text": "30,000.00 COP", "weight": 1, "align": "RIGHT" } ] },
    { "type": "columns", "columns": [
        { "text": "1x Fresh Juice", "weight": 2, "align": "LEFT" },
        { "text": "8,000.00 COP", "weight": 1, "align": "RIGHT" } ] },
    { "type": "divider", "dividerType": "SOLID" },
    { "type": "columns", "columns": [
        { "text": "TOTAL", "weight": 2, "align": "LEFT" },
        { "text": "38,000.00 COP", "weight": 1, "align": "RIGHT" } ] },
    { "type": "qr", "content": "https://yourbusiness.com/receipt/TICKET-190209", "dotSize": 6, "errorLevel": "M", "align": "CENTER" },
    { "type": "feed", "lines": 3 },
    { "type": "cut" }
  ]
}

Send the request from your back-end:

JavaScript

Python

The terminal answers immediately:

{
  "printJobId": "TICKET-190209",
  "status": "PENDING",
  "message": "Impresión encolada correctamente"
}

Code	Meaning
`202 Accepted`	Job queued. Returns the `printJobId` and `PENDING` status
`400 Bad Request`	Malformed payload or unknown enumerated value
`409 Conflict`	A job is already `PENDING` or `IN_PROGRESS`

Job result

You have two mechanisms to learn the final result. Use one or both in parallel.

Option A: webhook

If you sent a webhookUrl when queueing, the terminal makes a POST to that URL when the job turns COMPLETED or FAILED.

Successful job

{
  "printJobId": "TICKET-190209",
  "status": "COMPLETED",
  "externalReference": "Table-14"
}

Hardware failure

{
  "printJobId": "TICKET-190209",
  "status": "FAILED",
  "externalReference": "Table-14",
  "errorCode": "OUT_OF_PAPER",
  "errorMessage": "La impresora está sin papel."
}

This webhook does not retry

If your server does not answer with a 2xx code within 5 seconds, the terminal does not retry: it carries on so the printer is not blocked. Answer fast, make your endpoint idempotent and use the status query as a fallback in flows where losing the confirmation is costly.

This behavior differs from the transaction webhook, which does retry with exponential backoff.

The field is webhookUrl

Do not confuse it with events_webhook_url, which belongs to the transaction webhook. The two channels use different parameter names and share no delivery policy.

Option B: query the status

Use this when your system cannot receive inbound connections from the terminal, or as a webhook fallback.

Local Network

GET /terminal/v1/print_job?print_job_id=TICKET-190209

Cloud

POST /terminal/v1/{terminalSerial}/sync/print_job

{
  "print_job_id": "TICKET-190209"
}

On Cloud the identifier goes in the body

The Cloud query uses POST and sends print_job_id in the request body, not as a query parameter in the URL. Sending it in the URL returns a validation error.

Poll every 2 or 3 seconds and stop once status is COMPLETED or FAILED.

{
  "printJobId": "TICKET-190209",
  "status": "COMPLETED"
}

Job statuses

`status`	Description
`PENDING`	Queued, waiting its turn
`IN_PROGRESS`	The driver is sending commands to the printer
`COMPLETED`	Receipt printed and cut successfully
`FAILED`	Physical error during printing. Check `errorCode`

The webhook only reports final states

You will not receive notifications for PENDING or IN_PROGRESS. If you need to follow those intermediate states, use the status query.

Hardware error codes

The possible values of errorCode are OUT_OF_PAPER, COVER_OPEN, COVER_INCOMPLETE, PAPER_JAM, PRINTER_HOT, MOTOR_HOT, CUTTER_ERROR, OFFLINE and UNKNOWN_ERROR. They arrive with type: TERMINAL-PRINTER in the error body.

A busy queue is not one of them: it arrives as TER-004 with type: TERMINAL, and over HTTP as a 409.

Print endpoints do return real HTTP codes

Unlike the payment operations — where the status is always 200 and the outcome lives in the body — printing answers 202 when the job is queued, 404 when the print_job_id does not exist and 409 while the printer is busy.

And TER-004 means two different things: on a print endpoint the printer is busy and you retry in a few seconds; on a payment endpoint the cardholder cancelled on the terminal and you must not retry. The endpoint you called tells you which one.

Best practices

Send your own printJobId so you can reprint the same receipt and discard duplicates in your system.

Use externalReference to tie the receipt to your order, table or invoice.

Answer the webhook with 2xx before processing it. A slow endpoint means you lose the notification.

Treat FAILED as an operational condition, not an integration error: show the errorMessage to the operator so they can fix the physical problem.

Send images already binarized and at the right width. A heavy logo lengthens print time.

Accept payments with Kushki ONE

Process card-present payments and pair them with printing the receipt.

Printer errors

Look up the cause and the recommended action for every hardware error code.

Printing on SmartPOS terminal

Requirements#

How it works#

Authentication#

Use cases#

Anatomy of a receipt#

Request structure#

Command types#

Full example#

Job result#

Option A: webhook#

Option B: query the status#

Job statuses#

Hardware error codes#

Best practices#

Requirements

How it works

Authentication

Use cases

Anatomy of a receipt

Request structure

Command types

Full example

Job result

Option A: webhook

Option B: query the status

Job statuses

Hardware error codes

Best practices