API Payout

July 30, 2026

Elenca i payout FlowAlp Pay e recupera un singolo payout con transazioni, commissioni e riferimento bancario per la tua riconciliazione.

Un Payout è il bonifico che trasferisce il saldo incassato tramite FlowAlp Pay sul tuo conto bancario. L'API è in sola lettura: puoi elencare i payout, recuperare l'intestazione di un singolo payout e scorrere i transfer di dettaglio che contiene — le singole transazioni, le commissioni e le rettifiche. Per il concetto di liquidazione lato merchant parti da Payout e riconciliazione.

Elencare i Payout

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

Parametro	Tipo	Descrizione
instance	string (obbligatorio)	Query parameter: nome della tua instance (tenant).
limit	integer	Numero massimo di righe da restituire.
offset	integer	Numero di righe da saltare, per la paginazione.
orderByDate	string	`ASC` (default) oppure `DESC` — ordinamento per data del payout.

Elencare i payoutbash

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

Elencare i payout (SDK PHP)PHP

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

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

try {
    $payouts = $client->getAll(new Payout());
    foreach ($payouts as $payout) {
        echo $payout->getUuid() . PHP_EOL;
    }
} catch (Exception $e) {
    error_log('Payout list failed: ' . $e->getMessage());
}

L'elenco restituisce gli oggetti payout in data senza il dettaglio dei transfer (transfers resta vuoto). Per caricare il contenuto di un payout usa l'endpoint dei dettagli qui sotto.

Recuperare un Payout

GEThttps://api.pay.flowalp.com/v1.16/Payout/{uuid}/v1.14 · v1.15 · v1.16

Parametro	Tipo	Descrizione
uuid	string (obbligatorio)	Path parameter: UUID del payout, preso ad esempio dalla response di elenco o dal campo `payoutUuid` di una transazione.
instance	string (obbligatorio)	Query parameter: nome della tua instance (tenant).

Recuperare l'intestazione di un payoutbash

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

Questa variante restituisce l'intestazione del payout — totali, stato, data e conto di destinazione — senza risolvere i transfer contenuti.

Recuperare un Payout con i dettagli

GEThttps://api.pay.flowalp.com/v1.16/Payout/{uuid}/detailsv1.14 · v1.15 · v1.16

Parametro	Tipo	Descrizione
uuid	string (obbligatorio)	Path parameter: UUID del payout.
instance	string (obbligatorio)	Query parameter: nome della tua instance (tenant).
limit	integer	Query parameter: numero di transfer per pagina; è consigliata una dimensione di pagina di 100 elementi.
offset	integer	Query parameter: offset da usare insieme a `limit`. Default `0`.

Recuperare i dettagli di un payoutbash

curl "https://api.pay.flowalp.com/v1.16/Payout/C6B438B9/details?instance=<tenant>&limit=100&offset=0" \
  -H "x-api-key: <api-secret>"

Recuperare i dettagli di un payout (SDK PHP)PHP

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

// $client: stesso costruttore dell'esempio di elenco qui sopra
$payout = new Payout();
$payout->setUuid('C6B438B9');

try {
    $details = $client->details($payout);
} catch (Exception $e) {
    error_log('Payout details failed: ' . $e->getMessage());
}

Dalla versione v1.16 i tentativi di payout ripetuti vengono risolti nei transfer originali sottostanti. Nelle versioni precedenti un tentativo ripetuto compariva come singola voce aggregata con un oggetto transaction vuoto; ora la response elenca le vere transazioni individuali del payout originale.

Response

Gli endpoint per un singolo payout restituiscono un oggetto in data (l'elenco restituisce un array). Tutti gli importi sono in unità minori. Ogni voce di transfers ha un type, un amount, un date_time e un array items i cui valori sommano sempre all'importo del transfer — un pagamento di CHF 300.00 con CHF 3.00 di commissioni mostra items 30000 e -300 e un transfer di 29700. Quando un transfer riguarda un pagamento, il suo oggetto transaction contiene uuid e reference_id della transazione da abbinare ai tuoi ordini; altrimenti è un oggetto vuoto.

Campo	Tipo	Descrizione
uuid	string	Identificativo pubblico del payout.
mode	string	`LIVE` oppure `TEST`.
object	string	Sempre `payout`.
amount	integer	Importo totale trasferito, in unità minori.
total_fees	integer	Somma di tutte le commissioni contenute nel payout, in unità minori.
currency	string	Codice valuta ISO del payout.
date	string	Data del payout, formato `YYYY-MM-DD`.
statement	string	Testo che compare sull'estratto conto bancario.
status	string	Stato del payout, vedi tabella sotto.
destination	object	Conto di destinazione: `type` (ad esempio `bank_account`), `iban` e `account_holder`.
transfers	array	Contenuto del payout: transazioni, commissioni, rettifiche e riserve.
merchant	object	I dati del tuo account: `name`, `site_title` e un oggetto `owner`.

Esempio di response (dettagli)JSON

{
  "status": "success",
  "data": {
    "uuid": "C6B438B9",
    "mode": "LIVE",
    "object": "payout",
    "amount": 29690,
    "total_fees": 310,
    "currency": "CHF",
    "date": "2026-07-06",
    "statement": "Demo Shop Thun",
    "status": "sent",
    "destination": {
      "type": "bank_account",
      "iban": "CH93 0076 2011 6238 5295 7",
      "account_holder": "Demo Firma"
    },
    "transfers": [
      {
        "type": "payout-fee",
        "amount": -10,
        "date_time": "2026-07-06T13:45:18+00:00",
        "items": [
          { "type": "payout-fee", "amount": -10 }
        ],
        "transaction": {}
      },
      {
        "type": "transaction",
        "amount": 29700,
        "date_time": "2026-06-25T13:44:30+00:00",
        "items": [
          { "type": "transaction", "amount": 30000 },
          { "type": "transaction-fee", "amount": -300 }
        ],
        "transaction": {
          "type": "transaction",
          "amount": 30000,
          "uuid": "aabb1122",
          "fee": 300,
          "currency": "CHF",
          "time": "2026-06-25T14:44:31+01:00",
          "payment": { "brand": "visa" },
          "reference_id": "ORDER-2026-0815"
        }
      }
    ],
    "merchant": {
      "name": "demo-shop",
      "site_title": "Demo Shop",
      "owner": {
        "company": "Demo Firma",
        "first_name": "Anna",
        "last_name": "Keller",
        "address": "Bahnhofstrasse 12",
        "zip": "3600",
        "place": "Thun",
        "email": "finance@demo-shop.example"
      }
    }
  }
}

Valori possibili di type per un transfer: transaction, transaction-reversal, dispute, dispute-reversal, payout, payout-reversal, adjustment, manual-adjustment, payout-fee, payout-reserve, payout-reserve-reversal e alternative-currency-payout-fee-percent.

Stati del payout

Stato	Descrizione
initiated	Il payout è stato avviato dal sistema.
pending	Il payout è creato e pronto per l'elaborazione.
under-review	Il payout richiede una verifica più approfondita prima del rilascio.
processing	Il file del payout è stato consegnato per l'esecuzione bancaria.
sent	Il payout è stato trasmesso con successo alla banca.
failed	Il payout non è riuscito ed è stato restituito dalla banca.

Le notifiche webhook vengono inviate per gli stati processing, sent e failed — non per initiated, pending o under-review.

Errori

Stato HTTP	Significato
400	Richiesta non valida — il campo `message` del body di errore descrive il problema esatto.
404	Nessun payout con lo UUID indicato esiste su questa instance.

Ogni transazione liquidata espone il payoutUuid del payout a cui appartiene — vedi Elencare e recuperare le Transaction. Per il flusso completo di liquidazione e riconciliazione leggi Payout e riconciliazione; per ricevere automaticamente i cambi di stato dei payout configura i webhook.

API Payout

Elencare i Payout#

Recuperare un Payout#

Recuperare un Payout con i dettagli#

Response#

Stati del payout#

Errori#