How to Integrate a Receipt API in Your POS System in 5 Minutes

Published on March 31, 2026 · 7 min read

Building receipt generation into a POS system used to mean weeks of development: laying out thermal printer templates pixel by pixel, handling paper widths, managing VAT calculations, and formatting edge cases. With a receipt API, the entire process collapses into a single HTTP call.

This guide walks you through integrating the Doxnex receipt API into your point-of-sale system, from the first API call to a printed thermal receipt. If you can make a curl request, you can follow along.

Prerequisites

A Doxnex API key (sign up at doxnex.io)
A POS application capable of making HTTP requests
A thermal printer connected to your POS terminal (for physical printing)

The 5-Step Integration

1 Get Your API Key

After creating your Doxnex account, navigate to the API settings page and generate a new API key. This key authenticates all your requests and determines your rate limits and plan features.

Store your API key securely. Never expose it in client-side code or public repositories. Use environment variables or a secrets manager in production.

export DOXNEX_API_KEY="your_api_key_here"

2 Send Your First Receipt Request

The receipt endpoint accepts a JSON payload describing the transaction. At minimum, you need the line items, a payment method, and a terminal identifier. The API handles everything else: formatting, totals, tax calculations, and compliance fields.

curl -X POST https://api.doxnex.io/v1/receipts \
  -H "Authorization: Bearer $DOXNEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "terminalId": "POS-01",
    "storeId": "STORE-PARIS-001",
    "items": [
      {
        "label": "Croissant",
        "quantity": 3,
        "unitPrice": 1.20,
        "vatRate": 5.5
      },
      {
        "label": "Cafe Latte",
        "quantity": 2,
        "unitPrice": 3.50,
        "vatRate": 10.0
      }
    ],
    "paymentMethod": "card",
    "locale": "fr"
  }'

3 Receive the Generated Receipt

The API responds with the receipt content in your chosen format. By default, you receive a PDF binary optimized for 80mm thermal paper. You can also request HTML output for digital receipts or email delivery.

# Response headers include:
# Content-Type: application/pdf
# X-Receipt-Number: R-2026-000142
# X-Receipt-Hash: a3f2b8c1...e4d5
# X-Chain-Valid: true

# The response body contains the PDF binary

Notice the response headers: the API returns the receipt number, the NF525 hash chain signature, and a chain validation status. These are critical for compliance and audit purposes.

4 Print to Thermal Printer

Send the PDF output directly to your thermal printer. Most modern thermal printers accept PDF input through their driver. If your printer requires ESC/POS commands, you can request the escpos format from the API instead.

# Print the PDF to default printer (Linux/macOS)
curl -s -X POST https://api.doxnex.io/v1/receipts \
  -H "Authorization: Bearer $DOXNEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d @transaction.json \
  -o receipt.pdf && lp receipt.pdf

# Or request ESC/POS format directly
curl -X POST https://api.doxnex.io/v1/receipts \
  -H "Authorization: Bearer $DOXNEX_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/escpos" \
  -d @transaction.json \
  -o receipt.bin

5 Handle Errors and Edge Cases

Robust POS integrations must handle network failures, API errors, and printer issues gracefully. Here is a defensive approach:

# Pseudocode for production integration
response = http.post(DOXNEX_RECEIPT_URL, data=transaction)

if response.status == 200:
    save_receipt(response.body, response.headers)
    send_to_printer(response.body)
elif response.status == 429:
    # Rate limited - retry after delay
    retry_after(response.headers["Retry-After"])
elif response.status >= 500:
    # Server error - queue for retry
    queue_for_retry(transaction)
    show_fallback_receipt(transaction)
else:
    # Client error - log and alert
    log_error(response.status, response.body)

Understanding the Receipt Workflow

Here is what happens behind the scenes when you call the receipt API:

Validation — The API validates your payload: checks that item prices are positive, VAT rates are valid, and required fields are present.
Sequence assignment — A sequential receipt number is assigned for your terminal, guaranteed to be unique and gap-free.
Tax computation — VAT totals are computed per rate, with proper rounding according to French or EU rules.
Hash chain computation — The SHA-256 hash is computed, incorporating the previous receipt's hash to maintain the NF525 chain.
Template rendering — The transaction data is merged with the receipt template, producing the final layout.
Output generation — The rendered receipt is converted to PDF (or ESC/POS or HTML) and returned in the response.

This entire pipeline executes in under 300 milliseconds on average, which means your customer is not waiting at the counter.

Digital Receipts via Email or SMS

Physical thermal receipts are being replaced by digital alternatives in many markets. The Doxnex API supports sending receipts directly to customers via email by adding a delivery configuration to your request:

curl -X POST https://api.doxnex.io/v1/receipts \
  -H "Authorization: Bearer $DOXNEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "terminalId": "POS-01",
    "items": [...],
    "paymentMethod": "card",
    "delivery": {
      "email": "[email protected]",
      "sendPdf": true
    }
  }'

The API generates the receipt, sends it to the customer, and returns the receipt data to your POS for record-keeping. The customer receives a professional, branded email with the receipt attached as a PDF.

Customizing Receipt Templates

Every business has different branding requirements. Doxnex allows you to customize receipt templates through the dashboard. You can modify the header (store logo, address, phone number), footer (return policy, loyalty program details), and the overall layout. Template changes take effect immediately without any code changes in your POS system.

Ready to generate your first receipt?

Start with Doxnex →

Frequently Asked Questions

How long does it take to integrate a receipt API?

A basic receipt API integration can be completed in as little as 5 minutes using a REST API like Doxnex. You send a POST request with transaction data and receive a formatted receipt in return. More complex setups with thermal printing, NF525 compliance, and custom templates may take a few hours.

Can I print receipts on a thermal printer via the API?

Yes. The receipt API returns output optimized for thermal printers, typically as a PDF sized for 80mm or 58mm paper widths. Your POS application sends this output directly to the connected thermal printer using standard printing libraries or raw ESC/POS commands.

Does the receipt API work offline?

Cloud-based receipt APIs require an internet connection. However, Doxnex is designed for high availability. For offline scenarios, you can implement a local queue that stores transaction data and sends it to the API when connectivity is restored, printing receipts retroactively.

What data do I need to send to generate a receipt?

At minimum, you need: line items (product name, quantity, unit price), payment method, and a terminal or store identifier. Optional fields include customer information, VAT breakdowns, discounts, and loyalty points. The API handles formatting, totals, and compliance fields automatically.