Tokenisation : débiter des moyens de paiement enregistrés

La tokenisation enregistre le moyen de paiement d'un client sous forme de token réutilisable lors d'un checkout normal. Vous pouvez ensuite débiter ce client côté serveur — quel que soit le montant, à tout moment — sans le renvoyer vers une page de paiement. Les données de carte sensibles ne touchent jamais vos systèmes : FlowAlp Pay les conserve, vous ne gardez que des IDs.

Comment fonctionne la tokenisation#

1. Créez un Gateway avec "preAuthorization": true. Le client passe par le checkout hébergé habituel, mais au lieu d'un débit, seul le moyen de paiement est enregistré.
2. La transaction reçoit le statut authorized — transmis par le webhook de transaction, avec l'ID de la transaction.
3. Chaque fois que vous devez encaisser, débitez cet ID de transaction via l'endpoint Transaction avec le montant de votre choix.
4. Chaque débit crée une nouvelle transaction (confirmed en cas de succès) qui renvoie au token via preAuthorizationId.

Les tokens n'expirent pas et peuvent être débités autant de fois que nécessaire, avec n'importe quel montant. Contrairement à une préautorisation, aucun fonds n'est toutefois bloqué — un débit peut échouer (carte expirée, provision insuffisante), votre code doit donc gérer les échecs.

Enregistrer un moyen de paiement au checkout#

Réglez preAuthorization sur true lors de la création du Gateway. Lors d'une tokenisation simple, le montant n'est pas débité — le checkout enregistre uniquement le moyen de paiement. Si le premier paiement doit être encaissé immédiatement, réglez en plus chargeOnAuthorization sur true.

curl -X POST "https://api.pay.flowalp.com/v1.16/Gateway/?instance=demo-shop" \
  -H "x-api-key: $FLOWALP_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 2990,
    "currency": "CHF",
    "purpose": "Save payment method",
    "referenceId": "CUST-55021-SETUP",
    "preAuthorization": true,
    "chargeOnAuthorization": true,
    "successRedirectUrl": "https://app.example.com/billing/success",
    "failedRedirectUrl": "https://app.example.com/billing/failed",
    "cancelRedirectUrl": "https://app.example.com/billing/cancel"
  }'

Quand le webhook signale le statut authorized, enregistrez l'ID de la transaction avec la fiche du client — c'est la clé de tous les débits futurs. Vous pouvez aussi le lire en récupérant le Gateway.

Débiter le token côté serveur#

Un débit ultérieur est une simple requête POST sur l'ID de transaction enregistré — sans aucune interaction du client. Le montant est libre, en unité minimale :

curl -X POST "https://api.pay.flowalp.com/v1.16/Transaction/98123/?instance=demo-shop" \
  -H "x-api-key: $FLOWALP_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 1490,
    "purpose": "Usage fees July",
    "referenceId": "CUST-55021-2026-07"
  }'

<?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(98123); // transaction with status "authorized"
$charge->setAmount(1490); // CHF 14.90
$charge->setPurpose('Usage fees July');
$charge->setReferenceId('CUST-55021-2026-07');

$response = $client->charge($charge);

Chaque débit réussi apparaît dans vos webhooks comme une nouvelle transaction confirmed, dont le preAuthorizationId renvoie au token. Surveillez les débits échoués pour les relancer ou contacter le client. Tous les paramètres de l'endpoint sont documentés dans Débiter, encaisser, rembourser et annuler des Transactions.

Sécurité et périmètre PCI#

• Les données de carte et de compte ne sont saisies que sur le checkout FlowAlp Pay et restent sur la plateforme — votre base de données ne contient que des IDs client et transaction, rien de lié à la carte.
• Gardez le secret API strictement côté backend et faites-le tourner en cas de fuite suspectée : quiconque le détient pourrait débiter les tokens enregistrés.
• Vérifiez la signature des webhooks avant d'enregistrer un débit comme réussi.

Tokenisation ou abonnements ?#

Utilisez la tokenisation quand les montants ou les intervalles varient : facturation à l'usage, recommandes en un clic, débits ajoutés à une ardoise ouverte, ou logique récurrente autogérée où vous décidez du moment du débit et de la gestion des échecs et résiliations. Utilisez les abonnements quand un montant fixe revient à intervalle fixe et que FlowAlp Pay doit débiter le client automatiquement — voir Abonnements et paiements récurrents.