Tokenisierung: gespeicherte Zahlungsmittel belasten

Die Tokenisierung speichert das Zahlungsmittel eines Kunden während eines normalen Checkouts als wiederverwendbares Token. Danach können Sie diesen Kunden server-seitig belasten — mit beliebigem Betrag, zu beliebiger Zeit — ohne ihn erneut auf eine Zahlungsseite zu schicken. Sensible Kartendaten berühren Ihre Systeme nie: FlowAlp Pay verwahrt sie, Sie speichern nur IDs.

So funktioniert die Tokenisierung#

1. Erstellen Sie ein Gateway mit "preAuthorization": true. Der Kunde durchläuft den gewohnten gehosteten Checkout, statt einer Belastung wird aber nur das Zahlungsmittel registriert.
2. Die Transaktion erhält den Status authorized — zugestellt über den Transaktions-Webhook, inklusive Transaktions-ID.
3. Wann immer Sie Geld einziehen möchten, belasten Sie diese Transaktions-ID über den Transaction-Endpoint mit einem Betrag Ihrer Wahl.
4. Jede Belastung erzeugt eine neue Transaktion (confirmed bei Erfolg), die über preAuthorizationId auf das Token verweist.

Tokens laufen nicht ab und können beliebig oft mit beliebigem Betrag belastet werden. Anders als bei einer Vorautorisierung werden jedoch keine Mittel blockiert — eine Belastung kann fehlschlagen (abgelaufene Karte, ungenügende Deckung), Ihr Code muss Fehlschläge also behandeln.

Zahlungsmittel im Checkout speichern#

Setzen Sie beim Erstellen des Gateways preAuthorization auf true. Bei einer reinen Tokenisierung wird der Betrag nicht belastet — der Checkout registriert nur das Zahlungsmittel. Soll die erste Zahlung sofort eingezogen werden, setzen Sie zusätzlich chargeOnAuthorization auf true.

curl -X POST "https://api.pay.flowalp.com/v1.16/Gateway/?instance=demo-shop" \
  -H "x-api-key: $FLOWALP_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 2990,
    "currency": "CHF",
    "purpose": "Save payment method",
    "referenceId": "CUST-55021-SETUP",
    "preAuthorization": true,
    "chargeOnAuthorization": true,
    "successRedirectUrl": "https://app.example.com/billing/success",
    "failedRedirectUrl": "https://app.example.com/billing/failed",
    "cancelRedirectUrl": "https://app.example.com/billing/cancel"
  }'

Meldet der Webhook den Status authorized, speichern Sie die Transaktions-ID beim Kundendatensatz — sie ist der Schlüssel für alle künftigen Belastungen. Sie können sie auch durch Abrufen des Gateways auslesen.

Token server-seitig belasten#

Eine spätere Belastung ist eine einzelne POST-Anfrage auf die gespeicherte Transaktions-ID — ganz ohne Kundeninteraktion. Der Betrag ist frei wählbar, in der kleinsten Einheit:

curl -X POST "https://api.pay.flowalp.com/v1.16/Transaction/98123/?instance=demo-shop" \
  -H "x-api-key: $FLOWALP_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 1490,
    "purpose": "Usage fees July",
    "referenceId": "CUST-55021-2026-07"
  }'

<?php
use FlowAlpPay\FlowAlpPay;
use FlowAlpPay\Models\Request\Transaction;

$client = new FlowAlpPay(
    getenv('FLOWALP_TENANT'),
    getenv('FLOWALP_API_SECRET'),
    FlowAlpPay::DEFAULT_COMMUNICATION_HANDLER,
    'pay.flowalp.com',
    '1.16'
);

$charge = new Transaction();
$charge->setId(98123); // transaction with status "authorized"
$charge->setAmount(1490); // CHF 14.90
$charge->setPurpose('Usage fees July');
$charge->setReferenceId('CUST-55021-2026-07');

$response = $client->charge($charge);

Jede erfolgreiche Belastung erscheint in Ihren Webhooks als neue confirmed-Transaktion, deren preAuthorizationId auf das Token verweist. Überwachen Sie fehlgeschlagene Belastungen und wiederholen Sie sie oder kontaktieren Sie den Kunden. Alle Endpoint-Parameter finden Sie in Transactions belasten, einziehen, erstatten und stornieren.

Sicherheit und PCI-Umfang#

• Karten- und Kontodaten werden nur im FlowAlp Pay Checkout eingegeben und bleiben auf der Plattform — Ihre Datenbank enthält Kunden-IDs und Transaktions-IDs, nichts Kartenbezogenes.
• Bewahren Sie das API-Secret ausschließlich im Backend auf und rotieren Sie es bei Verdacht auf ein Leck: Wer es besitzt, könnte gespeicherte Tokens belasten.
• Prüfen Sie Webhook-Signaturen, bevor Sie eine Belastung als erfolgreich verbuchen.

Tokenisierung oder Abo?#

Verwenden Sie die Tokenisierung, wenn Beträge oder Intervalle variieren: nutzungsbasierte Abrechnung, One-Click-Nachbestellungen, Belastungen auf einer offenen Rechnung oder selbst verwaltete wiederkehrende Logik, bei der Sie über Zeitpunkt, Fehlerbehandlung und Kündigungen entscheiden. Verwenden Sie Abos, wenn ein fixer Betrag in festem Intervall wiederkehrt und FlowAlp Pay den Kunden automatisch belasten soll — siehe Abos und wiederkehrende Zahlungen.