Documentation
Documentation
Paiement express

1Introduction

Express Checkout permet aux clients de payer directement depuis une page produit ou panier à l’aide de boutons de wallet (par exemple PayPal, Apple Pay ou Google Pay), sans passer par un formulaire de paiement séparé.

2Étapes d’intégration

L’intégration comporte cinq étapes logiques :

Étape Partie Obligatoire ? Signification pour le marchand

1

Créer une session (POST /api/v2.0/express-checkout/session/create)

Oui

Créez une session par tentative de paiement et enregistrez les identifiants retournés.

2

Afficher le widget de wallet (iframe avec sessionToken)

Oui

Affichez l’interface du wallet au client.

3

Callback d’expédition (merchantShippingCallbackUrl)

Conditionnel

Requis uniquement lorsque des articles à expédier existent et que les options d’expédition doivent être calculées dynamiquement.

4

Retour à la boutique et création de la commande (GET merchantRedirectUrl)

Oui

Après l’approbation du client, le flux revient à votre boutique. Créez la commande à cette étape. Vous pouvez éventuellement récupérer les détails de la session (GET /api/v2.0/express-checkout/session) afin de valider ou d’enrichir la commande avec l’adresse finale, l’option d’expédition et les totaux.

5

Traiter la session (POST /api/v2.0/express-checkout/session/process)

Oui

Appelez cet endpoint après le retour vers merchantRedirectUrl, puis redirigez le navigateur vers le redirectUrl retourné.

Termes de redirection :

  • merchantRedirectUrl est l’URL vers laquelle le flux renvoie le client dans votre boutique.

  • redirectUrl est retournée par /express-checkout/session/process et correspond à la prochaine URL vers laquelle votre boutique doit rediriger le client.

3Flux

Flux d’intégration Express Checkout

3.11. Créer une session Express Checkout

  • Méthode : POST

  • URL : /api/v2.0/express-checkout/session/create

  • Authentification : jeton HMAC

Pour la liste complète des champs et leur description, consultez API Client. Modèle de requête : IExpressCheckoutSession.ICreate. Modèle de réponse : ExpressCheckoutSessionCreateResponse.

{
  "currency": "CHF",
  "authorizationEnvironment": "TEST",
  "merchantRedirectUrl": "https://your-shop.com/checkout/complete?sessionUuid=550e8400-e29b-41d4-a716-446655440000",
  "merchantShippingCallbackUrl": "https://your-shop.com/api/shipping-options?sessionUuid=550e8400-e29b-41d4-a716-446655440000",
  "lineItems": [
    {
      "uniqueId": "item-1",
      "sku": "SKU-001",
      "name": "Product Name",
      "type": "PRODUCT",
      "quantity": 1,
      "amountIncludingTax": 42.00,
      "shippingRequired": true,
      "currency": "CHF",
      "taxes": []
    }
  ]
}

Dans cet exemple, sessionUuid=550e8400-e29b-41d4-a716-446655440000 est une valeur de corrélation générée par le marchand. La boutique doit associer sessionUuid au sessionId retourné.

La réponse contient :

  • sessionId — l’ID de la session créée

  • sessionToken — le jeton de sécurité nécessaire au traitement

Notes d’implémentation :

  • Requis en pratique : incluez les données qui définissent la commande (currency, lineItems, merchantRedirectUrl).

  • Requis : fournissez authorizationEnvironment (TEST ou PRODUCTION). Cet environnement sert à déterminer la disponibilité des wallets et le comportement de traitement de la session.

  • Requis sous condition : fournissez merchantShippingCallbackUrl lorsque le wallet doit demander des options d’expédition.

  • Requis pour une corrélation fiable : générez votre propre sessionUuid, ajoutez-le à merchantRedirectUrl et à merchantShippingCallbackUrl, puis stockez une association sessionUuid <→ sessionId.

  • Stockage approprié des identifiants : persistez sessionId pour le traitement ultérieur. Gardez sessionToken disponible jusqu’à la fin de l’affichage du widget (le stockage persistant est facultatif).

3.22. Afficher le widget de wallet

Intégrez l’iframe du wallet dans votre page en utilisant l’URL du widget construite avec le sessionToken. Le widget gère la sélection de l’adresse, l’affichage des options d’expédition et l’approbation du paiement.

Exemple d’intégration minimal :

<script src="https://<scope-base-path>/assets/payment/express-checkout-handler.js"></script>

<div id="express-checkout-container"></div>

<script>
  window.ExpressCheckoutHandler.load('express-checkout-container', sessionToken, {
    maxColumns: 3,
    maxRows: 2,
    onError: function (error) {
      // Hook d'erreur personnalisé facultatif.
      // error = { source, code, message }
      console.error('Erreur wallet Express Checkout', error);
      alert(error.message);
    }
  });
</script>

Notes d’implémentation :

  • Requis : affichez le widget avec le containerId et le sessionToken issus de la création de session.

  • Facultatif (maxColumns) : contrôle le nombre de boutons de wallet affichés par ligne. La plage autorisée est de 1 à 6. En cas d’omission, la valeur par défaut du widget est 2.

  • Facultatif (maxRows) : contrôle le nombre maximal de lignes affichées initialement. La plage autorisée est de 1 à 10. En cas d’omission, aucune limite de lignes n’est appliquée (toutes les lignes rendues sont affichées).

  • Facultatif (onError) : callback appelé lorsqu’une iframe de wallet publie une erreur d’intégration ou d’exécution. Reçoit un objet avec source, code et message. Lorsqu’il est présent, ce callback devient le hook actif de l’interface d’erreur. En son absence, la gestion d’erreur par défaut du widget reste active.

  • Journalisation opérationnelle : les erreurs des iframes de wallet sont signalées au backend et journalisées à des fins de diagnostic.

3.33. Traiter le paiement

Après l’approbation du wallet et le retour vers votre merchantRedirectUrl, appelez l’endpoint de traitement pour créer la transaction et autoriser le paiement.

  • Méthode : POST

  • URL : /api/v2.0/express-checkout/session/process

  • Authentification : jeton HMAC (identique à tous les appels de l’API REST)

Pour la liste complète des champs et leur description, consultez API Client. Modèle de requête : IExpressCheckoutSessionProcessRequest. Modèle de réponse : ExpressCheckoutSessionProcessResponse.

{
  "sessionId": 123456,
  "merchantReference": "EC-MR-789",
  "successUrl": "https://your-shop.com/checkout/success",
  "failureUrl": "https://your-shop.com/checkout/failure"
}

Notes d’implémentation :

  • Requis : appelez cet endpoint après l’approbation et après la redirection du client depuis le portail vers votre boutique.

  • Requis : fournissez sessionId, une merchantReference idempotente non vide, ainsi que successUrl et failureUrl.

  • Requis : redirigez le navigateur vers l’URL retournée dans la réponse.

  • Important : Express Checkout n’utilise pas le fallback de l’URL de résultat par défaut de la page de paiement. L’appel de traitement doit fournir explicitement les URL de résultat du marchand.

  • Facultatif (recommandé) : récupérez les détails de la session avant le traitement afin de valider le montant final, l’adresse et l’option d’expédition sélectionnée.

  • Recommandé : considérez les webhooks comme la source de vérité pour le statut asynchrone final (AUTHORIZED / FAILED), tandis que les redirections du navigateur pilotent la navigation du client.

La réponse contient une URL cible de redirection. Redirigez le client vers cette URL pour poursuivre le 3DS (si nécessaire) et terminer le flux.

4Facultatif : lire les détails de la session avant le traitement

Vous pouvez récupérer la session Express Checkout approuvée avant le traitement. C’est utile pour créer ou valider la commande de la boutique en fonction des sélections finales du client.

  • Méthode : GET

  • URL : /api/v2.0/express-checkout/session

  • Authentification : jeton HMAC

Pour la liste complète des champs et leur description, consultez API Client.

Utilisation typique :

  1. Résolvez votre référence interne de checkout vers le sessionId stocké

  2. Récupérez les détails de la session

  3. Construisez ou validez votre commande à partir de l’adresse, de l’option d’expédition sélectionnée et des totaux retournés

  4. Appelez /express-checkout/session/process

5Facultatif : Shipping Options Provider API

Si vos produits nécessitent une expédition, vous devez implémenter un endpoint de callback que wallee appelle pour récupérer les options d’expédition lorsque le client modifie son adresse. L’URL de cet endpoint est fournie par session via le champ merchantShippingCallbackUrl de la requête de création.

Le contrat de callback utilise les trois modèles suivants :

  • IExpressCheckoutShippingOptionRequest

    • Requis : countryCode, currency, language, expressCheckoutId, spaceId, requestId

    • Facultatif : state, street, city, postalCode

  • IExpressCheckoutShippingOptionsResponse

    • shippingOptions : liste d’entrées IExpressCheckoutShippingOption (retournez au moins une entrée en cas de succès, une liste vide en cas d’erreur). Pour la liste complète des champs et leur description, consultez IExpressCheckoutShippingOption.

    • error : null en cas de succès, ou un objet IExpressCheckoutShippingOptionsClientError en cas d’erreur métier

  • IExpressCheckoutShippingOptionsClientError

    • Champs : error (type court), message (explication lisible par un humain), timestamp (chaîne de temps facultative)

5.1Spécification de l’endpoint

  • Méthode : POST

  • URL : votre URL de callback configurée

  • Content-Type : application/json

5.2Requête

Wallee envoie les champs suivants dans IExpressCheckoutShippingOptionRequest :

Champ Type Obligatoire ? Notes

expressCheckoutId

Long

Oui

Identifiant de la session Express Checkout.

spaceId

String

Oui

Identifiant du space marchand.

requestId

String

Oui

ID de corrélation pour le traçage.

countryCode

String

Oui

Code pays (ISO-3166 alpha-2).

currency

String

Oui

Code devise (ISO-4217).

language

String

Oui

Code langue (ISO-639).

state

String

Non

Code de l’État, du canton ou de la province.

street

String

Non

Adresse de rue.

city

String

Non

Nom de la ville.

postalCode

String

Non

Code postal ou ZIP.

 
{
  "expressCheckoutId": 123456,
  "spaceId": "84",
  "requestId": "21a2f7fe-51b7-4ed5-9f88-1fb128292986",
  "countryCode": "CH",
  "currency": "CHF",
  "language": "fr",
  "state": "ZH",
  "street": "Rue Exemple 5",
  "city": "Winterthur",
  "postalCode": "8400"
}

5.3Réponse (retournée par votre boutique)

Retournez un objet JSON avec des options d’expédition ou une erreur. L’endpoint de votre boutique doit retourner IExpressCheckoutShippingOptionsResponse à wallee comme corps de réponse HTTP.

Contrat de réponse :

  • Chemin de succès : retournez une ou plusieurs shippingOptions et définissez error à null.

  • Chemin d’erreur : retournez un tableau shippingOptions vide et fournissez un objet error renseigné.

  • N’utilisez pas de codes HTTP non-200 pour les erreurs métier : conservez HTTP 200 et communiquez les erreurs dans le corps.

  • Utilisez les codes HTTP non-200 uniquement pour les défaillances techniques : par exemple un format de payload invalide, un échec d’authentification ou une panne côté serveur.

5.3.1Champs des options d’expédition

Champ Type Obligatoire ? Notes

id

String

Oui

Identifiant unique de l’option d’expédition.

label

String

Oui

Nom affiché au client.

description

String

Non

Texte descriptif facultatif.

amountIncludingTax

Decimal

Oui

Montant total de l’expédition taxes comprises.

taxes

Array

Non

Lignes de taxes avec title et rate (pourcentage). Peut être vide.

currency

String

Oui

Code devise ISO-4217. Doit correspondre à la devise de la session.

5.3.2Champs d’erreur

Champ Type Obligatoire ? Notes

error

String

Oui

Identifiant court du type d’erreur (par exemple INVALID_ADDRESS, SERVICE_UNAVAILABLE).

message

String

Oui

Description de l’erreur lisible par un humain.

timestamp

String

Non

Horodatage de l’apparition de l’erreur.

5.3.3Succès 

{
  "shippingOptions": [
    {
      "id": "standard",
      "label": "Livraison standard",
      "description": "Livraison en 3 à 5 jours ouvrables",
      "amountIncludingTax": 9.99,
      "taxes": [
        { "title": "TVA", "rate": 7.70 }
      ],
      "currency": "CHF"
    },
    {
      "id": "express",
      "label": "Livraison express",
      "description": "Livraison en 1 à 2 jours ouvrables",
      "amountIncludingTax": 19.99,
      "taxes": [
        { "title": "TVA", "rate": 7.70 }
      ],
      "currency": "CHF"
    }
  ],
  "error": null
}

5.3.4Erreur 

{
  "shippingOptions": [],
  "error": {
    "error": "INVALID_ADDRESS",
    "message": "L'adresse de livraison fournie n'est pas valide pour le calcul des frais d'expédition",
    "timestamp": "2025-10-10T12:00:00Z"
  }
}

6Wallets pris en charge

Wallet Statut Notes

Bogus Pay

Disponible

Uniquement pour les tests et le développement.

PayPal

Disponible

Prêt pour la production dans Express Checkout.

Apple Pay

Planifié

—

Google Pay

Planifié

—

7Tester avec Bogus Pay

Pour les tests, utilisez Bogus Pay.

Il fournit des adresses fictives, des cartes de test et des flux d’approbation (y compris la simulation 3DS).

Staging 2.207.2