Charge, Capture, Refund und Storno von Transactions

July 30, 2026

Tokenisierte Zahlungen belasten, Reservierungen einziehen, ganz oder teilweise erstatten und wartende Transaktionen in FlowAlp Pay stornieren.

Sobald eine Transaktion in FlowAlp Pay existiert, können Sie mit ihr weiterarbeiten: ein gespeichertes Zahlungsmittel belasten, einen reservierten Betrag einziehen, ganz oder teilweise erstatten, eine nie abgeschlossene Zahlung stornieren und die auf einer Tokenisierung gespeicherten Daten pflegen. Alle folgenden Aufrufe verwenden die API-Version v1.16 und den Header x-api-key, siehe Authentifizierung.

Tokenisierte oder reservierte Transaction belasten

Zwei Abläufe erzeugen belastbare Transaktionen. Eine Tokenisierung (Gateway mit preAuthorization) hinterlässt eine Transaktion mit Status authorized: Sie können sie beliebig oft und jedes Mal mit einem anderen Betrag belasten, und der Token läuft nicht ab — ein erfolgreicher Einzug ist jedoch nicht garantiert. Eine Vorautorisierung (Gateway mit reservation) hinterlässt eine Transaktion mit Status reserved: Sie kann genau einmal belastet werden, höchstens mit dem reservierten Betrag, und die Reservierung hält je nach Kartenherausgeber typischerweise rund fünf Tage.

POSThttps://api.pay.flowalp.com/v1.16/Transaction/{id}/v1.14 · v1.15 · v1.16

Request

Parameter	Typ	Beschreibung
id	integer (erforderlich)	Path-Parameter: ID der zu belastenden Transaktion — ihr Status muss `authorized` oder `reserved` sein.
instance	string (erforderlich)	Query-Parameter: Name Ihrer Instance (Tenant).
amount	integer	Zu belastender Betrag in Minor Units (`4500` = CHF 45.00).
purpose	string	Wofür der Kunde bezahlt.
referenceId	string	Ihre eigene Referenz für die belastete Transaktion; sie wird im Transaktions-Webhook mitgeliefert.
payoutDescriptor	string	Text, der dem Auszahlungs-Buchungstext hinzugefügt wird, maximal 80 Zeichen. Gilt nur für von FlowAlp Pay eingezogene Zahlungen, die als Einzeltransaktions-Auszahlung überwiesen werden.

Transaktion belastenbash

curl -X POST "https://api.pay.flowalp.com/v1.16/Transaction/9034/?instance=<tenant>" \
  -H "x-api-key: <api-secret>" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 4500,
    "purpose": "Monthly plan July",
    "referenceId": "SUB-2026-07-042"
  }'

Transaktion belasten (PHP SDK)PHP

<?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(9034);
$charge->setAmount(4500);
$charge->setPurpose('Monthly plan July');
$charge->setReferenceId('SUB-2026-07-042');

try {
    $transaction = $client->charge($charge);
    echo $transaction->getStatus();
} catch (Exception $e) {
    error_log('Charge failed: ' . $e->getMessage());
}

Response

Beispiel-ResponseJSON

{
  "status": "success",
  "data": [
    {
      "id": 9107,
      "uuid": "b32a7620",
      "referenceId": "SUB-2026-07-042",
      "time": "2026-07-15 08:03:11",
      "status": "confirmed",
      "lang": "de",
      "psp": "Native_PSP",
      "amount": 4500,
      "contact": {
        "id": 23,
        "uuid": "1a2b3c",
        "firstname": "Anna",
        "lastname": "Keller",
        "email": "anna.keller@example.com"
      }
    }
  ]
}

Vorautorisierte Transaction einziehen (Capture)

Ein Capture zieht einen bereits genehmigten Betrag unverändert ein. Der Aufruf kennt ausser der ID im Pfad und Ihrer Instance keine dokumentierten Body-Parameter.

POSThttps://api.pay.flowalp.com/v1.16/Transaction/{id}/capturev1.14 · v1.15 · v1.16

Transaktion einziehenbash

curl -X POST "https://api.pay.flowalp.com/v1.16/Transaction/9034/capture?instance=<tenant>" \
  -H "x-api-key: <api-secret>"

Transaktion einziehen (PHP SDK)PHP

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

// $client: gleicher Konstruktor wie im Charge-Beispiel oben
$capture = new Transaction();
$capture->setId(9034);

try {
    $client->capture($capture);
} catch (Exception $e) {
    error_log('Capture failed: ' . $e->getMessage());
}

Wenn Sie einen tieferen Betrag als den reservierten einziehen möchten, verwenden Sie kein Capture, sondern belasten Sie die Reservierung mit einem expliziten amount. Eine reservierte Transaktion kann nur einmal eingezogen werden.

Transaction erstatten (Refund)

Eine Rückerstattung gibt dem Kunden Geld zurück. Lassen Sie amount weg, um die gesamte Transaktion zu erstatten, oder übergeben Sie einen Betrag in Minor Units für eine Teilerstattung. Ob eine Erstattung aktuell möglich ist, hängt von Zahlungsmethode und Transaktionszustand ab — prüfen Sie die Flags refundable und partiallyRefundable aus Transactions auflisten und abrufen. Den Fortschritt zeigen die Status refund_pending, refunded und partially-refunded.

POSThttps://api.pay.flowalp.com/v1.16/Transaction/{id}/refundv1.14 · v1.15 · v1.16

Parameter	Typ	Beschreibung
id	integer (erforderlich)	Path-Parameter: ID der zu erstattenden Transaktion.
instance	string (erforderlich)	Query-Parameter: Name Ihrer Instance (Tenant).
amount	integer	Optional. Teilerstattungsbetrag in Minor Units; weglassen für eine vollständige Erstattung.

Teilerstattung von CHF 15.00bash

curl -X POST "https://api.pay.flowalp.com/v1.16/Transaction/4712/refund?instance=<tenant>" \
  -H "x-api-key: <api-secret>" \
  -H "Content-Type: application/json" \
  -d '{"amount": 1500}'

Transaktion erstatten (PHP SDK)PHP

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

// $client: gleicher Konstruktor wie im Charge-Beispiel oben
$refund = new Transaction();
$refund->setId(4712);
$refund->setAmount(1500); // setAmount() weglassen für eine Vollerstattung

try {
    $client->refund($refund);
} catch (Exception $e) {
    error_log('Refund failed: ' . $e->getMessage());
}

Wartende Transaction stornieren

Eine Transaktion, die noch im Status waiting ist — gestartet, aber nie abgeschlossen — kann storniert werden. Die Response liefert die Transaktion mit Status cancelled. Existiert die Transaktion, wartet aber nicht mehr, antwortet die API mit 404.

PATCHhttps://api.pay.flowalp.com/v1.16/Transaction/{id}/cancelv1.14 · v1.15 · v1.16

Wartende Transaktion stornierenbash

curl -X PATCH "https://api.pay.flowalp.com/v1.16/Transaction/377/cancel?instance=<tenant>" \
  -H "x-api-key: <api-secret>"

Beispiel-ResponseJSON

{
  "status": "success",
  "data": [
    {
      "id": 377,
      "uuid": "2639f2f9",
      "referenceId": "",
      "time": "2026-07-18 17:22:29",
      "status": "cancelled",
      "lang": "de",
      "psp": "Native_PSP",
      "amount": 10000
    }
  ]
}

Kontaktdaten einer Vorautorisierung oder Tokenisierung aktualisieren

Tokenisierungen und Vorautorisierungen speichern Kontaktdaten zusammen mit dem Zahlungsmittel. Aktualisieren Sie diese Daten, indem Sie ein fields-Objekt senden, in dem jeder Eintrag ein Objekt mit dem Schlüssel value ist.

PUThttps://api.pay.flowalp.com/v1.16/Transaction/{id}/v1.14 · v1.15 · v1.16

Kontaktfelder: title, forename, surname, company, street, postcode, place, country, phone, email, date_of_birth — title akzeptiert mister, miss oder diverse.
Lieferadressfelder: delivery_title, delivery_forename, delivery_surname, delivery_company, delivery_street, delivery_postcode, delivery_place, delivery_country.
Benutzerdefinierte Felder: custom_field_1 … custom_field_5, jeweils mit name, value und export_name.
terms und privacy_policy: Wenn Sie diese Felder in der Anfrage mitsenden, müssen sie akzeptiert sein.

Kontaktdaten aktualisierenbash

curl -X PUT "https://api.pay.flowalp.com/v1.16/Transaction/9034/?instance=<tenant>" \
  -H "x-api-key: <api-secret>" \
  -H "Content-Type: application/json" \
  -d '{
    "fields": {
      "forename": {"value": "Anna"},
      "surname": {"value": "Keller"},
      "email": {"value": "anna.keller@example.com"}
    }
  }'

Wenn Sie sich mit ApiSignature statt mit dem API-Key-Header authentifizieren, müssen die fields[...]-Parameter bei der Signaturberechnung eine stabile Reihenfolge behalten.

Tokenisierung aktualisieren

Passen Sie den auf einer bestehenden Tokenisierung gespeicherten Mehrwertsteuersatz an. Die Response liefert die Tokenisierung mit aktualisiertem vatRate.

PATCHhttps://api.pay.flowalp.com/v1.16/Transaction/{id}/updateTokenizationv1.14 · v1.15 · v1.16

Parameter	Typ	Beschreibung
id	integer (erforderlich)	Path-Parameter: ID der ursprünglichen Tokenisierung.
instance	string (erforderlich)	Query-Parameter: Name Ihrer Instance (Tenant).
vatRate	integer (erforderlich)	Neuer Mehrwertsteuersatz als Prozentwert.

Tokenisierung aktualisierenbash

curl -X PATCH "https://api.pay.flowalp.com/v1.16/Transaction/9034/updateTokenization?instance=<tenant>" \
  -H "x-api-key: <api-secret>" \
  -H "Content-Type: application/json" \
  -d '{"vatRate": 8}'

Fehler

HTTP-Status	Bedeutung
400	Fehlerhafte Anfrage — das Feld `message` im Fehler-Body beschreibt das genaue Problem.
404	Auf dieser Instance existiert keine Transaktion mit der angegebenen ID. Bei Stornierungen tritt dies auch auf, wenn die Transaktion nicht im Status `waiting` ist.

Status und IDs von Transaktionen finden Sie über Transactions auflisten und abrufen. Die Konzepte hinter diesen Operationen erklären die Guides Tokenisierung und Vorautorisierung.

Charge, Capture, Refund und Storno von Transactions

Tokenisierte oder reservierte Transaction belasten#

Request#

Response#

Vorautorisierte Transaction einziehen (Capture)#

Transaction erstatten (Refund)#

Wartende Transaction stornieren#

Kontaktdaten einer Vorautorisierung oder Tokenisierung aktualisieren#

Tokenisierung aktualisieren#

Fehler#