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.
https://api.pay.flowalp.com/v1.16/Invoice/v1.14 · v1.15 · v1.16Verwenden 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
| Parameter | Typ | Pflicht | Beschreibung |
|---|---|---|---|
| instance | string | Ja | Name Ihrer Händler-Instance; identifiziert Ihr Konto bei jedem API-Aufruf. |
Body-Parameter
| Parameter | Typ | Pflicht | Beschreibung |
|---|---|---|---|
| title | string | Ja | Titel, der oben auf der gehosteten Zahlungsseite angezeigt wird. |
| description | string | Ja | Beschreibungstext, der auf der Zahlungsseite angezeigt wird. |
| referenceId | string | Ja | Ihre eigene Rechnungs- oder Bestellreferenz; wird in Responses und Webhooks zurückgegeben. |
| purpose | string | Ja | Zweck der Zahlung, der dem Kunden angezeigt wird. |
| amount | integer | Ja | Betrag in Minoreinheiten der Währung; CHF 89.25 wird zu 8925. |
| currency | string | Ja | Währung der Zahlung als ISO-4217-Code, zum Beispiel CHF. |
| vatRate | float | Nein | Mehrwertsteuersatz in Prozent. Default: null. |
| psp | array of integers | Nein | IDs der Payment Provider, die für diesen Paylink angeboten werden. |
| pm | array of strings | Nein | Identifier der anzuzeigenden Zahlungsmethoden. |
| sku | string | Nein | Artikelnummer (Stock Keeping Unit) des Produkts. |
| preAuthorization | boolean | Nein | Autorisiert das Zahlungsmittel für eine spätere Belastung statt sofort zu belasten. Default: false. |
| reservation | boolean | Nein | Reserviert den Betrag für ein späteres Capture. Default: false. |
| name | string | Nein | Interner Name der Zahlungsseite; nur für Administratoren sichtbar. |
| fields | array of strings | Nein | Namen der Kontaktdatenfelder, die auf der Zahlungsseite angezeigt werden. |
| hideFields | boolean | Nein | Blendet den gesamten Kontaktdaten-Bereich auf der Zahlungsseite aus. Default: false. |
| buttonText | string | Nein | Eigene Beschriftung für den Bezahlbutton. |
| expirationDate | date | Nein | Datum, an dem der Link abläuft, zum Beispiel 2026-08-31. |
| successRedirectUrl | string | Nein | URL, auf die der Kunde nach erfolgreicher Zahlung weitergeleitet wird. |
| failedRedirectUrl | string | Nein | URL, auf die der Kunde nach fehlgeschlagener Zahlung weitergeleitet wird. |
| subscriptionState | boolean | Nein | Behandelt die Zahlung als Subscription. Default: false. |
| subscriptionInterval | string | Nein | Abrechnungsintervall der Subscription in Periodennotation, zum Beispiel P1M. |
| subscriptionPeriod | string | Nein | Gesamtdauer der Subscription in Periodennotation. |
| subscriptionCancellationInterval | string | Nein | Frist, innerhalb derer die Subscription gekündigt werden kann, in Periodennotation. |
| attachments | file | Nein | Dateianhänge, die dem Kunden zur Verfügung gestellt werden. |
| isPriceExclusiveVat | boolean | Nein | Wenn true, wird die Mehrwertsteuer zusätzlich zu amount berechnet statt darin enthalten zu sein. |
| concardisOrderId | string | Nein | Bestell-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
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"
}'<?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.
{
"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-Status | Bedeutung | Empfohlene Massnahme |
|---|---|---|
| 400 | Die 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.