Tokenization: addebitare metodi di pagamento salvati

La tokenization salva il metodo di pagamento del cliente come token riutilizzabile durante un normale checkout. Da quel momento puoi addebitare quel cliente lato server — con qualsiasi importo, in qualsiasi momento — senza rimandarlo a una pagina di pagamento. I dati sensibili della carta non toccano mai i tuoi sistemi: li custodisce FlowAlp Pay, tu conservi solo gli ID.

Come funziona la tokenization#

1. Crei un Gateway con "preAuthorization": true. Il cliente passa dal consueto checkout hosted, ma invece di un addebito viene registrato soltanto il metodo di pagamento.
2. La transazione riceve lo stato authorized, notificato tramite il webhook di transazione insieme all'ID della transazione.
3. Ogni volta che devi incassare, addebiti quell'ID di transazione tramite l'endpoint Transaction con l'importo che preferisci.
4. Ogni addebito crea una nuova transazione (confirmed in caso di successo) che rimanda al token tramite preAuthorizationId.

I token non scadono e possono essere addebitati quante volte vuoi, con qualsiasi importo. A differenza della pre-authorization, però, nessun fondo viene bloccato: un addebito può fallire (carta scaduta, fondi insufficienti), quindi il tuo codice deve gestire gli errori.

Salva un metodo di pagamento al checkout#

Imposta preAuthorization su true quando crei il Gateway. In una tokenization semplice l'importo non viene addebitato: il checkout registra soltanto il metodo di pagamento. Se il primo pagamento va incassato subito, imposta in aggiunta chargeOnAuthorization su true.

curl -X POST "https://api.pay.flowalp.com/v1.16/Gateway/?instance=demo-shop" \
  -H "x-api-key: $FLOWALP_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 2990,
    "currency": "CHF",
    "purpose": "Save payment method",
    "referenceId": "CUST-55021-SETUP",
    "preAuthorization": true,
    "chargeOnAuthorization": true,
    "successRedirectUrl": "https://app.example.com/billing/success",
    "failedRedirectUrl": "https://app.example.com/billing/failed",
    "cancelRedirectUrl": "https://app.example.com/billing/cancel"
  }'

Quando il webhook riporta lo stato authorized, salva l'ID della transazione insieme alla scheda del cliente: è la chiave per tutti gli addebiti futuri. Puoi leggerlo anche recuperando il Gateway.

Addebita il token lato server#

Un addebito successivo è una singola POST sull'ID di transazione salvato, senza alcuna interazione del cliente. L'importo è libero, in unità minime:

curl -X POST "https://api.pay.flowalp.com/v1.16/Transaction/98123/?instance=demo-shop" \
  -H "x-api-key: $FLOWALP_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 1490,
    "purpose": "Usage fees July",
    "referenceId": "CUST-55021-2026-07"
  }'

<?php
use FlowAlpPay\FlowAlpPay;
use FlowAlpPay\Models\Request\Transaction;

$client = new FlowAlpPay(
    getenv('FLOWALP_TENANT'),
    getenv('FLOWALP_API_SECRET'),
    FlowAlpPay::DEFAULT_COMMUNICATION_HANDLER,
    'pay.flowalp.com',
    '1.16'
);

$charge = new Transaction();
$charge->setId(98123); // transaction with status "authorized"
$charge->setAmount(1490); // CHF 14.90
$charge->setPurpose('Usage fees July');
$charge->setReferenceId('CUST-55021-2026-07');

$response = $client->charge($charge);

Ogni addebito riuscito compare nei tuoi webhook come nuova transazione confirmed, con preAuthorizationId che rimanda al token. Monitora gli addebiti falliti e riprova o contatta il cliente. Tutti i parametri dell'endpoint sono documentati in Addebitare, incassare, rimborsare e annullare le Transactions.

Sicurezza e perimetro PCI#

• I dati di carte e conti vengono inseriti solo sul checkout FlowAlp Pay e restano sulla piattaforma: il tuo database conserva ID cliente e ID transazione, nulla che riguardi la carta.
• Custodisci l'API secret solo nel backend e ruotalo se sospetti una fuga: chi lo possiede può addebitare i token salvati.
• Verifica la firma dei webhook prima di registrare un addebito come riuscito.

Tokenization o abbonamenti?#

Usa la tokenization quando importi o intervalli variano: fatturazione a consumo, riordini one-click, addebiti aggiunti a un conto aperto, oppure logica ricorrente self-managed in cui decidi tu quando addebitare e come reagire a errori e disdette. Usa gli abbonamenti quando un importo fisso ricorre a intervallo fisso e FlowAlp Pay deve addebitare il cliente automaticamente — vedi Abbonamenti e pagamenti ricorrenti.