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.
https://api.pay.flowalp.com/v1.16/Invoice/v1.14 · v1.15 · v1.16Utilisez 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ètre | Type | Obligatoire | Description |
|---|---|---|---|
| instance | string | Oui | Nom de votre instance marchande ; identifie votre compte à chaque appel API. |
Paramètres du corps
| Paramètre | Type | Obligatoire | Description |
|---|---|---|---|
| title | string | Oui | Titre affiché en haut de la page de paiement hébergée. |
| description | string | Oui | Texte descriptif affiché sur la page de paiement. |
| referenceId | string | Oui | Votre propre référence de facture ou de commande ; renvoyée dans les réponses et les webhooks. |
| purpose | string | Oui | Objet du paiement affiché au client. |
| amount | integer | Oui | Montant en unités mineures de la devise ; CHF 89.25 devient 8925. |
| currency | string | Oui | Devise du paiement au format ISO 4217, par exemple CHF. |
| vatRate | float | Non | Taux de TVA en pourcentage. Défaut : null. |
| psp | array of integers | Non | IDs des payment providers à proposer pour ce Paylink. |
| pm | array of strings | Non | Identifiants des moyens de paiement à afficher. |
| sku | string | Non | Référence article (stock keeping unit) du produit. |
| preAuthorization | boolean | Non | Autorise le moyen de paiement pour un débit ultérieur au lieu d'un débit immédiat. Défaut : false. |
| reservation | boolean | Non | Réserve le montant pour une capture ultérieure. Défaut : false. |
| name | string | Non | Nom interne de la page de paiement ; visible uniquement par les administrateurs. |
| fields | array of strings | Non | Noms des champs de contact à afficher sur la page de paiement. |
| hideFields | boolean | Non | Masque toute la section des données de contact sur la page de paiement. Défaut : false. |
| buttonText | string | Non | Libellé personnalisé pour le bouton de paiement. |
| expirationDate | date | Non | Date d'expiration du lien, par exemple 2026-08-31. |
| successRedirectUrl | string | Non | URL vers laquelle le client est redirigé après un paiement réussi. |
| failedRedirectUrl | string | Non | URL vers laquelle le client est redirigé après un paiement échoué. |
| subscriptionState | boolean | Non | Traite le paiement comme une subscription. Défaut : false. |
| subscriptionInterval | string | Non | Intervalle de facturation de la subscription en notation de période, par exemple P1M. |
| subscriptionPeriod | string | Non | Durée totale de la subscription en notation de période. |
| subscriptionCancellationInterval | string | Non | Délai pendant lequel la subscription peut être résiliée, en notation de période. |
| attachments | file | Non | Pièces jointes mises à disposition de votre client. |
| isPriceExclusiveVat | boolean | Non | Si true, la TVA est ajoutée en plus d'amount au lieu d'y être incluse. |
| concardisOrderId | string | Non | ID 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
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"
}'<?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.
{
"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 HTTP | Signification | Action recommandée |
|---|---|---|
| 400 | La 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.