Invoice in, payment QR out — via API

Ready in three steps

1. 1

   Create an API key

   Sign in to the app and create a key under "API & integrations". It starts with gsk_live_ and is shown exactly once — store it safely. 10 free tokens are already on the account.

2. 2

   Pick a door

   REST for your system, MCP for your AI agent, email for existing sending workflows — or simply the web app. The key is the same everywhere.

3. 3

   Send invoices

   Document in, response with payment data and the GiroCode out — for PDFs also the stamped PDF. Every response states tokens charged and remaining.

The REST API and the MCP server authenticate with the same GiroSnap API key as a bearer token. There is no separate "MCP key" — the gsk_live_ key from the app is the one key:

Authorization: Bearer gsk_live_...

Keys are created and revoked only in the app (signed-in session) — a leaked key can never mint new keys. The plaintext is never retrievable after creation.

JSON or multipart, max 12 MB per document (JPG, PNG, WEBP, PDF). The fastest start is the all-in-one endpoint:

curl -X POST https://www.girosnap.eu/api/v1/invoices \
  -H "Authorization: Bearer gsk_live_..." \
  -F "file=@rechnung.pdf"

• POST/api/v1/invoicesAll in one: payment data + QR, for PDFs also the stamped PDF.
• POST/api/v1/extractExtract payment data only (no QR, no stamping).
• POST/api/v1/qrQR only — from payment data (no extraction) or from a document.
• POST/api/v1/stampStamp the GiroCode onto a PDF.
• GET/api/v1/balanceQuery token balance, warning flag and packages (free).
• POST/api/v1/checkoutCreate a directly payable Stripe link for a token package.

Every parameter, response format and error code — including "try it out" right in the browser: Open the interactive API reference

MCP (Model Context Protocol) is the open standard AI agents (e.g. Claude) use to call external tools. Our MCP server hands your agent GiroSnap as a toolbox: it photographs an invoice, calls a tool, and gets the GiroCode or the stamped PDF right back into its flow.

The easiest path — Claude (web & desktop): Settings → Connectors → “Add custom connector”, name it “GiroSnap”, and paste this URL with your key. Leave the OAuth fields empty:

https://www.girosnap.eu/api/mcp?key=GIROSNAP_API_KEY

This URL contains your API key — treat it like a password and don’t share it.

Connect: enter the server URL and pass your API key as the Authorization header — the same config works in Claude, IDE agents and your own SDK agents:

{
  "mcpServers": {
    "girosnap": {
      "type": "http",
      "url": "https://www.girosnap.eu/api/mcp",
      "headers": {
        "Authorization": "Bearer gsk_live_..."
      }
    }
  }
}

GIROSNAP_API_KEY is your regular gsk_live_ key from the app — there is no separate MCP key.

The tools in detail

• extract_invoice1 token/page

  Reads beneficiary, IBAN, BIC, amount (in cents) and payment reference from an invoice photo or PDF. Only needed when your agent cannot or should not read the invoice itself.

• create_payment_qr1 token/page

  Generates the scannable EPC/GiroCode — as an image, SVG and raw payload. Takes ready payment data (fastest path, no extraction) or a document.

• stamp_invoice_pdf1 token/page

  Stamps the GiroCode onto the PDF invoice — onto free space or an appended page; signed PDFs and e-invoices stay untouched and get a companion sheet.

• get_token_balancefree

  Current token balance, warning flag, package list and top-up link.

• buy_tokensfree

  Creates a directly payable Stripe checkout link for a token package — tokens are credited automatically after payment.

Pro tip: if your agent already knows the payment data (it has seen the invoice, after all), it simply passes it as payment to create_payment_qr or stamp_invoice_pdf — no extraction runs on our side and the response is fastest.

Send invoices simply by email — no code at all. Photos get the GiroCode in the reply body, PDFs come back stamped as attachments, several per email if you like.

1. Register your sender address in the app under "API & integrations".
2. Click the confirmation link in the email — done.
3. Send invoices (PDF, JPG, PNG, WEBP) to the processing address and wait for the reply.

Up to 10 attachments per email, 12 MB each. The reply always states tokens charged and remaining; when the balance runs low, the top-up link is included.

The app itself is the fourth door: upload, review, stamp — right in the browser. And whichever door an invoice comes in through, everything is journaled in your history, with QR, PDFs and costs retrievable any time.

One rule, everywhere: 1 token per page (a QR from ready payment data counts as one page). New accounts start with 10 free tokens; top up via Stripe — in the app, via POST /api/v1/checkout or with the buy_tokens tool.

When the balance runs low we warn you by email; at 0 processing pauses on every door (no AI service is called) and every response carries the top-up link.

Billed fairly: if processing fails on our side, the token is refunded. If the model ran but could not read the invoice, it stays spent.

Every error uses the same envelope — a machine-readable code, a human message, and on token shortage (HTTP 402) the top-up link right in the response:

{
  "error": {
    "code": "insufficient_tokens",
    "message": "Not enough tokens for this operation.",
    "needed": 3,
    "balance": 1,
    "checkoutUrl": "https://www.girosnap.eu/app?screen=tokens"
  }
}

Key codes: insufficient_tokens (402), unreadable (422, the model ran — token spent), extraction_failed (502, refunded), unsupported_media (415), file_too_large (413). Full catalog in the interactive reference.