mpInit

The mpInit service initiates flow for wallet cards (Masterpass) and returns id of the session, that can be used for future payment authorization without sending any card parameters.

On success, the service returns walletSessionId and redirectUrl, which are used by merchant to direct the customer to the Masterpass site, where the customer has to choose his/her card and shipping address and confirm payment information.

The endpoint for the JSON service:

https://api.dibspayment.com/merchant/v1/JSON/Transaction/mpInit

Input parameters

Parameter Type Description

merchantId *

String, max 36 letters Integration ID from DIBS Admin 2.0.
acceptableCards String

A comma-­separated list of card types supported. Duplicates are not allowed. Possible MP values are

master, amex, diners, discover, maestro, visa

addFee

Boolean

If set to true, fee amount will be included to the final authorized amount.

cartContent List of OrderItem objects

A list of OrderItem objects for using in the future payment. See below for more information.

currencyCode * String, 3 letters/digits

The currency for future payment. Either the numeric or alphabetic ISO4217 code is accepted.

shippingAddress

SimpleAddressInfo object

Address Information from the merchant. See below for more information.
shippingLocationProfile String

This parameter determines the regions your company ships to. Use one of the accepted values below.

Shipping Locations Accepted values
Denmark DK
Finland FI
Norway NO
Sweden SE
Denmark,Finland DKFI
Denmark, Norway DKNO
Denmark, Sweden DKSE
Finland, Norway FINO
Finland, Sweden FISE
Norway, Sweden NOSE
Denmark, Finland, Norway DKFINO
Denmark, Finland, Sweden DKFISE
Denmark, Norway, Sweden DKNOSE
Finland, Norway, Sweden FINOSE
Denmark, Finland, Norway Sweden DKFINOSE
All countries (no restrictions) all
suppressShippingAddress Boolean

If set to true, Masterpass won’t ask the consumer to provide a shipping address.

consumerEmail String, max. 128 letters Consumer's email address, provided by the merchant.
Supposed to be returned in mpValidate response, to match result with consumer's data for not registered consumer.
consumerPhone String, max. 128 letters Consumer's email address, provided by the merchant.
Supposed to be returned in mpValidate response, to match result with consumer's data for not registered consumer.
test Boolean

Use the set up test acquirers

MAC * String, 64 letters This parameter contains a Message Authentication Code.

*: Always validated by DIBS

OrderItem object:

Parameter Type Description
quantity Strings Quantity. Specified in the unit of measure.
unitOfMeasure String Unit of measure used in quantity.
description String Description of order item.
amount String Amount including VAT.
vatAmount String VAT.
vatPercentage String VAT percentage.
productId String Product ID for the order item.
imageUrl String Url to the picture of the current item, for displaying on Masterpass site. (coming soon)

SimpleAddressInfo object:

Parameter Type Description
firstName String First name of the contact.
lastName String Last name of the contact
address String First address line.
address2 String Second  address line.
postalCode String Address postal code.
postalPlace String Address postal place.
country String Country of the contact.
email String, 128 letters  Consumer's email address, provided by Masterpass. This parameter is taken from selected shipping address on Masterpass site if appropriate address has this parameter filled, or from Masterpass account details otherwise.
phone String, 128 letters Consumer's phone, provided by Masterpass. This parameter is taken from the field "recipientPhoneNumber" of selected shipping address on Masterpass site if appropriate address has this parameter filled, or from Masterpass account details otherwise.

 

Return parameters

Parameter Type Description
status [ACCEPTED, DECLINED, ERROR] Status of the call. ACCEPTED means that request was processed and the Masterpass information is returned.
walletSessionId String (for status ACCEPTED) Id of the wallet card session. This value equals to the oauth_token parameter
declineReason String (for status DECLINED) Reason for decline or error (Masterpass internal message, if presented, or default error message), null for ACCEPTED status.
redirectUrl String (for status ACCEPTED) Url of the Masterpass authorization window to redirect consumer to

 

Code examples

/**
 * Dependencies:
 * Apache-Commons/Commons-Codec for Hex encoding/decoding
 * Codehaus/Jackson for JSON mapping
 */
/**
 * postToDIBS Sends a post to the specified DIBS function
 *
 * @param parameters A Map<String, String> holding the parameters to be parsed to DIBS
 * @param func A String holding the name of the function to be used
 * @return A Map<String, String> holding the parameters returned by DIBS
 */
public Map<String, String> postToDIBS(Map<String, String> parameters, String func) {
  try {
    //Set the endpoint for the chosen function
        String endpoint = null;
        if (func.equals("AuthorizeCard")) {
            endpoint = "https://v2.api.dibspayment.com/merchant/v1/JSON/Transaction/AuthorizeCard";
        } else if (func.equals("AuthorizeTicket")) {
            endpoint = "https://v2.api.dibspayment.com/merchant/v1/JSON/Transaction/AuthorizeTicket";
        } else if (func.equals("CancelTransaction")) {
            endpoint = "https://v2.api.dibspayment.com/merchant/v1/JSON/Transaction/CancelTransaction";
        } else if (func.equals("CaptureTransaction")) {
            endpoint = "https://v2.api.dibspayment.com/merchant/v1/JSON/Transaction/CaptureTransaction";
        } else if (func.equals("CreateTicket")) {
            endpoint = "https://v2.api.dibspayment.com/merchant/v1/JSON/Transaction/CreateTicket";
        } else if (func.equals("RefundTransaction")) {
            endpoint = "https://v2.api.dibspayment.com/merchant/v1/JSON/Transaction/RefundTransaction";
        } else if (func.equals("Ping")) {
            endpoint = "https://v2.api.dibspayment.com/merchant/v1/JSON/Transaction/Ping";
        } else if (func.equals("mpInit")) {
            endpoint = "https://v2.api.dibspayment.com/merchant/v1/JSON/Transaction/mpInit";
        } else if (func.equals("mpValidate")) {
            endpoint = "https://v2.api.dibspayment.com/merchant/v1/JSON/Transaction/mpValidate";
        } else if (func.equals("mpAuthorize")) {
            endpoint = "https://v2.api.dibspayment.com/merchant/v1/JSON/Transaction/mpAuthorize";
        } else if (func.equals("calcFee")) {
            endpoint = "https://v2.api.dibspayment.com/merchant/v1/JSON/Transaction/calcFee";
        else {
            System.out.println("Error in postToDIBS(): Given function does not exist");
            return null;
        }

    // Set properties for connection.
    // Connection is not initialized until parameters are posted
    URL url = new URL(endpoint);
    HttpURLConnection connection = (HttpURLConnection) url.openConnection();
    connection.setDoOutput(true);
    connection.setRequestMethod("POST");

    // Initiate output stream for connection and post message
    OutputStream out = connection.getOutputStream();
    out.write("request=".getBytes(Charset.forName("UTF-8")));
    ObjectMapper objectMapper = new ObjectMapper(); // ObjectMapper from the Jackson library
    objectMapper.writeValue(out, parameters);
    out.flush();
    out.close();

    if (connection.getResponseCode() == HttpURLConnection.HTTP_OK) {
      // OK
      @SuppressWarnings("unchecked")
      Map<String, String> response = objectMapper.readValue(connection.getInputStream(), Map.class);
      return response;
    } else {
      // Server returned HTTP error code.
      System.out.println("HTTP error!" + connection.getResponseCode());
      return null;
    }
  } catch (MalformedURLException e) {
    e.printStackTrace();

  } catch (IOException e) {
    e.printStackTrace();
  }
  return parameters;
}
/**
 * Dependencies:
 * Apache-Commons/Commons-Codec for Hex encoding/decoding
 * Codehaus/Jackson for JSON mapping
 */
/**
 * MasterpassFlow initialization. Starts a new Masterpass session using Masterpass JSON services.
 *
 * @param amount The amount of the purchase in smallest unit
 * @param currency The currency either in numeric or string format (e.g. 208/DKK)
 * @param merchantId DIBS Merchant ID / customer number
 * @param slp shipping localiton id parameter
 * @param macKeyHex The secret HMAC key from DIBS Admin
 */
public void MasterpassFlow_mpInit(int amount, String currency, String merchantId, String slp, boolean suppressShippingAddress,
        boolean addFee, boolean isTest, String macKeyHex) {

        // Create JSON object and add parameters
        Map<String, String> parameters = new HashMap();
        parameters.put("amount", String.valueOf(amount));
        parameters.put("currency", currency);
        parameters.put("merchantId", merchantId);
        parameters.put("shippingAddress", getShippingAddressJsonString());
        parameters.put("shippingLocationProfile", slp);
        parameters.put("cartContent", getCartContentList());
        parameters.put("suppressShippingAddress", suppressShippingAddress);
        parameters.put("acceptableCards", "visa,master");
        parameters.put("addFee", addFee);
        parameters.put("test", isTest);

        parameters.put("consumerEmail", "merchantsMail@mail.dk");
        parameters.put("consumerPhone", "112233445566");

        // Add MAC value for request
        parameters.put("MAC", calculateMac(parameters, macKeyHex));

        // Post to the DIBS system and receive response
        Map<String, String> resp = postToDIBS(parameters, "mpInit");

        if (resp.get("status").equals("ACCEPT")) {
        // Initialization accepted. Check resp.get("redirectUrl") to redirect customer to.
        // Save value of resp.get("walletSessionId") to link future actions to current session data (shipping address, cart content etc.)
        // ...
        System.out.println("MpInit accepted. Response:");
        System.out.println(resp.toString());
        } else if (resp.get("status").equals("DECLINE")) {
        // Initialization declined. Check resp.get("declineReason") for more information
        // ...
        System.out.println("MpInit declined. Response:");
        System.out.println(resp.toString());
        } else {
        // An error happened. Check Check resp.get("declineReason") for more information
        // ...
        System.out.println("An error happened during initialization. Response:");
        System.out.println(resp.toString());
        }
}

/**
 * MasterpassFlow validation. Validates and checks out customers data from Masterpass side for existed session.
 *
 * @param merchantId DIBS Merchant ID / customer number
 * @param walletSessionId Valid Masterpass session token.
 * @param oAuthVerifier An authorization checksum from Masterpass request.
 * @param checkoutResourceUrl An endpoint URL for the Masterpass checkout service.
 * @param macKeyHex The secret HMAC key from DIBS Admin
 */
public void MasterpassFlow_mpValidate(String walletSessionId, String merchantId, String oAuthVerifier, String checkoutResourceUrl, String macKeyHex) {

        // Create JSON object and add parameters
        Map<String, String> parameters = new HashMap();
        parameters.put("merchantId", merchantId);
        parameters.put("walletSessionId", walletSessionId);

        // These values supposed to be returned from Masterpass directly.
        parameters.put("oAuthVerifier", oAuthVerifier);
        parameters.put("checkoutResourceUrl", checkoutResourceUrl);

        parameters.put("MAC", calculateMac(parameters, macKeyHex));

        // Post to the DIBS system and receive response
        Map<String, String> resp = postToDIBS(parameters, "mpValidate");

        if (resp.get("status").equals("ACCEPT")) {
        // Validation accepted. Check resp.get("cardBrandId"), resp.get("cardBrandName") and resp.get("maskedCardNumber") for payment's data.
        // Check  resp.get("shippingAddress") for shipping detailes.
        // Check  resp.get("consumerPhone"), resp.get("consumerEmail") for contact detailes.
        // ...
        System.out.println("MpValidate accepted. Response:");
        System.out.println(resp.toString());
        } else if (resp.get("status").equals("DECLINE")) {
        // Validation declined. Check resp.get("declineReason") for more information
        // ...
        System.out.println("MpValidate declined. Response:");
        System.out.println(resp.toString());
        } else {
        // An error happened. Check Check resp.get("declineReason") for more information
        // ...
        System.out.println("An error happened during validation. Response:");
        System.out.println(resp.toString());
        }
}

/**
 * MasterpassFlow fee calculation. Calculates fee for authorizing payment amount.
 *
 * @param merchantId DIBS Merchant ID / customer number
 * @param walletSessionId Valid Masterpass session token.
 * @param amount The future authorizing amount of the purchase (for e.g. initial amount with extra shipping fee) in smallest unit.
 * @param macKeyHex The secret HMAC key from DIBS Admin
 */
public void MasterpassFlow_calcFee(String walletSessionId, String merchantId, int amount, String macKeyHex) {

        // Create JSON object and add parameters
        Map<String, String> parameters = new HashMap();
        parameters.put("merchantId", merchantId);
        parameters.put("walletSessionId", walletSessionId);
        parameters.put("amount", String.valueOf(amount));

        parameters.put("MAC", calculateMac(parameters, macKeyHex));

        // Post to the DIBS system and receive response
        Map<String, String> resp = postToDIBS(parameters, "calcFee");

        if (resp.get("status").equals("ACCEPT")) {
        // Fee calculated. Check resp.get("amount") for the value.
        } else if (resp.get("status").equals("ERROR")) {
        // An error happened. Check Check resp.get("declineReason") for more information
        // ...
        System.out.println("An error happened during fee calculation. Response:");
        System.out.println(resp.toString());
        }
}

/**
 * MasterpassFlow validation. Validates and checks out customers data from Masterpass side for existed session.
 *
 * @param merchantId DIBS Merchant ID / customer number
 * @param walletSessionId Valid Masterpass session token.
 * @param oAuthVerifier An authorization checksum from Masterpass request.
 * @param checkoutResourceUrl An endpoint URL for the Masterpass checkout service.
 * @param macKeyHex The secret HMAC key from DIBS Admin
 */
public void MasterpassFlow_mpAuthorize(String walletSessionId, String merchantId, int amount, String orderId, String clientIp, String macKeyHex) {

        // Create JSON object and add parameters
        Map<String, String> parameters = new HashMap();
        parameters.put("merchantId", merchantId);
        parameters.put("walletSessionId", walletSessionId);
        parameters.put("amount", String.valueOf(amount));
        parameters.put("orderId", orderId);
        parameters.put("clientIp", clientIp);

        parameters.put("MAC", calculateMac(parameters, macKeyHex));

        // Post to the DIBS system and receive response
        Map<String, String> resp = postToDIBS(parameters, "mpAuthorize");

        if (resp.get("status").equals("ACCEPT")) {
        // Authorization accepted. Check resp.get("transactionId") for transaction ID.
        // resp.get("acquirer") will contain short name of acquirer, that has processed payment.
        // ...
        System.out.println("MpAuthorize accepted. Response:");
        System.out.println(resp.toString());
        } else if (resp.get("status").equals("DECLINE")) {
        // Validation declined. Check resp.get("declineReason") for more information
        // ...
        System.out.println("MpAuthorize declined. Response:");
        System.out.println(resp.toString());
        } else {
        // An error happened. Check Check resp.get("declineReason") for more information
        // ...
        System.out.println("An error happened during authorization. Response:");
        System.out.println(resp.toString());
        }
}


private static List getCartContentList() {
        List<Map<String, String>> cartContent = new ArrayList<>();
        Map item = new HashMap();
        item.put("quantity", "2");
        item.put("unitOfMeasure", "psc");
        item.put("description", "Goods description");
        item.put("amount", "100");
        item.put("vatAmount", "100");
        item.put("productId", "123abc");
        item.put("imageUrl", "http://example.dibs.dk/picture.jpg");
        cartContent.add(item);
        return cartContent;
}

private static String getShippingAddressJsonString() {
        Map parameters = new HashMap();
        parameters.put("firstName", "Tony");
        parameters.put("lastName", "Anonymousen");
        parameters.put("address", "home1");
        parameters.put("address2", "home2");
        parameters.put("postalCode", "7777");
        parameters.put("postalPlace", "Lilleby");
        parameters.put("country", "Denmark");
        parameters.put("email", "customerEmail");
        parameters.put("phone", "customerPhone");
        return parameters.toString();
}
<form method="post" action="https://v2.api.dibspayment.com/merchant/v1/JSON/Transaction/mpInit">
    <input name="request" value='{
  "merchantId":"12345678",
  "currency":"SEK",
  "MAC":"a114861ad3f1eb4645dba4f89022a4a0105e0991121d869c2db96cea9844ebe9",
  "shippingAddress":{
            "firstName":"Tony",
            "lastName":"Anonymousen",
            "address":"home1",
            "address2":"home2",
            "postalCode":"7777",
            "postalPlace":"Lilleby",
            "country":"Denmark",
            "email":"customerEmail",
            "phone":"customerPhone"},
  "amount":"10000",
  "shippingLocationProfile":"1",
  "cartContent":[{
            "quantity":"2",
            "unitOfMeasure":"psc",
            "description":"ACME Rocket Roller skates",
            "amount":"100",
            "vatAmount":"100",
            "productId":"123abc",
            "imageUrl":"http://example.dibs.dk/picture.jpg"}],
  "suppressShippingAddress":"true",
  "acceptableCards":"visa,master",
  "consumerEmail":"merchantsMail@mail.dk",
  "consumerPhone":"112233445566",
  "addFee":"false",
  "test":"true"}' type="hidden" />
  <input type="submit">
</form>
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