Virtuelles POS (iyzico/PayTR) in Individualsoftware integrieren: 3DS, sichere Webhooks & Abstimmung

Ein virtuelles POS (Zahlungsgateway) in eine Individualsoftware zu integrieren, ist – anders als viele Teams glauben – nicht damit getan, "die API von iyzico oder PayTR aufzurufen". Eine produktionsreife Integration muss vier voneinander getrennte Probleme gleichzeitig lösen: (1) den 3-D-Secure-Ablauf (3DS) korrekt aufsetzen — den Nutzer zur Verifizierungsseite der Bank schicken und wieder zurückholen; (2) Callback/Webhook sicher verifizieren — per Signatur beweisen, dass die eingehende Benachrichtigung wirklich vom Anbieter stammt, gegen wiederholte Benachrichtigungen idempotent sein und schnell mit 2xx antworten; (3) Zahlung und Bestellung abstimmen — das Ereignis, mit dem Sie das Geld vereinnahmen, der richtigen Bestellung zuordnen; und (4) nachgelagerte Szenarien wie Rückerstattung/Stornierung/Ratenzahlung verwalten. Fehlt auch nur eines davon, wirkt die Integration zwar, als würde sie "funktionieren", ist aber in der Produktion anfällig für stille Fehler, die Geld kosten: eine doppelt verarbeitete Bestellung, ein als "bezahlt" angezeigter, aber nicht bestätigter Warenkorb oder ein per gefälschtem Callback ergaunertes Gratisprodukt. In diesem Beitrag teilen wir als ein in Sakarya ansässiges B2B-/White-Label-Softwareunternehmen unser Framework für virtuelle POS-Integrationen genau so, wie wir es umsetzen: Bank-POS oder Zahlungsdienstleister, Hosted Form oder Direct API, 3DS-Ablauf, sicherer Webhook, Abstimmung, Rückerstattung/Ratenzahlung sowie eine Checkliste vor dem Go-live.

Dieser Beitrag behandelt die Zahlungsintegration als ein Thema der API-Integration und der E-Commerce-Infrastruktur. Dieselbe Disziplin haben wir auch auf der ERP-/E-Rechnung-Seite angewandt; wenn Sie die Entscheidung "fertige Lösung oder Individualintegration" interessiert, werfen Sie einen Blick in unseren Beitrag zu E-Commerce-, ERP- und E-Rechnung-Integration. Die folgenden technischen Details stützen sich auf die offizielle Dokumentation von iyzico und PayTR; da sich jeder Anbieter im Laufe der Zeit ändern kann, ist die einzig verbindliche Quelle stets die offizielle Dokumentation zum Zeitpunkt der Integration.

Bank-POS oder Zahlungsdienstleister?

Die erste Architekturentscheidung ist, über welchen Kanal Sie Karten einziehen. In der Türkei wird ein virtuelles POS auf zwei Wegen angeboten: (a) ein Bank-POS mit direktem Vertrag bei einer Bank und (b) bankenunabhängige Zahlungsdienstleister (wie iyzico, PayTR). Zahlungsdienstleister agieren im Rahmen des türkischen Gesetzes Nr. 6493 über Zahlungs- und Wertpapierabwicklungssysteme, Zahlungsdienste und E-Geld-Institute und erhalten ihre Betriebserlaubnis nicht von der BDDK, sondern von der türkischen Zentralbank TCMB (Gesetz Art. 12) (TCMB — Zahlungsinstitute).

Der praktische Unterschied: Bei einem Bank-POS ist in der Regel für jede Bank eine eigene Integration und ein eigener Vertrag erforderlich; ein unabhängiger Zahlungsdienstleister ermöglicht Ihnen dagegen, mit einer einzigen Integration die Karten der meisten Banken zu akzeptieren. iyzico sticht besonders bei Marktplatz-/Submerchant-Szenarien (Unterhändler) hervor. Die Entscheidungsregel ist einfach:

• Wenn Sie eine einzige Bank, hohes Volumen und die niedrigste Provision priorisieren und eine starke Beziehung zu genau einer Bank haben, kann ein Bank-POS sinnvoll sein; sobald Sie jedoch Unterstützung für mehrere Banken wünschen, vervielfacht sich der Integrationsaufwand.
• Wenn Sie einen schnellen Go-live, die Akzeptanz mehrerer Banken und eine einzige Integration wollen, bringt ein Zahlungsdienstleister (iyzico/PayTR) in den meisten B2B- und KMU-Szenarien geringere Wartungskosten mit sich.
• Wenn Sie Marktplatz-Funktionen / Provisionsaufteilung / Submerchant benötigen, ist ein Zahlungsdienstleister mit Submerchant-Unterstützung nahezu zwingend.

Hosted Form oder Direct API? Hier entscheidet sich Ihr PCI-DSS-Geltungsbereich

Die zweite und vielleicht wichtigste Entscheidung ist, wo die Kartendaten durchlaufen — denn das bestimmt unmittelbar Ihren PCI-DSS-Geltungsbereich. Es gibt zwei Ansätze:

• Hosted / gehostetes Zahlungsformular: Die Kartendaten werden auf einer vom Anbieter gehosteten Seite oder in einem iFrame erfasst. Bei der PayTR iFrame API gibt der Nutzer seine Karte im iFrame von PayTR ein; auf der iyzico-Seite ist CheckoutForm die von iyzico gehostete Zahlungsseite (mit CF-Initialize wird eine paymentPageUrl/ein Token zurückgegeben, mit iframe=true lässt es sich einbetten). In beiden Fällen berühren die sensiblen Kartendaten Ihren Server nicht, wodurch sich Ihr PCI-DSS-Geltungsbereich erheblich verkleinert.
• Direct API: Sie erfassen die Zahlung mit Ihrem eigenen Zahlungsformular; die Kartendaten laufen durch Ihre eigene Infrastruktur. Das bietet volle Kontrolle und ein gebrandetes Erlebnis, erhöht aber Ihre PCI-DSS-Pflichten erheblich.

Sowohl iyzico als auch PayTR übernehmen den PCI-Schutz auf Anbieterseite; iyzico positioniert sich als PCI-DSS-Level-1-Dienstleister. Doch sagen wir es klar: Ihr genauer SAQ-Typ (SAQ A, SAQ A-EP usw.) hängt von den Integrationsdetails ab und wird in diesem Beitrag nicht behauptet; allgemein gilt, dass sich der Geltungsbereich reduziert, wenn die Kartendaten Ihren Server nicht berühren. Unsere praktische Empfehlung ist eindeutig:

Wenn Sie keine geschäftliche Notwendigkeit für ein gebrandetes, vollständig kontrolliertes Checkout-Erlebnis haben, wählen Sie das Hosted Form. Die paar Pixel Individualisierung, die Sie gewinnen, sind die PCI-DSS-Prüf- und Haftungslast, die Sie sich aufbürden, nicht wert.

Wie funktioniert der 3DS-Ablauf? (Beispiel iyzico)

3-D Secure ist eine zusätzliche Verifizierung durch die Bank des Karteninhabers (Einmalcode, Bestätigung in der Bank-App usw.). Wird dieser Schritt übersprungen, bleiben das Chargeback-Risiko und die Haftung weitgehend beim Händler. Bei iyzico ist 3DS ein zweistufiger POST-Ablauf:

• Schritt 1 — Init 3DS: Sie senden per POST Karten-/Käuferdaten und eine callbackUrl an den Endpunkt /payment/3dsecure/initialize. In der Antwort wird ein base64-kodierter threeDSHtmlContent zurückgegeben. Dieses HTML wird gerendert, wodurch der Nutzer zur 3DS-Verifizierungsseite der Bank weitergeleitet wird.
• Schritt 2 — Auth 3DS: Nachdem der Nutzer die Verifizierung bei der Bank abgeschlossen hat und zu Ihrer callbackUrl zurückgekehrt ist, senden Sie mit der aus Init zurückgegebenen paymentId einen zweiten POST an den Auth-Endpunkt. iyzico empfiehlt hier die Nutzung des v2-Endpunkts (/payment/v2/3dsecure/auth, also 3DS 2.0); der Legacy-Endpunkt /payment/3dsecure/auth ist 3DS 1.0.

Das Ergebnis der Verifizierung trägt das Feld mdStatus: 1 bedeutet erfolgreich, die Werte 0 sowie 2–8 bedeuten eine fehlgeschlagene Verifizierung. Ein wichtiger Hinweis: Das genaue Feldschema des POST-Bodys, den die Bank an Ihre callbackUrl sendet, geben wir hier nicht als abschließende Liste an — denn das kann je nach Version und Integration variieren; es ist ein Detail, das vor dem Go-live anhand der aktuellen offiziellen Dokumentation zu verifizieren ist (iyzico — Init 3DS, iyzico — Auth 3DS).

Um Anfrage und Antwort über den gesamten Ablauf hinweg einander zuzuordnen, wird die conversationId verwendet. iyzico definiert sie als "eindeutige ID zur Request-/Response-Korrelation"; Sie können hier Ihre eigene Bestellnummer eintragen, und der in der Anfrage gesendete Wert kommt in der Antwort unverändert zurück. Zusätzlich vergibt iyzico jeder erfolgreichen Zahlung auf seiner Seite eine eigene paymentId; Rückerstattungen und Stornierungen laufen über diese paymentId.

Sichere Webhook-/Callback-Verifizierung: Signatur, Idempotenz, schnelles 2xx

Dies ist der am häufigsten übersehene und gefährlichste Teil einer Zahlungsintegration. Der Callback/Webhook ist das eigentliche, von Server zu Server eintreffende Ereignis, mit dem Sie das Geld als vereinnahmt markieren. Drei Regeln sind nicht verhandelbar: Signatur verifizieren, idempotent sein, schnell mit 2xx antworten.

1) Signaturverifizierung — beweisen, dass die Benachrichtigung wirklich vom Anbieter stammt

Werten Sie niemals einen an Ihren Callback eingehenden POST als "bezahlt", ohne dessen Signatur zu verifizieren. Andernfalls könnte ein Angreifer durch das Senden einer gefälschten "erfolgreiche Zahlung"-Benachrichtigung eine Gratisbestellung auslösen. Die Mechanismen der beiden Anbieter unterscheiden sich:

• PayTR (iFrame API): Bei der an notify_url eingehenden Benachrichtigung wird der Hash mit base64_encode(hash_hmac('sha256', merchant_oid + merchant_salt + status + total_amount, merchant_key, true)) berechnet. Stimmt der hash im eingehenden POST mit diesem Wert nicht exakt überein, ist die Anfrage als nicht von PayTR stammend zu betrachten und abzulehnen. Diese Formel gilt für die iFrame API (vier Felder); bei den anderen APIs von PayTR kann der Feldsatz anders sein — nicht verwechseln.
• iyzico (Webhook): Die Verifizierung erfolgt über den Header X-IYZ-SIGNATURE-V3 mittels HMAC-SHA256 (HEX); ältere Header-Versionen werden nicht mehr unterstützt. Der kritische Punkt: Die Reihenfolge der für die Signatur verketteten Felder ändert sich je nach Webhook-Typ. Direct Payment, HPP und Subscription verwenden unterschiedliche Parameterreihenfolgen — es gibt keine einzige "allgemeine" Webhook-Signaturreihenfolge; verifizieren Sie die Reihenfolge Ihres eigenen Integrationstyps anhand der offiziellen Tabelle.

iyzico bietet außerdem für synchrone API-Antworten einen separaten Response-Signature-Mechanismus: Bestimmte Parameter werden mit Doppelpunkt (:) verkettet, mit dem secretKey per HMAC-SHA256 gehasht und in HEX kodiert; unnötige nachfolgende Nullen in Preisen werden entfernt (10.50 → 10.5, 10.00 → 10). Die Parameterreihenfolge variiert je nach Endpunkt; zum Beispiel lautet die Reihenfolge bei Non-3DS-Auth paymentId:currency:basketId:conversationId:paidPrice:price, und v2-3DS-Auth verwendet dieselbe Feldreihenfolge (iyzico — Response Signature Validation, iyzico — Webhook, PayTR — iFrame API Schritt 2).

2) Idempotenz — trifft dieselbe Benachrichtigung zweimal ein, nicht zweimal verarbeiten

Beide Anbieter können für dieselbe Transaktion mehrere Benachrichtigungen senden. Führen Sie keine Deduplizierung über Ihre Bestell-ID durch, wird dieselbe Bestellung zweimal bestätigt, der Bestand zweimal reduziert, der Versand zweimal ausgelöst. PayTR weist ausdrücklich darauf hin: Die Wiederholungsprüfung ist anhand des eindeutigen Feldes merchant_oid vorzunehmen; zum Bestätigen/Stornieren der Bestellung darf nur die erste Benachrichtigung verarbeitet werden, wiederholten ist lediglich zu antworten. In der Praxis: Halten Sie den Status der Benachrichtigung (verarbeitet/nicht verarbeitet) in einem eindeutigen, an die Bestell-ID gebundenen Datensatz in Ihrer Datenbank und führen Sie die Verarbeitung in einer einzigen atomaren Transaktion aus.

3) Schnell mit 2xx antworten — die schwere Arbeit asynchron erledigen

Der Anbieter erwartet auf die Benachrichtigung binnen kurzer Zeit eine positive Antwort; bleibt sie aus, versucht er es erneut. Antwortet der Händler beim iyzico-Webhook nicht mit 2xx, versucht iyzico es alle 15 Minuten, höchstens 3 Mal erneut. PayTR wiederum versucht es nach 1 Minute erneut, wenn kein "OK" eingeht, und verlangt, dass der Antwort-Body — ohne HTML oder sonstige Inhalte — ausschließlich der reine Text OK ist. Daraus ergeben sich zwei Regeln:

• Zuerst verifizieren, dann speichern, dann antworten: Verifizieren Sie die Signatur, markieren Sie die Bestellung eindeutig und geben Sie anschließend die erwartete Antwort zurück. Schwere Aufgaben wie E-Mail-Versand, Rechnungsstellung oder das Schreiben ins ERP legen Sie in eine asynchrone Warteschlange; führen Sie sie nicht so synchron aus, dass sie die Callback-Antwort blockieren.
• Geben Sie den Antwort-Body im vom Anbieter erwarteten Format zurück: für PayTR exakt OK; für iyzico einen 2xx-HTTP-Statuscode. Andernfalls erleben Sie unnötige Retries und "verlorene" Zahlungen.

Zahlungs-Bestell-Abstimmung (Reconciliation)

Die Abstimmung ist die Brücke zwischen "dem vom Anbieter vereinnahmten Geld" und "der Bestellung in Ihrem System". Eine schwach aufgesetzte Abstimmung bereitet in der Buchhaltung und im Kundenservice die meisten Kopfschmerzen. Beide Anbieter schlagen diese Brücke über eine vom Händler erzeugte, eindeutige Bestell-ID:

• PayTR: merchant_oid (höchstens 64 alphanumerische Zeichen) ist die eindeutige Bestellnummer, die Sie für die Transaktion festlegen; sie wird Ihnen im Callback zurückgegeben und ermöglicht so die Abstimmung. Außerdem wird in Schritt 1 der paytr_token per HMAC-SHA256 + base64 erzeugt, und der verkettete String enthält die Felder merchant_id + user_ip + merchant_oid + email + payment_amount + user_basket + no_installment + max_installment + currency + test_mode + merchant_salt.
• iyzico: Verwenden Sie die conversationId als Ihre eigene Bestellnummer; der in der Anfrage gesendete Wert kommt in der Antwort unverändert zurück. Das Pendant auf Anbieterseite ist die paymentId — Rückerstattung/Stornierung erfolgen über diese. Speichern Sie beide IDs in Ihrem eigenen Bestelldatensatz.

Praktische Grundsätze für eine robuste Abstimmung:

• Geben Sie die Autorität dem Callback, nicht dem Browser: Die "Erfolgsseite", auf die der Browser des Nutzers zurückkehrt, ist ein Hinweis, kein Beweis. Bestätigen Sie die Bestellung maßgeblich über den von Server zu Server eintreffenden, signaturverifizierten Callback.
• Vergleichen Sie Betrag und Währung: Gleichen Sie den Betrag im Callback mit dem in Ihrer Bestellung erwarteten Betrag ab; stimmen sie nicht überein, verarbeiten Sie nicht, sondern schlagen Sie Alarm.
• Schließen Sie ausstehende (pending) Zustände: Kommt gar kein Callback, prüfen Sie Bestellungen mit dem Status "Zahlung gestartet, aber nicht abgeschlossen" über einen Hintergrundjob per Abfrage-API des Anbieters und schließen Sie sie.
• Tägliche Abstimmung: Vergleichen Sie die Transaktions-/Zahlungsberichte des Anbieters regelmäßig mit Ihren eigenen Aufzeichnungen; verlassen Sie sich nicht allein auf den Webhook.

Rückerstattung, Teilrückerstattung und Ratenzahlung

Die zweite Hälfte des Zahlungsablaufs sind die nachgelagerten Szenarien; hier gewinnt man Kundenerlebnis und buchhalterische Korrektheit. Speziell bei iyzico die grundlegenden Unterscheidungen:

• Rückerstattung (Refund) — vollständig oder teilweise: Es gibt zwei Wege. /payment/refund arbeitet positionsbasiert (mit paymentTransactionId, also der Transaktions-ID der Warenkorbposition, und price). /v2/payment/refund arbeitet dagegen zahlungsbasiert (mit paymentId und price); die zu erstattende Warenkorbposition bestimmt das System selbst. Beide Versionen unterstützen vollständige/teilweise Rückerstattung und geben eine Bankreferenz zurück (refundHostReference, authCode).
• Stornierung (Cancel): /payment/cancel wird nur mit der paymentId aufgerufen, unterstützt keinen Teilbetrag und storniert die gesamte Zahlung. Laut iyzico-Dokumentation kann die Cancel-Operation am selben Tag wie die Zahlung erfolgen und erzeugt auf dem Kartenauszug keinen Belastungs-/Gutschriftseintrag; eine Rückerstattung (Refund) hingegen erscheint auf dem Auszug und kann je nach Bank einige Tage dauern. Die genauen Regeln zu Stichtag/Uhrzeit hängen von Bank und Valuta ab; nehmen Sie dies als allgemeines Prinzip, nicht als verbindliche Buchhaltungsregel.
• Ratenzahlung und BIN-Abfrage: Mit POST /payment/iyzipos/installment können Sie durch Senden von price (Pflicht) und optional binNumber (8-stellige BIN) die Ratenoptionen, deren Sätze und Beträge sowie Kartenfamilie/-schema und Bankinformationen abfragen. Auch nur mit dem Betrag (ohne BIN) lassen sich Ratensätze abrufen; die conversationId wird in der Anfrage gesendet und kommt in der Antwort unverändert zurück (iyzico — Refund & Cancel, iyzico — Installment & BIN).

Als Geschäftsregel: Verankern Sie die Logik "am selben Tag Stornierung, danach Rückerstattung" in Ihrem System; wenn Sie dem Nutzer eine Teilrückerstattung gewähren, halten Sie auf Ihrer Seite fest, welche Position/welcher Betrag erstattet wurde, und bewahren Sie die Bankreferenzen auf.

Checkliste vor dem Go-live

• Signaturverifizierung: Wird für jeden Callback/Webhook die Signatur verifiziert? Wird eine nicht verifizierte Anfrage definitiv abgelehnt? Wird bei iyzico die zu Ihrem Integrationstyp passende Feldreihenfolge verwendet?
• Idempotenz: Wird eine für dieselbe Bestell-ID (merchant_oid / conversationId) ein zweites Mal eintreffende Benachrichtigung nicht erneut verarbeitet, sondern nur die passende Antwort zurückgegeben?
• Schnelle Antwort: Antwortet der Callback im erwarteten Format und schnell mit 2xx / OK? Werden schwere Aufgaben in eine asynchrone Warteschlange gelegt?
• Betragsprüfung: Werden Betrag und Währung im Callback mit dem in der Bestellung erwarteten Wert verglichen?
• Autoritätsquelle: Beruht die Bestellbestätigung auf der Server-zu-Server-Benachrichtigung statt auf der Browser-Weiterleitung?
• Schließen ausstehender Vorgänge: Gibt es für "gestartete, aber nicht abgeschlossene" Zahlungen ohne Callback eine Hintergrundabfrage?
• Rückerstattung/Stornierung: Wurden die Szenarien vollständige und teilweise Rückerstattung, Stornierung sowie Ratenzahlung getestet? Werden die Bankreferenzen aufbewahrt?
• Secrets und HTTPS: Werden Secrets wie secretKey/merchant_key/merchant_salt ausschließlich serverseitig, in Umgebungsvariablen, aufbewahrt? Ist die Callback-URL HTTPS?
• Logging: Wird jedes Zahlungsereignis (Anfrage, Antwort, Callback, Signaturergebnis) nachvollziehbar geloggt?
• Testumgebung: Wurde im Sandbox-/Testmodus des Anbieters eine End-to-End-Verifizierung (einschließlich 3DS) durchgeführt?

Wie setzt Partnerfy das auf?

Als ein in Sakarya ansässiges B2B-/White-Label-Softwareunternehmen behandeln wir die virtuelle POS-Integration nicht als einen "API-Aufruf", sondern als ein Sicherheits- und Abstimmungsproblem. In einem Projekt für individuelle Websoftware oder E-Commerce klären wir zunächst die Entscheidung: Zahlungsdienstleister oder Bank-POS, Hosted Form oder Direct API (je nach Ihrem PCI-DSS-Geltungsbereich). Anschließend setzen wir den 3DS-Ablauf, den signaturverifizierten und idempotenten Callback, die Betragsabstimmung sowie die Rückerstattungs-/Ratenzahlungsszenarien Ende-zu-Ende auf und verifizieren sie in der Testumgebung. In der Regel verbinden wir dies als eine API-Integration mit Ihren bestehenden ERP-/Buchhaltungssystemen.

Eine ehrliche Anmerkung: Keine Integration kann die Garantie "es tritt nie ein Problem auf" geben — Banken, Anbieter und Dokumentationen ändern sich mit der Zeit. Unser Versprechen ist keine Garantie, sondern Disziplin: die Signatur verifizieren, idempotent sein, die Autorität dem Callback geben sowie jeden Schritt loggen und abstimmen. Wenn Sie diskutieren möchten, ob ein fertiges Plugin oder eine Individualintegration für Sie passt, hilft Ihnen auch unser Beitrag Individualsoftware oder Standardsoftware, diese Entscheidung einzuordnen.

Fazit

Eine produktionsreife virtuelle POS-Integration beginnt mit dem API-Aufruf, endet dort aber nicht. Die eigentliche Arbeit besteht darin: den richtigen Kanal wählen (Zahlungsdienstleister vs. Bank-POS), den PCI-DSS-Geltungsbereich bewusst verkleinern (Hosted vs. Direct), den 3DS-Ablauf korrekt aufsetzen, den Callback per Signatur verifizieren, idempotent sein, schnell mit 2xx/OK antworten, Betrag und Bestellung abstimmen und die Szenarien Rückerstattung/Stornierung/Ratenzahlung lückenlos verwalten. Jeder dieser Schritte trennt eine Integration, die "aussieht, als würde sie funktionieren", von einer wirklich sicheren. Wenn Sie beim Entwurf Ihrer Zahlungsintegration oder beim Absichern eines bestehenden Setups einen Wegbegleiter brauchen, kontaktieren Sie uns; wir erarbeiten gemeinsam den Kanal, den PCI-Geltungsbereich und den Abstimmungsplan passend zu Ihrem Szenario.

Quellen

• iyzico — Init 3DS (/payment/3dsecure/initialize, threeDSHtmlContent, conversationId)
• iyzico — Auth 3DS (v2 empfohlen, Abschluss mit paymentId, mdStatus)
• iyzico — Response Signature Validation (HMAC-SHA256 + HEX)
• iyzico — Webhook (X-IYZ-SIGNATURE-V3, 2xx-Pflicht, Retry)
• iyzico — Installment & BIN Service (/payment/iyzipos/installment)
• iyzico — Refund & Cancel (/payment/refund, /v2/payment/refund, /payment/cancel)
• iyzico — CheckoutForm (gehostete Zahlungsseite, PCI-Geltungsbereich reduziert sich)
• PayTR — iFrame API Schritt 1 (paytr_token, gehosteter iFrame, merchant_oid)
• PayTR — iFrame API Schritt 2 (Callback-Hash, "OK"-Antwort, Deduplizierung über merchant_oid)
• TCMB — Zahlungsinstitute (Gesetz Nr. 6493 Art. 12, Betriebserlaubnis)

Häufig gestellte Fragen (FAQ)