Elencare e recuperare le Transaction

July 30, 2026

Elenca e filtra le transazioni FlowAlp Pay o recupera una singola transazione tramite ID, con tutti gli stati spiegati per la Merchant API.

Ogni pagamento elaborato tramite FlowAlp Pay viene registrato come Transaction. La Merchant API espone due endpoint in lettura per questa risorsa: uno restituisce un elenco filtrabile, l'altro un singolo record tramite il suo ID numerico. Per le nuove integrazioni usa la versione API v1.16 e autentica ogni chiamata con l'header x-api-key, come descritto in Autenticazione.

Elencare le Transaction

GEThttps://api.pay.flowalp.com/v1.16/Transaction/v1.14 · v1.15 · v1.16

L'endpoint di elenco restituisce le transazioni della tua instance ordinate per data di creazione. Combina i filtri data in UTC con limit e offset per scorrere set di risultati estesi. Tutti i parametri sono facoltativi tranne instance.

Parametri della request

Parametro	Tipo	Descrizione
instance	string (obbligatorio)	Nome della tua instance (tenant). Identifica l'account su cui viene eseguita la richiesta.
filterDatetimeUtcGreaterThan	date	Limite inferiore in UTC, formato `YYYY-MM-DD HH:MM:SS`. Vengono restituite solo le transazioni create dopo questo momento.
filterDatetimeUtcLessThan	date	Limite superiore in UTC, stesso formato.
filterMyTransactionsOnly	boolean	Default `false`. Se impostato a `1`, restituisce solo le transazioni create con la API key usata per questa richiesta.
orderByTime	string	`ASC` (default) oppure `DESC` — ordinamento per data della transazione.
offset	integer	Numero di righe da saltare, per la paginazione.
limit	integer	Numero massimo di righe da restituire.

Elencare le transazionibash

curl "https://api.pay.flowalp.com/v1.16/Transaction/?instance=<tenant>&orderByTime=DESC&limit=20&offset=0" \
  -H "x-api-key: <api-secret>"

Elencare le transazioni (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'
);

$request = new Transaction();
$request->setFilterDatetimeUtcGreaterThan(new DateTime('2026-07-01 00:00:00'));
$request->setFilterDatetimeUtcLessThan(new DateTime('2026-07-31 23:59:59'));
$request->setOrderByTime('DESC');
$request->setLimit(20);

try {
    $transactions = $client->getAll($request);
    foreach ($transactions as $transaction) {
        echo $transaction->getId() . ': ' . $transaction->getStatus() . PHP_EOL;
    }
} catch (Exception $e) {
    error_log('Listing transactions failed: ' . $e->getMessage());
}

Recuperare una Transaction

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

Parametro	Tipo	Descrizione
id	integer (obbligatorio)	Path parameter: ID numerico della transazione da recuperare. Lo ricevi alla creazione della transazione e in ogni notifica webhook.
instance	string (obbligatorio)	Query parameter: nome della tua instance (tenant).

Recuperare una transazionebash

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

Recuperare una transazione (SDK PHP)PHP

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

// $client: stesso costruttore dell'esempio di elenco qui sopra
$request = new Transaction();
$request->setId(4712);

try {
    $transaction = $client->getOne($request);
    echo $transaction->getStatus();
} catch (Exception $e) {
    error_log('Transaction lookup failed: ' . $e->getMessage());
}

Response

Entrambi gli endpoint rispondono con un campo status e un array data; il recupero singolo restituisce un array con esattamente un elemento. Gli importi sono espressi in unità minori (6250 = CHF 62.50). refundable e partiallyRefundable indicano quali operazioni di rimborso sono possibili in questo momento, mentre payoutUuid collega la transazione al payout che l'ha liquidata.

Esempio di responseJSON

{
  "status": "success",
  "data": [
    {
      "id": 4712,
      "uuid": "f384000b",
      "status": "confirmed",
      "time": "2026-07-12 09:41:27",
      "lang": "de",
      "psp": "Native_PSP",
      "pspId": 26,
      "mode": "LIVE",
      "referenceId": "ORDER-2026-0815",
      "pageUuid": "892dcf5c",
      "payment": {
        "brand": "visa",
        "wallet": null
      },
      "payoutUuid": "AB12CD34",
      "invoice": {
        "currencyAlpha3": "CHF",
        "products": [
          { "quantity": 1, "name": "Hoodie", "amount": 5900 }
        ],
        "discount": null,
        "shippingAmount": 350,
        "totalAmount": 6250,
        "customFields": null
      },
      "refundable": true,
      "partiallyRefundable": true,
      "contact": {
        "id": 16,
        "uuid": "9c9c0282",
        "firstname": "Anna",
        "lastname": "Keller",
        "email": "anna.keller@example.com",
        "country": "Switzerland",
        "countryISO": "CH"
      }
    }
  ]
}

Stati della transazione

Il campo status indica il punto del ciclo di vita in cui si trova la transazione:

Stato	Descrizione
waiting	Il pagamento è stato avviato ma non è ancora concluso.
confirmed	Il pagamento è riuscito e l'importo è stato addebitato.
authorized	Il metodo di pagamento è stato tokenizzato con successo; nessun importo è stato addebitato.
reserved	Un importo è stato riservato tramite pre-authorization.
refunded	L'intero importo è stato restituito al cliente.
partially-refunded	Una parte dell'importo è stata restituita al cliente.
refund_pending	Un rimborso è in fase di elaborazione.
cancelled	Il pagamento è stato annullato dal cliente.
declined	Il pagamento non ha superato il 3-D Secure o è stato rifiutato dalla banca emittente.
chargeback	Il titolare della carta ha richiesto la restituzione dei fondi tramite la sua banca.
disputed	È stata aperta una contestazione per questa transazione.
error	Si è verificato un problema tecnico durante l'elaborazione.
expired	Il pagamento è stato interrotto per inattività.

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.

Le response di errore hanno la forma {"status": "error", "message": "..."}.

Le operazioni successive al pagamento — addebito, capture, rimborso e annullamento — sono descritte in Addebitare, catturare, rimborsare e annullare le Transaction. Per capire come gli incassi confermati arrivano sul tuo conto leggi la Payouts API e ricevi i cambi di stato in tempo reale con gli eventi webhook.

Elencare e recuperare le Transaction

Elencare le Transaction#

Parametri della request#

Recuperare una Transaction#

Response#

Stati della transazione#

Errori#