Payora in eine benutzerdefinierte PHP-Website integrieren

Wie man Payora mit einer benutzerdefinierten PHP-Website verbindet

Wenn Ihre Website als eigenständige PHP-Lösung aufgebaut ist, ist die Sache ziemlich einfach: Zahlung anlegen, Kundschaft zu Payora weiterleiten und das Ergebnis anschließend in Ihr eigenes Bestellsystem zurückholen. Kein WooCommerce nötig. Und auch kein Plugin-Dschungel.

Dieser Leitfaden zeigt, wie Sie Payora mit PHP Website verbinden, ohne Ihren Checkout zu einem Großprojekt aufzublasen. Sie sehen genau, wo PHP die Zahlung starten sollte, wo die Rückgabe ankommen sollte und wo Ihre App entscheidet, ob eine Bestellung bezahlt, ausstehend oder fehlgeschlagen ist. Im Kern geht es um eine saubere Payora PHP Integration, die sich auch für eine benutzerdefinierte PHP Website Payora gut warten lässt.

1. Das Integrationsmuster für eine benutzerdefinierte PHP-Website festlegen

Beginnen Sie mit einer Entscheidung: Bauen Sie nur einen einfachen Checkout-Link, eine serverseitige Zahlungsanfrage oder einen kompletten Zahlungsablauf mit Bestellverfolgung? Das ist nicht dasselbe. Eine einseitige Spendenseite kommt vielleicht mit einem Zahlungslink aus, während ein Shop mit 20 Produkten vor dem Verlassen der Website meist eine serverseitige Auftragserstellung braucht.

Für eine benutzerdefinierte PHP-Website ist das sauberste Muster oft: Bestellung lokal anlegen, Zahlung über PHP bei Payora erstellen, Kundschaft weiterleiten und dann Rückgabe sowie Serverbestätigung auswerten. So haben Sie schon vor dem Geldtransfer einen Eintrag auf Ihrer Seite. Außerdem bleiben Warenkorb- und Rechnungslogik in Ihrer App, wo sie hingehören.

Wenn Ihr Checkout sehr klein ist, reicht vielleicht auch nur eine Weiterleitung zu einer von Payora gehosteten Zahlungsseite. Wenn Sie Positionen, Kundennotizen oder Bestellnummern brauchen, sollte Ihr PHP-Code diese Daten vor der Weiterleitung senden. Einfach. Aber nicht simpel.

Ein praktisches Beispiel hilft. Eine Digitalagentur, die ein dreistufiges Wartungspaket verkauft, kann die Bestellung in PHP anlegen, die E-Mail des Kunden anhängen und den Kunden mit der Rechnungsreferenz zu Payora schicken. Ein Hobbyprojekt, das einen einzelnen Lizenzschlüssel verkauft, braucht möglicherweise nur den Zahlungslink und eine Rückgabeseite. Der Unterschied liegt in dem Zustand, den Sie bewahren müssen, nicht in der Menge des Codes.

2. Die genauen Seiten, Endpunkte und den Sitzungsablauf abbilden

Bevor Sie Code schreiben, listen Sie die Seiten auf. Sie brauchen mindestens drei: eine Checkout-Seite, eine Rückgabeseite und einen Server-Endpunkt für die Zahlungsbestätigung. Wenn Sie diese Abbildung überspringen, raten Sie am Ende nur noch, welche Anfrage die Bestellung verändert hat. Raten ist teuer.

Nutzen Sie für den Browser-Ablauf eine normale PHP-Sitzung, verlassen Sie sich aber nicht allein darauf. Der Sitzungsstatus kann verschwinden, wenn der Kunde das Gerät wechselt, den Tab schließt oder später von Payora zurückkommt. Bewahren Sie die Bestell-ID zusätzlich in Ihrer Datenbank auf, damit Ihr PHP-Code die Transaktion auch dann findet, wenn die Browsersitzung weg ist.

Ein typischer Ablauf sieht so aus:

• Die Checkout-Seite erfasst Produkt, E-Mail und Menge.
• PHP legt lokal eine Bestellung mit dem Status ausstehend an.
• PHP leitet den Kunden zu Payora weiter.
• Payora bringt den Browser zu Ihrer Rückgabe-URL zurück.
• Ihr Server prüft den Zahlungsstatus, bevor die Bestellung als bezahlt markiert wird.

Dieser Ablauf trennt die Rückgabeseite im Browser von der serverseitigen Wahrheit. Gut so. Sie sollten getrennt sein. Der Browser zeigt, was der Kunde gesehen hat; Ihr Server sollte entscheiden, was die Bestellung bedeutet.

Eine kleine Gewohnheit spart später Stunden: Speichern Sie die Payora-Zahlungsreferenz direkt neben Ihrer Bestell-ID, sobald Sie die Zahlung anlegen. Wenn Sie damit bis nach der Weiterleitung warten, kann ein Netzwerkausfall oder ein ungeduldiges Neuladen am Ende eine Bestellung ohne Payora-Referenz zurücklassen. Dann spielen Sie in der Produktion Detektiv.

3. Eine minimale PHP-Schicht für Zahlungsanfragen vorbereiten

Halten Sie Zahlungslogik aus Vorlagen heraus. Eine kleine PHP-Klasse oder ein Helper reicht völlig aus. Eine Methode kann die Nutzlast bauen, eine zweite die HTTP-Anfrage senden und eine dritte die Antwort parsen. Diese Trennung ist wichtig, weil sich Zahlungslogik häufiger ändert als das Seitenlayout.

Ihr Helper kann zum Beispiel ein Array mit amount, currency, order_id und return_url entgegennehmen und dann Ihre Payora-Zugangsdaten aus Umgebungsvariablen ergänzen. Die Checkout-Seite sollte nie wissen, wo das API-Token liegt. Sie sollte nur wissen, welcher Button geklickt wurde.

Hier ist die Form der Logik, nicht eine vollständige Implementierung:

1. Die Bestellung aus der Datenbank lesen.
2. Ein Payora-Anfrage-Array aufbauen.
3. Die Anfrage mit cURL oder einem ähnlichen HTTP-Client senden.
4. Die zurückgegebene Payora-Zahlungsreferenz speichern.
5. Den Kunden zur Payora-Zahlungs-URL weiterleiten.

Halten Sie diesen Helper langweilig. Langweiliger Code ist leichter zu testen. Langweiliger Code bricht seltener, wenn Sie nächsten Monat einen Produktpreis ändern oder ein zweites Checkout-Formular hinzufügen.

Wenn Ihre App bereits eine Zahlungsabstraktion hat, verwenden Sie sie. Wenn nicht, erstellen Sie eine Datei und geben Sie ihr einen klaren Namen, zum Beispiel PayoraClient.php. Diese Datei sollte Zugangsdaten, API-Aufrufe und Antwortverarbeitung enthalten. Sonst nichts. Kein HTML. Kein CSS. Keine Dankesnachricht.

4. Den Kunden aus Ihrem benutzerdefinierten Checkout zu Payora weiterleiten

Sobald die lokale Bestellung existiert, senden Sie die Payora-Zahlungsanfrage ab und leiten den Kunden zur Payora-Zahlungsseite weiter. Die Übergabe sollte erst erfolgen, nachdem Ihr Server die Bestellung gespeichert hat, denn der Nutzer kann den Tab schließen, sobald die Weiterleitung beginnt.

Übergeben Sie die tatsächlich benötigten Bestelldaten. Das bedeutet meist Bestell-ID, Betrag, Währung und E-Mail des Kunden. Sie können auch Metadaten wie Produktname oder interne Konto-ID mitsenden, aber werfen Sie nicht einfach jedes Feld aus Ihrer Datenbank in die Anfrage, nur weil es verfügbar ist. Zusätzliche Daten können später Verwirrung stiften, wenn der Support Datensätze vergleicht.

Ein benutzerdefinierter Checkout verwendet oft ein POST-Formular mit einem „Jetzt bezahlen“-Button. Dieses Formular sendet an Ihren PHP-Endpunkt, der Endpunkt erstellt die Payora-Zahlung und antwortet dann mit einer Weiterleitung. Der Kunde sieht nie die API-Antwort. Er sieht nur Payora.

Eine kleine Warnung: Vertrauen Sie nicht den clientseitigen Summen. Wenn Ihre Produktseite 49 $ anzeigt und Ihr Browser 39 $ sendet, muss Ihr Server die Abweichung zurückweisen. Eine Zahlungsanfrage sollte auf dem serverseitigen Bestellwert basieren, nicht auf dem im Formular versteckten Wert. Diese Regel gilt immer.

Wenn Sie einen breiteren Überblick über Muster zur Zahlungsintegration möchten, bietet der Leitfaden zum Krypto-Zahlungsgateway für E-Commerce hilfreichen Kontext, ohne den PHP-Ablauf hier zu wiederholen.

5. Das Zahlungsergebnis in der eigenen App empfangen und validieren

Die Rückgabe-URL im Browser ist nützlich, aber nicht das letzte Wort. Sie kann zeigen, dass die Zahlungsseite besucht wurde, und sie kann einen Statuswert mitbringen, aber Ihre PHP-App sollte dieses Ergebnis trotzdem nur als vorläufig behandeln, bis der Server es bestätigt. Ausstehend ist nicht bezahlt.

Gestalten Sie die Rückgabeseite für drei Fälle: Erfolg, ausstehend und fehlgeschlagen. Wenn Payora Erfolg meldet, zeigen Sie eine Dankeseite und teilen Sie mit, dass die Bestellung gerade bestätigt wird. Wenn der Status ausstehend ist, sagen Sie genau das. Wenn es fehlgeschlagen ist, laden Sie den Kunden ein, es erneut zu versuchen, ohne den Bestellnachweis zu verlieren. Klare Formulierungen reduzieren Support-Tickets.

Dazu gibt es eine nützliche Regel: Die Rückgabeseite sollte die bezahlte Bestellung niemals selbst anlegen. Sie sollte nur den aktuellen Zustand anzeigen und eventuell einen Link zurück zur Bestellseite anbieten. Die Aktualisierung in Ihrer Datenbank erfolgt nach der Prüfung, nicht nach einer Browser-Weiterleitung. Dieser Unterschied schützt vor versehentlichen Doppelaktualisierungen.

Halten Sie den Rückgabe-Endpunkt so einfach, dass man ihn auf einen Blick versteht. Wenn er eine Payora-Zahlungsreferenz erhält, sehen Sie diese nach. Fehlt die Referenz, protokollieren Sie die Anfrage und stoppen Sie. Ist die Bestellung bereits bezahlt, zeigen Sie eine freundliche Nachricht und ändern Sie nichts mehr. So bleiben idempotente Abläufe auch bei wiederholtem Neuladen ruhig.

Für Teams, die auch einen Checkout-Vergleich auf Kundenseite wollen, enthält der Artikel über wie man Krypto-Zahlungen annimmt hilfreiche Hinweise zur Abrechnung, besonders wenn Sie Dienstleistungen mit wiederkehrenden Rechnungen oder manuellen Freigaben verkaufen.

6. Die Transaktion serverseitig bestätigen, bevor die Bestellung als bezahlt markiert wird

Das ist der sicherere Schritt. Ihre PHP-App sollte Payora serverseitig abfragen und den Transaktionsstatus bestätigen, bevor sie die Bestellung auf bezahlt setzt. Browser-Weiterleitungen können unvollständig sein; Serverprüfungen ist egal, ob der Kunde den Tab geschlossen, zweimal aktualisiert oder ein zweites Gerät verwendet hat.

Verwenden Sie die zuvor gespeicherte Payora-Referenz und fragen Sie dann den aktuellen Transaktionsstatus ab. Vergleichen Sie den zurückgegebenen Status mit dem Status, den Sie für die Ausführung benötigen. Wenn die Transaktion beglichen oder bestätigt ist, aktualisieren Sie die Bestellung. Wenn sie ausstehend ist, bleibt die Bestellung ausstehend. Wenn sie fehlgeschlagen oder storniert ist, lassen Sie die Bestellung unangetastet.

Noch ein Hinweis: Genau an diesem Punkt werden viele benutzerdefinierte PHP-Websites unsauber. Sie vertrauen der Rückgabeseite, weil das schneller zu programmieren ist. Schneller, ja. Sicherer, nein. Ein fünfsekündiger Prüf-Schritt ist jedem Support-Mail-Verlauf später überlegen.

Wenn Payora einen signierten Callback oder einen server-zu-server-Mechanismus zur Bestätigung bereitstellt, verwenden Sie ihn zusammen mit der Statusabfrage. Das gibt Ihnen zwei Prüfungen: eine aus dem Kundenfluss und eine aus dem Serverfluss. Wenn Ihre Umsetzung eine schrittweise Signaturprüfung benötigt, sehen Sie sich wie man eine Krypto-Zahlung testet an, um die Art von Prüfdiziplin zu bekommen, die sich vor dem Start auszahlt.

Markieren Sie die Bestellung erst dann als bezahlt, wenn der Server zustimmt. Nicht wenn der Kunde es sagt. Nicht wenn der Browser es sagt. Ihre Datenbank sollte den von Payora bestätigten Zahlungsstatus widerspiegeln, denn genau diesem Status werden Fulfillment und Buchhaltung später vertrauen.

7. Den Zahlungsdatensatz speichern und doppelte Übermittlungen behandeln

Speichern Sie die Payora-Transaktionsreferenz, die lokale Bestell-ID, den Betrag, die Währung und den endgültigen Status in Ihrer Datenbank. Tun Sie das möglichst in einem einzigen Schreibvorgang. Wenn sich später ein Kunde mit „Ich habe zweimal bezahlt“ meldet, brauchen Sie einen sauberen Datensatz und nicht drei halbfertige Updates.

Doppelte Übermittlungen passieren aus ganz normalen Gründen. Der Kunde klickt zweimal. Die Zurück-Schaltfläche wird benutzt. Der Browser versucht die Anfrage erneut. Ihr PHP-Code sollte erkennen, dass die Bestellung bereits eine Payora-Referenz hat, und sich weigern, für dieselbe Bestellung eine zweite Zahlung anzulegen, es sei denn, die erste ist fehlgeschlagen oder abgelaufen. Das ist der Kern von Idempotenz.

Eine einfache Regel funktioniert gut: eine lokale Bestellung, eine aktive Payora-Transaktion. Wenn eine zweite Anfrage für dieselbe Bestellung eingeht, während die erste noch ausstehend ist, zeigen Sie den vorhandenen Payora-Checkout-Link an, statt eine neue Zahlung zu erzeugen. Wenn die Bestellung bereits bezahlt ist, tun Sie nichts. Ganz still. Dieses Schweigen ist eine Funktion.

Machen Sie Ihre Datenbankspalten spezifisch. Behalten Sie zum Beispiel payora_reference, payment_status, paid_at und last_checked_at. Diese Felder helfen Support, Buchhaltung und Fehlersuche. Wenn Sie später eine Zahlung abgleichen müssen, beantworten diese vier Felder die meisten Fragen, ohne eine Stunde lang Protokolle zu durchsuchen.

Wenn Sie statt eines Shop-Checkouts einen Kundenrechnungsfluss aufbauen, kann Ihnen auch der Artikel über das Krypto-Zahlungsgateway für Freelancer bei derselben Logik zur Nachverfolgung helfen, vor allem dort, wo Rechnungsnummern wichtiger sind als Warenkörbe.

8. Den gesamten Ablauf auf einer Staging-Kopie der Website testen

Bevor Sie live gehen, klonen Sie die Website auf Staging und testen Sie die komplette Kette: Auftragserstellung, Payora-Weiterleitung, Rückgabeseite, Serverprüfung und Umgang mit Doppelklicks. Wenn Sie nur die Weiterleitung testen, haben Sie nur ein Drittel des Problems geprüft.

Führen Sie mindestens diese Prüfungen durch:

• Neue Bestellung anlegen und bestätigen, dass die Payora-Zahlungsanfrage erzeugt wird.
• Die Rückgabeseite zweimal neu laden und bestätigen, dass sich die Bestellung nicht erneut ändert.
• Das Checkout-Formular zweimal absenden und prüfen, dass nur 1 aktive Transaktion existiert.
• Ein ausstehendes oder fehlgeschlagenes Ergebnis erzwingen und bestätigen, dass die Bestellung unbezahlt bleibt.
• Prüfen, ob die gespeicherte Payora-Referenz mit dem Datenbankeintrag übereinstimmt.

Testen Sie mit genau der PHP-Version und dem Server-Setup, das Sie live verwenden wollen. Ein Ablauf, der auf einem lokalen Laptop funktioniert, kann auf einem Produktionsserver mit strengerer SSL-Konfiguration oder einer anderen cURL-Einstellung scheitern. Das ist nicht selten. Das passiert.

Ein letzter praktischer Test: Öffnen Sie die Bestellung in einem Inkognito-Fenster, schließen Sie die Zahlung ab und öffnen Sie dann dieselbe Rückgabe-URL in einem zweiten Browser. Ihre App sollte keine zweite Zahlungsaktualisierung auslösen. Wenn doch, beheben Sie das vor dem Start. Ohne Ausnahme.

Für Teams, die neben anderen Zahlungsmethoden auch USDC-Checkout-Pfade anbieten, können die Hinweise in wie man USDC-Zahlungen annimmt helfen, die Erwartungen der Kundschaft zu vergleichen, bevor Sie den PHP-Ablauf in die Produktion bringen.

Das ist der letzte Punkt, den Sie prüfen sollten: Dieselbe Bestellung sollte eine Weiterleitung, ein Neuladen und eine Serverbestätigung überstehen, ohne aus dem Takt zu geraten. Wenn das klappt, ist Ihr benutzerdefinierter PHP-Checkout bereit für die erste Live-Zahlung.