Ce guide fournit aux e-commerçants Salesforce Commerce Cloud (SFCC) les étapes clés pour intégrer la solution Caisse express d’Affirm à l’aide de la cartouche Affirm SFRA. Cela suppose que vous avez déjà terminé l’intégration standard d’Affirm à SFCC. Pour consulter la référence de l’API Caisse express indépendante de la plateforme, consultez la documentation officielle de la Caisse express d'Affirm.

Aperçu

La Caisse express d’Affirm est une solution hébergée par Affirm qui peut être lancée à partir de n’importe quelle page hébergée par un commerçant, sans nécessiter au préalable l’adresse d’expédition du client ni le montant final de la commande. Affirm recueille l’adresse de livraison, la méthode d’expédition et les modalités de financement au cours de son processus de paiement hébergé, puis renvoie les détails complets à votre boutique en ligne pour finaliser la commande.

Remarque : la Caisse express fonctionne en parallèle avec le mode de paiement Affirm standard sur la page de paiement, mais elle ne le remplace pas. Les clients peuvent toujours utiliser le flux de paiement traditionnel d’Affirm au moment du passage à la caisse. La Caisse express offre simplement un point d’entrée supplémentaire et plus rapide.

En quoi Affirm Express Checkout diffère d’Affirm Checkout standard

Disponibilité régionale

• États-Unis uniquement — toutes les transactions doivent être en USD
• L’adresse d’expédition du client doit être une adresse valide aux États-Unis
• Si vous ne livrez pas dans certaines régions des États-Unis (p. ex., Hawaï, Alaska), gérez cela à l’aide du code d’erreur UNSUPPORTED_SHIPPING_ZONE

Comment intégrer

Conditions préalables

Avant d’activer la Caisse express, vérifiez :

1. L’intégration SFRA standard d’Affirm fonctionne — les cartouches int_affirm et int_affirm_sfra sont installées, les préférences du site sont configurées et les fonctions de paiement standard d’Affirm fonctionnent correctement.
2. Version de la cartouche — vous êtes sur la branche master (ou une version ultérieure au 02/10/2026).
3. Configuration du compte Affirm — communiquez avec votre gestionnaire de compte technique Affirm (TAM) pour activer la Caisse express sur votre compte commerçant
4. Le mode VCN est désactivé — la Caisse express n'est pas compatible avec l'intégration de numéro de carte virtuelle Affirm (VCN). La préférence de site AffirmVCNIntegration doit être définie sur off.
5. La balise de script d'en-tête Affirm est incluse — Vérifiez que votre modèle htmlHead.isml comprend le script SDK d'Affirm : . Cela fait partie de l’intégration standard et est nécessaire pour l’API JavaScript affirm.checkout() utilisée par Express Checkout.
6. Client privé SLAS configuré — Le Paiement express utilise SCAPI pour calculer les totaux d’expédition dans un contexte sans session. Cela nécessite un client privé SLAS. Consultez l’étape 2 pour les détails de configuration.

Step 1: Import Metadata

Importez les métadonnées mises à jour pour ajouter les nouvelles préférences du site et les définitions de service requises pour la Caisse express.

Téléversez metadata/affirm.zip dans votre instance à partir de Administration > Développement du site > Importation et exportation du site, puis sélectionnez-le et lancez l’importation.

Cette seule importation ajoute tout ce qui suit :

Vérifier l'importation

Après l’importation, confirmez que chaque élément de métadonnées a été créé avec succès :

1. Préférences du site — Accédez à Outils du commerçant > Préférences du site > Préférences personnalisées > AFFIRM_PAYMENT. Faites défiler jusqu'au bas de la page et vérifiez que les préférences SCAPI/SLAS s'affichent.
2. Services — Accédez à Administration > Opérations > Services. Vérifiez que affirm.slas.auth et affirm.scapi.basket apparaissent dans la liste des services avec le profil AffirmSCAPI attribué.

Si certains de ces éléments sont manquants, relancez l’importation et consultez le journal d’importation pour repérer les erreurs.

Remarque : Le schéma services.xml exige que tous les éléments apparaissent avant tout élément . Si vous modifiez services.xml manuellement, respectez cet ordre.

Étape 2 : configurer le client privé SLAS

La Caisse express utilise SCAPI (Shopper Commerce API) pour créer un panier sans session afin de calculer les frais d’expédition. Cela nécessite un client privé SLAS (Shopper Login and Activity Sequence).

Créer le client

1. Assurez-vous que votre utilisateur dispose du rôle Administrateur de l’organisation SLAS dans Account Manager
2. Accédez à l’IU Admin SLAS à https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth-admin/
3. Cliquez sur Clients > Ajouter un client
4. Sélectionnez votre instance B2C Commerce comme locataire
5. Choisissez "BFF or Web App" comme type d’application (crée un client privé avec un secret généré automatiquement)
6. Copiez immédiatement le secret — il ne s’affiche qu’une seule fois
7. Configurez :
   1. Channels/Sites: votre ID de site SFCC (p. ex., RefArch, YourSite)
   2. Portées : sfcc.shopper-baskets-orders.rw, sfcc.shopper-myaccount.baskets.rw, sfcc.shopper-context.rw

Important : La propagation des nouveaux clients SLAS peut prendre jusqu'à 15 minutes. Attendez avant de tester.

Testez le client

curl -X POST "https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{orgId}/oauth2/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -u "{clientId}:{clientSecret}" \
  -d "grant_type=client_credentials&channel_id={siteId}"

Une réponse réussie renvoie access_token, refresh_token et expires_in.

Étape 3 : Configurer les préférences du site

Dans Outils pour les commerçants > Préférences du site > Préférences personnalisées du site > AFFIRM_PAYMENT:

1. AffirmExpressCheckoutEnabled — Réglez sur true
2. AffirmSCAPIShortCode — Le code court de votre instance (p. ex., abcd1234). Se trouve dans BM sous Administration > Préférences globales > Paramètres SCAPI.
3. AffirmSCAPIOrgId — Votre ID d’organisation SCAPI (p. ex. f_ecom_xxxx_001). Se trouve dans la même page des paramètres SCAPI. Remarque : utilisez le format complet avec le préfixe f_ecom_.
4. AffirmSCAPISiteId — Votre identifiant de site SFCC (p. ex., RefArch). Doit correspondre à la valeur Channels/Sites configurée sur votre client SLAS. Laissez vide pour effectuer une détection automatique via Site.getCurrent().getID().
5. AffirmSLASClientId — L’ID client de l’étape 2
6. AffirmSLASClientSecret — Le secret de l’étape 2
7. Vérifiez que ces préférences existantes sont correctement configurées :
   1. AffirmOnline — true
   2. AffirmStaticJS — Yes (nécessaire pour que le SDK Affirm puisse se charger)
   3. AffirmPublicKey — votre clé API publique Affirm
   4. AffirmPrivateKey — votre clé API privée Affirm (utilisée pour la vérification HMAC)
   5. AffirmVCNIntegration — off (La caisse express est incompatible avec VCN)
   6. AffirmMode — sandbox pour les tests, production pour la production

Étape 4 : Activer l’exécution du hook API

Accédez à Administration > Préférences globales > Commutateurs de fonctionnalités et activez l’exécution du hook d’API. Ceci est requis pour le hook modifyPUTResponse qui calcule les totaux d’expédition lorsqu’une adresse de livraison est définie dans le panier SCAPI.

Étape 5 : Créer les ressources côté client

Le JavaScript côté client d’Express Checkout doit être compilé. Assurez-vous que vos chemins package.json font correctement référence à la cartouche SFRA de base, puis exécutez :

sgmf-scripts --compile js

Cela compile cartridge/client/default/js/expressCheckout.js en cartridge/static/default/js/expressCheckout.js.

Si vous n’utilisez pas d’outil de compilation, vous pouvez utiliser le bundle précompilé déjà inclus à cartridge/static/default/js/expressCheckout.js.

Étape 6 : téléversez les cartouches

Téléversez les cartouches int_affirm et int_affirm_sfra sur votre instance SFCC au moyen de WebDAV ou de votre IDE préféré (p. ex. VS Code avec l’extension Prophet, Eclipse avec UX Studio). Téléversez-les dans le répertoire de la version de code active à l’emplacement suivant :

https://.demandware.net/on/demandware.servlet/webdav/Sites/Cartridges//

Ajoutez-les ensuite au chemin de cartouches de votre site dans Administration > Sites > Gérer les sites> Sélectionner votre site > Paramètres. Dans le champ Cartouches, assurez-vous que int_affirm_sfra apparaît avant int_affirm:

int_affirm_sfra:int_affirm:...existing_cartridges...

Étape 7 : Vérifier le point de terminaison Expédition et totaux

L’URL du point de terminaison Expédition et totaux est automatiquement transmise à Affirm par l’intermédiaire du champ merchant_shipping_and_totals_callback_url dans l’objet checkout. Pour empêcher l’injection d’URL de rappel malveillantes lors de la création du paiement, Affirm vérifie le nom d’hôte merchant_shipping_and_totals_callback_url par rapport à une liste de modèles de noms d’hôte attendus enregistrés pour votre compte commerçant. Seul le nom d’hôte est validé; le chemin de l’URL, les paramètres de chemin et les paramètres de requête ne sont pas vérifiés. Affirm prend en charge et encourage l’utilisation de listes d’autorisations différentes selon l’environnement, p. ex. pour les environnements de test et de production.

Pour enregistrer ou mettre à jour vos modèles de nom d'hôte autorisés, contactez votre responsable technique de compte (TAM), car ces listes d'autorisations sont configurées en interne par Affirm et ne sont pas directement accessibles ou modifiables par les commerçants.

La cartouche génère automatiquement cette URL à l’aide de URLUtils.https('Affirm-ShippingTotals'), qui correspond au nom d’hôte approprié à votre environnement (test ou production). Vous pouvez vérifier l’URL générée en consultant les journaux de débogage Caisse express pour la valeurmerchant_shipping_and_totals_callback_url .

Aperçu de l’architecture

Approche SCAPI à double panier

Le principal défi du paiement express est que le rappel Expédition et totaux d’Affirm est une requête de serveur à serveur — il n’y a pas de session de navigateur. Les paniers SFCC sont liés à une session (BasketMgr.getCurrentBasket() ne renvoie rien sans session), donc nous ne pouvons pas calculer directement les frais d’expédition sur le panier de la boutique en ligne.

La solution : créer un deuxième panier via SCAPI (Salesforce Commerce API) pendant la phase de session du navigateur. Les paniers SCAPI sont accessibles au moyen d’un jeton Bearer, et non d’une session, ce qui les rend accessibles dans le rappel S2S sans session.

Identité du jeton et jetons de rafraîchissement

Les paniers SCAPI sont associés à l’identité de l’invité qui les a créés. Un autre jeton SLAS (même provenant du même client) ne peut pas accéder au panier — il renvoie "Client non valide."

Pour résoudre ce problème sans stockage côté serveur, nous chiffrons le jeton de rafraîchissement SLAS, l’ID de panier SCAPI et l’ID d’expédition dans un paramètre opaque de la chaîne de requête (scapi) sur le merchant_shipping_and_totals_callback_url. Lors du rappel S2S, la cartouche déchiffre le paramètre, échange le jeton de rafraîchissement contre un nouveau jeton d’accès avec la même identité d’invité, et l’utilise pour accéder au panier.

Le chiffrement utilise AES avec la clé privée Affirm, de sorte que les jetons ne sont exposés ni dans les URL ni dans les journaux du serveur. Le champ order_id reste un UUID bien formé tout au long du cycle de vie du paiement.

Flux de bout en bout

Phase 1: ExpressCheckout (Browser Session — GET)
├── Get SLAS token (client_credentials) → access_token + refresh_token
├── Create SCAPI basket with storefront basket items
├── Apply coupons to SCAPI basket
├── Encrypt SCAPI IDs + refresh token → append as ?scapi= query param on callback URL
├── Store SCAPI IDs + token in session (for Cancel/Confirmation cleanup)
└── Return Affirm checkout object with clean order_id (UUID only)

Phase 2: ShippingTotals (S2S, No Session — POST)
├── Decrypt ?scapi= query param → extract basketId, shipmentId, refreshToken
├── Exchange refresh token → new access token (same guest identity)
├── Call SCAPI setShippingAddress on the SCAPI basket
├── SCAPI hooks fire (two-phase design):
│   ├── afterPUT (transactional):
│   │   ├── Iterates all applicable shipping methods
│   │   ├── For each: set method → calculate → capture totals
│   │   └── Stores results on request.custom.affirmShippingTotals
│   └── modifyPUTResponse (read-only):
│       └── Attaches results to response as c_shippingOptions + c_subtotalCents
└── Return shipping_options to Affirm

Phase 3: ExpressConfirmation (Browser Session — POST)
├── Read checkout details from Affirm API (GET /api/v2/checkout/{checkout_id})
├── Apply shipping address, billing address, shipping method to storefront basket
├── Set Affirm payment instrument
├── Recalculate basket
├── Create and place SFCC order
├── Authorize with Affirm, validate totals
├── Send confirmation email
├── Cleanup: delete SCAPI basket (best-effort)
└── Redirect to Order-Confirm page

Nouveaux points de terminaison du contrôleur

La cartouche ajoute trois nouveaux points de terminaison au contrôleur Affirm :

Affirm-ExpressCheckout (OBTENEZ)

• Appelé par : Navigateur (JS côté client)
• Objectif : Créer un panier SCAPI et renvoyer l’objet Affirm Checkout
• Paramètres : pid (facultatif, pour PDP), quantity (facultatif, 1 par défaut)
• Reenvois : JSON avec checkoutObject pour l’appel affirm.checkout()
• Ce qu’elle fait :
  • Vérifie que la fonctionnalité est activée et que VCN est désactivé
  • Si pid est fourni (flux PDP) : ajoute le produit au panier de la vitrine
  • Gets SLAS token via client_credentials grant
  • Crée un panier SCAPI qui reflète les articles du panier de la vitrine
  • Applique les coupons du panier de la vitrine au panier SCAPI
  • Chiffre les identifiants SCAPI + le jeton de rafraîchissement dans le paramètre de requête merchant_shipping_and_totals_callback_url
  • Renvoie l’objet Caisse express

Affirm-ShippingTotals (POST)

• Appelé par : le système dorsal d’Affirm (serveur à serveur, sans session)
• Objectif : renvoie les options d’expédition et les totaux disponibles pour une adresse donnée
• En-têtes : X-Affirm-Signature (HMAC-SHA512), Content-Type: application/json
• Corps : {order_id, currency, shipping: { line1, city, state, zipcode, country }}
• Renvois : JSON avec un tableau shipping_options (chaque élément contenant shipping_type, shipping_label, shipping_amount, tax_amount, total)
• Ce qu’elle fait :
  • Vérifie la signature HMAC-SHA512 de l’en-tête X-Affirm-Signature
  • Déchiffre l’ID du panier SCAPI, l’ID d’expédition et le jeton de rafraîchissement à partir du paramètre de requête scapi
  • Échange le jeton de rafraîchissement contre un jeton d’accès (même identité d’invité)
  • Normalise le code de pays (USA → US)
  • Valide l’adresse d’expédition (États-Unis seulement)
  • Appelle SCAPI setShippingAddress sur le panier SCAPI
  • Le hook modifyPUTResponse calcule les options d’expédition pour toutes les méthodes applicables
  • Renvoie HTTP 200 avec les options, ou HTTP 422 avec les codes d’erreur

Remarque: Affirm envoie le code de pays au format ISO 3166-1 alpha-3 (p. ex., "USA"). La cartouche normalise automatiquement ce code au format alpha-2 (p. ex., "US") pour assurer la compatibilité avec SCAPI.

Affirm-ExpressConfirmation (POST)

• Appelé par : redirection du navigateur depuis Affirm après que l’utilisateur a terminé son paiement
• Parameter: checkout_token
• Ce qu’elle fait :
  • Lit les détails du passage en caisse à partir de l’API Affirm via GET /api/v2/checkout/{checkout_id}
  • Applique l’adresse d’expédition, l’adresse de facturation, le mode d’expédition et le courriel au panier
  • Recalcule les totaux du panier
  • Autorise la transaction avec Affirm
  • Crée et passe la commande SFCC
  • Envoie un courriel de confirmation
  • Nettoie le panier SCAPI (dans la mesure du possible)
  • Redirige vers la page Order-Confirm

Crochets d’extensibilité

La cartouche expose quatre points d’extension HookMgr facultatifs permettant à une cartouche de commerçant de personnaliser le comportement Caisse express sans créer de branche dérivée à partir de ce code. Chacun est protégé par HookMgr.hasHook — si l’un d’eux n’est pas implémenté, le comportement par défaut s’applique. Enregistrez les implémentations dans le hooks.json de votre propre cartouche.

app.affirm.express.modifyShopperContextBody

• Appelé par : scapiBasket.setShopperContext, avant le PUT de contexte client SCAPI (Phase 1, Affirm-ExpressCheckout)
• Objectif : ajouter ou remplacer des champs dans le corps du contexte de l’acheteur envoyé à SCAPI (p. ex. effectiveDateTime, assignmentQualifiers.store, couponCodes) afin que les promotions de la vitrine et les critères de groupe de clients se déclenchent à nouveau correctement dans le panier SCAPI miroir
• Paramètres : body (l’objet de requête de contexte de l’acheteur), basket (la vitrine dw.order.Basket)
• Renvois : le corps modifié

app.affirm.express.prefilterPossibleShippingMethods

• Appelé par : le afterPUT du hook SCAPI shippingAddressTotals, avant la boucle calculate pour chaque méthode (phase 2, Affirm-ShippingTotals)
• Objectif: limiter les objets dw.order.ShippingMethod pris en compte pour une adresse donnée avant que les totaux ne soient calculés pour chacun d'eux (p. ex. exclure le ramassage en magasin ou les méthodes limitées à une région). Filtrer ici plutôt que dans app.affirm.express.filterShippingMethods donne accès à moins de renseignements (montants), mais présente l'avantage de réduire la latence globale en évitant un appel SCAPI.
• Paramètres : applicableShippingMethods (dw.util.Collection sur dw.order.ShippingMethod), basket, shipment, shippingAddress (OrderAddressWO)
• Renvoie: la collection réduite, Remarque : si vous créez une nouvelle liste, renvoyez une véritable dw.util.Collection

app.affirm.express.filterShippingMethods

• Appelé par : Affirm-ShippingTotals, une fois les options d’expédition calculées
• Objectif: supprimer, réorganiser ou modifier le libellé des options d'expédition déjà calculées avant leur renvoi à Affirm
• Paramètres : shippingOptions (tableau de {shipping_type, shipping_label, shipping_amount, tax_amount, total}), shippingAddress (Object)
• Renvois : le tableau modifié

app.affirm.express.overrideErrorMessage

• Appelé par : Affirm-ShippingTotals, pour toute réponse d'erreur
• Objectif : personnaliser le message pour un code d’erreur Affirm donné
• Paramètres : errorCode (string)
• Renvois : le message à utiliser. Ce message ne sera pas nécessairement affiché au client — l’interface d’Affirm contrôle la présentation finale.

Nouveaux fichiers

Intégration de modèle

Le cartridge comprend le positionnement des boutons prêt à l’emploi sur les pages PDP et du panier. Si votre vitrine utilise les modèles SFRA standard, les boutons s’afficheront automatiquement une fois la fonctionnalité activée.

How It Works

Button template: templates/default/affirm/expressCheckoutButton.isml

Ce modèle est rendu de manière conditionnelle — il ne s’affiche que lorsque :

• AffirmExpressCheckoutEnabled est true
• AffirmOnline est true
• AffirmVCNIntegration n’est pas on

Placements préconfigurés :

Chargement du script : templates/default/common/scripts.isml charge le bundle expressCheckout.js lorsque Caisse express est activé.

Personnalisation du placement des boutons

Si votre vitrine remplace les modèles SFRA par défaut, vous devez inclure manuellement le bouton de paiement express. Ajoutez l’inclusion ISML suivante à l’endroit où vous souhaitez que le bouton apparaisse :

Sur la page PDP :

<isinclude template="affirm/expressCheckoutButton" />

Une fois ces valeurs pdict définies :

<isset name="pageType" value="product" scope="pdict"></isset> <isset name="expressPid" value="${product.id}" scope="pdict"></isset> <isset name="expressQuantity" value="${product.selectedQuantity}" scope="pdict" />

Dans le panier :

<isinclude template="affirm/expressCheckoutButton" />

Avec :

<isset name="pageType" value="cart" scope="pdict" />

Personnalisation de l’apparence du bouton

Le bouton prend en charge des attributs d’apparence facultatifs au moyen de pdict.expressButtonAttrs :

<isset name="expressButtonAttrs" value="${{
    theme: 'dark',
    shape: 'pill',
    size: 'lg',
    buttonText: 'Checkout with Affirm'
}}" scope="pdict" />

Ces éléments correspondent aux attributs data-theme, data-shape, data-size et data-button-text du conteneur du bouton, utilisés par la méthode affirm.ui.checkoutButton.render() du SDK Affirm.

Actualisation des boutons après les mises à jour AJAX

Si votre vitrine met à jour dynamiquement le contenu de la page au moyen d’AJAX (p. ex. les changements de quantité dans le panier, "Afficher plus" dans les résultats de recherche), vous devez appeler affirm.ui.refresh() après la mise à jour du DOM pour afficher de nouveau les éléments d’interface Affirm, y compris les boutons Caisse express. Il s’agit de la même exigence que pour la messagerie promotionnelle Affirm.

// In your cart.js or wherever you handle AJAX cart updates:
success: function (data) {
    // ... update cart HTML ...
    if (typeof affirm !== 'undefined') {
        affirm.ui.refresh();
    }
}

Dépannage

Problèmes courants

Fichiers journaux

Activez le journal des communications pour les services affirm.scapi.basket et affirm.slas.auth dans Administration > Opérations > Services afin d’assurer la journalisation complète des requêtes/réponses HTTP.