Addebitare, catturare, rimborsare e annullare le Transaction

July 30, 2026

Addebita pagamenti tokenizzati, cattura importi riservati, rimborsa in modo totale o parziale e annulla transazioni in attesa con FlowAlp Pay.

Una volta creata una transazione in FlowAlp Pay puoi continuare a lavorarci: addebitare un metodo di pagamento salvato, incassare un importo riservato, emettere rimborsi totali o parziali, annullare un pagamento mai completato e aggiornare i dati salvati su una tokenization. Tutte le chiamate qui sotto usano la versione API v1.16 e l'header x-api-key descritto in Autenticazione.

Addebitare una Transaction tokenizzata o riservata

Due flussi producono transazioni addebitabili. Una tokenization (Gateway creato con preAuthorization) lascia una transazione con stato authorized: puoi addebitarla quante volte vuoi, ogni volta con un importo diverso, e il token non scade — ma il buon esito dell'addebito non è garantito. Una pre-authorization (Gateway creato con reservation) lascia una transazione con stato reserved: può essere addebitata una sola volta, con un importo non superiore a quello riservato, e la prenotazione resta valida in genere circa cinque giorni a seconda dell'emittente della carta.

POSThttps://api.pay.flowalp.com/v1.16/Transaction/{id}/v1.14 · v1.15 · v1.16

Request

Parametro	Tipo	Descrizione
id	integer (obbligatorio)	Path parameter: ID della transazione da addebitare — il suo stato deve essere `authorized` o `reserved`.
instance	string (obbligatorio)	Query parameter: nome della tua instance (tenant).
amount	integer	Importo da addebitare in unità minori (`4500` = CHF 45.00).
purpose	string	Che cosa sta pagando il cliente.
referenceId	string	Il tuo riferimento per la transazione addebitata; viene incluso nel webhook della transazione.
payoutDescriptor	string	Testo aggiunto alla causale del payout, massimo 80 caratteri. Vale solo per i pagamenti incassati da FlowAlp Pay liquidati come payout a transazione singola.

Addebitare una transazionebash

curl -X POST "https://api.pay.flowalp.com/v1.16/Transaction/9034/?instance=<tenant>" \
  -H "x-api-key: <api-secret>" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 4500,
    "purpose": "Monthly plan July",
    "referenceId": "SUB-2026-07-042"
  }'

Addebitare una transazione (SDK PHP)PHP

<?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(9034);
$charge->setAmount(4500);
$charge->setPurpose('Monthly plan July');
$charge->setReferenceId('SUB-2026-07-042');

try {
    $transaction = $client->charge($charge);
    echo $transaction->getStatus();
} catch (Exception $e) {
    error_log('Charge failed: ' . $e->getMessage());
}

Response

Esempio di responseJSON

{
  "status": "success",
  "data": [
    {
      "id": 9107,
      "uuid": "b32a7620",
      "referenceId": "SUB-2026-07-042",
      "time": "2026-07-15 08:03:11",
      "status": "confirmed",
      "lang": "de",
      "psp": "Native_PSP",
      "amount": 4500,
      "contact": {
        "id": 23,
        "uuid": "1a2b3c",
        "firstname": "Anna",
        "lastname": "Keller",
        "email": "anna.keller@example.com"
      }
    }
  ]
}

Catturare una Transaction pre-autorizzata

La capture incassa un importo già approvato senza modificarlo. La chiamata non prevede parametri di body documentati oltre all'ID nel path e alla tua instance.

POSThttps://api.pay.flowalp.com/v1.16/Transaction/{id}/capturev1.14 · v1.15 · v1.16

Catturare una transazionebash

curl -X POST "https://api.pay.flowalp.com/v1.16/Transaction/9034/capture?instance=<tenant>" \
  -H "x-api-key: <api-secret>"

Catturare una transazione (SDK PHP)PHP

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

// $client: stesso costruttore dell'esempio di addebito qui sopra
$capture = new Transaction();
$capture->setId(9034);

try {
    $client->capture($capture);
} catch (Exception $e) {
    error_log('Capture failed: ' . $e->getMessage());
}

Per incassare un importo inferiore a quello riservato non usare la capture: addebita la prenotazione indicando un amount esplicito. Una transazione riservata può essere incassata una sola volta.

Rimborsare una Transaction

Un rimborso restituisce denaro al cliente. Ometti amount per rimborsare l'intera transazione oppure passa un importo in unità minori per un rimborso parziale. La possibilità di rimborso dipende dal metodo di pagamento e dallo stato della transazione: controlla i flag refundable e partiallyRefundable restituiti da Elencare e recuperare le Transaction. L'avanzamento del rimborso è visibile negli stati refund_pending, refunded e partially-refunded.

POSThttps://api.pay.flowalp.com/v1.16/Transaction/{id}/refundv1.14 · v1.15 · v1.16

Parametro	Tipo	Descrizione
id	integer (obbligatorio)	Path parameter: ID della transazione da rimborsare.
instance	string (obbligatorio)	Query parameter: nome della tua instance (tenant).
amount	integer	Facoltativo. Importo del rimborso parziale in unità minori; omettilo per rimborsare l'intero importo.

Rimborso parziale di CHF 15.00bash

curl -X POST "https://api.pay.flowalp.com/v1.16/Transaction/4712/refund?instance=<tenant>" \
  -H "x-api-key: <api-secret>" \
  -H "Content-Type: application/json" \
  -d '{"amount": 1500}'

Rimborsare una transazione (SDK PHP)PHP

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

// $client: stesso costruttore dell'esempio di addebito qui sopra
$refund = new Transaction();
$refund->setId(4712);
$refund->setAmount(1500); // ometti setAmount() per un rimborso totale

try {
    $client->refund($refund);
} catch (Exception $e) {
    error_log('Refund failed: ' . $e->getMessage());
}

Annullare una Transaction in attesa

Una transazione ancora in stato waiting — avviata ma mai completata — può essere annullata. La response restituisce la transazione con stato cancelled. Se la transazione esiste ma non è più in attesa, l'API risponde con 404.

PATCHhttps://api.pay.flowalp.com/v1.16/Transaction/{id}/cancelv1.14 · v1.15 · v1.16

Annullare una transazione in attesabash

curl -X PATCH "https://api.pay.flowalp.com/v1.16/Transaction/377/cancel?instance=<tenant>" \
  -H "x-api-key: <api-secret>"

Esempio di responseJSON

{
  "status": "success",
  "data": [
    {
      "id": 377,
      "uuid": "2639f2f9",
      "referenceId": "",
      "time": "2026-07-18 17:22:29",
      "status": "cancelled",
      "lang": "de",
      "psp": "Native_PSP",
      "amount": 10000
    }
  ]
}

Aggiornare i dati di contatto di pre-authorization o tokenization

Tokenization e pre-authorization conservano i dati di contatto insieme al metodo di pagamento. Aggiornali inviando un oggetto fields in cui ogni voce è un oggetto con una chiave value.

PUThttps://api.pay.flowalp.com/v1.16/Transaction/{id}/v1.14 · v1.15 · v1.16

Campi di contatto: title, forename, surname, company, street, postcode, place, country, phone, email, date_of_birth — title accetta mister, miss o diverse.
Campi dell'indirizzo di consegna: delivery_title, delivery_forename, delivery_surname, delivery_company, delivery_street, delivery_postcode, delivery_place, delivery_country.
Campi personalizzati: da custom_field_1 a custom_field_5, ciascuno con name, value ed export_name.
terms e privacy_policy: se includi questi campi nella richiesta, devono risultare accettati.

Aggiornare i dati di contattobash

curl -X PUT "https://api.pay.flowalp.com/v1.16/Transaction/9034/?instance=<tenant>" \
  -H "x-api-key: <api-secret>" \
  -H "Content-Type: application/json" \
  -d '{
    "fields": {
      "forename": {"value": "Anna"},
      "surname": {"value": "Keller"},
      "email": {"value": "anna.keller@example.com"}
    }
  }'

Se ti autentichi con ApiSignature invece che con l'header della API key, i parametri fields[...] devono mantenere un ordine stabile al momento del calcolo della firma.

Aggiornare una tokenization

Modifica l'aliquota IVA salvata su una tokenization esistente. La response restituisce la tokenization con il vatRate aggiornato.

PATCHhttps://api.pay.flowalp.com/v1.16/Transaction/{id}/updateTokenizationv1.14 · v1.15 · v1.16

Parametro	Tipo	Descrizione
id	integer (obbligatorio)	Path parameter: ID della tokenization di origine.
instance	string (obbligatorio)	Query parameter: nome della tua instance (tenant).
vatRate	integer (obbligatorio)	Nuova aliquota IVA come valore percentuale.

Aggiornare una tokenizationbash

curl -X PATCH "https://api.pay.flowalp.com/v1.16/Transaction/9034/updateTokenization?instance=<tenant>" \
  -H "x-api-key: <api-secret>" \
  -H "Content-Type: application/json" \
  -d '{"vatRate": 8}'

Errori

Stato HTTP	Significato
400	Richiesta non valida — il campo `message` del body di errore descrive il problema esatto.
404	Nessuna transazione con l'ID indicato esiste su questa instance. Per gli annullamenti si verifica anche quando la transazione non è in stato `waiting`.

Per consultare stati e ID delle transazioni usa Elencare e recuperare le Transaction. I concetti alla base di queste operazioni sono spiegati nelle guide Tokenization e Pre-authorization.

Addebitare, catturare, rimborsare e annullare le Transaction

Addebitare una Transaction tokenizzata o riservata#

Request#

Response#

Catturare una Transaction pre-autorizzata#

Rimborsare una Transaction#

Annullare una Transaction in attesa#

Aggiornare i dati di contatto di pre-authorization o tokenization#

Aggiornare una tokenization#

Errori#