One-Tap Pay From QR Menu via iyzico Inline Checkout: Integration Steps

A 45-table steakhouse in Ankara Çankaya wanted to eliminate the 7-9 minute dead time between a guest saying "check please" and walking out. Their goal was not just speed: they needed Turkish-compliant invoice PDFs with 10% VAT on food and 20% VAT on alcohol, generated automatically.

Why Inline Checkout? 3DS v2 and PCI scope

Inline Checkout keeps the card form inside an iyzico iframe — your server never touches the PAN. This drops you to PCI DSS SAQ-A scope: annual audit cost goes from roughly USD 2,500-4,000 down to zero. 3DS v2 triggers automatically, with frictionless flow active on ~78% of transactions.

Architecture is simple: customer taps "Pay" on QR menu → POSTs to /api/payments/initialize → backend fetches checkoutFormContent from iyzico → iframe opens. The customer enters card details into iyzico, and the callback returns only a token.

Webhook idempotency and race conditions

iyzico fires webhooks 3-7 times for the same paymentId, especially during 3DS challenge. Solution: UNIQUE constraint on paymentId in an iyzico_webhook_events table. Each event tries INSERT; on 23505 (duplicate) return 200 no-op. Same pattern as Stripe.

• Signature verify: iyzico signs with HMAC-SHA256; pull the secret from merchant panel into an env var.
• Replay window: 5 minutes — reject older timestamps.
• Status mapping: SUCCESS → orders.payment_status = paid; FAILURE → retryable error code.

VAT-split invoice PDF (food 10%, alcohol 20%)

Turkish regulation requires restaurants to split food VAT (10%) and alcohol VAT (20%) into separate invoice lines. In the Çankaya example, a 480 TL bill splits as 320 TL food (29.09 TL VAT) and 160 TL alcohol (26.67 TL VAT).

PDF generation uses @react-pdf/renderer; VKN/TCKN, taxpayer name, and invoice date fields map directly to e-Arşiv requirements. At ~3,200 invoices/month, server cost stays under USD 4-6.

FAQ

What is iyzico's commission? Standard 2.49% + 0.25 TL per transaction; above 100K TL monthly volume you can negotiate to 1.99%.

Is card-save (Card Storage) secure? iyzico returns cardUserKey/cardToken; you store no PAN, so you remain PCI scope-free.

How fast are refunds? Same-day full refund posts instantly; after T+1 the bank settles in 2-7 business days.

Found this helpful? Share it.