API versions and changelog

The FlowAlp Pay Merchant API is versioned through the URL path. Every request declares the version it expects, which keeps existing integrations stable while new capabilities ship in newer versions.

How versioning works#

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

The version segment (for example v1.16) selects the API behavior for that single request. There is no account-wide switch: two of your systems can call different versions at the same time, which makes gradual migrations straightforward. The general URL conventions are described in Request format.

Supported versions#

Use v1.16 unless you maintain an older integration that has not been re-tested against it yet.

Pin a version#

REST clients pin the version directly in the URL path:

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

The PHP client takes the version — without the leading v — as its fifth constructor argument:

<?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'
);

Upgrade guidance#

1. Read the changelog below for every version between your current one and the target.
2. Update the version segment (or the SDK constructor argument) in a staging environment first.
3. Run a credentials smoke test with SignatureCheck, then execute your core flows end to end: checkout, webhook processing, capture and refund.
4. Compare the response fields your code parses, especially where the changelog mentions changed response structures.
5. Roll out to production and monitor error rates; if needed, you can revert by switching the version segment back.

A structured test plan is described in Testing for developers.

Changelog#

v1.16#

• Payout details: repeated payout attempts are no longer collapsed into a single aggregate entry, which previously surfaced an empty transaction object. The payout detail response now resolves such aggregates into the original, underlying transfers, so you see the individual transactions behind a payout. See Payouts API.

v1.15#

• Error handling: failed requests return a specific HTTP status code for the failure instead of a generic response. This change affects all endpoints; align your error handling with Merchant API errors.

v1.14#

v1.14 is the baseline of the currently supported range. No dedicated changelog entries are published for it; treat it as the reference behavior that v1.15 and v1.16 refine.