How to implement the payment form
Principle:
1. You display a payment page including a payment 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.dalenys.com/hosted-fields/v2.0.0/hosted-fields.min.js"/>
<script type="text/javascript" src="https://js.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/submitcardpayment
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/submitcardpayment" 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-Include OPERATIONID, PAYINTOKENID and EXTRADATA properties (from the result of the call to create the card payment) in hidden fields:
<input type="hidden" name="smoperationid" value="@Model.OperationId" />
<input type="hidden" name="smpayintokenid" value="@Model.PayinTokenId" />
<input type="hidden" name="smextradata" value="@Model.ExtraData" />The "name" attributes of the input hidden tags shouldn’t be changed.
Payment with 3d secure Authentication
Depending on the card used during the payment, the submission of the payment 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.