Create Print Job

🚧 Beta — Early Access
This API is in early access. Endpoints, parameters, and response structures
may change without prior notice. Do not deploy to production without
coordinating with the Kushki integration team.

Queues a print job to the terminal's thermal printer.
Returns 202 Accepted immediately — printing is asynchronous.

Both print endpoints require the same signed Authorization and timestamp
headers as the Payment API.

The final result (COMPLETED or FAILED) is delivered via:

Webhook push: supply webhookUrl in the request.

Status polling: call GET /terminal/v1/print_job?print_job_id={id}.

Command Types

The commands array contains polymorphic objects. The type property
(required on every object) determines its behavior. Write type in lowercase
(text, columns, divider…); every other enum value — align, dividerType,
algorithm, errorLevel — must be sent in UPPERCASE.

`type`	Description
`text`	Text line with configurable size, alignment, bold, italic, and 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 precise pixel-level vertical whitespace.
`cut`	Trigger the auto-cutter. Silently ignored on cutterless terminals.
`image`	Print a Base64-encoded PNG/JPG — typically used for merchant logos.
`qr`	Generate a QR code natively in printer hardware.
`barcode`	Generate a CODE128 barcode natively in printer hardware.

`text` — Text Line

Prints a line or paragraph of text with full format control.
Append \n to the text field to force an explicit line break.

Parameter	Type	Required	Default	Description
`text`	String	✅	—	Text to print.
`align`	`LEFT` \| `CENTER` \| `RIGHT`	❌	`LEFT`	Horizontal alignment.
`size`	Integer	❌	`24`	Font size in px. Reference: `24` normal · `32` subtitle · `48` title.
`bold`	Boolean	❌	`false`	Bold.
`italic`	Boolean	❌	`false`	Italic.
`underline`	Boolean	❌	`false`	Underline.

{
  "type": "text",
  "text": "RESTAURANTE EL BUEN SABOR\n",
  "align": "CENTER",
  "size": 32,
  "bold": true
}

`columns` — Multi-Column Row

Prints text in proportional columns on a single paper line.
The weight field controls the relative width of each column.

Field (per column)	Type	Required	Default	Description
`text`	String	✅	—	Cell text.
`weight`	Integer	❌	`1`	Relative width. Weights `2` and `1` give the first column 2/3 of the paper.
`align`	`LEFT` \| `CENTER` \| `RIGHT`	❌	`LEFT`	Alignment within the cell.

{
  "type": "columns",
  "columns": [
    { "text": "2x Combo Burger", "weight": 2, "align": "LEFT" },
    { "text": "S/ 300.00",         "weight": 1, "align": "RIGHT" }
  ]
}

`divider` — Separator Line

Prints a full-width horizontal rule. Use it to delimit receipt sections
(header, items, totals).

Parameter	Type	Required	Default	Description
`dividerType`	`SOLID` \| `DOTTED` \| `EMPTY`	❌	`EMPTY`	Line style.
`offset`	Integer	❌	`10`	Extra space in px before the separator.

{ "type": "divider", "dividerType": "DOTTED", "offset": 10 }

`feed` — Paper Advance

Advances the paper N blank lines. Always use before cut to fully expose
the printed content past the tear edge.

Parameter	Type	Required	Default	Description
`lines`	Integer	❌	`1`	Number of blank lines to advance.

{ "type": "feed", "lines": 3 }

`space` — Pixel-Precise Spacing

Inserts vertical whitespace with pixel precision. More granular than feed
for fine adjustments between receipt elements.

Parameter	Type	Required	Default	Description
`pixels`	Integer	❌	`10`	Pixels of blank space to insert.

{ "type": "space", "pixels": 20 }

`cut` — Paper Cut

Triggers the hardware auto-cutter. No additional parameters.
On cutterless terminals (e.g., Sunmi V2) the command is silently ignored.

{ "type": "cut" }

`image` — Base64 Image

Prints a PNG or JPG sent as Base64. Typically used for the merchant logo
in the receipt header.

Parameter	Type	Required	Default	Description
`base64Image`	String	✅	—	Raw Base64 string. Do not include the `data:image/...;base64,` prefix.
`align`	`LEFT` \| `CENTER` \| `RIGHT`	❌	`CENTER`	Image alignment.
`width`	Integer	❌	—	Max width in px. Sunmi P3 / P2 SE support up to 384 px.
`algorithm`	`BINARIZATION` \| `DITHERING`	❌	`DITHERING`	`BINARIZATION`: maximum sharpness for logos. `DITHERING`: simulates grayscale for photos.

Send only the raw Base64 string. Including the data:image/png;base64,
prefix will cause the image to fail silently.

{
  "type": "image",
  "base64Image": "iVBORw0KGgoAAAANSUhEUgAAAAo...",
  "align": "CENTER",
  "width": 384,
  "algorithm": "BINARIZATION"
}

`qr` — QR Code

Generates a QR code natively in printer hardware from a content string —
no image rendering required. Faster and higher-density than sending a
pre-rendered bitmap.

Parameter	Type	Required	Default	Description
`content`	String	✅	—	URL or text to encode.
`dotSize`	Integer	❌	`8`	Size in px of each QR module. Affects the total code size.
`errorLevel`	`L` \| `M` \| `Q` \| `H`	❌	`L`	Error correction: `L`=7% · `M`=15% · `Q`=25% · `H`=30%.
`align`	`LEFT` \| `CENTER` \| `RIGHT`	❌	`CENTER`	Horizontal alignment.

{
  "type": "qr",
  "content": "https://yourstore.com/receipt/4421",
  "dotSize": 6,
  "errorLevel": "M",
  "align": "CENTER"
}

`barcode` — CODE128 Barcode

Generates a 1D barcode natively in hardware. Format: CODE128.

Parameter	Type	Required	Default	Description
`content`	String	✅	—	Data to encode (e.g., UPC, invoice number).
`align`	`LEFT` \| `CENTER` \| `RIGHT`	❌	`CENTER`	Horizontal alignment.
`width`	Integer	❌	`3`	Width of each vertical bar in points.
`height`	Integer	❌	`162`	Total barcode height in px.

{
  "type": "barcode",
  "content": "A-1234567890",
  "align": "CENTER",
  "width": 2,
  "height": 162
}

Idempotency
Reuse the same printJobId on network-failure retries.
The terminal deduplicates the job and will not print twice.

curl --location '/terminal/v1/print' \ --header 'Authorization: nRvpFJZHjqLU4k8Rz2YiDvxA3mQs9oB1cW7eT0=' \ --header 'timestamp: 1700000000000' \ --header 'Content-Type: application/json' \ --data '{ "commands": [ { "type": "text", "text": "RECIBO DE PAGO\n", "align": "CENTER", "size": 28, "bold": true }, { "type": "text", "text": "Total: S/ 120.00\n", "align": "CENTER", "size": 24 }, { "type": "feed", "lines": 3 }, { "type": "cut" } ] }'

🚧 Beta — Early Access

Command Types

`text` — Text Line

`columns` — Multi-Column Row

`divider` — Separator Line

`feed` — Paper Advance

`space` — Pixel-Precise Spacing

`cut` — Paper Cut

`image` — Base64 Image

`qr` — QR Code

`barcode` — CODE128 Barcode

Idempotency

Callbacks

printJobResult

Request

Responses

Create Print Job

🚧 Beta — Early Access#

Command Types#

text — Text Line#

columns — Multi-Column Row#

divider — Separator Line#

feed — Paper Advance#

space — Pixel-Precise Spacing#

cut — Paper Cut#

image — Base64 Image#

qr — QR Code#

barcode — CODE128 Barcode#

Idempotency#

Callbacks

printJobResult

Request

Responses

🚧 Beta — Early Access

Command Types

`text` — Text Line

`columns` — Multi-Column Row

`divider` — Separator Line

`feed` — Paper Advance

`space` — Pixel-Precise Spacing

`cut` — Paper Cut

`image` — Base64 Image

`qr` — QR Code

`barcode` — CODE128 Barcode

Idempotency