Débiter, capturer, rembourser et annuler des Transactions

July 30, 2026

Débitez des paiements tokenisés, capturez des réservations, remboursez tout ou partie et annulez des transactions en attente avec FlowAlp Pay.

Une fois qu'une transaction existe dans FlowAlp Pay, vous pouvez continuer à la manipuler : débiter un moyen de paiement enregistré, encaisser un montant réservé, émettre des remboursements totaux ou partiels, annuler un paiement jamais finalisé et tenir à jour les données stockées sur une tokenisation. Tous les appels ci-dessous utilisent la version d'API v1.16 et l'en-tête x-api-key décrit dans Authentification.

Débiter une Transaction tokenisée ou réservée

Deux parcours produisent des transactions débitables. Une tokenisation (Gateway créé avec preAuthorization) laisse une transaction au statut authorized : vous pouvez la débiter autant de fois que nécessaire, avec un montant différent à chaque fois, et le token n'expire pas — mais la réussite du débit n'est pas garantie. Une pré-autorisation (Gateway créé avec reservation) laisse une transaction au statut reserved : elle ne peut être débitée qu'une seule fois, pour un montant au plus égal au montant réservé, et la réservation reste généralement valable environ cinq jours selon la banque émettrice.

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

Requête

Paramètre	Type	Description
id	integer (requis)	Paramètre de chemin : ID de la transaction à débiter — son statut doit être `authorized` ou `reserved`.
instance	string (requis)	Paramètre de requête : nom de votre instance (tenant).
amount	integer	Montant à débiter en unités mineures (`4500` = CHF 45.00).
purpose	string	Ce que le client paie.
referenceId	string	Votre propre référence pour la transaction débitée ; elle est incluse dans le webhook de transaction.
payoutDescriptor	string	Texte ajouté au libellé du versement, 80 caractères au maximum. S'applique uniquement aux paiements encaissés par FlowAlp Pay versés en versement à transaction unique.

Débiter une transactionbash

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"
  }'

Débiter une transaction (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());
}

Réponse

Exemple de réponseJSON

{
  "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"
      }
    }
  ]
}

Capturer une Transaction pré-autorisée

La capture encaisse un montant déjà approuvé, sans le modifier. L'appel ne prévoit aucun paramètre de corps documenté en dehors de l'ID de chemin et de votre instance.

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

Capturer une transactionbash

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

Capturer une transaction (SDK PHP)PHP

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

// $client : même constructeur que dans l'exemple de débit ci-dessus
$capture = new Transaction();
$capture->setId(9034);

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

Pour encaisser un montant inférieur au montant réservé, n'utilisez pas la capture : débitez la réservation avec un amount explicite. Une transaction réservée ne peut être encaissée qu'une seule fois.

Rembourser une Transaction

Un remboursement restitue de l'argent au client. Omettez amount pour rembourser la totalité de la transaction, ou passez un montant en unités mineures pour un remboursement partiel. La possibilité de remboursement dépend du moyen de paiement et de l'état de la transaction : vérifiez les indicateurs refundable et partiallyRefundable renvoyés par Lister et récupérer les Transactions. L'avancement du remboursement apparaît dans les statuts refund_pending, refunded et partially-refunded.

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

Paramètre	Type	Description
id	integer (requis)	Paramètre de chemin : ID de la transaction à rembourser.
instance	string (requis)	Paramètre de requête : nom de votre instance (tenant).
amount	integer	Facultatif. Montant du remboursement partiel en unités mineures ; omettez-le pour rembourser la totalité.

Remboursement partiel de 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}'

Rembourser une transaction (SDK PHP)PHP

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

// $client : même constructeur que dans l'exemple de débit ci-dessus
$refund = new Transaction();
$refund->setId(4712);
$refund->setAmount(1500); // omettez setAmount() pour un remboursement total

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

Annuler une Transaction en attente

Une transaction encore au statut waiting — initiée mais jamais finalisée — peut être annulée. La réponse renvoie la transaction avec le statut cancelled. Si la transaction existe mais n'est plus en attente, l'API répond 404.

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

Annuler une transaction en attentebash

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

Exemple de réponseJSON

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

Mettre à jour les coordonnées d'une pré-autorisation ou tokenisation

Les tokenisations et pré-autorisations conservent des coordonnées avec le moyen de paiement. Mettez-les à jour en envoyant un objet fields dont chaque entrée est un objet avec une clé value.

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

Champs de contact : title, forename, surname, company, street, postcode, place, country, phone, email, date_of_birth — title accepte mister, miss ou diverse.
Champs d'adresse de livraison : delivery_title, delivery_forename, delivery_surname, delivery_company, delivery_street, delivery_postcode, delivery_place, delivery_country.
Champs personnalisés : custom_field_1 … custom_field_5, chacun avec name, value et export_name.
terms et privacy_policy : si vous incluez ces champs dans la requête, ils doivent être acceptés.

Mettre à jour les coordonnéesbash

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"}
    }
  }'

Si vous vous authentifiez avec ApiSignature au lieu de l'en-tête de clé API, les paramètres fields[...] doivent conserver un ordre stable lors du calcul de la signature.

Mettre à jour une tokenisation

Ajustez le taux de TVA enregistré sur une tokenisation existante. La réponse renvoie la tokenisation avec son vatRate mis à jour.

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

Paramètre	Type	Description
id	integer (requis)	Paramètre de chemin : ID de la tokenisation d'origine.
instance	string (requis)	Paramètre de requête : nom de votre instance (tenant).
vatRate	integer (requis)	Nouveau taux de TVA en pourcentage.

Mettre à jour une tokenisationbash

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}'

Erreurs

Statut HTTP	Signification
400	Requête mal formée — le champ `message` du corps d'erreur décrit le problème exact.
404	Aucune transaction avec l'ID indiqué n'existe sur cette instance. Pour les annulations, ce code survient aussi lorsque la transaction n'est pas au statut `waiting`.

Pour consulter les statuts et les ID des transactions, utilisez Lister et récupérer les Transactions. Les concepts derrière ces opérations sont expliqués dans les guides Tokenisation et Pré-autorisation.

Débiter, capturer, rembourser et annuler des Transactions

Débiter une Transaction tokenisée ou réservée#

Requête#

Réponse#

Capturer une Transaction pré-autorisée#

Rembourser une Transaction#

Annuler une Transaction en attente#

Mettre à jour les coordonnées d'une pré-autorisation ou tokenisation#

Mettre à jour une tokenisation#

Erreurs#