Dalenys Hosted Fields - Enregistrement carte bancaire

Implémentation du formulaire enregistrement

Principe :

Vous affichez une page d’enregistrement carte comprenant un formulaire de paiement, sauf que les champs de saisie de carte bancaire sont remplacés par des conteneurs de champs hébergés. Ces conteneurs peuvent être n’importe quelle balise HTML : DIV, P, SPAN… la bibliothèque JavaScript des champs hébergés injecte des iframes hébergés par Dalenys dans ces conteneurs, chacun contenant les champs de saisie de données de la carte.

Lors du processus de soumission, vous devrez appeler la méthode Javascript createToken de la bibliothèque de champs hébergés qui déclenchera la création de jetons des données du titulaire de la carte (numéro de carte, date d’expiration et cryptogramme). Si la création de jetons aboutit, vous devez ajouter le jeton reçu à votre demande de soumission de formulaire dans un champ <input type= « hidden» />.

Création du formulaire :

Vous devez posséder un certificat TLS (voir en fin de documentation) pour héberger une page de paiement HTTPS valide, sinon le navigateur de l’utilisateur affichera des alertes de sécurité et le bloquera probablement.
La bibliothèque de champs hébergés doit toujours être appelée en ligne. L’utilisation d’une version téléchargée hébergée sur votre propre serveur peut entraîner de graves dysfonctionnements, notamment dans le cas d’une mise à jour de l’API Dalenys.

1- Inclure les librairies javascript suivantes entre les balises <head>…</head>

   • <script type="text/javascript" src="https://js.sandbox.be2bill.com/hostedfields/v1/hosted-fields.min.js"/>  
   • <script type="text/javascript" src=" https://js.sandbox.be2bill.com/branddetector/v1/brand-selector-widget.min.js "/>

2- Déclarer l’encodage UTF-8 dans les métadonnées <meta charset="UTF-8">

3- Créer un formulaire <form></form> avec trois conteneurs identifiés par un attribut id. Le choix de l’identifiant utilisé est libre mais doit être unique et seront utilisés dans le code javascript présenté dans les points suivants.

A noter que l’exemple ci-dessous est minimaliste et selon le besoin peut être complété :

<form method="post" action="URL">
   <span id="card-container"></span>
   <span id="expiry-container"></span>
   <span id="cvv-container"></span>
   <span id="brand-container"></span>
   <input type="submit" value="Pay">
</form>

L’url à renseigner dans l’attribut action est la suivante :
URL_API/psp/submitcardregistration

4- Configuration des champs hébergés

L’étape suivante consiste à désigner les conteneurs dans lesquels créer les champs hébergés sécurisés, à l’aide de JavaScript. Pour ce faire, initialisez la bibliothèque de champs hébergés avec votre clé API publique et la configuration souhaitée : S-money doit fournir les clés nécessaires au hosted fields.

<script type="text/javascript">    
   // Initialize the hosted-fields library    
   var hfields = be2bill.hostedFields({        
       // Use your Public API Key        
       key: {            
           id : ‘XXX’            
           value : ‘XXX’        
       },        
       // Link and configure each hosted input field by providing the corresponding container ID        
       fields: {            
           'card': {                
               id: 'card-container',  
               //enable the card field format auto spacing        
               enableAutospacing: true                
           },            
           'expiry': {                
               id: 'expiry-container'            
           },            
           'cryptogram': {                
               id: 'cvv-container'            
           }      
           'brand': {                
               id: 'brand-container'            
           }
       },        
       // Choose the language for error messages        
       location: "fr"    
   });
</script>

Les identifiants utilisés dans le script pour désigner les champs sont ceux utilisés pour les identifiants des conteneurs créés dans le formulaire. Ceci permettant au script d’injecter les champs hébergés par Dalenys dans ces conteneurs.

5- Charger la bibliothèque des champs hébergés

<script type="text/javascript">    
   hfields.load();
</script>

À ce stade, votre navigateur Web peut afficher les champs de saisie de la carte bancaire dans leurs conteneurs.

6- Générer le jeton

A la soumission du formulaire, vous devez appeler la méthode CREATETOKEN() sur l’événement ONSUBMIT() pour déclencher le processus de création de jetons.

Cette méthode attend un paramètre de rappel qui sera déclenché une fois la demande de tokénisation terminée.

Votre rappel recevra un objet de résultat contenant ces propriétés :

  • execCode : code de résultat technique de l’appel tokenization. En cas de succès, 0000 sera envoyé
  • message : la description liée à l’execCode
  • cardType : le type de carte
  • cardCode : Les 6 premiers et les 4 derniers chiffres du numéro de la carte du titulaire
  • cardValidityDate : Date d’expiration de la carte
  • hfToken : le jeton généré

En cas de succès, vous devez ajouter le jeton reçu à la demande d’envoi de formulaire dans une balise <input type= « hidden» />

<form method="post" name="formName" action="URL_API/psp/submitcardregistration" onsubmit="return tokenizeHandler()">    
   <!-- ... -->    
   <input type="hidden" name="hftoken" id="hftoken">    
   <!-- ... -->
</form>
<script type="text/javascript">    
   function tokenizeHandler() {        
       hfields.createToken(function (result) {            
           //console.log(result); // Debug            
           if (result.execCode == '0000') {                
               // Set the token in an hidden input field to transmit it to the merchant submit page                
               document.getElementById('hftoken').value = result.hfToken;                
               // Send the form request                
               document.formName.submit();            
           }        
       });        
       // Prevents the submit of the form in case of failed tokenization request        
       return false;    
   }
</script>

7- Inclure la propriété Smoney EXTRADATA (issues du résultat de l’appel api pour enregistrer la carte bancaire) en champs hidden en plus de celui du jeton.

<input type="hidden" name="smextradata" value="@Model.ExtraData" />

Les attributs « name » des balises input hidden ne doivent pas être changés.

Enregistrement carte avec authentification 3DSecure :

Selon la carte enregistrée et son enrollement 3DSecure, une authentification 3DSecure peut être nécessaire.

Dans ce cas, en réponse à l’action du formulaire, la page HTML du formulaire 3DSecure est envoyée en contenu de la réponse accompagnée d’un http status code 200 (OK). La soumission du formulaire 3DSecure se terminera par une redirection 302 vers l’url renseignée dans le champ urlReturn de la requête initiale.

Dans le cas contraire, une réponse 302 (redirect) est directement faite et redirige le navigateur de l’utilisateur vers l’url renseignée dans le champ urlReturn de la requête initiale.

Ressources

1.CardRegistration

Property Type Mandatory Description
ThreeDSecurePreference Int O 0 = ask for a strong authentication
1 = ask for a frictionless authentication
2 = ask for no preference, the decision will be made by issuer ;
3 = ask for no authentication
availableCards String O List of cards to be displayed on the registration page.
Possible values ( to separate with ’ ;’ ) :
CB
MASTERCARD
MAESTRO
VISA
VISA_ELECTRON
AuthorizationAmount Int N Deux valeurs possibles (en centimes) :
• 0
• 100 (1€)
urlReturn String O Url of callback client requested at the end of a card registration
urlCallback String O Specify url of callback server requested at the end of adding card (the domain must be the same as the one of the callback URL provided initially)
Status Int O Status of the card registration
0 = Waiting
1 = Completed
2 = Failed
ErrorCode Int O 0 = 0XXX operation succeeded or still processing
10 = 1XXX operation rejected because of bad request configuration
11 = 2XXX operation rejected because of bad reference usage
12 = 3XXX operation rejected because of bad account configuration
13 = 4XXX operation rejected because of the bank or the supplier
14 = 5XXX operation rejected because of a system error
15 = 6XXX operation rejected because of anti-fraud engine
Extradata String / ExtraData to be included in card registration form into : <input type= « hidden» />

2.Card

Property Type Mandatory Description
Id Long / Card ID
AppCardId String O Card identifier in the third-party application
Network Long / UNKNOWN = -1,
CB = 1,
MASTERCARD = 2,
VISA = 3,
Hint String / Hide the card number. 6XXXX4 format
Name String O Card name
Country String / ISO country code of the card
ExpiryDate Date / Card expiration date

3.Holder

Property Type Mandatory Description
Name String O The holder’s full name (as described on the payment method).
mail String O The user’s email.

4.Extraparameters

Property Type Mandatory Description
ProfilName String O Value “3DSV2” to call 3D-Secure 2.0
By default, without profil, 3DS V1 will be called

5.Billing

Property Type Mandatory Description
City String O The billing city.
Country String O The country code (ISO_3166-1_alpha-2).
Address String O The billing address. Be careful not to integrate any line breaks.
PostalCode String O The billing postal code.
Billingaddressstate String N The billing address state.

6.ShipTo

Property Type Mandatory Description
City String O* The shipping city.
Mandatory if AdresseType is not EDELIVERY
Country String O* The country code (ISO_3166-1_alpha-2 format)
Mandatory if AdresseType is not EDELIVERY
Address String O* The shipping address.
Mandatory if AdresseType is not EDELIVERY
PostalCode String O* The shipping postal code.
Mandatory if AdresseType is not EDELIVERY
AddressType Int O Shipping indicator.
0 = eDelivery
1 = Verified
2 = New
3 = Billing
4 = Store Pickup
5 = Travel Pickup
6 = Other
The parameter DELIVERYEMAIL is mandatory when EDELIVERY mode is set. The other ship to address fields are optional when ‘storepickup’, travelpickup or other is set.
AddressState String N The shipping address state.
AddressDate String N Date when the shipping address used for this transaction was first used with the 3DS Requestor.

7.Delivery

Property Type Mandatory Description
email String O* Mandatory if ShipToAddressType value is eDelivery
For Electronic delivery, the email address to which the merchandise was delivered.
timeframe String N Possible values : electronic, sameday, overnight, longer

8.ClientScreen

Property Type Mandatory Description
ColorDepth Int O Value representing the bit depth of the colour palette for displaying images, in bits per pixel. Obtained from Cardholder browser using the screen.colorDepth property.
Ex : 32
ScreenHeight Int O Total height of the Cardholder’s screen in pixels. Value is returned from the screen.height property.
Ex : 1280
ScreenWidth Int O Total width of the cardholder’s screen in pixels. Value is returned from the screen.width property.
Ex : 1024

9.ThreeDsOptData

Property Type Mandatory Description
ClientAuthMethod String N guest : No merchant authentication occurred (i.e. cardholder “logged in” as guest) ;
credentials : Login to the cardholder account at the merchant system using merchant’s own credentials ;
federated : Login to the cardholder account at the merchant system using federated ID ;
issuer : Login to the cardholder account at the merchant system using issuer credentials ;
thirdparty : Login to the cardholder account at the merchant system using third-party authentication ;
fido : Login to the cardholder account at the merchant system using FIDO Authenticator ;
AccountChangeDate Date N Date that the cardholder’s account with the 3DS Requestor was last changed, including Billing or Shipping address, new payment account, or new user(s) added.
AccountCreationDate Date N Date that the cardholder opened the account with the 3DS Requestor.
Passwordchangedate Date N Date that cardholder’s account with the 3DS Requestor had a password change or account reset.
Last6MonthsPurchaseCount Int N Number of purchases with this cardholder account during the previous six months.
Last24hoursaddcardattempts Int N Number of “Add Card” attempts in the last 24 hours.
Last24hourstransactioncount Int N Number of transactions (successful and abandoned) for this cardholder account with the 3DS Requestor across all payment accounts in the previous 24 hours.
Last12Monthstransactioncount Int N Number of transactions (successful and abandoned) for this cardholder account with the 3DS Requestor across all payment accounts in the previous year.
Cardenrolldate date N Date that the payment account was enrolled in the cardholder’s account with the 3DS Requestor.
Suspiciousaccountactivity Boolean N Indicates whether the 3DS Requestor has experienced suspicious activity (including previous fraud) on the cardholder account.
Homephone string(max 32) N The home phone number provided by the Cardholder in international (E.164) format.
Mobilephone string(max 32) N The mobile phone number provided by the Cardholder in international (E.164) format.
Workphone string(max 32) N The work phone number provided by the Cardholder in international (E.164) format.
Preorderdate date N For a pre-ordered purchase, the expected date that the merchandise will be available.
Itemavailability Boolean N Indicates whether Cardholder is placing an order for merchandise with a future availability or release date.
Reorderingitem Boolean N Indicates whether the cardholder is reordering previously purchased merchandise.
Recurringexpiry date N Date after which no further authorisations shall be performed in a recurring payment workwlow.
recurringfrequency Int N Indicates the minimum number of days between authorisations.
Ex : 10

10.GiftCard

Property Type Mandatory Description
Amount Int N For prepaid or gift card purchase, the purchase amount total of prepaid or gift card(s) in minor units (cents).
Count Int N For prepaid or gift card purchase, total count of individual prepaid or gift cards/codes purchased.
Currency String N For prepaid or gift card purchase, the currency code of the card as defined in ISO 4217.

11.ExtraResults

Property Type Mandatory Description
threedsecure Boolean / True / False
threedsecureauthstatus Int / 0 = Yes
1 = No
2 = unavaible
3 = Attempted
threedsecuresignaturestatus Int / 0 = Yes
1 = No
threedsecureglobalstatus Int / 0 = Yes
1 = Not_enrolled
2 = unavaible
3 = Not_required
ThreeDsCardEnrolled Int / 0 = Yes
1 = No
2 = unavaible
ExecCode String (4) / The operation result code
ExecMessage String / The operation result description linked to EXECCODE
warrantyresult String / Yes / no
3dsecureversion Int / The kind of 3-D Secure protocol version.
Ex : 1
3dsecuremode Int / Applied authentification mode :
0 = ask for a strong authentication
1 = ask for a frictionless authentication
bankauthresult Int / Return code of the authorisation request returned by the issuing bank

Enregistrer une carte bancaire

2.1 Envoi des données de la requête d’enregistrement carte au serveur S-money

Pour ajouter une carte bancaire, les paramètres obligatoires sont les suivants :
- card
- appcardid
- urlReturn

Les autres paramètres sont optionnels.

Veuillez vous référer à l’exemple présent en marge de droite de cette page, pour l’enregistrement d’une carte bancaire d’un utilisateur.

Le paramètre "href" contient l’url vers laquelle l’application tierce doit rediriger le navigateur client pour effectuer l’enregistrement de la carte.

2.2 Envoie des données de l’enregistrement carte au serveur tiers

Le serveur tiers doit mettre à disposition une url serveur permettant au serveur S-money de le notifier du résultat de l’exécution du paiement.

L’appel du serveur S-money est effectué en méthode HTTP POST.

Les paramètres de la requête HTTP sont :

Paramètre Type Description
id Long Id de la carte
error Int Code d’erreur pour les renseignements carte échoués, 0 si aucune erreur.
1 = Le commerçant doit contacter la banque du porteur
2 = Paiement refusé
3 = Paiement annulé par le client
4 = Porteur non enrôlé 3D-Secure
5 = Erreur authentification 3D-Secure
6 = Erreur technique SystemPay
type Int Type de l’opération
5 =enregistrement carte
userid String Identifiant de l’utilisateur chez l’application tierce

2.3 Redirection en fin d’enregistrement carte

Le serveur tiers doit mettre à disposition une url permettant au serveur S-money de rediriger le client vers l’environnement tiers.

L’url peut-être soit associée au scheme web (http/https) ou à un scheme privatif dans le cas où l’appel serait effectué à partir d’une application mobile tierce.

L’appel du serveur S-money est effectué en méthode HTTP POST.
Les paramètres de la requête HTTP sont :

Paramètre Type Description
Id Long Id de la carte bancaire
Type Int Type de l’opération
5 = enregistrement carte
Result Int Statut de la transaction
0 = Erreur
1 = OK

Récupérer une Carte Enregistrée

Pour récupérer les informations relatives à l’enregistrement de la carte de l’utilisateur, veuillez vous référer à l’exemple en marge de droite de cette page.

Les informations sur les différents paramètres de la réponse sont disponible dans le chapitre Ressources.