AuthorizeCard

The service performs the first part of a credit card transaction (the authorization). The authorization includes e.g. credit- and debit-card control and reservation of the required amount for later capture. Please note that this service requires a PCI certification, as directed by Visa International

The endpoint for the JSON service:

https://v2.api.dibspayment.com/merchant/v1/JSON/Transaction/AuthorizeCard
Note: Handling of card data must be in compliance with the existing PCI rules dictated by your acquirer.

Essential input parameters

Parameter Type Description
MAC * String. Max 62 characters Contains the calculated HMAC value for the used parameters.
amount * Integer

The smallest unit of an amount in the selected currency, following the ISO4217 standard (see the minor unit list here).

Example:

Smallest unit for EUR is "cent" thus setting 'amount="150"' becomes 1,50 EUR
Smallest unit for JPY is "yen" thus setting 'amount="150"' becomes 150 JPY
cardNumber * String. Max 19 characters The credit card number.
clientIp * String. Max 39 characters The customer's IP adress.
currency * String. 3 characters. The currency. Either the numeric or alphabetic ISO4217 code is accepted.
cvc Integer The card verification code.
expMonth Integer The expiration month. E.g. 8 for august and 12 for December.
expYear Integer The expiration year - applicable for some maestro/solo cards.
merchantId * String. Max 36 characters Integration ID from DIBS Admin 2.0.
orderId * String. Max 50 characters The shop’s order number for this particular puchase. It can be seen later when payment is captured, and will in some instances appear on the customer's bank statement (both numerals and letters may be used).

*: Always validated by DIBS

Optional input parameters

ParameterTypeDescription
issueNumberIntegerThe issue number - applicable for some maestro/solo cards.
startMonthIntegerThe start month - applicable for some maestro/solo cards.
startYearIntegerThe start year - applicable for some maestro/solo cards.
testBooleanUse the set up test acquirers.

 

Return parameters

ParameterTypeDescription
acquirerString. Max 36 charactersThe acquirer used for the specific transaction if ACCEPT.
declineReasonString. Max 140 charactersReason for decline or failure of the authorization. Will not be returned for successful calls.
statusString. Max 36 charactersACCEPT/DECLINE/ERROR
transactionIdString. Max 36 charactersThe ID of the transaction is returned if status is ACCEPT.

 

Code examples

Below is an example of a payment authorized using the recommended parameters for the AuthorizeCard JSON service.

<form method="post" action="https://api.dibspayment.com/merchant/v2/JSON/Transaction/AuthorizeCard">
<input name="request" value='{
  "merchantId":"98765432",
  "amount":"123",
  "currency":"208",
  "orderId":"my_orderid-1234",
  "cardNumber":"4711100000000000",
  "expMonth":"6",
  "expYear":"24",
  "cvc":"684",
  "clientIp":"123.321.123.321",
  "MAC":"053b160f1b6e9d941a1c8e0834b2d371b7bdac54dd53e55ee2fcba17f6f511d2",
}' type="hidden" />
</form>
/**
* postToDIBS
* Sends a set of parameters to a DIBS API function
* @param string $paymentFunction The name of the target payment function, e.g. AuthorizeCard
* @param array $params A set of parameters to be posted in key => value format
* @return array
*/
function postToDIBS($paymentFunction, $params) {
  //Create JSON string from array of key => values
  $json_data = json_encode($params);
  
  //Set correct POST URL corresponding to the payment function requested
  switch ($paymentFunction) {
    case "AuthorizeCard":
      $postUrl = "https://v2.api.dibspayment.com/merchant/v1/JSON/Transaction/AuthorizeCard";
      break;
    case "AuthorizeTicket":
      $postUrl = "https://v2.api.dibspayment.com/merchant/v1/JSON/Transaction/AuthorizeTicket";
      break;
    case "CancelTransaction":
      $postUrl = "https://v2.api.dibspayment.com/merchant/v1/JSON/Transaction/CancelTransaction";
      break;
    case "CaptureTransaction":
      $postUrl = "https://v2.api.dibspayment.com/merchant/v1/JSON/Transaction/CaptureTransaction";
      break;
    case "CreateTicket":
      $postUrl = "https://v2.api.dibspayment.com/merchant/v1/JSON/Transaction/CreateTicket";
      break;
    case "RefundTransaction":
      $postUrl = "https://v2.api.dibspayment.com/merchant/v1/JSON/Transaction/RefundTransaction";
      break;
    case "Ping":
      $postUrl = "https://v2.api.dibspayment.com/merchant/v1/JSON/Transaction/Ping";
      break;
    default:
      echo("Wrong input paymentFunctions to postToDIBS");
      $postUrl = null;
  }
  
  //Use Curl to communicate with the server.
  $ch = curl_init();
  curl_setopt($ch, CURLOPT_URL,$postUrl);
  curl_setopt($ch, CURLOPT_POST, 1);
  //curl_setopt($ch, CURLOPT_SSLVERSION, CURL_SSLVERSION_TLSv1_2); //Can be uncommented to specify SSL security level
  curl_setopt($ch, CURLOPT_POSTFIELDS, "request=" . $json_data);
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_CONNECTTIMEOUT, 15);
  $json_output = curl_exec ($ch);
  
  //Check for errors in the Curl operation
  if (curl_errno($ch) != 0) {
    error_log("Curl failed:");
    error_log(curl_getinfo($ch));
    error_log(curl_errno($ch));
    error_log(curl_error($ch));
  }
  curl_close ($ch);
  
  //Convert JSON server output to array of key => values
  $res = json_decode(urldecode($json_output), true);
  
  return $res;
}
/**
* AuthorizeCard
* Authorizes a given card using the AuthorizeCard JSON service
* @param int @amount The amount of the purchase in smallest unit
* @param int @cardNumber The customers cardnumber
* @param string @clientIp The customers IP address
* @param string @currency The currency either in numeric or string format (e.g. 208/DKK)
* @param int @cvc Card Verification Value, 3 digit
* @param string @expMonth Expiry month of the card, 1 or 2 digits (e.g. 6/06)
* @param string @expYear Expiry year of the card, 2 digits (e.g. 18 for 2018)
* @param int @merchantId DIBS Merchant ID / customer number
* @param string @orderId The shops order ID for the purchase
* @param string @K The secret HMAC key from DIBS Admin
*/
function AuthorizeCard($amount, $cardNumber, $clientIp, $currency, $cvc, $expMonth, $expYear, $merchantId, $orderId, $K) {
  //Create message array consisting of all input parameters
  $message = array(
    "merchantId" => $merchantId,
    "amount" => $amount,
    "currency" => $currency,
    "orderId" => $orderId,
    "cardNumber" => $cardNumber,
    "expMonth" => $expMonth,
    "expYear" => $expYear,
    "cvc" => $cvc,
    "clientIp" => $clientIp,
  );
  
  //Uncomment following line for test mode to be active
  $message["test"] = "true";
  
  //Calculate MAC value for request
  $mac = calculateMac($message, $K); 
  $message["MAC"] = $mac;
  
  //Post to the DIBS system
  $res = postToDIBS("AuthorizeCard", $message);
  
  if ($res["status"] == "ACCEPT") {
    //Payment accepted. Check $res["transactionId"] for transaction ID.
    //Insert own code to update shop system
  } else if ($res["status"] == "DECLINE") { 
    //Check $res["declineReason"] for more information.
    //Insert own code to update shop system
  } else {
    //An error happened. Check $res["declineReason"] for more information.
    //Insert own code to update shop system
  }
}
using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
using System.Net;
using System.Web;
using System.IO;
using Newtonsoft.Json;
using System.Globalization;
using System.Security.Cryptography;
/**
* postToDIBS
* Sends a set of parameters to a DIBS API function
* @param paymentFunction The name of the target payment function, e.g. AuthorizeCard
* @param data A set of parameters to be posted in Dictionary<string, string> format
* @return Dictionary<string, string>
*/
static Dictionary<string, string> postToDIBS(string paymentFunction, Dictionary<string, string> data)  {
  //Set correct POST URL corresponding to the payment function requested
  string postUrl = "https://v2.api.dibspayment.com/merchant/v1/JSON/Transaction/";
  switch (paymentFunction) {
    case "AuthorizeCard":
      postUrl += "AuthorizeCard";
      break;
    case "AuthorizeTicket":
      postUrl += "AuthorizeTicket";
      break;
    case "CancelTransaction":
      postUrl += "CancelTransaction";
      break;
    case "CaptureTransaction":
      postUrl += "CaptureTransaction";
      break;
    case "CreateTicket":
      postUrl += "CreateTicket";
      break;
    case "RefundTransaction":
      postUrl += "RefundTransaction";
      break;
    case "Ping":
      postUrl += "Ping";
      break;
    default:
      System.Console.WriteLine("Wrong input paymentFunctions to postToDIBS");
      postUrl = null;
      break;
  }

  //Create JSON string from Dictionary<string, string>
  string json_data = JsonConvert.SerializeObject(data);
  json_data = "request=" + json_data;

  ASCIIEncoding encoding = new ASCIIEncoding();
  byte[] json_data_encoded = encoding.GetBytes(json_data);

  //Using HttpWebRequest for posting and receiving response
  HttpWebRequest con = (HttpWebRequest)WebRequest.Create(postUrl);

  con.Method = "POST";
  con.ContentType = "application/x-www-form-urlencoded";
  con.ContentLength = json_data_encoded.Length;
  con.Timeout = 15000; //15 seconds timeout

  //Send the POST request
  using (Stream stream = con.GetRequestStream()) {
    stream.Write(json_data_encoded, 0, json_data_encoded.Length);
  }

  //Receive response
  Dictionary<string, string> res_dict = new Dictionary<string, string> {};
  try {
    HttpWebResponse response = (HttpWebResponse)con.GetResponse();
    string responseString = new StreamReader(response.GetResponseStream()).ReadToEnd();
    responseString = HttpUtility.UrlDecode(responseString);
    //Create Dictionary<string,string> hashmap from response JSON data
    res_dict = JsonConvert.DeserializeObject<Dictionary<string, string>>(responseString);
  }
  catch (System.Net.WebException) {
    Console.WriteLine("Timeout occured...");
  }
  return res_dict;
}
using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
using System.Net;
using System.IO;
using Newtonsoft.Json;
using System.Globalization;
using System.Security.Cryptography;
/**
* AuthorizeCard
* Authorizes a given card using the AuthorizeCard JSON service.
* @param amount The amount of the purchase in smallest unit
* @param cardNumber The customers cardnumber
* @param clientIp The customers IP address
* @param currency The currency either in numeric or string format (e.g. 208/DKK)
* @param merchantId DIBS Merchant ID / customer number
* @param orderId The shops order ID for the purchase
* @param cvc Card Verification Value, 3 digit
* @param expMonth Expiry month of the card, 1 or 2 digits (e.g. 6/06)
* @param expYear Expiry year of the card, 2 digits (e.g. 18 for 2018)
* @param K The secret HMAC key from DIBS Admin
**/
static void AuthorizeCard(string amount, string cardNumber, string clientIp, string currency, string cvc, string expMonth, string expYear, string merchantId, string orderId, string K) {
  //Create Dictionary<string, string> object with used values. Can be modified to contain additional parameters.
  Dictionary<string, string> message = new Dictionary<string, string> {
    {"amount", amount},
    {"cardNumber", cardNumber},
    {"clientIp", clientIp},
    {"currency",currency},
    {"cvc", cvc},
    {"expMonth", expMonth},
    {"expYear", expYear},
    {"merchantId", merchantId},
    {"orderId", orderId}
  };

  //Uncomment following line for test mode to be active
  message.Add("test", "true");

  //Calculate mac and add it
  string mac = calculateMac(message, K);
  message.Add("MAC", mac);

  //Use postToDIBS() function to send the parameters and receive the response
  Dictionary<string, string> res = postToDIBS("AuthorizeCard", message);

  System.Console.WriteLine("Authorization done.");
  System.Console.WriteLine("Response:");
  foreach (KeyValuePair<string, string> r in res) {
    System.Console.WriteLine("{0} = {1}", r.Key, r.Value);
  }
  System.Console.WriteLine();
}
/**
 * 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 {
			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
 */
/**
 * AuthorizeCard Authorizes a given card using the AuthorizeCard JSON service.
 *
 * @param amount The amount of the purchase in smallest unit
 * @param cardNumber The customers cardnumber
 * @param clientIp The customers IP address
 * @param currency The currency either in numeric or string format (e.g. 208/DKK)
 * @param merchantId DIBS Merchant ID / customer number
 * @param orderId The shops order ID for the purchase
 * @param cvc Card Verification Value, 3 digit
 * @param expMonth Expiry month of the card, 1 or 2 digits (e.g. 6/06)
 * @param expYear Expiry year of the card, 2 digits (e.g. 18 for 2018)
 * @param macKeyHex The secret HMAC key from DIBS Admin
 */
public void AuthorizeCard(int amount, String cardNumber, String clientIp, String currency, String merchantId, String orderId, String cvc, int expMonth, int expYear, String macKeyHex) {
  // Create JSON object and add parameters
  Map<String, String> parameters = new HashMap<String, String>();
  parameters.put("amount", String.valueOf(amount));
  parameters.put("cardNumber", cardNumber);
  parameters.put("clientIp", clientIp);
  parameters.put("currency", currency);
  parameters.put("merchantId", merchantId);
  parameters.put("orderId", orderId);
  parameters.put("cvc", cvc);
  parameters.put("expMonth", String.valueOf(expMonth));
  parameters.put("expYear", String.valueOf(expYear));

  // Uncomment following line for test mode to be active
  parameters.put("test", String.valueOf(Boolean.TRUE));

  // 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, "AuthorizeCard");

  if (resp.get("status").equals("ACCEPT")) {
    // Authorization accepted. Check resp.get("transactionId") for transaction ID
    // ...
    System.out.println("Auth accepted. Response:");
    System.out.println(resp.toString());
  } else if (resp.get("status").equals("DECLINE")) {
    // Authorization declined. Check resp.get("declineReason") for more information
    // ...
    System.out.println("Auth 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 Auth. Response:");
    System.out.println(resp.toString());
  }
}
Do you have 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