Configuration
La fonction setup crée et initialise les modes de paiement Paysafe.js à l’intérieur des conteneurs d’éléments HTML sélectionnés (généralement des élémentsdiv) sur votre page de paiement. Cette fonction a les paramètres suivants :
- La version encodée en Base64 de la clé API générant des jetons à usage unique utilisée pour l’authentification avec l’API REST Coffre-fort client. Notez que cette clé ne peut être utilisée que pour générer des jetons à usage unique à utiliser avec l’API Paiements par carte et qu’elle ne dispose d’aucun autre droit d’accès à l’API (notamment pour encaisser des paiements). Par conséquent, cette clé peut être exposée publiquement dans le navigateur de l’utilisateur.
- Un objet options contenant l’environnement à utiliser (Test ou Production), les données relatives aux champs que vous souhaitez créer (y compris les sélecteurs CSS pour les éléments du conteneur sur votre page de paiement) et le style des champs hébergés.
- Un rappel pour notifier votre code de toute erreur et recevoir l’instance Paysafe.js.
La signature de la fonction est la suivante :
paysafe.fields.setup(apikey,options,callback);
L’objet options contient trois sections principales : environment, fields et styles, qui sont décrits ci-dessous.
Environnement
La chaîne environment est utilisée pour sélectionner l’environnement à utiliser pour la tokenisation. Les environnements acceptés sont LIVE (l’environnement de production Paysafe) et TEST (l’environnement de test marchand Paysafe ou le bac à sable).
N’utilisez pas de vrais numéros de cartes ou d’autres détails d’instruments de paiement dans l’environnement de test du marchand. Il n’est pas conforme aux normes de sécurité des données de l’industrie des cartes de paiement (PCI-DSS) et ne protège pas les informations relatives aux titulaires de cartes et aux bénéficiaires. Tout téléchargement de données réelles de titulaires de cartes est strictement interdit, comme décrit dans les conditions d’utilisation..
Test
paysafe.fields.setup("my Base64 encoded single-use-token API key", {
environment: "TEST",
fields: {...}
}, function (instance, error) {...});
Production
paysafe.fields.setup("my Base64 encoded single-use-token API key", {
environment: "LIVE",
fields: {...}
}, function (instance, error) {...});
Si vous omettez l’objet environment – en passant une valeur vide ou nulle pour ce paramètre – c’est l’environnement Live qui est utilisé.
Champs
L’objet fields indique les champs hébergés à créer. Les options suivantes sont disponibles pour chaque champ :
- selector – le sélecteur CSS à utiliser pour localiser le conteneur de ce champ sur votre page de paiement.
- placeholder – le texte de remplacement à insérer dans ce champ pour indiquer au client ce qu’il doit insérer.
- separator – utilisé entre les groupes de chiffres dans le champ du numéro de carte.
- optional – indique si le champ est facultatif.
- masked – indique si le champ CVV doit être masqué.
- accessibilityLabel – indique un titre de champ qui sera lu par les lecteurs d’écran.
- iframeTitle – indique un titre d’iframe qui sera lu par les lecteurs d’écran.
- accessibilityErrorMessage – indique un message d’erreur qui sera lu par les lecteurs d’écran en cas d’erreur de validation.
Vous pouvez inclure un ou deux champs de date :
| Option | Champs |
|---|---|
| Données de la carte avec un seul champ de date |
expiryDate utilise le format mm/aa |
| Données de la carte avec plusieurs champs de date |
|
Améliorer l’accessibilité grâce aux options
Les paramètres facultatifs accessibilityLabel, iframeTitle et accessibilityErrorMessage sont exposés afin d’accroître la flexibilité de l’accessibilité. Ces paramètres affectent la manière dont les outils de lecture d’écran présenteront les entrées.
<html>
...
<body>
<div id="cardNumber"></div>
<div id="cvv"></div>
<div id="expiryDate"></div>
<script>
paysafe.fields.setup("my API key", {
fields: {
cardNumber: {
selector: "#cardNumber",
accessibilityLabel: "Card number",
placeholder: "00000000000000",
iframeTitle: "Credit card details container",
accessibilityErrorMessage: "Invalid card number"
},
cvv: {
selector: "#cvv"
},
expiryDate: {
selector: "#expiryDate"
}
}
}, function (instance, error) {...});
</script>
</body>
</html>
Voir la matrice de décision pour la prise en charge par les lecteurs d’écran de accessibilityLabel et placeholder :
| Propriété du champ | Résultat HTML | |||
|---|---|---|---|---|
| title | accessibilityLabel | placeholder | valeur du titre (cette valeur sera lue par le lecteur d’écran en mode présentation) | valeur arie-labelledby (cette valeur sera lue par le lecteur d’écran) |
| Cadre de saisie du numéro de carte de crédit | Numéro de la carte | *** | Cadre de saisie du numéro de carte de crédit | Numéro de la carte |
| Cadre de saisie du numéro de carte de crédit | <none> | Saisir le numéro de la carte | Cadre de saisie du numéro de carte de crédit | Saisir le numéro de la carte |
| <none> | Numéro de la carte | <none> | sécurisé (valeur par défaut) | Numéro de la carte |
| <none> | <none> | <none> | sécurisé (valeur par défaut) | Numéro de carte (il s’agit d’une valeur par défaut si aucun espace réservé ni étiquette d’accessibilité n’est spécifié) |
Voir la matrice de décision pour la prise en charge de accessibilityErrorMessage par les lecteurs d’écran :
| accessibilityErrorMessage | Événement | valeur aria-describedby (qui sera lue par le lecteur d’écran) | Attribut aria-descibedby (l’identifiant de l’élément du message d’erreur) |
|---|---|---|---|
| Invalid | on load | <empty> | null |
| Invalid | on valid | <empty> | null |
| Invalid | on invalid | <empty> (à l’exception des événements non valides dépendant du champ actuel (CVV, mois d’expiration)) | aria-describedby |
| Invalid | on focus (lorsque non valide) | Invalid | aria-describedby |
| Invalid | on focus (lorsque non valide) | Invalid | aria-describedby |
| <none> | on load | <empty> | null |
| <none> | on valid | <empty> | null |
| <none> | on invalid | <empty> | null |
| <none> | on focus (lorsque non valide) | <empty> | null |
| <none> | on focus (lorsque valide) | <empty> | null |
Styles
L’option style vous permet de préciser divers styles CSS pour vos champs en utilisant la syntaxe JavaScript. Par exemple :
<html>
...
<body>
...
<script>
paysafe.fields.setup("my Base64 encoded single-use-token API key", {
style: {
input: {
"font-family": "robotoregular,Helvetica,Arial,sans-serif",
"font-weight": "normal",
"font-size": "14px"
},
"#card-number.valid": {
"color": "green"
},
":focus": {
"color": "yellow"
}
}
}, function (instance, error) {...});
</script>
</body>
</html>
Des identifiants et des classes sont ajoutés aux champs de saisie, qui peuvent être utilisés comme sélecteurs CSS; vous pouvez également inclure des pseudo-sélecteurs, comme :focus.
Callback
Enfin, la fonction de configuration doit contenir une fonction de rappel utilisée pour gérer les éventuelles erreurs survenues au cours de l’initialisation, ainsi que tout code spécial à exécuter en cas d’initialisation réussie. La fonction de rappel a la signature suivante :
function callback(instance, error) {
if (error) {
// error handling
} else {
// instance manipulation
}
}
Un exemple montrant comment cette fonction peut être utilisée est présenté ci-dessous :
<html>
...
<body>
<script>
paysafe.fields.setup("my Base64 encoded single-use-token API key", function (instance, error) {
if (error) {
...
} else {
...
}
});
</script>
</body>
</html>
Les paramètres de la fonction de rappel sont décrits ci-dessous :
| Paramètre | Requis | Type | Description |
|---|---|---|---|
| instance | false | object | Instance Paysafe.js transmise lorsque la configuration réussit, permettant d’accéder via l’API aux événements dans les champs de paiement sensibles. |
| error | false | object | Erreur renvoyée en cas d’échec de la configuration. |
| {return} | false | any | |
| {context} | object | L’objet options transmis à la fonction de configuration. |
Objet d’erreur de rappel
Le tableau suivant décrit le contenu de l’objet « erreur » :
| Paramètre | Requis | Type | Description |
|---|---|---|---|
| code | true | string | Code d’erreur |
| displayMessage | true | string | Message d’erreur à montrer aux clients. |
| detailedMessage | true | string | Description détaillée de l’erreur (cette information ne doit pas être montrée aux clients). |
| correlationId | true | string | Identifiant d’erreur unique à fournir au service de soutien Paysafe lors de l’enquête. |
Fonction et objets de configuration
Le tableau suivant répertorie les paramètres de la fonction de configuration, les objets JavaScript utilisés par la fonction de configuration et les paramètres qu’ils contiennent.
| Paramètre | Requis | Type | Description |
|---|---|---|---|
| apiKey | true | string | La version encodée en Base64 de la clé API générant des jetons à usage unique utilisée pour l’authentification avec l’API REST Coffre-fort client. |
| options | false | object | Englobe l’environnement, les champs et le style. |
| callback | false | function | Utilisé pour gérer les éventuelles erreurs lors de l’initialisation et pour fournir tout code spécial à exécuter en cas d’initialisation réussie. |
| {return} | false | any | |
| options | |||
| environment | false | string | Environnement à utiliser pour tous les appels à la tokenisation et à la journalisation; soit :
|
| champs | false | object | Configuration des champs spécifiés. |
| style | false | object | Représentation Javascript des propriétés CSS à appliquer aux champs. |
| initializationTimeout | false | number | Durée maximale (en millisecondes; la valeur par défaut est 5000) pendant laquelle la SDK attend que les iframes soient prêtes avant de renvoyer une erreur. |
| champs | |||
| fieldName | false | string | Nom du champ à configurer :
|
| selector | true | string | Sélecteur CSS qui identifie de manière unique le conteneur vide dans lequel insérer l’iframe du champ. |
| placeholder | false | string | Paramètre fictif pour l’élément de saisie iframe. |
| accessibilityLabel | false | string | Une étiquette d’accessibilité qui sera lue dans les lecteurs d’écran, si le client en utilise (par défaut ; si aucune étiquette d’accessibilité n’est spécifiée, la valeur du paramètre fictif est utilisée. S’il n’y a ni accessibilityLabel ni paramètre fictif, la valeur par défaut est Card Number/CVV/Card expiry date/Card expiry month/Card expiry year) |
| accessibilityErrorMessage | false | string | Un message d’erreur qui sera lu par les lecteurs d’écran lorsque le champ n’est pas valide (si le client en utilise). Vide par défaut. |
| iframeTitle | false | string | Le titre qui sera attribué à l’iframe. La valeur par défaut est « secured ». |
| separator | false | string | Disponible uniquement pour le champ du numéro de carte. Si aucun séparateur n’est spécifié, la valeur par défaut est l’espace blanc (" "). Les valeurs acceptées sont : null, undefined, "", "", "-". Si la valeur du séparateur est nulle ou indéfinie, aucun séparateur n’est appliqué. Si le séparateur est « » ou « - », il est automatiquement ajouté après tous les 4 chiffres lorsqu’un numéro de carte est introduit (par exemple, « 4532-5647-1747-9616 », "4078 2050 3082 0 »). |
| optional | false | boolean | Disponible pour tous les champs uniquement en cas d’utilisation de la fonctionnalité de carte enregistrée (passage de singleUseCustomerToken et paymentTokenFrom sur la fonction de segmentation en unités), sinon disponible uniquement pour le champ CVV. Valeurs par défauts à « false ». Si la valeur est « true », le champ ne sera pas requis pour effectuer une tokenisation, mais sera validé s’il n’est pas vide. |
| mask | false | boolean | Disponible uniquement pour le champ CVV. Valeurs par défauts à « false ». Si la valeur est « true », la valeur du CVV sera masquée. |
| style | |||
| cssSelectorName | false | object | Sélecteur CSS qui identifie l’élément auquel s’appliquent les styles transmis. Liste des identifiants :
Liste des classes :
|
| cssSelectorName | |||
| cssStyleName | false | string | Nom du style CSS à appliquer et valeur correspondante. Noms de style CSS pris en charge :
|
Erreurs de configuration
Code | Message affiché | Message détaillé | Description |
|---|---|---|---|
| 9004 | Une erreur est survenue (9004); veuillez contacter notre service de soutien. | Paramètre de rappel non valide. | |
| 9012 | Une erreur s’est produite (9012); veuillez contacter notre service de soutien. | Nombre d’arguments non valides | Le nombre d’arguments fourni n’est ni 2 ni 3. |
Erreurs de rappel
Code | Message affiché | Message détaillé | Description |
|---|---|---|---|
| 9013 | Une erreur s’est produite (9013); veuillez contacter notre service de soutien. | Paramètre apiKey non valide. | Le paramètre apiKey fourni n’est pas une chaîne. |
| 9014 | Une erreur s’est produite (9014); veuillez contacter notre service de soutien. | Une erreur non gérée s’est produite. | Une erreur qui n’a pas été gérée par la SDK Paysafe.js a été déclenchée. |
| 9015 | Il y a eu une erreur (9015), veuillez contacter notre service de soutien. | Argument d’options non valide. | Le paramètre options fourni n’est pas un objet. |
| 9016 | Une erreur est survenue (9016); veuillez contacter notre service de soutien. | Options de style non valides | Les options de style fournies ne sont ni un objet ni un tableau. |
| 9017 | Une erreur est survenue (9017); veuillez contacter notre service de soutien. | Les options d’environnement ne sont ni une chaîne ni un objet. | Le paramètre environment fourni n’est ni une chaîne ni un objet. |
| 9018 | Une erreur est survenue (9018); veuillez contacter notre service de soutien. | L’environnement ne correspond à aucune des valeurs prédéfinies (possible : TEST, LIVE; actual: ${environment}). | |
| 9019 | Une erreur est survenue (9019); veuillez contacter notre service de soutien. | L’url de l’environnement doit être une chaîne non vide. | Le paramètre environmentUrl est vide ou n’est pas une chaîne. |
| 9021 | Une erreur est survenue (9021); veuillez contacter notre service de soutien. | La valeur du sélecteur CSS pour ${styleName} n’est pas un objet. | La valeur du paramètre selector n’est ni un objet ni un tableau. |
| 9022 | Une erreur est survenue (9022); veuillez contacter notre service de soutien. | La propriété CSS ${styleName}.${propertyName} doit être une chaîne ou un nombre. | Les styles fournis contiennent une propriété dont la valeur n’est ni une chaîne ni un nombre. |
| 9023 | Une erreur est survenue (9023); veuillez contacter notre service de soutien. | Aucun élément conteneur n’a été trouvé en utilisant le sélecteur ${fieldName}. | |
| 9024 | Une erreur est survenue (9024); veuillez contacter notre service de soutien. | Plus d’un élément conteneur a été trouvé en utilisant le sélecteur ${fieldName}. | |
| 9025 | Une erreur est survenue (9025); veuillez contacter notre service de soutien. | Le même conteneur a été trouvé pour ${firstField} et ${secondField} | |
| 9026 | Une erreur est survenue (9026); veuillez contacter notre service de soutien. | Mauvaise configuration du champ de la date d’expiration La date d’expiration (expiryDate) ou le mois d’expiration (expiryMonth) et l’année d’expiration (expiryYear) doivent être définis. | |
| 9028 | Une erreur s’est produite (9028); veuillez contacter notre service de soutien. | Échec de l’initialisation des iframes Paysafe.js. | Les iframes utilisés pour les champs de paiement sensibles n’ont pas été initialisés dans les 5 secondes. Cela peut se produire si le serveur qui génère le code HTML pour l’iframe n’est pas disponible. |
| 9029 | Une erreur est survenue (9029); veuillez contacter notre service de soutien. | Le paramètre fictif ${fieldName} doit être une chaîne. | |
| 9030 | Une erreur est survenue (9030); veuillez contacter notre service de soutien. | Le séparateur de numéro de carte doit être une chaîne. | |
| 9031 | Une erreur est survenue (9031); veuillez contacter notre service de soutien. | Séparateur de numéro de carte non valide. | La valeur spécifiée pour le séparateur de numéro de carte n’est pas nulle, indéfinie, "" (chaîne vide), " " (espace blanc) ou "-" (tiret). |
| 9032 | Une erreur est survenue (9032); veuillez contacter notre service de soutien. | L’étiquette d’accessibilité ${fieldName} doit être une chaîne. | Utilisé lorsque accessibilityLabel n’est pas une chaîne valide. |
| 9033 | Une erreur est survenue (9033); veuillez contacter notre service de soutien. | Le sélecteur doit être défini soit sur tous les champs, soit sur aucun. | Le sélecteur n’a été défini que pour certains champs. Par exemple, les options de configuration spécifiaient cardNumber, cvv et expiryDate, mais les sélecteurs ne sont prévus que pour cardNumber et cvv. |
| 9072 | Il y a eu une erreur (9072), veuillez contacter notre service de soutien. | ${fieldName} accessibilityErrorMessage doit être une chaîne. | Utilisé lorsque accessibilityErrorMessage n’est pas une chaîne valide. |
| 9078 | Une erreur est survenue (9078); veuillez contacter notre service de soutien. | Paramètre facultatif ${fieldName} non valide. | |
| 9079 | Une erreur est survenue (9079); veuillez contacter notre service de soutien. | ${fieldName} ne peut pas avoir de paramètre facultatif. | |
| 9082 | Une erreur est survenue (9082); veuillez contacter notre service de soutien. | initializationTimeout doit être un nombre supérieur à zéro. | |
| 9097 | Une erreur est survenue (9097); veuillez contacter notre service de soutien. | ${fieldName} iframeTitle doit être une chaîne. | Utilisé lorsque iframeTitle n’est pas une chaîne valide. |