Panoramica Merchant API

La Merchant API di FlowAlp Pay è un'interfaccia REST per accettare e gestire pagamenti dal tuo backend. Puoi creare checkout ospitati (Gateway), seguire le transazioni, gestire le subscription, emettere paylink e invoice e riconciliare i payout.

URL di base e versioni#

Ogni richiesta usa un URL di base versionato. La versione API fa parte del path, quindi ogni integrazione dichiara esplicitamente il comportamento su cui fa affidamento:

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

Il parametro query instance identifica il tuo account merchant ed è obbligatorio in ogni chiamata — vedi Instance name. Le versioni v1.14, v1.15 e v1.16 sono supportate; per le nuove integrazioni usa v1.16 e consulta Versioni API e changelog per differenze e indicazioni di upgrade.

Autenticazione#

Le richieste si autenticano con l'API Secret della tua instance. Hai due metodi a disposizione:

• Header x-api-key (consigliato): invii l'API Secret come header HTTP.
• Parametro ApiSignature: una firma HMAC-SHA256 calcolata sui parametri della request.

Consulta Autenticazione della Merchant API per configurazione ed esempi di codice. Per verificare che le credenziali funzionino, chiama l'endpoint SignatureCheck:

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

Formato delle request e convenzioni#

• application/json è il formato consigliato; è supportato anche application/x-www-form-urlencoded.
• Gli importi sono numeri interi in unità minime: CHF 89.25 si invia come 8925.
• Le valute usano i codici ISO, ad esempio CHF o EUR.
• referenceId contiene il tuo ID ordine o di correlazione.
• I verbi HTTP seguono la semantica REST: POST crea, GET recupera, PUT aggiorna, DELETE elimina.

Dettagli ed esempi: Formato delle request.

Risorse principali#

Pagine di riferimento: Creare un Gateway, Elencare e recuperare le Transaction, API Subscription, API Payout, Provider e identificatori dei metodi di pagamento, Creare un Paylink.

A seconda della configurazione del tuo account, il checkout può offrire TWINT, Visa, Mastercard, American Express, PostFinance, Apple Pay, Google Pay, PayPal, Klarna e bonifico bancario.

Errori e rate limit#

• Le richieste fallite restituiscono status HTTP specifici e un body JSON di errore: Errori della Merchant API.
• Il limite è di 600 request ogni 5 minuti; pianifica i retry con backoff: Rate limit della Merchant API.

SDK PHP#

Per i backend PHP, il client PHP di FlowAlp Pay gestisce autenticazione, firma e trasporto:

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

Guida completa: SDK PHP.