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
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
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:
A full list of accepted countries and related ISO 3166-1 Codes can be found here
