Autenticazione della Merchant API

La Merchant API richiede un'instance valida e un'API Secret. Puoi autenticarti in due modi:

• X-API-KEY (consigliato) — header HTTP con l'API Secret
• ApiSignature — HMAC-SHA256 calcolato sui parametri della request

Questa sezione è rilevante se non usi un SDK. Se sviluppi in PHP, valuta lo SDK PHP (/docs/flowalp-pay/sdk/php) (package tecnico basato su Payrexx PHP SDK).

TODO FlowAlp: creare e collegare sdk/php

Prerequisiti

• Instance name (/docs/flowalp-pay/getting-started/instance-name)
• Credenziali API (/docs/flowalp-pay/getting-started/api-credentials)
• API Secret disponibile come variabile d'ambiente, ad esempio FLOWALP_PAY_API_SECRET

Autenticazione con X-API-KEY (consigliata)

Passa l'API Secret nell'header HTTP:

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

Esempio:

# 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: confermare che SignatureCheck sia l'endpoint ufficiale per verificare credenziali/firma nella versione corrente prima della pubblicazione.

Autenticazione con ApiSignature

L'ApiSignature è un HMAC secondo RFC 2104.

Regole dalla API Reference:

• calcola la signature su tutti i parametri eccetto instance;
• costruisci la query string URL-encoded dei parametri;
• calcola l'HMAC-SHA256 binario usando l'API Secret come chiave;
• codifica il risultato in Base64;
• invia il valore nel parametro ApiSignature.

Algoritmo (equivalente PHP di riferimento nella fonte):

# 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

Encoding della query string

La query string usata per la signature deve essere RFC 1738 encoded: gli spazi diventano +.

Non inventare varianti dell'algoritmo. Se il tuo linguaggio produce encoding diversi, confronta il risultato con un payload di test noto.

Esempio TypeScript (firma)

# 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!),
};

Formato request

Il payload può essere:

Formato | Nota
JSON | Consigliato
`application/x-www-form-urlencoded` | RFC 3986; spazi percent-encoded come `%20` nel payload

URL base:

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

Campo | Posizione | Tipo | Obbligatorio | Descrizione
instance | query | string | sì | Instance name del merchant
object | path | string | sì | Risorsa API
id | path | string | no* | Entità singola per GET/PUT/DELETE
X-API-KEY | header | string | sì** | API Secret
ApiSignature | body/query | string | sì** | Alternativa a X-API-KEY

\ obbligatorio quando operi su una singola entità \\* usa uno dei due metodi di autenticazione

Rate limit

Limite | Dettaglio
600 request / 5 minuti | Enforce via AWS WAF

Se superi il limite puoi ricevere prima 405 Method Not Allowed, poi 403 Forbidden.

Pratiche consigliate:

• retry con exponential backoff su 405/403 legati al rate limit;
• quando possibile, aggregare operazioni invece di moltiplicare le request.

Dettagli: Rate limit (/docs/flowalp-pay/api/rate-limits).

TODO FlowAlp: creare e collegare api/rate

Sicurezza

• Preferisci X-API-KEY sul backend; non usarlo in browser o app pubbliche.
• Non loggare header X-API-KEY né ApiSignature.
• Ruota le credenziali compromesse.
• Usa sempre HTTPS.

Passaggi successivi

• Formato delle request (/docs/flowalp-pay/api/request-format)
• Prima richiesta API (/docs/flowalp-pay/getting-started/first-api-request)
• Creare un Gateway (/docs/flowalp-pay/api/gateway/create)

TODO FlowAlp: creare e collegare request