Receipt Generation API

Receipt Generation API: ein PDF-Beleg für jede Zahlung

Wenn in Ihrem System eine Zahlung gelingt, bekommt Ihre Kundschaft einen Beleg im Markenlook — automatisch, in A4, Letter oder Thermobreite, angehängt an die E-Mail, die Sie ohnehin senden.

  • 50 kostenlose Renderings/Monat
  • Ohne Kreditkarte
  • 58 mm, 80 mm, A4 oder Letter

Was ist eine API zur Belegerstellung?

Eine API zur Belegerstellung macht aus einer abgeschlossenen Zahlung ein Dokument, das die Kundschaft behalten kann. Ihr System sendet Betrag, Zahlungsart, Posten und Datum; die API setzt sie in Ihre Markenvorlage ein und liefert ein PDF oder Bild zurück — meist binnen einer Sekunde nach Zahlungseingang, bereit als Anhang für die Bestätigungs-E-Mail.

Drei verschiedene Dinge heißen „Beleg-API". Manche Dienste lesen Belege und machen per OCR aus einem Foto strukturierte Daten. Manche Zahlungsanbieter liefern einen Beleg als Teil ihres eigenen Checkouts, in ihrem Layout. Diese API erstellt das Dokument aus Daten, die Sie schon haben, in Ihrem Design — für die Zahlungen, die Ihr Unternehmen annimmt.

Receipt Generation API: die wichtigsten Fakten
EndpunktPOST https://api.dynamicdocumentapi.com/v1/pdf/from-template oder /v1/images/from-template für einen PNG-Beleg
EingabeIhre Zahlungsdaten als JSON: Betrag, Währung, Zahlungsart, Posten, Steuer, Zeitstempel
PapierA4, Letter oder eine eigene Breite wie 80 mm und 58 mm für Rollendrucker; mit single_page folgt die Höhe dem Inhalt
FormatierungJede Währung und Sprache, formatiert mit Unicode-CLDR-Daten; Ihre Zeitzone über timezone
CodesQR-Codes für einen Link zum erneuten Herunterladen oder eine Bewertungsseite, dazu 16 Barcode-Typen
DuplikateEin Idempotency-Key je Zahlungs-ID: Ein doppelt zugestellter Webhook erzeugt trotzdem nur einen Beleg (24 Stunden)
AuslieferungSignierte URL (standardmäßig 1 Stunde, bis zu 7 Tage), binär für E-Mail-Anhänge oder base64
RenderzeitMedian 216 ms, p95 516 ms1
PreisFree: 50 Renderings/Monat. Bezahlt ab 15 €/Monat (jährlich abgerechnet) für 3.000 Renderings, automatisches Nachladen ab 6 € je 1.000, etwa 0,005 € pro Beleg

1. Gemessen über 1.664 erfolgreiche Renderings auf Engine 2026.4. total_ms = Wartezeit in der Warteschlange plus Verarbeitung im Worker, ohne API-Overhead und Netzwerkübertragung. Belege sind kleine Dokumente und liegen am schnellen Ende dieses Bereichs.

Beleg oder Rechnung — was brauchen Sie?

Beide Dokumente entstehen oft aus denselben Daten und werden genauso oft verwechselt. Der Unterschied ist die Richtung des Geldes.

  • Eine Rechnung fordert eine Zahlung. Sie trägt eine Rechnungsnummer, ein Fälligkeitsdatum, Zahlungsbedingungen und in den meisten Ländern eine Reihe gesetzlicher Pflichtangaben. Wenn Sie das brauchen, deckt die Invoice PDF API es ab, einschließlich mehrseitiger Posten und Steuerspalten.
  • Ein Beleg bestätigt eine Zahlung. Er nennt den tatsächlich gezahlten Betrag, die Zahlungsart, die letzten vier Ziffern der Karte, die Uhrzeit und die Transaktionsreferenz. Er ist kürzer, wird im Nachhinein ausgestellt und hat nie ein Fälligkeitsdatum.

Viele Unternehmen senden beides: eine Rechnung mit der Bestellung, einen Beleg bei Zahlungseingang. Eine Vorlagenbibliothek kann beide enthalten, und sie können sich Kopf, Logo und Fußzeile teilen.

Einen Beleg aus einem Zahlungsereignis erzeugen

Auslöser ist ein Webhook Ihres Zahlungsanbieters — Stripe, Adyen, Mollie, PayPal oder Ihre eigene Kasse. Ihr Handler macht aus dem Ereignis Belegdaten und ruft die API mit der Zahlungs-ID als Idempotenzschlüssel auf.

curl https://api.dynamicdocumentapi.com/v1/pdf/from-template \
  -H "Authorization: Bearer $DYNAMIC_DOCUMENT_API_KEY" \
  -H "Idempotency-Key: pi_3Qk8sLd92" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "tpl_receipt_thermal",
    "data": {
      "receipt_no": "R-2026-18422",
      "paid_at": "2026-09-25T10:14:02Z",
      "method": "Visa •••• 4242",
      "locale": "en-US",
      "currency": "USD",
      "items": [
        { "name": "Flat white", "qty": 2, "total": 7.80 },
        { "name": "Croissant",  "qty": 1, "total": 3.68 }
      ],
      "subtotal": 11.48, "tax": 1.42, "total": 12.90,
      "reprint_url": "https://shop.example.com/r/R-2026-18422"
    },
    "pdf": {
      "paper": { "width": "80mm" },
      "single_page": true,
      "margin": { "top": "4mm", "right": "3mm", "bottom": "4mm", "left": "3mm" },
      "timezone": "America/New_York"
    },
    "delivery": "binary"
  }' \
  --output receipt.pdf
// Node.js 18+: called from your payment webhook handler
export async function receiptFor(payment) {
  const res = await fetch("https://api.dynamicdocumentapi.com/v1/pdf/from-template", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.DYNAMIC_DOCUMENT_API_KEY}`,
      "Idempotency-Key": payment.id, // providers retry webhooks
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      template_id: "tpl_receipt",
      data: {
        receipt_no: payment.receiptNo,
        paid_at: payment.paidAt,
        method: `${payment.brand} •••• ${payment.last4}`,
        currency: payment.currency,
        items: payment.items,
        total: payment.total,
      },
      pdf: { paper: { format: "A4" } },
      delivery: "binary", // bytes for the email attachment
    }),
  });
  if (!res.ok) throw new Error(await res.text());
  return Buffer.from(await res.arrayBuffer());
}
import os
import requests

def receipt_pdf(payment: dict, thermal: bool = False) -> bytes:
    """Called from the payment webhook. Returns PDF bytes."""
    paper = {"width": "80mm"} if thermal else {"format": "A4"}
    res = requests.post(
        "https://api.dynamicdocumentapi.com/v1/pdf/from-template",
        headers={
            "Authorization": f"Bearer {os.environ['DYNAMIC_DOCUMENT_API_KEY']}",
            "Idempotency-Key": payment["id"],
        },
        json={
            "template_id": "tpl_receipt",
            "data": payment,
            "pdf": {"paper": paper, "single_page": thermal},
            "delivery": "binary",
        },
        timeout=30,
    )
    res.raise_for_status()
    return res.content
<?php
function receiptPdf(array $payment): string
{
    $ch = curl_init('https://api.dynamicdocumentapi.com/v1/pdf/from-template');
    curl_setopt_array($ch, [
        CURLOPT_POST           => true,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER     => [
            'Authorization: Bearer ' . getenv('DYNAMIC_DOCUMENT_API_KEY'),
            'Idempotency-Key: ' . $payment['id'],
            'Content-Type: application/json',
        ],
        CURLOPT_POSTFIELDS     => json_encode([
            'template_id' => 'tpl_receipt',
            'data'        => $payment,
            'pdf'         => [
                'paper'       => ['width' => '58mm'], // narrow roll printer
                'single_page' => true,
            ],
            'delivery'    => 'binary',
        ]),
    ]);
    return curl_exec($ch); // PDF bytes
}

Zahlungsanbieter wiederholen Webhooks, dasselbe Ereignis kommt also oft zweimal an. Mit der Zahlungs-ID als Idempotency-Key liefert der zweite Aufruf 24 Stunden lang den bereits gerenderten Beleg zurück, statt einen weiteren zu erzeugen. Mit Testschlüsseln spielen Sie echte Ereignisse gegen eine Ausgabe mit Wasserzeichen nach, ohne Kontingent zu verbrauchen.

Thermorolle, A4 oder Bild — derselbe Beleg

Wo der Beleg landet, bestimmt seine Form. Ein Rollendrucker an der Kasse will einen schmalen, endlosen Streifen; ein Buchhaltungspostfach will A4 oder Letter; eine Bestätigungs-E-Mail wirkt oft besser, wenn der Beleg als Bild erscheint. Alle drei entstehen aus einer Vorlage.

Rollen mit 80 mm und 58 mm

Legen Sie die Papierbreite direkt fest und lassen Sie die Höhe dem Inhalt folgen. Mit single_page ist das PDF eine durchgehende Seite: Ein Verkauf mit zwei Posten druckt kurz, einer mit zwanzig lang — ohne leeren Rest und ohne abgeschnittene Summen.

"paper": { "width": "80mm" },
"single_page": true,
"margin": { "left": "3mm", "right": "3mm" }

A4 und Letter fürs Archiv

Dieselben Daten in einer breiteren Vorlage ergeben das Dokument, das die Buchhaltung erwartet: Ihr Adressblock, die Steuerübersicht, die Transaktionsreferenz. Dreizehn benannte Seitenformate stehen bereit, dazu jede eigene Größe bis 200 Zoll.

PNG für den E-Mail-Text

Manche Kunden öffnen nie Anhänge. Die Image Generation API rendert dieselbe Vorlage als PNG oder JPG, das Sie direkt in der E-Mail zeigen können, mit Viewport und Skalierung Ihrer Wahl.

Währung, Sprache und Zeitzone

Beträge, Dezimaltrennzeichen und Daten folgen den Unicode-CLDR-Regeln für die übergebene Sprache, und timezone sorgt dafür, dass „10:14" die Ortszeit der Kundschaft meint und nicht die Ihres Servers.

Erstattungen, Teilzahlungen und Spenden

Eine Vorlage kann jede Variante bedienen, die Ihr Checkout erzeugt, weil das Layout auf die Daten reagiert. Eine Bedingung entscheidet, ob ein Block überhaupt erscheint.

{% if refund %}
  <h1>Refund receipt</h1>
  <p class="ref">Refunds {{ original_no }}</p>
{% elif balance > 0 %}
  <h1>Partial payment</h1>
  <p class="bal">Remaining: {{ balance | format_currency(currency, locale) }}</p>
{% else %}
  <h1>Receipt</h1>
{% endif %}

Derselbe Mechanismus ergänzt eine Trinkgeldzeile für eine Kassenzahlung, einen Spenderblock und die Registernummer einer gemeinnützigen Organisation für eine Spendenquittung oder einen Hinweis, dass in Raten gezahlt wurde. Was jedes Dokument enthalten muss, entscheidet Ihre Steuerberatung; die Vorlage rendert es, und jede Version dieser Vorlage bleibt erhalten — Sie sehen also genau, was eine Kundin oder ein Kunde im letzten März bekommen hat.

Der Beleg bei der Kundschaft

  • E-Mail-Anhang. "delivery": "binary" liefert die Bytes, bereit für das Anhangsfeld Ihres E-Mail-Anbieters. Die API erstellt das Dokument; der Versand bleibt bei dem System, das bereits Ihre Bestätigungen verschickt.
  • Download-Link. Die Standardantwort enthält eine signierte URL, eine Stunde gültig und mit expires_in bis zu sieben Tage — lang genug für einen Button „Beleg ansehen" in der Bestätigungs-E-Mail.
  • Kundenportal. Speichern Sie die Render-ID zur Zahlung und erzeugen Sie einen frischen Link, sobald die Kundschaft ihre Bestellhistorie öffnet.
  • Druck an der Kasse. Das Thermo-PDF geht aus Ihrer Kassensoftware direkt an einen Rollendrucker.
  • Aufbewahrung nach Ihren Vorgaben. Dateien bleiben so lange, wie Sie es mit retention_days festlegen, bis zum Maximum Ihres Tarifs, und lassen sich jederzeit löschen. Wie lange Sie den Beleg aufbewahren müssen, regelt das Steuerrecht — führen Sie Ihre eigene Archivkopie, etwa in Ihrem eigenen Storage-Bucket.

Was das Erzeugen eines Belegs kostet

Free

€0

50 Belege pro Monat — genug, um den Webhook anzubinden und beide Papierbreiten zu testen.

Starter

€15 / Monat

3.000 Renderings pro Monat, jährlich abgerechnet (19 € bei monatlicher Abrechnung). Etwa 0,005 € pro Beleg.

Checkouts mit hohem Volumen wachsen mit dem Growth-Tarif: 15.000 Renderings für 47 € bei jährlicher Abrechnung, etwa 0,0031 € pro Beleg, mit automatischem Nachladen, wenn ein Monat heiß läuft. Siehe die Kosten pro Beleg in jedem Tarif.

FAQ

Receipt Generation API: häufige Fragen

Was ist der Unterschied zwischen einem Beleg und einer Rechnung?

Eine Rechnung fordert Geld: Sie listet auf, was geschuldet wird, mit Fälligkeitsdatum und Zahlungsbedingungen. Ein Beleg bestätigt, dass Geld angekommen ist: Er nennt gezahlten Betrag, Zahlungsart und Datum. Viele Unternehmen senden beides — eine Rechnung bei der Bestellung, einen Beleg bei Zahlungseingang.

Kann ich Belege in Thermodrucker-Breite erzeugen?

Ja. Legen Sie eine eigene Papierbreite von 80 mm oder 58 mm fest und schalten Sie single_page ein — dann folgt die Seitenhöhe dem Inhalt, statt in A4-Seiten geschnitten zu werden. Ein kurzer Beleg bleibt kurz und ein langer wird einfach länger, genau wie ein Rollendrucker es erwartet.

Können Belege nach einer Stripe-Zahlung automatisch versendet werden?

Ja, aus Ihrem eigenen Webhook-Handler. Meldet Ihr Zahlungsanbieter eine erfolgreiche Zahlung, macht Ihr Code aus dem Ereignis Belegdaten und ruft die API mit der Zahlungs-ID als Idempotenzschlüssel auf. Anbieter wiederholen Webhooks, und dieser Schlüssel sorgt dafür, dass ein doppeltes Ereignis keinen zweiten Beleg erzeugt.

Kann ich Spendenquittungen erstellen?

Ja. Eine Spendenquittung ist dieselbe Vorlage mit anderen Feldern: Spender, Betrag, Datum, die Registernummer Ihrer gemeinnützigen Organisation und jede Formulierung, die Ihre Steuerbehörde verlangt. Wie diese Formulierung lauten muss, klären Sie mit Ihrer Steuerberatung; die API rendert, was in Ihrer Vorlage steht.

Kann eine Vorlage Erstattungen und Teilzahlungen abdecken?

Ja. Vorlagen nutzen Bedingungen, dieselbe Datei kann also je nach gesendeten Daten einen Erstattungsbeleg mit negativer Summe drucken, „teilweise bezahlt" mit Restbetrag zeigen oder eine Trinkgeldzeile für eine Kassenzahlung ergänzen.

Liest die API Daten aus Fotos von Belegen?

Nein. Das ist Beleg-OCR und geht in die andere Richtung: ein Bild hinein, strukturierte Daten heraus. Diese API erstellt Belege aus Daten, die Sie bereits haben. Wenn Sie Daten aus gescannten Belegen auslesen müssen, ist ein OCR-Dienst das richtige Werkzeug.

Senden Sie Ihren ersten Beleg kostenlos

50 Renderings im Monat im Free-Tarif, ohne Kreditkarte, automatisches Nachladen in Bezahltarifen.

Kostenlos starten