Paiements en ligne

Concept clé : session vs paiement

Il est essentiel de comprendre que dans l'API externe existent deux concepts distincts : la session et le paiement. Bien qu'ils soient liés, ils représentent des choses différentes et ont des cycles de vie indépendants.

La session (sessionId)

La session est ce que votre système crée en appelant POST /payment/session. Elle représente l'intention d'encaissement : le montant, la devise, les URLs de retour, la description, etc. Lors de sa création, vous recevez un sessionId et une paymentUrl pour rediriger le client.

Lorsque le client finalise le paiement avec succès, la session passe à l'état completed et se ferme.

La session ne se modifie pas une fois terminée. Son rôle est accompli : elle a permis au client de payer.

Le paiement (paymentReference)

Le paiement est la transaction réelle créée lorsque le client finalise avec succès le formulaire de paiement. C'est l'objet que le processeur de paiement reconnaît et sur lequel des opérations peuvent être effectuées.

Le paymentReference (référence du paiement autorisé) apparaît dans la session une fois terminée, dans le champ paymentReference et aussi dans le tableau attempts.

Le paiement est ce qui compte pour les opérations ultérieures. Remboursements, captures, annulations et extensions s'effectuent sur le paymentReference, pas sur le sessionId.

Relation visuelle

Session (sessionId: "SHOP01-EXT-1719500000")
  |
  |-- Le client finalise le paiement (status: "authorised")  <-- C'EST LE PAIEMENT
  |
  État de la session : "completed"
  paymentReference: "KVGQSN3K2SKFNVNS"  <-- référence du paiement réel

En résumé

Règle pratique : utilisez sessionId pour consulter l'état et obtenir le paymentReference. Utilisez paymentReference pour modifier le paiement (refund, capture, cancel, extend).

---

Flux complet d'un paiement en ligne

Avant d'aborder les endpoints, il est important de comprendre le flux complet. Un paiement en ligne implique trois participants et trois redirections :

Votre système              Avirato Payments             Client
    |                          |                           |
    |  1. POST /payment/session                            |
    |  (avec urlOk et urlKo)   |                           |
    |------------------------->|                           |
    |                          |                           |
    |  2. Reçoit paymentUrl    |                           |
    |<-------------------------|                           |
    |                          |                           |
    |  3. Redirige le client vers paymentUrl               |
    |------------------------->+---------------------------->
    |                          |                           |
    |                     4. Le client voit la page        |
    |                     de paiement et paie              |
    |                          |<--------------------------+
    |                          |                           |
    |                     5. Avirato Payments redirige     |
    |                     vers urlOk (succès) ou urlKo (échec)|
    |                          +--------------------------->
    |                          |                           |
    |  6. Le client arrive sur votre urlOk ou urlKo        |
    |<-------------------------+---------------------------+
    |                          |                           |
    |  7. Votre système consulte                           |
    |  GET /payment/session/{id}                           |
    |------------------------->|                           |
    |<-------------------------|                           |

Étape par étape

1. Votre système crée la session en appelant POST /payment/session avec le montant, la devise et deux URLs de retour : urlOk et urlKo
2. Vous recevez un sessionId et une paymentUrl. La paymentUrl est un lien vers la page de paiement sécurisée d'Avirato Payments
3. Redirigez le client vers la paymentUrl. Vous pouvez faire une redirection HTTP 302 ou ouvrir un nouvel onglet, selon votre cas d'usage
4. Le client voit la page de paiement. Il y saisit sa carte, complète la 3D Secure si nécessaire et confirme le paiement. Votre système n'intervient pas à cette étape
5. Avirato Payments redirige automatiquement le client vers l'une des deux URLs que vous avez fournies :
6. urlOk si le paiement a réussi
7. urlKo si le paiement a échoué, a été annulé par le client ou a expiré
8. Le client arrive sur votre page. Sur urlOk, vous pouvez afficher une confirmation. Sur urlKo, vous pouvez informer du problème et, si pertinent, créer une nouvelle session de paiement pour proposer une nouvelle tentative
9. Votre système confirme le paiement avec les outils fournis : les données chiffrées reçues dans le paramètre data de la urlOk (déchiffrables avec votre client secret), le webhook que vous recevrez automatiquement quelques secondes plus tard, et optionnellement la consultation GET /payment/session/{id} pour vérification supplémentaire

Environnement Test : le flux est identique. La seule différence à l'étape 4 est que la page de paiement est un formulaire simulé (non connecté à un processeur réel). Le client saisit des cartes fictives et le résultat est déterminé selon le nom du titulaire (voir Cartes de test).

L'importance de urlOk et urlKo

Ces deux URLs sont le pont de retour entre notre page de paiement et votre système. Elles sont obligatoires et déterminent l'expérience du client après le paiement :

• urlOk : où le client arrive lorsque le paiement réussit. Ce doit être une page de votre système affichant une confirmation (ex. : « Merci, votre paiement est finalisé »). L'URL recevra un paramètre data avec des informations chiffrées sur le paiement (déchiffrables avec votre client secret)
• urlKo : où le client arrive en cas d'échec (carte refusée, délai dépassé, annulation). Ce doit être une page qui informe du problème. Pour proposer une nouvelle tentative, créez une nouvelle session de paiement depuis votre backend et redirigez le client vers la nouvelle paymentUrl

Recommandation pratique : utilisez le champ customReference lors de la création de la session pour inclure votre référence interne (ex. : numéro de commande, ID d'opération). Cette valeur est incluse dans les données chiffrées de la redirection et dans les webhooks, ce qui vous permet d'associer automatiquement le résultat à l'opération d'origine dans votre système.

Ne vous fiez pas uniquement à l'URL de retour : vérifiez l'état avec GET /payment/session/{sessionId} et surtout avec les webhooks. En Live, l'état définitif d'un paiement peut évoluer après la redirection ou une consultation antérieure (par exemple, un chargeback notifié par le processeur). Traitez les webhooks comme référence métier pour les changements tardifs et consultez à nouveau l'API si vous avez besoin de l'état persisté (voir Webhooks).

---

Créer une session de paiement

Crée une session de paiement et obtient une URL où rediriger le client pour finaliser le paiement.

Live: POST https://aviratopayments.com/external/v1/payment/session
Test: POST https://aviratopayments.com/external/v1/test/payment/session

Paramètres du body

Exemple de requête (Live)

curl -X POST https://aviratopayments.com/external/v1/payment/session \
  -H "X-API-KEY: votre_cle_api_live" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-12345-payment" \
  -d '{
    "webcode": "SHOP01",
    "amount": {
      "value": 15000,
      "currency": "EUR"
    },
    "urlOk": "https://tu-sistema.com/pago-ok",
    "urlKo": "https://tu-sistema.com/pago-error",
    "countryCode": "ES",
    "shopperLocale": "es-ES",
    "description": "Pedido #12345 - Servicio premium",
    "customReference": "ORD-2026-12345",
    "isPreAuth": false
  }'

Exemple de requête (Test)

curl -X POST https://aviratopayments.com/external/v1/test/payment/session \
  -H "X-API-KEY: votre_cle_api_test" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: test-order-12345-payment" \
  -d '{
    "webcode": "SHOP01",
    "amount": {
      "value": 15000,
      "currency": "EUR"
    },
    "urlOk": "https://tu-sistema.com/pago-ok",
    "urlKo": "https://tu-sistema.com/pago-error",
    "description": "Pedido #12345 - Servicio premium",
    "customReference": "ORD-2026-12345"
  }'

Réponse réussie (201)

{
  "success": true,
  "data": {
    "sessionId": "SHOP01-EXT-17195000001234",
    "paymentUrl": "https://aviratopayments.com/pay-external/eyJhbGciOi...",
    "status": "pending",
    "amount": {
      "value": 15000,
      "currency": "EUR"
    },
    "description": "Pedido #12345 - Servicio premium",
    "customReference": "ORD-2026-12345",
    "isPreAuth": false,
    "createdAt": "2026-06-28 10:30:00"
  }
}

Format de sessionId : en Live le format est {webcode}-EXT-{timestamp}. En Test le format est {webcode}-EXTT-{timestamp}. Cela permet d'identifier d'un coup d'œil l'environnement d'origine d'une session.

paymentUrl en Test : l'URL pointe vers une page de paiement simulée (non connectée à la passerelle réelle). Le formulaire accepte des cartes fictives et le résultat est déterminé par le nom du titulaire. Voir Cartes de test.

Que faire avec la réponse

1. Enregistrez le sessionId dans votre système, associé à l'opération (commande, service, etc.). Vous en aurez besoin pour consulter l'état et obtenir le paymentReference une fois le paiement finalisé
2. Redirigez immédiatement le client vers paymentUrl. Il y verra la page de paiement sécurisée avec les moyens de paiement disponibles
3. Préparez vos pages de retour (urlOk et urlKo). Le client arrivera sur l'une d'elles après le paiement

Délai pour payer

Une fois que le client ouvre la paymentUrl, il dispose de 5 minutes (300 secondes) pour finaliser le paiement. Passé ce délai, la page de paiement expire automatiquement et le client est redirigé vers urlKo.

La session elle-même n'a pas d'expiration fixe côté serveur : ce qui expire, c'est la page de paiement dans le navigateur du client. Si le client n'ouvre pas la paymentUrl, la session reste en état pending indéfiniment.

La page de paiement affiche un compte à rebours visible pour le client ; vous n'avez pas besoin de l'informer de votre côté.

Cycle de vie de la session

La session (pas le paiement) passe par ces états :

pending --> (le client finalise le paiement) --> completed  --> Le paiement existe, utilisez paymentReference
        --> (le client annule)                  --> cancelled
        --> (erreur de paiement)                --> failed
        --> (délai expiré)                      --> expired

Important : une session completed ne changera plus d'état. À partir de ce moment, ce qui compte, c'est le paiement (paymentReference), que vous pouvez rembourser, capturer, etc.

Si le paiement échoue

Si le paiement échoue (carte refusée, 3DS annulé, timeout), le client est redirigé vers votre urlKo. Pour proposer une nouvelle tentative, créez une nouvelle session et redirigez le client vers la nouvelle paymentUrl.

---

Redirection post-paiement : ce qui se passe à la fin

Une fois que le client a finalisé le formulaire de paiement (ou l'a abandonné / a échoué), Avirato Payments le redirige automatiquement vers l'URL correspondante :

• Paiement réussi -> le client est redirigé vers votre urlOk
• Paiement échoué, annulé ou expiré -> le client est redirigé vers votre urlKo

La redirection est automatique : le client voit brièvement un message « Redirection… » et arrive sur votre page sans avoir à cliquer.

Le paramètre data dans urlOk

Lorsque le client arrive sur votre urlOk, l'URL inclut un paramètre data avec un JWT contenant des informations chiffrées sur le paiement :

https://tu-sistema.com/pago-ok?data=eyJhbGciOiJIUzI1NiIs...

Pour lire ces informations :

1. Extrayez le paramètre data de l'URL
2. Décodez le JWT en utilisant votre client secret comme clé (voir Authentification - Client Secret)
3. Le payload déchiffré contient les données du paiement : référence, montant, état, etc.

urlKo n'inclut pas le paramètre data, car il n'y a pas de paiement réussi à signaler. Sur urlKo, affichez un message adapté au client.

Environnement Test : le paramètre data dans urlOk fonctionne exactement comme en Live. Il est chiffré avec le client secret de l'environnement Test, et vous le déchiffrez avec ce même secret. Le contenu a la même structure.

Validation des données de redirection

Lorsque vous recevez le client sur urlOk avec le paramètre data, validez les informations chiffrées par rapport aux données en clair :

1. Décodez le JWT avec votre client secret
2. Comparez les données du payload (montant, référence, état) avec ce que vous attendez selon votre logique métier
3. Si les données ne correspondent pas, traitez l'opération comme suspecte

Cela protège contre les manipulations : un utilisateur pourrait modifier l'URL manuellement, mais ne peut pas falsifier le JWT sans votre client secret.

Si le client ferme le navigateur

Si le client finalise le paiement mais ferme le navigateur avant la redirection, le paiement est tout de même finalisé.

Dans ce cas, le client n'arrive jamais sur votre urlOk. Pour couvrir ce scénario :

1. Vous recevrez un webhook quelques secondes après la finalisation du paiement (voir Webhooks)
2. En alternative, vous pouvez faire un polling périodique avec GET /payment/session/{sessionId} pour détecter les sessions passées à completed sans retour du client

Recommandation : ne dépendez pas exclusivement de la redirection vers urlOk pour confirmer les paiements. Utilisez les webhooks comme source principale de confirmation et la redirection comme amélioration de l'expérience utilisateur.

---

Cartes de test (environnement Test)

En environnement Test, la page de paiement est un formulaire simulé. Elle n'est connectée à aucun processeur réel. Le résultat du paiement est déterminé par le nom du titulaire de la carte (holderName) :

Paiement réussi

Utilisez tout nom qui n'est pas l'une des valeurs spéciales du tableau suivant. Exemple : Jean Dupont, Test User, Marie Martin.

Simuler des échecs

Données de la carte

Le formulaire simulé valide le format de la carte de manière réaliste :

• Numéro : 13 à 19 chiffres et validation Luhn. Exemple : 4111 1111 1111 1111 (Visa)
• Mois d'expiration : format MM (01-12), ne peut pas être expiré
• Année d'expiration : format YY (2 chiffres), ne peut pas être expirée
• CVC : 3 chiffres (Visa/Mastercard) ou 4 chiffres (Amex)
• Nom du titulaire : minimum 3 caractères

Astuce : pour tester rapidement un flux réussi, utilisez 4111 1111 1111 1111, expiration 12/30, CVC 737, nom Test User.

---

Préautorisations

Si vous devez réserver un montant sans le capturer immédiatement (ex. : dépôt de garantie), utilisez isPreAuth: true.

Avec une préautorisation, vous pouvez ensuite :

• Capturer le montant total ou partiel : POST /payment/capture
• Annuler la préautorisation : POST /payment/cancel
• Prolonger le délai avant expiration : POST /payment/extend

Voir Modifications pour plus de détails.

---

Devises acceptées

Actuellement, l'API externe accepte les devises suivantes :

Si vous envoyez un code devise non pris en charge, vous recevrez une erreur 400 Bad Request.

---

Erreurs courantes