Prima richiesta API

Questa guida ti porta dalla configurazione delle credenziali a una request HTTP autenticata verso la Merchant API di FlowAlp Pay.

Prerequisiti

• Instance name nota (Instance name (/docs/flowalp-pay/getting-started/instance-name))
• API Secret creata (Credenziali API (/docs/flowalp-pay/getting-started/api-credentials))
• Autenticazione compresa (Autenticazione (/docs/flowalp-pay/api/authentication))
• Ambiente in grado di eseguire HTTPS outbound

Variabili d'ambiente consigliate:

# bash
export FLOWALP_PAY_INSTANCE="demo-shop"
export FLOWALP_PAY_API_SECRET="<api-secret>"

Versione API

Negli esempi usiamo la versione esposta come server URL nella API Reference corrente:

# text
https://api.pay.flowalp.com/v1.16/

TODO FlowAlp: allineare la versione raccomandata se la guida merchant (/account/api-and-plugins) continua a citare 1.13.

Procedura

1. Verifica instance e secret

Controlla che:

• l'instance corrisponda al sottodominio https://<instance>.pay.flowalp.com;
• l'API Secret sia quella copiata da API and Plugins (non un valore di esempio).

2. Invia una request di controllo autenticata

Esempio con header X-API-KEY:

# bash
curl --request GET \
  --url "https://api.pay.flowalp.com/v1.16/SignatureCheck/?instance=${FLOWALP_PAY_INSTANCE}" \
  --header "X-API-KEY: ${FLOWALP_PAY_API_SECRET}" \
  --fail-with-body \
  --show-error

TODO FlowAlp: verificare endpoint e response body di SignatureCheck sulla white-label FlowAlp Pay prima della pubblicazione. In alternativa, usare un GET su una risorsa read-only documentata (es. elenco payment provider) come smoke test.

3. Interpreta l'esito

Status | Significato | Azione consigliata
2xx | Credenziali e instance accettate | Procedi a creare un Gateway di test
401 / 403 | Autenticazione fallita o accesso negato | Ricontrolla API Secret, instance e metodo di auth
404 | Path o risorsa non trovata | Verifica versione API e path
405 poi 403 | Possibile rate limit WAF | Attendi e ritenta con backoff

4. Crea un Gateway di prova (passo successivo tipico)

Campi minimi richiesti dalla reference Create a Gateway: amount (centesimi) e currency.

# bash
curl --request POST \
  --url "https://api.pay.flowalp.com/v1.16/Gateway/?instance=${FLOWALP_PAY_INSTANCE}" \
  --header "X-API-KEY: ${FLOWALP_PAY_API_SECRET}" \
  --header "Content-Type: application/json" \
  --data '{
    "amount": 2500,
    "currency": "CHF",
    "purpose": "Order ORDER-2026-001",
    "referenceId": "ORDER-2026-001",
    "successRedirectUrl": "https://shop.example.com/payment/success",
    "failedRedirectUrl": "https://shop.example.com/payment/failed",
    "cancelRedirectUrl": "https://shop.example.com/payment/cancel"
  }'

TODO FlowAlp: verificare se l'endpoint Gateway accetta application/json o richiede application/x-www-form-urlencoded nell'ambiente FlowAlp Pay (la OpenAPI della fonte elenca form-urlencoded). Adeguare l'esempio prima della pubblicazione.

Dopo la creazione, la response include l'URL di pagamento del Gateway. Reindirizza il cliente a quell'URL (o usalo in embed).

Il redirect alla success URL non conferma da solo il pagamento. Conferma sempre via webhook e/o retrieve della transazione/Gateway.

Esempio Node.js

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

async function createGateway() {
  const url = `https://api.pay.flowalp.com/v1.16/Gateway/?instance=${encodeURIComponent(instanceName)}`;

  const response = await fetch(url, {
    method: "POST",
    headers: {
      "X-API-KEY": apiSecret,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      amount: 2500,
      currency: "CHF",
      purpose: "Order ORDER-2026-001",
      referenceId: "ORDER-2026-001",
      successRedirectUrl: "https://shop.example.com/payment/success",
      failedRedirectUrl: "https://shop.example.com/payment/failed",
      cancelRedirectUrl: "https://shop.example.com/payment/cancel",
    }),
  });

  if (!response.ok) {
    const body = await response.text();
    throw new Error(`Create Gateway failed: ${response.status} ${body}`);
  }

  return response.json();
}

Sicurezza

• Esegui queste chiamate solo dal backend.
• Non stampare FLOWALP_PAY_API_SECRET nei log.
• Usa importi e URL di redirect di test finché non completi la checklist di go-live (/docs/flowalp-pay/testing/launch-checklist).

TODO FlowAlp: creare e collegare testing/launch

Passaggi successivi

• Creare un Gateway (/docs/flowalp-pay/api/gateway/create) — parametri completi
• Configurare i webhook (/docs/flowalp-pay/webhooks/configuration)
• Testing (/docs/flowalp-pay/testing/overview)

TODO FlowAlp: creare e collegare le pagine successive