Create a Gateway

July 30, 2026

Create a hosted FlowAlp Pay checkout with POST /Gateway/. Full parameter table, curl and PHP SDK examples, response fields and error codes.

A Gateway is a hosted FlowAlp Pay checkout session for one payment. Create it from your backend as soon as a customer is ready to pay, then send the customer to the payment page URL returned in the response.

POSThttps://api.pay.flowalp.com/v1.16/Gateway/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 and Request format. 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
amount	integer	Yes	Payment 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 or EUR.
purpose	string	No	Description of the payment shown to the customer on the payment page.
referenceId	string	No	Your own order identifier; echoed in responses and webhooks so you can match the payment.
successRedirectUrl	string	No	URL-encoded address the customer returns to after a successful payment.
failedRedirectUrl	string	No	URL-encoded address the customer returns to after a failed payment.
cancelRedirectUrl	string	No	URL-encoded address the customer returns to after cancelling the payment manually.
vatRate	float	No	VAT rate in percent applied to the payment. Default: null.
sku	string	No	Stock keeping unit of the product being paid for.
basket	array of objects	No	Product lines with name, description, quantity, amount (minor units) and vatRate (percent); the sum of all lines must equal amount.
psp	array of integers	No	IDs of the payment providers to offer; when omitted, every provider active on your instance is offered.
pm	array of strings	No	Payment method identifiers to display, used to narrow down the methods offered.
preAuthorization	boolean	No	Authorizes and stores the payment method for a later charge (type authorization). Default: false.
reservation	boolean	No	Reserves the amount so you can capture it later (type reservation). Default: false.
chargeOnAuthorization	boolean	No	Requires preAuthorization set to true; charges the amount already during the first payment.
reserveOnAuthorization	boolean	No	Requires preAuthorization set to true; creates a reservation from the authorization of the first payment.
fields	object	No	Contact data stored together with the payment; see the supported field names below.
language	string	No	Language of the payment page as an ISO 639-1 code, for example de, fr, it or en.
skipResultPage	boolean	No	Skips the hosted result page and redirects straight to your success or failed URL. Default: false.
validity	integer	No	How long the Gateway can be used, in minutes.
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 for one month.
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.
buttonText	array of strings	No	Custom label that replaces the default Pay text on the checkout button.
lookAndFeelProfile	string	No	UUID of the Look and Feel profile to apply to the payment page.
successMessage	string	No	Custom message shown on the result page after a successful payment.
qrCodeSessionId	string	No	Session ID of a scanned static QR code; only relevant for static TWINT QR payments.
applicationFee	integer	No	Fee in minor units of the currency, deducted as application fee.
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.

The fields object stores contact data with the payment. Each entry uses the field name as key and carries a value; the five custom fields also accept a localized name. Supported field names:

Identity: title, forename, surname, company
Address: street, postcode, place, country
Delivery address: delivery_title, delivery_forename, delivery_surname, delivery_company, delivery_street, delivery_postcode, delivery_place, delivery_country
Contact and consent: phone, email, date_of_birth, terms, privacy_policy
Free fields: custom_field_1 to custom_field_5 (optionally with a localized label)

If you send the body as application/x-www-form-urlencoded (for example when signing requests with ApiSignature), keep all fields[...] parameters grouped together and in a fixed order.

Some options depend on your account configuration: provider IDs for psp, method identifiers for pm, subscription settings 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 configuration in the dashboard or contact support.

Example request

Create a Gateway (cURL)bash

curl --request POST \
  --url "https://api.pay.flowalp.com/v1.16/Gateway/?instance=${FLOWALP_PAY_INSTANCE}" \
  --header "X-API-KEY: ${FLOWALP_PAY_API_SECRET}" \
  --header "Content-Type: application/json" \
  --data '{
    "amount": 8925,
    "currency": "CHF",
    "purpose": "Order ORDER-2026-001",
    "referenceId": "ORDER-2026-001",
    "successRedirectUrl": "https://shop.example.com/payment/success",
    "failedRedirectUrl": "https://shop.example.com/payment/failed",
    "cancelRedirectUrl": "https://shop.example.com/payment/cancel",
    "fields": {
      "forename": {"value": "Anna"},
      "surname": {"value": "Bernasconi"},
      "email": {"value": "anna.bernasconi@example.com"}
    }
  }'

Create a Gateway (PHP SDK)PHP

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

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

$gateway = new Gateway();
$gateway->setAmount(8925); // CHF 89.25 in minor units
$gateway->setCurrency('CHF');
$gateway->setPurpose('Order ORDER-2026-001');
$gateway->setReferenceId('ORDER-2026-001');
$gateway->setSuccessRedirectUrl('https://shop.example.com/payment/success');
$gateway->setFailedRedirectUrl('https://shop.example.com/payment/failed');
$gateway->setCancelRedirectUrl('https://shop.example.com/payment/cancel');

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

// Store the id, then send the customer to the hosted payment page.
$gatewayId  = $response->getId();
$paymentUrl = $response->getLink();

Response

A successful call returns HTTP 200 with the envelope shown below: status is success and data contains the new Gateway as its only element. Store the id, then redirect your customer to link. A freshly created Gateway always starts with status waiting.

200 OKJSON

{
  "status": "success",
  "data": [
    {
      "id": 42,
      "status": "waiting",
      "hash": "cb1a4e6ad0714b8c93cbfe6a6e2489d5",
      "referenceId": "ORDER-2026-001",
      "link": "https://demo-shop.pay.flowalp.com/?payment=cb1a4e6ad0714b8c93cbfe6a6e2489d5",
      "amount": 8925,
      "currency": "CHF",
      "preAuthorization": false,
      "reservation": false,
      "createdAt": "2026-07-30 11:52:08"
    }
  ]
}

Never treat the redirect to your successRedirectUrl as proof of payment. Confirm each payment with webhooks or read the current state with Retrieve a Gateway.

Errors

HTTP status	Meaning	Recommended action
400	The request failed validation, for example a required parameter is missing or has the wrong type.	Fix the request body and send the request again.
404	Nothing was found for the request, for example because the instance name is wrong.	Check the instance query parameter and the endpoint URL.

Error responses use the envelope {"status": "error", "message": "..."}; the general error model is described in Errors. The API allows 600 requests per 5 minutes — see Rate limits.

Next steps: embed the payment page with Checkout embedding, walk through the whole flow in Accept a one-time payment, or charge customers later with Pre-authorization and Subscriptions.

Create a Gateway

Request#

Query parameters#

Body parameters#

Example request#

Response#

Errors#