FlowAlp

Créer un Paylink

July 30, 2026

Créez un Paylink FlowAlp Pay via POST /Invoice/ : un lien de paiement à envoyer par e-mail ou code QR. Paramètres, exemples et erreurs.

Un Paylink est une page de paiement hébergée FlowAlp Pay à configuration fixe : vous le créez une fois puis le partagez — par e-mail, dans une facture PDF, en code QR ou par chat. Le client ouvre le lien et paie ; aucun code n'est requis sur votre site. Dans la Merchant API, la ressource sous-jacente s'appelle Invoice.

POSThttps://api.pay.flowalp.com/v1.16/Invoice/v1.14 · v1.15 · v1.16

Utilisez la version d'API v1.16 pour toute nouvelle intégration ; v1.14 et v1.15 restent prises en charge. Authentifiez-vous avec l'en-tête X-API-KEY et identifiez votre compte avec le paramètre de requête instance — voir Authentification. Le corps peut être envoyé en application/json (recommandé) ou application/x-www-form-urlencoded.

Requête

Paramètres de requête (query)

ParamètreTypeObligatoireDescription
instancestringOuiNom de votre instance marchande ; identifie votre compte à chaque appel API.

Paramètres du corps

ParamètreTypeObligatoireDescription
titlestringOuiTitre affiché en haut de la page de paiement hébergée.
descriptionstringOuiTexte descriptif affiché sur la page de paiement.
referenceIdstringOuiVotre propre référence de facture ou de commande ; renvoyée dans les réponses et les webhooks.
purposestringOuiObjet du paiement affiché au client.
amountintegerOuiMontant en unités mineures de la devise ; CHF 89.25 devient 8925.
currencystringOuiDevise du paiement au format ISO 4217, par exemple CHF.
vatRatefloatNonTaux de TVA en pourcentage. Défaut : null.
psparray of integersNonIDs des payment providers à proposer pour ce Paylink.
pmarray of stringsNonIdentifiants des moyens de paiement à afficher.
skustringNonRéférence article (stock keeping unit) du produit.
preAuthorizationbooleanNonAutorise le moyen de paiement pour un débit ultérieur au lieu d'un débit immédiat. Défaut : false.
reservationbooleanNonRéserve le montant pour une capture ultérieure. Défaut : false.
namestringNonNom interne de la page de paiement ; visible uniquement par les administrateurs.
fieldsarray of stringsNonNoms des champs de contact à afficher sur la page de paiement.
hideFieldsbooleanNonMasque toute la section des données de contact sur la page de paiement. Défaut : false.
buttonTextstringNonLibellé personnalisé pour le bouton de paiement.
expirationDatedateNonDate d'expiration du lien, par exemple 2026-08-31.
successRedirectUrlstringNonURL vers laquelle le client est redirigé après un paiement réussi.
failedRedirectUrlstringNonURL vers laquelle le client est redirigé après un paiement échoué.
subscriptionStatebooleanNonTraite le paiement comme une subscription. Défaut : false.
subscriptionIntervalstringNonIntervalle de facturation de la subscription en notation de période, par exemple P1M.
subscriptionPeriodstringNonDurée totale de la subscription en notation de période.
subscriptionCancellationIntervalstringNonDélai pendant lequel la subscription peut être résiliée, en notation de période.
attachmentsfileNonPièces jointes mises à disposition de votre client.
isPriceExclusiveVatbooleanNonSi true, la TVA est ajoutée en plus d'amount au lieu d'y être incluse.
concardisOrderIdstringNonID de commande transmis à l'acquéreur ; disponible uniquement si l'option correspondante est activée dans vos réglages de payment provider.

Certaines options dépendent de la configuration de votre compte : les IDs de providers pour psp, les identifiants pour pm, les réglages de subscription, les attachments et les paramètres propres à un provider comme concardisOrderId ne fonctionnent que si la fonction correspondante est active sur votre instance. Si un paramètre optionnel est refusé, vérifiez votre configuration dans le dashboard ou contactez le support.

Exemple de requête

Créer un Paylink (cURL)bash
curl --request POST \
  --url "https://api.pay.flowalp.com/v1.16/Invoice/?instance=${FLOWALP_PAY_INSTANCE}" \
  --header "X-API-KEY: ${FLOWALP_PAY_API_SECRET}" \
  --header "Content-Type: application/json" \
  --data '{
    "title": "Invoice INV-2026-0042",
    "description": "Consulting services, June 2026",
    "referenceId": "INV-2026-0042",
    "purpose": "Invoice INV-2026-0042",
    "amount": 8925,
    "currency": "CHF",
    "expirationDate": "2026-08-31",
    "successRedirectUrl": "https://shop.example.com/payment/success",
    "failedRedirectUrl": "https://shop.example.com/payment/failed"
  }'
Créer un Paylink (SDK PHP)PHP
<?php
use FlowAlpPay\FlowAlpPay;
use FlowAlpPay\Models\Request\Paylink;

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

$paylink = new Paylink();
$paylink->setTitle('Invoice INV-2026-0042');
$paylink->setDescription('Consulting services, June 2026');
$paylink->setReferenceId('INV-2026-0042');
$paylink->setPurpose('Invoice INV-2026-0042');
$paylink->setAmount(8925); // CHF 89.25 in minor units
$paylink->setCurrency('CHF');
$paylink->setSuccessRedirectUrl('https://shop.example.com/payment/success');
$paylink->setFailedRedirectUrl('https://shop.example.com/payment/failed');

$response = $client->create($paylink);

// Share this URL by e-mail or render it as a QR code.
$paylinkUrl = $response->getLink();

Réponse

Le nouveau Paylink est renvoyé dans l'enveloppe de succès. Envoyez à votre client l'URL contenue dans link — ou construisez l'URL à partir de hash — et enregistrez id et referenceId dans votre système. Pour relier un paiement entrant au Paylink, appuyez-vous sur link ou hash, pas uniquement sur referenceId.

200 OKJSON
{
  "status": "success",
  "data": [
    {
      "id": 57,
      "hash": "f7d1b2e94c3a48d2a5efb6c17d0a9c31",
      "referenceId": "INV-2026-0042",
      "link": "https://demo-shop.pay.flowalp.com/?payment=f7d1b2e94c3a48d2a5efb6c17d0a9c31",
      "title": "Invoice INV-2026-0042",
      "description": "Consulting services, June 2026",
      "purpose": "Invoice INV-2026-0042",
      "amount": 8925,
      "currency": "CHF",
      "createdAt": "2026-07-30 11:52:08"
    }
  ]
}

Erreurs

Statut HTTPSignificationAction recommandée
400La requête n'a pas passé la validation, par exemple un paramètre obligatoire comme title ou referenceId manque.Corrigez le corps de la requête puis renvoyez-la.

Les réponses d'erreur utilisent l'enveloppe {"status": "error", "message": "..."} — voir Erreurs et Limites de débit.

Sur le même sujet : le guide Liens de paiement et codes QR, la vérification des paiements avec Récupérer et lister les Paylinks, la gestion du cycle de vie dans Modifier et supprimer un Paylink et la confirmation des paiements via les webhooks.