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 paymentservice 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 steps:

  1. Creating a PaymentId
  2. The Checkout
  3. Business-to-Consumer (B2C) & Business-to-Business (B2B)
  4. Invoice Fee Surcharge
  5. Update cart
  6. Update shipping cost
  7. Destination based shipping cost
  8. Handle Payments After Checkout

1. 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 before you try to initiate the checkout.

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.

Important information: The paymentId is valid for 120 minutes, after that the transaction will expire if it hasn't been completed by the consumer.

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: The secret key found in the DIBS Easy portal. Use only UUID, that is without the "Live-Secret-Key-" or "Test-Secret-Key-"
Datastring: A collection of data, which is used to define the order.

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.

 

The URL in the Datastring must be the same URL as the URL you use to load the checkout from. If checkout is loaded from "https://www.mydomain.com/checkout" then the same URL must be sent to Easy Checkout when loading the checkout.

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

 

Datastring example

{
"order": {
	"items": [{
        "reference": "13",
        "name": "testproduct 1",
        "quantity": 2,
        "unit": "pcs",
        "unitPrice": 48648,
        "taxRate": 2500,
        "taxAmount": 24324,
        "grossTotalAmount": 121620,
        "netTotalAmount": 97296
    },
    {
        "reference": "21",
        "name": "testproduct 2",
        "quantity": 2,
        "unit": "kg",
        "unitPrice": 111840,
        "taxRate": 2500,
        "taxAmount": 55920,
        "grossTotalAmount": 279600,
        "netTotalAmount": 223680
    }
    ],
    "amount": 401220,
    "currency": "sek",
    "reference": "Demo Order"
    },
"checkout": {
 "url": "https://www.mydomain.com/checkout",
 "termsUrl": "https://www.mydomain.com/toc",
    "shippingCountries":
    [
        {"countryCode": "SWE"},
        {"countryCode": "NOR"}
    ],
    "consumerType": {
        "supportedTypes": [ "B2C", "B2B" ],
        "default": "B2C"
    }       
},
	
//You can extend the datastring with optional webhook-parameters for status such as "payment.created". Click for more info
"notifications": {
    "webhooks": [{
        "eventName": "payment.created",
        "url": "string",
        "authorization": "authorizationKey"
        }
    ]
},//This enables the merchant to charge an invoice fee towards the customer when invoice is used as paymentmethod
  "paymentMethods": [
   {
    "name": "easyinvoice",
    "fee": {
      "reference": "invFee",
      "name": "fee",
      "quantity": 1,
      "unit": "ct",
      "unitPrice": 1000,
      "taxRate": 25,
      "taxAmount": 250,
      "grossTotalAmount": 1250,
      "netTotalAmount": 1000
    }
  }
 ]
}

Restricting Shipping

To specify the available shipping countries, the merchant can extend the operation for creating payment with the ShippingCountries parameter. If not used, all countries will be avialable for the customer during the checkout.

example:

ShippingCountries" : [{"countryCode":"NOR"},{"countryCode":"SWE"}] 

The countries should be specified using ISO 3166-1 alpha-3 codes

If a country is not in the list, the merchant will be notified with the following error message.

{
    "errors": {
        "checkout.ShippingCountries": [
            "[SSS] as shipping country not supported "
        ]
    }
}
If a consumer’s shipping address country is not in the list of supported shipping countries an error will appear as seen in the image below:

Restrict Shipping consumer example

 

A full list of accepted countries and related ISO 3166-1 Codes can be found here

2. Initialize the checkout

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:

<div id="dibs-complete-checkout"> </div>	
 

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.


HTML Example


    
 

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;
                    initCheckout(paymentID);
                }
            });
        });

Checkout.js

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.

partnerMerchantNumber

"123456789", specifies partner

containerId

ID of DOM-element where iframe will be loaded.

language

Set the language used in checkout. Possible values:
en-GB (english)
sv-SE (swedish)
nb-NO (Norwegian Bokmål)
da-DK (Danish)
not specified (default): en-GB

theme

Change colors in the checkout. Possible values:
textColor - affects all text that is not a link,
but panel text can be overridden separately.
A new theme node is added, with the options in the example above.
All values are strings, and must be valid css.
linkColor - same thing for links, all links are affected,
unless those in a panel if set.
panelTextColor - and panelLinkColor affects text and links in panels
primaryColor - affects the pay button, default button outlines,
and radio buttons
buttonRadius - defines the squareness or roundness of buttons
buttonTextColor - sets the text color for all buttons
backgroundColor - sets the background color
panelColor - sets the panel color
outlineColor - sets the outline and separation lines for panels
primaryOutlineColor - sets the border color for radio buttons and checkboxes

* : Mandatory parameters

 
var checkoutOptions = {
   checkoutKey: “live-checkout-key-00000000000000000000000009000000”, //[Required] Test or Live GUID with dashes
   paymentId : "8b464458f2524bc39fe5d31deb8bedc1", //[required] GUID without dashes
   partnerMerchantNumber: "123456789", //[optional] Number
   containerId : "dibs-complete-checkout", //[optional] defaultValue: dibs-checkout-content
   language: "en-GB",//[optional] defaultValue: en-GB
   theme: { // [optional] - will change defaults in the checkout

					textColor: "blue", // any valid css color

					linkColor: "#bada55", // any valid css color

					panelTextColor: "rgb(125, 125, 125)", // any valid css color

					panelLinkColor: "#0094cf", // any valid css color

					primaryColor: "#0094cf", // any valid css color

					buttonRadius: "50px", // pixel or percentage value

					buttonTextColor: "#fff", // any valid css color

					backgroundColor: "#eee", // any valid css color

					panelColor: "#fff", // any valid css color

					outlineColor: "#444", // any valid css color

					primaryOutlineColor: "#444", // any valid css color   }

};
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 process, they are automatically returned back to the checkoutUrl with an added paymentId parameter.

At this point the checkout has to be re-initialized using the same paymentId, if the verification was successfull it will trigger the payment-completed function of the checkout.js. If the verification failed, it will alow the consumer to retry the purchase.

 

Restricted parameter: paymentId

Due to the nature of a 3D secure checkout process, the query string used to initiate the checkout the first time, must not contain a paymentId parameter as reference, as this will be used by the checkout in a later stage of the process.

Example:

http://yourdomain.no/checkout?paymentId=e8c35c8eed8f48e78c5997362a19d3d3
is forbidden and will cause an error when the checkout is initiated.

 

Pay-initialized event

This is an event that triggers whenever the consumer clicks on the "pay" button and is sent to the 3D secure step. Together with for instance a timer on the merchant side, this can be used to easily track if a consumer cancels the payment during the 3D secure step.

A spinner will be displayed to consumer while checkout is waiting for a response from the Merchant

  • Response is required within timeout
  • Respond with ‘payment-order-finalized’ and a boolean
  • True: Continue to processing
  • False: Something went wrong, don’t proceeed
  • ⇛ Payment failed.
    NB:If payment fail, the consumer will be able to try again.
     checkout.on('pay-initialized', function(response) {
    /*
    	Complete the desired operations such as update payment
    */
    	checkout.send('payment-order-finalized', true/false);
    });
    

     


3. Business-to-Consumer (B2C) & Business-to-Business (B2B)

Easy allows for business (B2B) and private consumers (B2C) to checkout with ease and smoothness through the few actions needed to complete a transaction.
The core functionality for businesses is the same as for private consumers, but with some differences in the checkout flow.

The checkout works exactly the same for B2C as for B2B, it stores addresses, cards and invoice and you have the option to be remembered on one or several devices.
This mean that returning B2B and B2C consumers will enjoy the same speed of checkout.

A private consumer registers with email-address, postal code, personal security number and phone number.
Easy does a lookup and retrieves the first name, last name and the civil registration address.

The flow for registering as a business is very similar to that of B2C. For Norway and Denmark, the form includes Company name in addition to the information collected from a private consumer. For the Swedish flow the business consumer will be enabled to do a lookup on organization number and retrieve the address.

Merchants need to enable B2B for it to display in the checkout on their sites. For modules and partner integrations that have built support for B2B they can easily do this in their portals. For direct integrations, merchants need to specify this in the API.

Merchants have flexibility when selecting their customer types. It's possible to choose to have B2C only, B2C and B2B, or even B2B only. Additionally, merchants can select which checkout loads as default on their site, so that you can tailor the user experience depending on your business model, which is a feature unique to Easy.

A B2B consumer is separated from a B2C consumer, so that consumers can separate their private and business Easy profiles. In practice this means that there is a B2B selector present in the checkout when a merchant has enabled both consumer types. The information stored on a private consumer will not be present for a Business consumer.

B2B consumers have mostly the same ways of paying as B2C, with some differences as B2B consumers will not be able to use instalments or invoice campaigns.

A B2B invoice has some limitations on the Easy platform as checkout security is based on only being able to ship to officially registered addresses, B2B companies can only pay with invoice when shipping to their headquarter. A key difference from B2C is that the due date is set to 30, not 14.

B2B payments will be presented to merchants in the portal as any other payment, with the exception that Company Name will also be there. All other functionality is the same.

 

This checkout defaults to B2C, with the option to login as B2B.

This checkout defaults to B2B, with the option to login as B2C.

Add/Update Invoice fee surcharge

To enable the invoice fee, the merchant must specify the fee when creating the payment. The "paymentMethodFee" part in the body below represents the fee. Please note: only easyinvoice supports payment fees, specifying anything else will result in a 400 "bad request" response.

{
	POST "v1/payments", HEADERS authorization *secret-key*
  "order": {
    "items": [
      {
        "reference": "abcd",
        "name": "Socks",
        "quantity": 1.0,
        "unit": "ct",
        "unitPrice": 1000,
        "taxRate": 25,
        "taxAmount": 250,
        "grossTotalAmount": 20000,
        "netTotalAmount": 1000
      }
    ],
    "amount": 20000,
    "currency": "NOK",
    "reference": "my order reference"
  },
  "checkout": {
    "url": "http://foo.bar",
    "consumer": null,
    "termsUrl": "http://foo.terms.bar",
    "shippingCountries": null,
    "shipping": {
      "countries": [],
      "merchantHandlesShippingCost": false
    },
    "consumerType": {
      "default": "B2C",
      "supportedTypes": [
        "B2C",
        "B2B"
      ]
    },
    "charge": false
  },
  "merchantNumber": null,
  "notifications": null,
  "subscription": null,
  "paymentMethods": [
   {
    "name": "easyinvoice",
    "fee": {
      "reference": "abcd",
      "name": "fee",
      "quantity": 1,
      "unit": "ct",
      "unitPrice": 1000,
      "taxRate": 25,
      "taxAmount": 250,
      "grossTotalAmount": 1250,
      "netTotalAmount": 1000
    }
  }
 ]
}

If the merchant needs to change the fee, for example if the total amount in the cart will reflect the size of the, they can update the size of the fee by using the "update cart" functionality:

PUT "v1/payments/{paymentID}/orderitems", HEADERS authorization *secret-key* 

{
  "amount": 30000,
  "items": [
    {
      "reference": "abcd",
      "name": "Zodiak",
      "quantity": 1.0,
      "unit": "ct",
      "unitPrice": 1000,
      "taxRate": 25,
      "taxAmount": 250,
      "grossTotalAmount": 30000,
      "netTotalAmount": 1000
    }
  ],
  "shipping": null,
  "paymentMethods": [ {
    "name": "easyinvoice",
    "fee": {
      "reference": "abcd",
      "name": "bigger-fee",
      "quantity": 1,
      "unit": "ct",
      "unitPrice": 2000,
      "taxRate": 25,
      "taxAmount": 500,
      "grossTotalAmount": 2500,
      "netTotalAmount": 2000
    }
  }]
}

Please note: if the merchant specified a gross total amount for the fee of 0, the fee will be removed. If the fee is left out when updating the cart, the intial fee specified when the payment was created will be kept. Portal functionality: The fee will be listed as an order item in the portal once the payment has been reserved.

4. Update cart

As a part of the shipping cost feature, we have implemented generic cart-updates. Merchant can update the order items in a cart by utilizing the new api-method: PUT "v1/payments/{paymentId}/orderitems". This method can be used to add or remove items to the cart, change the amount, quantity, etc on existing items or add or update shipping cost. Please note that shipping cost is an order line like any other order line. If the merchant handles shipping cost, the update cart must be invoked with shipping.costSpecified as shown in the example body:

{
  "amount": 30,
  "items": [
    {
      "reference": "abcd",
      "name": "Socks",
      "quantity": 1.0,
      "unit": "ct",
      "unitPrice": 0,
      "taxRate": 0,
      "taxAmount": 0,
      "grossTotalAmount": 10,
      "netTotalAmount": 0
    },
    {
      "reference": "reference a",
      "name": "Raskt levert!",
      "quantity": 1.0,
      "unit": "NA",
      "unitPrice": 0,
      "taxRate": 0,
      "taxAmount": 0,
      "grossTotalAmount": 20,
      "netTotalAmount": 0
    }
  ],
  "shipping": {
    "costSpecified": true
  }
}

 

5. Update shipping cost

  1. Set the merchantHandlesShippingCost flag in the "create payment" request
  2. On the front-end (javascript), listen to the new event "address-changed"
  3. When the address has changed (for example when the consumer changes the delivery address, or when the consumer was initially identified in the checkout):
    1. Recalculate the shipping cost
    2. Update the cart using the new update cart functionality in the payment api (see the "update cart" documentation above), remember to set the shipping.costSpecified flag when updating the cart
    checkout.on('address-changed', function(address){ // Subscribe to address-changed event
    	if (address){ // {postalCode: string, countryCode: string}
    		checkout.freezeCheckout(); // New method for visually freezing checkout
    
    		// "calculate shipping cost" should calculate shipping cost based on
    		// new postalcode and country.
    		calculateShippingCost(address.postalCode, address.countryCode).then(function(response) {
    			updateCart(response);
    			// "update cart" should call the "update cart" method on the payment API with the included shipping cost
    
    			checkout.thawCheckout();
    			// New method for thawing checkout - also triggers reloading of payment information
    		});
    	}
    });
  4. If the cart has been updated with the shipping cost (pt 3.2 above), the consumer can continue by clicking pay.

6. Destination based shipping cost

To enable destination based shipping cost, merchant must set the shipping cost flag when creating the payment (checkout.shipping.merchantHandlesShippingCost):

POST "v1/payments"

{
  "order": {
    "items": [
      {
        "reference": "abcd",
        "name": "Socks",
        "quantity": 1.0,
        "unit": "ct",
        "unitPrice": 0,
        "taxRate": 0,
        "taxAmount": 0,
        "grossTotalAmount": 10,
        "netTotalAmount": 0
      }
    ],
    "amount": 10,
    "currency": "NOK",
    "reference": "abcd"
  },
  "checkout": {
    "url": "http://foo.bar",
    "consumer": null,
    "termsUrl": "http://foo.bar",
    "shipping": {
      "countries": [],
      "merchantHandlesShippingCost": true
    },
    "consumerType": null,
    "directCharge": false
  },
  "merchantNumber": null,
  "notifications": null
}

Once the shipping address is set, such as when the consumer is selected, the merchant must calculate the shipping cost, and call the payment API with the new cart:

Note that shipping.costSpecified must be set to true in order for the subsequent payment to pass validation and succeed.

PUT "v1/payments/{paymentId}/orderitems"

{
  "amount": 30,
  "items": [
    {
      "reference": "abcd",
      "name": "Socks",
      "quantity": 1.0,
      "unit": "ct",
      "unitPrice": 0,
      "taxRate": 0,
      "taxAmount": 0,
      "grossTotalAmount": 10,
      "netTotalAmount": 0
    },
    {
      "reference": "reference a",
      "name": "Raskt levert!",
      "quantity": 1.0,
      "unit": "NA",
      "unitPrice": 0,
      "taxRate": 0,
      "taxAmount": 0,
      "grossTotalAmount": 20,
      "netTotalAmount": 0
    }
  ],
  "shipping": {
    "costSpecified": true
  }
}

When the customer clicks pay, the property amountConfirmedByConsumer must match the sum of the order lines in order for the payment to validate and succeed.

POST "v1/pay"

{
  "type": "card",
  "paymentType": {
    "card": {
      "cardNumber": "123456789012345",
      "expiryYear": "20",
      "expiryMonth": "01",
      "cardVerificationCode": "123"
    },
    "remember": false,
    "consumerId": "3587e2d6-b44f-4afa-b074-ad5f30cd1012",
    "addressId": "389ec898-129b-4c1a-95c5-f4bd890218f2",
    "consumerType": 0,
    "reference": "cdef"
  },
  "amountConfirmedByConsumer": 1337
}

 

7. Handle Payments after Checkout

The GET Payment function

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

Specified Information regarding the different API functions can be found here: https://tech.dibspayment.com/easy/integration/rest

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

 

Reciept Illustration

Payment Confirmation

Once a purchase is completed, the customer must receive a confirmation of the order and a receipt in the form of an on-screen-display and e-mail.

Order confirmation immediately on-screen-display after purchase.
- Transaction status (completed/accepted/declined)

Order confirmation e-mail must contain the following information and should be sent immediately to the customer after a successful order.

  • Payment ID
  • Expected date of delivery (i.e. "will be delivered within 5 days")
  • Your contact details including company name, address, e-mail address and/or telephone number
  • A complete description of the services/products purchased
  • The order number (your webshop’s internal order reference number)
  • The last four digits of the card number when purchase is done by card
  • Order date
  • Prices must include the currency
  • The total amount being charged (incl. charges, value added tax, shipping etc.)
  • The payment status (completed/declined)
  • The amount indicated must not exceed the amount quoted in the order form

     

The order confirmation/reciept is required in our site inspection and must be fulfilled before the solution is accepted.
For more information in regards to the site inspection process, please visit: http://www.dibspayment.com/easy/siteinspection

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