Easy checkout integration guide

Easy checkout is a payment page that embeds directly into your shop. The payment is handled through the Payment API and the checkout page is generated by javascript.

Introduction

The Embedded DIBS Easy checkout is a payment service which is embedded directly on the checkout page.
The following integration guide is meant to document a basic integration of the checkout using html, javascript, and php.

A integration towards DIBS Easy differs from other DIBS integrations by having the paymentId(transactionID) created before the checkout is initialized.

The integration guide consists of the following 3 steps:

  1. Creating a paymentId
  2. Initializing the checkout
  3. Handling a completed checkout

Creating a paymentId

Once a customer wishes to complete a purchase by proceeding to the Easy checkout, a payment has to be prepared by creating a paymentId.

A paymentId is created by making a server-to-server call to the Payment API with a datastring containing information about the order, customer, and merchant.

If the request is successful, the Payment API will respond with a paymentId token.

The Datastring

The datastring is an array of parameters, which are intended to make up a single order.

The following parameters have to be included in the datastring: Items, amount, currency (ISO 4217), reference (orderID), checkout (customer information), merchantReference.

For specified information regarding the different parameters in the datastring, see: Datastring Parameters

Create Payment API-request

The example below creates a simple cURL request based on the following parameters:
INIT URL: https://test.api.dibspayment.eu/v1/payments/
Authorization key: A secret key found in the DIBS Easy admin Portal
Datastring: A collection of data, which is used to define the order.

cUrl example

 

if($_GET['action'] == 'createPay') {                             
	$datastring = getDatastring($orderID);

	$ch = curl_init('https://test.api.dibspayment.eu/v1/payments');                                                                      
	curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");                                                                     
	curl_setopt($ch, CURLOPT_POSTFIELDS, $datastring);                                                                  
	curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);                                                                      
	curl_setopt($ch, CURLOPT_HTTPHEADER, array(                                                                          
		'Content-Type: application/json',
		'Accept: application/json',	
		'Authorization: 00000000000000000000000009000000')                                                                   
	);                                                                                                                                                                
	$result = curl_exec($ch);
	echo($result);
}
   
Response
{ "paymentId": "string" }

The request to create a paymentId must be done through server-to-server communication, any attempt at calling the API from a client (web-browser) will fail.

Initialize the checkout

HTML Example

 
	
	

    
    

Javascript source:

To initiate the checkout you first have to add the following javascript as a source to the checkout page:
TEST

https://test.checkout.dibspayment.eu/v1/checkout.js?v=1
LIVE
https://checkout.dibspayment.eu/v1/checkout.js?v=1

Add target element for checkout:

You will need a DIV element in which the checkout iframe will be loaded, in the example we use:

 

The javascript will create an iFrame containing the Easy checkout, and it will add the iframe to the position of the domElementId with a source url formatted based on the input parameters.


Trigger checkout javascript:

In the example above, we use a button to initialize the checkout:

 

This button triggers an ajax call to the createpayment php function, which generates a paymentId based on the datastring of collected information.
On successful execution, it assigns the new paymentID variable and initiates the checkout process.

 
$("#CreatePayment").on('click', function() {
            $.ajax({
                url: 'api/createpayment.php',
                data: {
                    action: 'createPay',
                    orderID
                },
                dataType: 'json',
                success: function(data) {
                    paymentID = JSON.stringify(data);
                    var obj = jQuery.parseJSON(paymentID);
                    paymentID = obj.paymentId;
                    intitCheckout(paymentID);
                }
            });
        });


Checkout Javascript

The checkout .js uses the variable checkoutOptions to initialize the iframe.
This variable consist of the following parameters:

Parameter Description
checkoutKey*

Merchant Identifier, found in Easy-Portal

paymentId*

Reference to the paymentId token created in previous steps.

containerId

ID of DOM-element where iframe will be loaded.

language

Language used in checkout. Possible values:
en-GB (english)
sv-SE (swedish)
not specified (default): en-GB

* : Mandatory parameters

 
var checkoutOptions = {
               checkoutKey: “00000000000000000000000009000000”, //[Required] GUID without dashes
               
               paymentId : "8b464458f2524bc39fe5d31deb8bedc1", //[required] GUID without dashes
               containerId : "dibs-complete-checkout", //[optional] defaultValue: dibs-checkout-content
               language: "en-GB",            //[optional] defaultValue: en-GB
};
var checkout = new Dibs.Checkout(checkoutOptions);

//this is the event that the merchant should listen to redirect to the “payment-is-ok” page

checkout.on('payment-completed', function(response) {
               /*
               Response: 
                              paymentId: string (GUID without dashes)
               */
               window.location = '/PaymentSuccessful';
});

3D-Secure Checkout Flow

If a customer has a 3Dsecure enrolled card, they will be redirected to verification during the checkout-process. When the customer has completed the verification, they are automatically returned back to the checkoutUrl with an added paymentId parameter.
At this point the checkout have to be re-initialized using the same paymentId, which will trigger the payment-completed function of the checkout.js.

Handle Payments after Checkout

After the checkout has been completed, the created payment can either be handled in Easy administration, or directly through our API functions.

Specified Information regarding the different API functions can be found here:http://tech.dibspayment.com/easy/server-to-server-api

The GET Payment function

 

Regardless of how you choose to handle payments, we always recommend to use the GET Payment API to retrieve the latest information regarding the payment.

This is done by sending a GET request to the PaymentAPI containing the paymentId you wish to retrieve information on.

https://test.api.dibspayment.eu/v1/payments/{paymentId}

Example:

 
//GET PAYMENT
if($_GET['action']=='getPayment') {
    $payId=$_GET['paymentID'];
    $ch=curl_init('https://test.api.dibspayment.eu/v1/payments/'. $payId . '');
    curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "GET");
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, array( 'Content-Type: application/json', 'Accept: application/json', 'Authorization: /* Secret Key */'));
    $result=curl_exec($ch);
    echo($result);
}

This request will respond with a json array containing all relevant information regarding the payment

 
{  
   "payment":{  
      "paymentId":"17252567c19b4519870e6bc82cb6e106",
      "summary":{  
         "reservedAmount":1000
      },
      "consumer":{  
         "billingAddress":{  

         },
         "shippingAddress":{  
            "addressLine1":"TESTADRESS",
            "postalCode":"00001",
            "city":"Copenhagen",
            "country":"DK"
         },
         "company":{  
            "phoneNumber":{  

            }
         },
         "privatePerson":{  
            "dateOfBirth":"1944-03-17T00:00:00",
            "firstName":"Test",
            "lastName":"Person",
            "email":"support@dibs.com",
            "phoneNumber":{  
               "prefix":"+46",
               "number":"11223344"
            },
            "merchantReference":"123456"
         }
      },
      "paymentDetails":{  
         "paymentType":"CARD",
         "paymentMethod":"MasterCard",
         "invoiceDetails":{  

         },
         "cardDetails":{  
            "maskedPan":"541300******0000",
            "expiryDate":"1119"
         }
      },
      "orderDetails":{  
         "amount":1000,
         "currency":"SEK",
         "reference":"DIBS DEMO"
      },
      "checkout":{  
         "url":"http://www.domain.com/easyDemo/index.php"
      },
      "created":"2017-03-22T11:52:41.5508+00:00"
   }
}
Do you have a question or need help?
Follow us
DIBS Payment Services
Stockholm +46 (0)8-527 525 00
Göteborg +46 031-600 800
København +45 7020 3077
Oslo +47 21 55 44 00