Choisir la version de l’API Payload : v1 ou v2

Payload, le prestataire de paiement derrière REDA Pay, propose deux versions de son interface de programmation. REDA Pay peut utiliser l’une ou l’autre, et le choix se fait par Pay Profile avec un seul champ, Version de l'API Payload (Payload API Version). Un profil laissé vide, ou réglé sur v1, fonctionne exactement comme REDA Pay l’a toujours fait. Un profil réglé sur v2 utilise l’interface actuelle de Payload et, avec elle, les nouveaux écrans de paiement : les informations de carte et de banque saisies dans un formulaire sécurisé que Payload affiche dans l’écran, des écrans qui fonctionnent sur tous les types de site Experience Cloud, des messages de webhook signés, et vos propres couleurs et polices.

Cet article explique ce qui diffère, comment décider, comment basculer un profil et comment revenir en arrière.

Avant de commencer

Le Pay Profile existe avec sa clé API enregistrée — consultez Créer un Pay Profile et enregistrer votre clé API Payload.
Vous avez REDA Pay - Admin User. Le champ n’est modifié que par les administrateurs.
Si le champ n’est pas sur votre page Pay Profile, votre organisation a été mise à niveau depuis une version antérieure et le champ doit d’abord être placé sur la présentation — consultez Mettre à niveau REDA Pay.

Ce qui diffère entre v1 et v2

Sujet	v1 (vide)	v2
Écran de paiement dans Salesforce	L’écran classique : le formulaire de carte ou de compte fait partie de la page	L’écran v2 s’ouvre depuis le même bouton : vignettes de moyens, panneau du montant, et un formulaire sécurisé servi par Payload pour le numéro de carte, le code de sécurité et le numéro de compte. Des messages de progression montrent ce qui se passe
Où vont les numéros de carte et de banque	Saisis sur l’écran REDA Pay, envoyés à Payload, jamais stockés	Saisis dans le propre formulaire de Payload dans l’écran ; ils ne transitent jamais par Salesforce
Pages du portail client et du site public	Les composants classiques (NewPayOrder, NewPayOrderRequest …), qui ne fonctionnent que sur les sites Aura	Les composants v2 (REDA Pay - New Pay Order (v2) …), qui fonctionnent sur les sites Aura et LWR. Un profil v2 a besoin des composants v2 sur ses pages : les composants classiques refusent un profil v2 avec « Cette page nécessite un profil de paiement sur l'API v2 de Payload. »
Webhooks	Dix webhooks à `…/payload/…` ; Configurer les webhooks supprime tous les webhooks de la clé API	Onze webhooks à `…/payloadv2/…`, signés en option avec un secret ; Configurer les webhooks ne supprime que les webhooks de ce profil
Apparence	Logo, en-tête et pied de page du compte de traitement ; couleurs fixes	Idem, plus les couleurs du thème hôte par défaut et vos propres couleurs et police via Apparence du paiement ou les paramètres du composant
Dépôts de garantie (EMD)	Disponibles	Refusés : un ordre EMD ne peut pas être créé sur un profil v2
Enregistrements, clients, moyens enregistrés, ordres, transactions	Identiques. Les deux versions lisent et écrivent les mêmes enregistrements et identifiants Payload, donc un client créé en v1 paie en v2 avec la carte enregistrée, et inversement
Boutons, planifications, rapports, API Apex	Identiques

Comment décider

Une nouvelle installation : choisissez v2. C’est l’interface actuelle de Payload, et le formulaire sécurisé signifie que votre organisation ne manipule jamais un numéro de carte.
Une organisation qui utilise déjà REDA Pay sur des sites Aura et dans Salesforce : rester en v1 ne change rien. Passez en v2 quand vous voulez le formulaire sécurisé, un site LWR ou des webhooks signés — et préparez d’abord les pages du portail et du site public, car un profil v2 y a besoin des composants v2.
Un portail client ou un site public LWR : v2 est obligatoire ; les composants classiques ne fonctionnent pas sur les pages LWR.
Dépôts de garantie (EMD) : gardez ce profil en v1.

Vous pouvez avoir un profil en v1 et un autre en v2 dans la même organisation. Les écrans lisent la version sur le profil de l’ordre payé.

Basculer un profil en v2

Faites-le d’abord dans une sandbox, puis en production. La bascule elle-même prend une minute ; les pages et les accès dont elle a besoin sont la partie la plus longue, alors lisez toute la liste avant de commencer.

Pages du portail et du site public. Si ce profil sert un portail client ou un site public de liens de paiement, placez les composants v2 sur ces pages et renseignez exactement les noms de page, comme décrit dans Permettre aux clients de payer dans votre portail et Configurer le site public des liens de paiement. Jusqu’à la bascule, les nouvelles pages côtoient les anciennes ; les pages classiques continuent de fonctionner pour la v1.
Accès pour vos propres profils. Si vos utilisateurs, les utilisateurs du portail ou l’utilisateur invité du site public ont vos propres profils ou des ensembles d’autorisations clonés au lieu des ensembles REDA Pay du package, accordez les deux classes et la page listées dans Mettre à niveau REDA Pay. Les organisations qui attribuent les ensembles du package les ont déjà.
Invité du site de webhooks. Sur le site qui reçoit les messages de Payload, activez la classe Apex rpay.PayloadCallbackV2 pour l’utilisateur invité, à côté de rpay.PayloadCallback — Configurer les webhooks, Partie 2.
Définir la version. Ouvrez l’application REDA Pay → Pay Profiles → le profil → Modifier. Dans Version de l'API Payload, choisissez v2. Enregistrez.
Secret de signature (recommandé). Cliquez sur Mettre à jour le secret du webhook (Update Webhook Secret), saisissez un secret de 64 caractères au plus que vous conservez en lieu sûr, cliquez sur Mettre à jour le secret. Le message « Le secret de signature du webhook a été mis à jour. Lancez Configurer les webhooks pour l’appliquer. » le confirme.
Enregistrer à nouveau les webhooks. Cliquez sur Configurer les webhooks (Setup Webhooks) et confirmez. L’onglet Configuration des webhooks du profil liste maintenant onze lignes dont les adresses contiennent /payloadv2/.
Republiez chaque site Experience Cloud qui héberge les écrans v2, si vous les avez placés à l’étape 1 sans publier.
Testez avec chaque type de payeur : un utilisateur interne depuis un Lead, un utilisateur du portail et un invité ouvrant un lien de paiement. Les informations de carte et de banque sont saisies dans le formulaire sécurisé ; les messages de progression apparaissent ; la Pay Transaction est créée ; quelques minutes plus tard son statut est mis à jour par les webhooks.

L’enregistrement Pay Profile avec Version de l'API Payload réglée sur v2, et l’action Mettre à jour le secret du webhook à côté de Mettre à jour le jeton d'API, Synchroniser les comptes de traitement et Configurer les webhooks

Le champ de version et les trois actions avec lesquelles il fonctionne. Tout le reste du profil est inchangé.

Revenir en v1

Réglez Version de l'API Payload sur v1 (ou videz le champ), enregistrez, et lancez à nouveau Configurer les webhooks pour que Payload envoie à l’adresse v1. Aucune donnée ne change. Les pages qui contiennent les composants v2 cessent de fonctionner pour ce profil (« Cette page nécessite un profil de paiement sur l'API v2 de Payload. »), alors repointez d’abord la navigation de votre portail vers les pages classiques. Comme Configurer les webhooks sur un profil v1 supprime tous les webhooks de la clé API, réenregistrez ensuite tout autre profil ou système qui partage cette clé.

Ce que la bascule ne fait pas

Elle ne déplace, ne copie ni ne réenregistre les clients, les moyens enregistrés, les ordres ou les transactions. Ils sont partagés.
Elle ne modifie pas vos comptes de traitement, frais, image de marque, contrôles ou paramètres de liens.
Elle ne change pas qui peut payer : les ensembles d’autorisations sont les mêmes.
Elle ne remplace pas les composants classiques sur vos pages. C’est vous qui placez les v2.

Erreurs à éviter

Erreur	Ce qui se passe	Correction
Passer en v2 avant que les pages du portail ou du site public ne contiennent les composants v2	Les clients et les payeurs de liens voient « Cette page nécessite un profil de paiement sur l'API v2 de Payload. »	Placez d’abord les composants v2, ou revenez en v1 jusqu’à ce qu’ils soient prêts
Basculer sans lancer Configurer les webhooks	Payload continue d’envoyer à l’adresse v1 ; les statuts cessent de se mettre à jour	Lancez Configurer les webhooks après chaque changement de version
Invité du site de webhooks sans `rpay.PayloadCallbackV2`	Les messages v2 de Payload sont refusés ; les statuts ne se mettent jamais à jour	Activez la classe sur le profil invité
Saisir le secret de signature dans le champ Secret de signature du webhook avec Modifier	La valeur est stockée en clair et ne correspond pas à ce avec quoi Payload signe	Utilisez l’action Mettre à jour le secret du webhook, puis Configurer les webhooks
Attendre des dépôts de garantie en v2	L’ordre EMD est refusé	Gardez un profil EMD en v1

Questions fréquentes

Non. La même clé sert aux deux versions. REDA Pay ajoute la version à chaque requête.

Elle appuie sur le même bouton. L’écran qui s’ouvre est celui de la v2 : des vignettes pour les moyens enregistrés, le formulaire sécurisé pour une nouvelle carte ou un nouveau compte, et des messages de progression pendant le paiement.

Oui. Créez un second Pay Profile avec la même clé API, réglez-le sur v2 et limitez-lui une page de test avec Limit Profile Selection. Un seul profil à la fois reçoit les webhooks de Payload pour une clé partagée, alors gardez les webhooks du profil de test pour le test seulement.

Pour aller plus loin

Configurer les webhooks — l’adresse v2, le secret de signature et la classe de l’invité.
Permettre aux clients de payer dans votre portail — les pages v2 sur un site Aura ou LWR.
Encaisser un paiement — l’écran v2 pas à pas.