Merchant API overview

The FlowAlp Pay Merchant API is a REST interface for accepting and managing payments from your own backend. You can create hosted checkouts (Gateway), follow up on transactions, manage subscriptions, issue paylinks and invoices, and reconcile payouts.

Base URL and versioning#

Every request targets a versioned base URL. The API version is part of the path, so each integration explicitly declares the behavior it relies on:

https://api.pay.flowalp.com/v1.16/<Object>/<id>/?instance=<instance>

The instance query parameter identifies your merchant account and is required on every call — see Instance name. Versions v1.14, v1.15 and v1.16 are supported; use v1.16 for new integrations and consult API versions and changelog for differences and upgrade guidance.

Authentication#

Requests are authenticated with the API secret of your instance. Two methods are available:

• x-api-key header (recommended): send the API secret as an HTTP header.
• ApiSignature parameter: an HMAC-SHA256 signature computed over the request parameters.

See Merchant API authentication for setup and code samples. To confirm that your credentials work, call the SignatureCheck endpoint:

curl --request GET \
  --url "https://api.pay.flowalp.com/v1.16/SignatureCheck/?instance=<instance>" \
  --header "x-api-key: <api-secret>"

Request format and conventions#

• application/json is recommended; application/x-www-form-urlencoded is also supported.
• Amounts are integers in minor units: CHF 89.25 is sent as 8925.
• Currencies use ISO codes such as CHF or EUR.
• referenceId carries your own order or correlation ID.
• HTTP verbs follow REST semantics: POST creates, GET retrieves, PUT updates, DELETE removes.

Details and examples: Request format.

Main resources#

Reference pages: Create a Gateway, List and retrieve Transactions, Subscriptions API, Payouts API, Payment providers and method identifiers, Create a Paylink.

Depending on your account configuration, checkouts can offer TWINT, Visa, Mastercard, American Express, PostFinance, Apple Pay, Google Pay, PayPal, Klarna and bank transfer.

Errors and rate limits#

• Failed requests return meaningful HTTP status codes and a JSON error body: Merchant API errors.
• The API allows 600 requests per 5 minutes; plan retries with backoff: Merchant API rate limits.

PHP SDK#

For PHP backends, the FlowAlp Pay PHP client wraps authentication, signing and transport:

<?php
use FlowAlpPay\FlowAlpPay;

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

Full guide: PHP SDK.