Create a Paylink

July 30, 2026

Create a FlowAlp Pay Paylink with POST /Invoice/: a hosted payment link to share by email or QR code. Parameters, examples and errors.

A Paylink is a hosted FlowAlp Pay payment page with a fixed configuration: you create it once and then share it — by e-mail, in an invoice PDF, as a QR code or in a chat message. Customers open the link and pay; no code on your website is required. In the Merchant API the underlying resource is called Invoice.

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

Use API version v1.16 for new integrations; v1.14 and v1.15 remain supported. Authenticate with the X-API-KEY header and identify your account with the instance query parameter — see Authentication. The body may be sent as application/json (recommended) or application/x-www-form-urlencoded.

Request

Query parameters

Parameter	Type	Required	Description
instance	string	Yes	Name of your merchant instance; identifies your account on every API call.

Body parameters

Parameter	Type	Required	Description
title	string	Yes	Title shown at the top of the hosted payment page.
description	string	Yes	Descriptive text shown on the payment page.
referenceId	string	Yes	Your own invoice or order identifier; echoed in responses and webhooks.
purpose	string	Yes	Purpose of the payment shown to the customer.
amount	integer	Yes	Amount in minor units of the currency; CHF 89.25 becomes 8925.
currency	string	Yes	Payment currency as an ISO 4217 code, for example CHF.
vatRate	float	No	VAT rate in percent. Default: null.
psp	array of integers	No	IDs of the payment providers to offer for this Paylink.
pm	array of strings	No	Payment method identifiers to display.
sku	string	No	Stock keeping unit of the product.
preAuthorization	boolean	No	Authorizes the payment method for a later charge instead of charging immediately. Default: false.
reservation	boolean	No	Reserves the amount for a later capture. Default: false.
name	string	No	Internal name of the payment page; visible only to administrators.
fields	array of strings	No	Names of the contact data fields to display on the payment page.
hideFields	boolean	No	Hides the whole contact data section on the payment page. Default: false.
buttonText	string	No	Custom label for the pay button.
expirationDate	date	No	Date on which the link expires, for example 2026-08-31.
successRedirectUrl	string	No	URL the customer is redirected to after a successful payment.
failedRedirectUrl	string	No	URL the customer is redirected to after a failed payment.
subscriptionState	boolean	No	Handles the payment as a subscription. Default: false.
subscriptionInterval	string	No	Billing interval of the subscription in period notation, for example P1M.
subscriptionPeriod	string	No	Total duration of the subscription in period notation.
subscriptionCancellationInterval	string	No	Period during which the subscription can be cancelled, in period notation.
attachments	file	No	File attachments made available to your customer.
isPriceExclusiveVat	boolean	No	When true, VAT is added on top of amount instead of being included in it.
concardisOrderId	string	No	Order ID forwarded to the acquirer; only available when the matching option is enabled in your payment provider settings.

Some options depend on your account configuration: provider IDs for psp, method identifiers for pm, subscription settings, attachments and provider-specific parameters such as concardisOrderId only take effect when the matching feature is active on your instance. If an optional parameter is rejected, review your dashboard configuration or contact support.

Example request

Create a Paylink (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"
  }'

Create a Paylink (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

The new Paylink is returned inside the success envelope. Send your customer the URL in link — or build the URL from hash — and store id and referenceId in your records. To connect an incoming payment to the Paylink, rely on link or hash, not on referenceId alone.

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"
    }
  ]
}

Errors

HTTP status	Meaning	Recommended action
400	The request failed validation, for example a required parameter such as title or referenceId is missing.	Fix the request body and send the request again.

Error responses use the envelope {"status": "error", "message": "..."} — see Errors and Rate limits.

Related: the product guide Pay links and QR codes, payment verification with Retrieve and list Paylinks, lifecycle management in Update and delete a Paylink, and payment confirmation via webhooks.

Create a Paylink

Request#

Query parameters#

Body parameters#

Example request#

Response#

Errors#