FlowAlp

First API request

July 30, 2026

Send your first FlowAlp Pay Merchant API request: verify credentials with SignatureCheck, then create a minimal Gateway with curl or PHP.

This guide takes you to your first two calls against the FlowAlp Pay Merchant API: a SignatureCheck that verifies your credentials without creating anything, followed by a minimal Gateway — a hosted checkout session for one payment. Examples use curl and the PHP SDK against API version v1.16.

Prerequisites

  • Your instance name (for example demo-shop).
  • An API Secret from the dashboard — see API credentials.
  • A basic idea of how requests are authenticated — see Authentication.
  • A backend environment that can make outbound HTTPS calls.
Environment variables used belowbash
export FLOWALP_PAY_INSTANCE="demo-shop"
export FLOWALP_PAY_API_SECRET="<api-secret>"

Step 1: Verify your credentials

SignatureCheck validates your instance and API Secret pair. It has no side effects, which makes it the ideal first call and a good health check for deployments. Details: SignatureCheck.

GEThttps://api.pay.flowalp.com/v1.16/SignatureCheck/v1.14 · v1.15 · v1.16
Check credentials with curlbash
curl --request GET \
  --url "https://api.pay.flowalp.com/v1.16/SignatureCheck/?instance=${FLOWALP_PAY_INSTANCE}" \
  --header "x-api-key: ${FLOWALP_PAY_API_SECRET}"

Valid credentials return HTTP 200 with a success status:

ResponseJSON
{
  "status": "success",
  "data": []
}

If the API Secret is wrong, the response carries an error status instead — fix the credentials before continuing.

Step 2: Create a minimal Gateway

A Gateway is a hosted checkout session for one payment. Amounts are always sent in minor units (CHF 25.00 becomes 2500), the currency is an ISO code, and referenceId carries your own order ID.

POSThttps://api.pay.flowalp.com/v1.16/Gateway/v1.14 · v1.15 · v1.16
Create a Gateway with curlbash
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": 2500,
    "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"
  }'
Create a Gateway with the PHP SDKPHP
<?php
require_once 'vendor/autoload.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(2500); // CHF 25.00 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');

try {
    $response = $client->create($gateway);
    echo $response->getLink() . PHP_EOL; // send your customer here
} catch (\Exception $e) {
    error_log('Gateway creation failed: ' . $e->getMessage());
}

More about the SDK: PHP SDK.

Expected response

Response (shortened)JSON
{
  "status": "success",
  "data": [
    {
      "id": 174,
      "status": "waiting",
      "referenceId": "ORDER-2026-001",
      "link": "https://demo-shop.pay.flowalp.com/?payment=<hash>",
      "amount": 2500,
      "currency": "CHF"
    }
  ]
}

Redirect your customer to the link URL — that is the hosted payment page. The Gateway starts in status waiting and changes state once the customer completes or aborts the payment. The full parameter list lives in Create a Gateway.

If something goes wrong

HTTP statusLikely causeWhat to do
401 / 403Authentication failed or access deniedRe-check API Secret, instance name, and the x-api-key header.
404Wrong path or API versionVerify the /v1.16/ prefix and the resource name.
405 followed by 403Rate limit reachedBack off and retry later — see the rate limits guide.
5xxTemporary server-side problemRetry with capped exponential backoff.

Error payloads and status semantics are described in Errors and Rate limits.

A redirect to your success URL is not a payment confirmation. Before fulfilling an order, verify the payment server-side through webhooks or by retrieving the transaction via the API (List and retrieve Transactions).

First calls working? Explore the full Gateway parameters, set up webhooks, and run through Testing for developers before go-live.