FlowAlp

Paylink erstellen

July 30, 2026

Paylink mit der FlowAlp Pay API erstellen: POST /Invoice/ für Zahlungslinks per E-Mail oder QR-Code. Parameter, Beispiele und Fehler.

Ein Paylink ist eine gehostete FlowAlp-Pay-Zahlungsseite mit fester Konfiguration: Sie erstellen ihn einmal und teilen ihn dann — per E-Mail, in einer PDF-Rechnung, als QR-Code oder im Chat. Der Kunde öffnet den Link und bezahlt; Code auf Ihrer Website ist nicht nötig. In der Merchant API heisst die zugrunde liegende Ressource Invoice.

POSThttps://api.pay.flowalp.com/v1.16/Invoice/v1.14 · v1.15 · v1.16

Verwenden Sie für neue Integrationen die API-Version v1.16; v1.14 und v1.15 werden weiterhin unterstützt. Authentifizieren Sie sich mit dem Header X-API-KEY und identifizieren Sie Ihr Konto über den Query-Parameter instance — siehe Authentifizierung. Der Body kann als application/json (empfohlen) oder application/x-www-form-urlencoded gesendet werden.

Request

Query-Parameter

ParameterTypPflichtBeschreibung
instancestringJaName Ihrer Händler-Instance; identifiziert Ihr Konto bei jedem API-Aufruf.

Body-Parameter

ParameterTypPflichtBeschreibung
titlestringJaTitel, der oben auf der gehosteten Zahlungsseite angezeigt wird.
descriptionstringJaBeschreibungstext, der auf der Zahlungsseite angezeigt wird.
referenceIdstringJaIhre eigene Rechnungs- oder Bestellreferenz; wird in Responses und Webhooks zurückgegeben.
purposestringJaZweck der Zahlung, der dem Kunden angezeigt wird.
amountintegerJaBetrag in Minoreinheiten der Währung; CHF 89.25 wird zu 8925.
currencystringJaWährung der Zahlung als ISO-4217-Code, zum Beispiel CHF.
vatRatefloatNeinMehrwertsteuersatz in Prozent. Default: null.
psparray of integersNeinIDs der Payment Provider, die für diesen Paylink angeboten werden.
pmarray of stringsNeinIdentifier der anzuzeigenden Zahlungsmethoden.
skustringNeinArtikelnummer (Stock Keeping Unit) des Produkts.
preAuthorizationbooleanNeinAutorisiert das Zahlungsmittel für eine spätere Belastung statt sofort zu belasten. Default: false.
reservationbooleanNeinReserviert den Betrag für ein späteres Capture. Default: false.
namestringNeinInterner Name der Zahlungsseite; nur für Administratoren sichtbar.
fieldsarray of stringsNeinNamen der Kontaktdatenfelder, die auf der Zahlungsseite angezeigt werden.
hideFieldsbooleanNeinBlendet den gesamten Kontaktdaten-Bereich auf der Zahlungsseite aus. Default: false.
buttonTextstringNeinEigene Beschriftung für den Bezahlbutton.
expirationDatedateNeinDatum, an dem der Link abläuft, zum Beispiel 2026-08-31.
successRedirectUrlstringNeinURL, auf die der Kunde nach erfolgreicher Zahlung weitergeleitet wird.
failedRedirectUrlstringNeinURL, auf die der Kunde nach fehlgeschlagener Zahlung weitergeleitet wird.
subscriptionStatebooleanNeinBehandelt die Zahlung als Subscription. Default: false.
subscriptionIntervalstringNeinAbrechnungsintervall der Subscription in Periodennotation, zum Beispiel P1M.
subscriptionPeriodstringNeinGesamtdauer der Subscription in Periodennotation.
subscriptionCancellationIntervalstringNeinFrist, innerhalb derer die Subscription gekündigt werden kann, in Periodennotation.
attachmentsfileNeinDateianhänge, die dem Kunden zur Verfügung gestellt werden.
isPriceExclusiveVatbooleanNeinWenn true, wird die Mehrwertsteuer zusätzlich zu amount berechnet statt darin enthalten zu sein.
concardisOrderIdstringNeinBestell-ID, die an den Acquirer weitergegeben wird; nur verfügbar, wenn die entsprechende Option in Ihren Payment-Provider-Einstellungen aktiviert ist.

Einige Optionen hängen von Ihrer Kontokonfiguration ab: Provider-IDs für psp, Methoden-Identifier für pm, Subscription-Einstellungen, attachments und providerspezifische Parameter wie concardisOrderId wirken nur, wenn die entsprechende Funktion auf Ihrer Instance aktiv ist. Wird ein optionaler Parameter abgelehnt, prüfen Sie die Konfiguration im Dashboard oder kontaktieren Sie den Support.

Beispiel-Request

Paylink erstellen (cURL)bash
curl --request POST \
  --url "https://api.pay.flowalp.com/v1.16/Invoice/?instance=${FLOWALP_PAY_INSTANCE}" \
  --header "X-API-KEY: ${FLOWALP_PAY_API_SECRET}" \
  --header "Content-Type: application/json" \
  --data '{
    "title": "Invoice INV-2026-0042",
    "description": "Consulting services, June 2026",
    "referenceId": "INV-2026-0042",
    "purpose": "Invoice INV-2026-0042",
    "amount": 8925,
    "currency": "CHF",
    "expirationDate": "2026-08-31",
    "successRedirectUrl": "https://shop.example.com/payment/success",
    "failedRedirectUrl": "https://shop.example.com/payment/failed"
  }'
Paylink erstellen (PHP-SDK)PHP
<?php
use FlowAlpPay\FlowAlpPay;
use FlowAlpPay\Models\Request\Paylink;

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

$paylink = new Paylink();
$paylink->setTitle('Invoice INV-2026-0042');
$paylink->setDescription('Consulting services, June 2026');
$paylink->setReferenceId('INV-2026-0042');
$paylink->setPurpose('Invoice INV-2026-0042');
$paylink->setAmount(8925); // CHF 89.25 in minor units
$paylink->setCurrency('CHF');
$paylink->setSuccessRedirectUrl('https://shop.example.com/payment/success');
$paylink->setFailedRedirectUrl('https://shop.example.com/payment/failed');

$response = $client->create($paylink);

// Share this URL by e-mail or render it as a QR code.
$paylinkUrl = $response->getLink();

Response

Der neue Paylink wird im Erfolgs-Envelope zurückgegeben. Senden Sie Ihrem Kunden die URL aus link — oder bauen Sie die URL aus hash — und speichern Sie id und referenceId in Ihrem System. Um eine eingehende Zahlung dem Paylink zuzuordnen, verlassen Sie sich auf link oder hash, nicht allein auf referenceId.

200 OKJSON
{
  "status": "success",
  "data": [
    {
      "id": 57,
      "hash": "f7d1b2e94c3a48d2a5efb6c17d0a9c31",
      "referenceId": "INV-2026-0042",
      "link": "https://demo-shop.pay.flowalp.com/?payment=f7d1b2e94c3a48d2a5efb6c17d0a9c31",
      "title": "Invoice INV-2026-0042",
      "description": "Consulting services, June 2026",
      "purpose": "Invoice INV-2026-0042",
      "amount": 8925,
      "currency": "CHF",
      "createdAt": "2026-07-30 11:52:08"
    }
  ]
}

Fehler

HTTP-StatusBedeutungEmpfohlene Massnahme
400Die Anfrage hat die Validierung nicht bestanden, zum Beispiel fehlt ein Pflichtparameter wie title oder referenceId.Korrigieren Sie den Request-Body und senden Sie die Anfrage erneut.

Fehler-Responses verwenden den Envelope {"status": "error", "message": "..."} — siehe Fehler und Rate limits.

Verwandt: der Leitfaden Pay-Links und QR-Codes, die Zahlungsprüfung mit Paylinks abrufen und auflisten, die Verwaltung in Paylink aktualisieren und löschen sowie die Zahlungsbestätigung per Webhooks.