API Payouts
July 30, 2026
Listez les versements FlowAlp Pay et récupérez un versement avec ses transactions, frais et référence bancaire pour la réconciliation.
Un Payout est le virement bancaire qui transfère le solde encaissé via FlowAlp Pay vers votre propre compte. L'API est en lecture seule : vous pouvez lister les versements, récupérer l'en-tête d'un versement unique et parcourir les transferts détaillés qu'il contient — transactions individuelles, frais et ajustements. Pour le concept de règlement côté marchand, commencez par Versements et réconciliation.
Lister les Payouts
https://api.pay.flowalp.com/v1.16/Payout/v1.14 · v1.15 · v1.16| Paramètre | Type | Description |
|---|---|---|
| instance | string (requis) | Paramètre de requête : nom de votre instance (tenant). |
| limit | integer | Nombre maximal de lignes renvoyées. |
| offset | integer | Nombre de lignes à ignorer, pour la pagination. |
| orderByDate | string | ASC (défaut) ou DESC — tri selon la date du versement. |
curl "https://api.pay.flowalp.com/v1.16/Payout/?instance=<tenant>&orderByDate=DESC&limit=20" \
-H "x-api-key: <api-secret>"<?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());
}La liste renvoie les objets payout dans data sans le détail des transferts (transfers reste vide). Pour charger le contenu d'un versement, utilisez l'endpoint de détails ci-dessous.
Récupérer un Payout
https://api.pay.flowalp.com/v1.16/Payout/{uuid}/v1.14 · v1.15 · v1.16| Paramètre | Type | Description |
|---|---|---|
| uuid | string (requis) | Paramètre de chemin : UUID du versement, obtenu par exemple dans la réponse de liste ou dans le champ payoutUuid d'une transaction. |
| instance | string (requis) | Paramètre de requête : nom de votre instance (tenant). |
curl "https://api.pay.flowalp.com/v1.16/Payout/C6B438B9/?instance=<tenant>" \
-H "x-api-key: <api-secret>"Cette variante renvoie l'en-tête du versement — totaux, statut, date et compte de destination — sans résoudre les transferts contenus.
Récupérer un Payout avec les détails
https://api.pay.flowalp.com/v1.16/Payout/{uuid}/detailsv1.14 · v1.15 · v1.16| Paramètre | Type | Description |
|---|---|---|
| uuid | string (requis) | Paramètre de chemin : UUID du versement. |
| instance | string (requis) | Paramètre de requête : nom de votre instance (tenant). |
| limit | integer | Paramètre de requête : nombre d'entrées de transfert par page ; une taille de page de 100 éléments est recommandée. |
| offset | integer | Paramètre de requête : décalage à utiliser avec limit. Défaut 0. |
curl "https://api.pay.flowalp.com/v1.16/Payout/C6B438B9/details?instance=<tenant>&limit=100&offset=0" \
-H "x-api-key: <api-secret>"<?php
use FlowAlpPay\Models\Request\Payout;
// $client : même constructeur que dans l'exemple de liste ci-dessus
$payout = new Payout();
$payout->setUuid('C6B438B9');
try {
$details = $client->details($payout);
} catch (Exception $e) {
error_log('Payout details failed: ' . $e->getMessage());
}Depuis la version v1.16, les tentatives de versement répétées sont résolues en leurs transferts d'origine. Dans les versions précédentes, une tentative répétée apparaissait comme une entrée agrégée unique avec un objet transaction vide ; la réponse liste désormais les transactions individuelles réelles du versement d'origine.
Réponse
Les endpoints d'un versement unique renvoient un objet payout dans data (la liste renvoie un tableau). Tous les montants sont en unités mineures. Chaque entrée de transfers possède un type, un amount, un date_time et un tableau items dont les valeurs s'additionnent toujours au montant du transfert — un paiement de CHF 300.00 avec CHF 3.00 de frais montre des items de 30000 et -300 et un transfert de 29700. Lorsqu'un transfert concerne un paiement, son objet transaction porte l'uuid et le reference_id de la transaction à rapprocher de vos commandes ; sinon, c'est un objet vide.
| Champ | Type | Description |
|---|---|---|
| uuid | string | Identifiant public du versement. |
| mode | string | LIVE ou TEST. |
| object | string | Toujours payout. |
| amount | integer | Montant total viré, en unités mineures. |
| total_fees | integer | Somme de tous les frais contenus dans le versement, en unités mineures. |
| currency | string | Code devise ISO du versement. |
| date | string | Date du versement, format YYYY-MM-DD. |
| statement | string | Texte qui apparaît sur le relevé bancaire. |
| status | string | Statut du versement, voir le tableau ci-dessous. |
| destination | object | Compte de destination : type (par exemple bank_account), iban et account_holder. |
| transfers | array | Contenu du versement : transactions, frais, ajustements et réserves. |
| merchant | object | Les données de votre compte : name, site_title et un objet owner. |
{
"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"
}
}
}
}Valeurs possibles de type pour un transfert : transaction, transaction-reversal, dispute, dispute-reversal, payout, payout-reversal, adjustment, manual-adjustment, payout-fee, payout-reserve, payout-reserve-reversal et alternative-currency-payout-fee-percent.
Statuts du versement
| Statut | Description |
|---|---|
| initiated | Le versement a été initié par le système. |
| pending | Le versement est créé et prêt à être traité. |
| under-review | Le versement doit être examiné de plus près avant d'être libéré. |
| processing | Le fichier de versement a été remis pour exécution bancaire. |
| sent | Le versement a été transmis avec succès à la banque. |
| failed | Le versement a échoué et a été retourné par la banque. |
Des notifications webhook sont envoyées pour les statuts processing, sent et failed — pas pour initiated, pending ni under-review.
Erreurs
| Statut HTTP | Signification |
|---|---|
| 400 | Requête mal formée — le champ message du corps d'erreur décrit le problème exact. |
| 404 | Aucun versement avec l'UUID indiqué n'existe sur cette instance. |
Chaque transaction réglée expose le payoutUuid du versement auquel elle appartient — voir Lister et récupérer les Transactions. Pour le flux complet de règlement et de réconciliation, lisez Versements et réconciliation ; pour recevoir automatiquement les changements de statut, configurez les webhooks.