Payment window API

This document is intended to describe the communications protocols that are used for communication between the Partner and Direct2Internet.

Production URL: https://{psp-url}/pay

Test URL: https://{psp-url}/pay/test

Merchant admin URL: https://{psp-url}/admin

The value {psp-url} depends on your setup. This can be your company name for instance the test URL could be located at https://pay.mycompany.com/pay/test. If you are setting up a test merchant the psp-url will commonly be pay.direct2internet.com, this means you will commonly make test payment calls to https://pay.direct2internet.com/pay/test and use https://pay.direct2internet.com/admin for accessing the administration gui.

To succesfully integrate a single merchant to D2I PSP you need a merchant id, secret key, user login, user password and the psp-url

Authentication using a checksum is based on the sum of parameter values and a secret key

Status return codes for success and failure are based on ISO8583 status codes ver 1993 with some minor differences. Status return code "000" is success while other return codes are basically failures. 

Note that the parameter order id can be no longer than 20 characters. The exact length of order id depends on how transactions are sent through Mastercard/Visa payment system. Many Mastercard/Visa systems cannot handle more than 20 characters, and in some rare cases only handle as few as 10 characters.

Flowchart

Order rows 

Column description

(* Mandatory fields)

<input type="hidden" name="oiTypes" value="AMOUNT;DESCRIPTION;ITEMID;ITEMPRICE;QUANTITY;DISCOUNT;VATPERCENT">
<input type="hidden" name="oiRow1" value="800;T-shirt blue;12211;500;2;200;2500">
<input type="hidden" name="oiRow2" value="1800;T-shirt red;12212;1000;2;200;2500">
<input type="hidden" name="oiRow3" value="-100;Discount;;;;;0">
<input type="hidden" name="oiRow4" value="2500;Shipping fee;;;;;0">

Call to accept_url

Call to accept_url sends through the customers web browser after a successful payment with HTTP GET or HTTP POST depending on the value of the parameter return_method. The parameters below is example on parameters that is sent:

Card payments parameters:

Invoice payments parameters:

Call to callback_url

{
    "trans_id": "2457", 
    "merchant_id": "1007", 
    "order_id": "WebOrder-2023",
    "amount": "1000",
    "currency": "SEK",
    "mac":"2637ace2f7863540bd3eb477e14ee675b74eb8f38da18b9172f700d215f5afe2",
    "status": "0",
    "card_no": "422222......2222",
    "pay_method": "visa",
    "time": "2012-03-06 09:58:49",
    "approval_code": "AB1624",
    "exp_mon": "12",
    "exp_year": "14",
    "error_message": "Approved",
}

{
    
    "mac":"2637ace2f7863540bd3eb477e56ee675b74eb8f38da18b9172f700d215f5afe2",
    "status": "909",
    "trans_id": "5034523",
    "event": "capture",

}

MAC calculation

Sort all parameters in alphabetic order based on the parameter name. Concatenate all parameter values into a single string. Append the merchant secret key to the string. Calculate SHA256 sum on the string to produce the mac value.

For example using the following parameter in the post call:

After copying all parameter values into a string we get the following:

https://www.butiken.com/store/show_receipt?order_id=WebOrder- 20231000https://payment.butiken.com/notificationSEK1007WebOrder-2023PAYWIN

Append the merchants secret key, in this example X85LmHiJ98, to produce the final string:

https://www.butiken.com/store/show_receipt?order_id=WebOrder- 20231000https://payment.butiken.com/notificationSEK1007WebOrder-2023PAYWINX85LmHiJ98

Calculate SHA-256-sum on the final string:

0a87b7f2c02f661d9bc982de586346f5dfd6ce0017cf8cdf74067c6518704639

The javascript code below can be used to calculate the MAC value. It depends on javascript JQuery, sha256 libs and the html form element included in the example.

<pre>
The following form should be sent to the client

<form action="https://pay.direct2internet.com/pay/test" 
    method="post" id="store-send-params">
 
	<input name="merchant_id" value="your merchant id">
        ... and additional fields..

        .. and include the mac field ..
        <input  id="actMAC" name="mac" value="">

</form>

Secret key (this key should be stored on server and never be sent to client)
<input  id="mac-secret" name="mac-secret" value="a secret key">  

Recalc button
<button onclick="recalcMAC()">Calc Mac</button>
<script>

function recalcMAC() {
        function joinData(data) {
                out = ""
                for(var i=0;i<data.length;i++) {
                        out = out + data[i][1];
                }
                return out;
        }

        var allInputsJQ = $("#store-send-params :input" );
        var allInputs = [];
        for(var i=0;i<allInputsJQ.length;i++) {
                var v = allInputsJQ[i];
                if(v.name!="" && v.name!="mac" && v.value!="") {
                        allInputs.push([v.name,v.value]);
                }
        }

        allInputs.sort();
        var nstr = joinData(allInputs) + $("#mac-secret")[0].value;
        var machash = Sha256.hash(nstr)
        $("#actMAC")[0].value = machash;
}


</script>
</pre>

API debit payment

When calling from an external source you must use html basic access authentication adding the user name and the password in the html header (Authorization field).

Parameters

Response

{
    "mac":"2637ace2f7863540bd3eb477e14ee675b74eb8f38da18b9172f700d215f5afe2",
    "status": "0",
    "error_message": "",
}

API void payment

 To void a reserved (authorized) amount wihout using the administration interface it's also possible to call it externally.

When calling from an external source you must use html basic access authentication adding the user name and the password in the html header (Authorization field).

Address to call externally

URL: https://{psp-url}/admin/void

Parameters

Response

{
    "mac":"2637ace2f7863540bd3eb477e14ee675b74eb8f38da18b9172f700d215f5afe2",
    "status": "0",
    "error_message": "",
}

API credit payment

To credit a debited payment without using the administration interface it’s also possible to call externally.

When calling from an external source you must use html basic access authentication adding the user name and the password in the html header (Authorization field).

Address to call externally

URL: https://{psp-url}/admin/credit

Parameters

Response

{
    "mac":"2637ace2f7863540bd3eb477e14ee675b74eb8f38da18b9172f700d215f5afe2",
    "status": "0",
    "error_message": "",
}

API recurring payment

To authorize/debit on a stored card number it’s possible to call:

When calling from an external source you must use html basic access authentication adding the user name and the password in the html header (Authorization field).

Address to call externally

URL: https://{psp-url}/admin/subscription_auth

Parameters

Response

{
    "trans_id":""
    "mac":"2637ace2f7863540bd3eb477e14ee675b74eb8f38da18b9172f700d215f5afe2",
    "status": "0",
    "error_message": "",
}