Merchant API authentication

The Merchant API requires a valid instance and an API Secret. You can authenticate in two ways:

• X-API-KEY (recommended) — HTTP header with the API Secret
• ApiSignature — HMAC-SHA256 calculated over the request parameters

This section matters if you do not use an SDK. If you develop in PHP, consider the PHP SDK (technical package based on the Payrexx PHP SDK).

TODO FlowAlp: creare e collegare sdk/php

Prerequisites

• Instance name
• API credentials
• API Secret available as an environment variable, for example FLOWALP_PAY_API_SECRET

Authentication with X-API-KEY (recommended)

Pass the API Secret in the HTTP header:

# http
X-API-KEY: <api-secret>

Example:

# bash
curl --request GET \
  --url "https://api.pay.flowalp.com/v1.16/SignatureCheck/?instance=<instance>" \
  --header "X-API-KEY: <api-secret>"

# javascript
const instanceName = process.env.FLOWALP_PAY_INSTANCE;
const apiSecret = process.env.FLOWALP_PAY_API_SECRET;

const response = await fetch(
  `https://api.pay.flowalp.com/v1.16/SignatureCheck/?instance=${encodeURIComponent(instanceName)}`,
  {
    method: "GET",
    headers: {
      "X-API-KEY": apiSecret,
    },
  }
);

if (!response.ok) {
  throw new Error(`FlowAlp Pay auth check failed: ${response.status}`);
}

TODO FlowAlp: confirm that SignatureCheck is the official endpoint to verify credentials/signature in the current version before publication.

Authentication with ApiSignature

ApiSignature is an HMAC according to RFC 2104.

Rules from the API Reference:

• calculate the signature over all parameters except instance;
• build the URL-encoded query string of the parameters;
• compute the binary HMAC-SHA256 using the API Secret as key;
• encode the result as Base64;
• send the value in the ApiSignature parameter.

Algorithm (PHP equivalent from the source):

# php
base64_encode(hash_hmac('sha256', http_build_query($params, null, '&'), $apiSecret, true));

Shell:

# bash
echo -n "HTTP-QUERY-STRING" | openssl dgst -sha256 -hmac "API-SECRET" -binary | openssl enc -base64

Query string encoding

The query string used for the signature must be RFC 1738 encoded: spaces become +.

Do not invent algorithm variants. If your language produces different encoding, compare the result with a known test payload.

TypeScript signing example

# typescript
import qs from "qs";
import Base64 from "crypto-js/enc-base64";
import hmacSHA256 from "crypto-js/hmac-sha256";

function buildSignature(data: Record<string, unknown>, secret: string): string {
  let queryStr = "";
  if (data) {
    queryStr = qs.stringify(data, { format: "RFC1738" });
    queryStr = queryStr.replace(/[!'()*~]/g, (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`);
  }
  return Base64.stringify(hmacSHA256(queryStr, secret));
}

const params = {
  amount: 2500,
  currency: "CHF",
};

const signed = {
  ...params,
  ApiSignature: buildSignature(params, process.env.FLOWALP_PAY_API_SECRET!),
};

Request format

The payload can be:

Format | Note
JSON | Recommended
`application/x-www-form-urlencoded` | RFC 3986; spaces percent-encoded as `%20` in the payload

Base URL:

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

Field | Location | Type | Required | Description
instance | query | string | yes | Merchant instance name
object | path | string | yes | API resource
id | path | string | no* | Single entity for GET/PUT/DELETE
X-API-KEY | header | string | yes** | API Secret
ApiSignature | body/query | string | yes** | Alternative to X-API-KEY

\ required when operating on a single entity \\* use one of the two authentication methods

Rate limit

Limit | Detail
600 requests / 5 minutes | Enforced via AWS WAF

If you exceed the limit you may first receive 405 Method Not Allowed, then 403 Forbidden.

Recommended practices:

• retry with exponential backoff on 405/403 related to rate limiting;
• when possible, aggregate operations instead of multiplying requests.

Details: Rate limits.

TODO FlowAlp: creare e collegare api/rate

Security

• Prefer X-API-KEY on the backend; do not use it in browsers or public apps.
• Do not log the X-API-KEY header or ApiSignature.
• Rotate compromised credentials.
• Always use HTTPS.

Next steps

• Request format
• First API request
• Create a Gateway

TODO FlowAlp: creare e collegare request