Dalenys Hosted Fields - Registration of a bank card

Method of integrating the registraton form

Principle:

1. You display a payment page including a registration form, except that the bankcard input fields are replaced by hosted-fields containers. These containers could be any HTML tag: div, p, span… the hosted-fields JavaScript library injects Dalenys-hosted iframes in these containers, each containing the card data input fields
2. At the submit process, you should call the createToken method of the hosted-fields library which will trigger the tokenization of the cardholder data (card number, expiry date and cryptogram)
3. If the tokenization is successful, you must add the received token to your form submission request (e.g. by adding a hidden input)

Creation of the form:

You must own a TLS certificate to host a valid HTTPS payment page, otherwise the user’s browser will display security alerts and is likely to block it.
The hosted-fields library must always be called online. Using a downloaded version hosted on your own server can cause serious malfunctions, especially in the case of an update of the API.

1- First of all, you must include the Dalenys hosted-fields dedicated library, by adding the following code between the <head> and </head> tags in your HTML:
<script type="text/javascript" src="https://js.sandbox.dalenys.com/hosted-fields/v2.0.0/hosted-fields.min.js"/>
<script type="text/javascript" src="https://js.sandbox.dalenys.com/brand-detector/v2.0.0/brand-selector-widget.min.js"/>

2- Declare the UTF-8 encoding
<meta charset="UTF-8">

3- Create a <form> </ form> form with 4 containers identified by an id attribute. The choice of the identifier used is free but must be unique and will be used in the javascript code presented in the following points.
In the following example, we’re generating a payment form using 4 span tags as containers:

<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>

The URL to enter in the action attribute is: URL_API/psp/submitcardregistration

4- Configure the hosted fields library
The next step is to designate the containers in which to create the secured hosted-fields, using JavaScript.
To do so, initialize the hosted-fields library with your Public API Key and your desired configuration: S-money must provide the necessary keys to the 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>

The identifiers used in the script to designate the fields are those used for the identifiers of the containers created in the form. This allow the script to inject the fields hosted by Dalenys in these containers.

5- Load the hosted fields library

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

At this point, your web browser may display the bank card input fields into their containers.

6- Token generation
Once the user submits the form, you should call the createToken method to trigger the tokenization process.
This method expects a callback in parameter which will be triggered once the tokenization request is finished.
Your callback will receive a result object containing these properties:
execCode: The technical result code of the tokenization call. In case of success, 0000 will be sent
message: The description linked to the execCode
cardType: The card type
cardCode: The first 6 and last 4 digits of the cardholder’s card number
cardValidityDate: Card expiry date
selectedBrand: Cardholder selected brand in case of co-branded card.
hfToken: Of course the generated token

In case of success you have to add the received token to the form submit request (by adding an hidden input for example) :

<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
               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- Include EXTRADATA property (from the result of the call to create the card payment) in hidden fields:
<input type="hidden" name="smextradata" value="@Model.ExtraData" />

Registration with 3d secure Authentication

Depending on the card used during the payment, the submission of the registration form, a 3DSecure authentication may be necessary.
In this case, the HTML page of the 3DSecure form is sent in response content with a http status code 200 (OK).
The submission of the 3DSecure form will end with a 302 redirection to the url entered in the urlReturn field of the initial request.

Resources

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 (max length 50). 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 (max length 50).
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

Add a bank card

Retrieve a bank card