FlowAlp

Request format

July 30, 2026

FlowAlp Pay Merchant API request format: URL structure, JSON and form-urlencoded bodies, HTTP verbs, amounts in minor units, examples.

All Merchant API requests share the same URL structure and conventions. This page describes how to address a resource, which content types are supported, and which fields appear in almost every call.

URL structure

URL patterntext
https://api.pay.flowalp.com/v1.16/<Object>/<id>/?instance=<instance>
ElementLocationRequiredDescription
<version>pathyesAPI version, for example v1.16 (recommended)
<Object>pathyesResource name, for example Gateway, Transaction, SignatureCheck
<id>pathno*Entity ID for GET/PUT/DELETE on a single record
instancequeryyesYour merchant instance name

* Required when the call addresses a single entity. The instance parameter always stays in the query string — for POST requests, every other parameter belongs in the body. See Instance name and API versions and changelog.

HTTP verbs

OperationVerbExample
CreatePOSTPOST /v1.16/Gateway/
Retrieve (single or list)GETGET /v1.16/Transaction/42/
UpdatePUTPUT /v1.16/Subscription/42/
Delete / cancelDELETEDELETE /v1.16/Gateway/42/

Content types

Content-TypeNotes
application/jsonRecommended
application/x-www-form-urlencodedSupported; percent-encode values, spaces as %20 (RFC 3986)

Set the Content-Type header to match the body you send. If you authenticate with ApiSignature, note the separate signing encoding described in Merchant API authentication.

Conventions and common fields

FieldTypeDescription
instancestringMerchant identifier; always in the query string
amountintegerAmount in minor units: CHF 89.25 → 8925
currencystringISO currency code, for example CHF, EUR
referenceIdstringYour own order or correlation ID
purposestringHuman-readable payment purpose

Amounts are always integers in the smallest currency unit. Sending decimals such as 89.25 is a common cause of 400 errors.

Examples

JSON request (recommended)bash
curl --request POST \
  --url "https://api.pay.flowalp.com/v1.16/Gateway/?instance=<instance>" \
  --header "x-api-key: <api-secret>" \
  --header "Content-Type: application/json" \
  --data '{
    "amount": 8925,
    "currency": "CHF",
    "referenceId": "ORDER-975382",
    "successRedirectUrl": "https://shop.example.com/payment/success",
    "failedRedirectUrl": "https://shop.example.com/payment/failed",
    "cancelRedirectUrl": "https://shop.example.com/payment/cancel"
  }'
Form-urlencoded requestbash
curl --request POST \
  --url "https://api.pay.flowalp.com/v1.16/Gateway/?instance=<instance>" \
  --header "x-api-key: <api-secret>" \
  --header "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "amount=8925" \
  --data-urlencode "currency=CHF" \
  --data-urlencode "referenceId=ORDER-975382"
PHP SDKPHP
<?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
$gateway->setCurrency('CHF');
$gateway->setReferenceId('ORDER-975382');

$response = $client->create($gateway);
Typical response envelopeJSON
{
  "status": "success",
  "data": [
    {
      "id": 42,
      "referenceId": "ORDER-975382"
    }
  ]
}

Successful responses contain a status field and a data array with the resource representation; the exact fields depend on the resource. Failed requests are described in Merchant API errors.

Common mistakes

  • instance placed in the body instead of the query string.
  • Missing Content-Type header, or one that does not match the body.
  • Amounts sent as decimals instead of integer minor units.
  • A query-string encoding that differs from what ApiSignature was computed over.
  • Mixing API versions within one flow without re-testing.

Next: create a Gateway, or review errors and rate limits.