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.
Parameters
NAME | FORMAT | MANDATORY | DESCRIPTION |
merchant_id | string | yes | Merchants unique id. |
order_id | string | yes | Order id is a reference generated by the merchants system it has maximum length is 20 chars. Order id should be unique to make it easy to trace payment issues and avoid errors with certain payments. Payments may however reuse order id when customers have issues with owned payment cards and try using another payment card. |
amount | string | yes | The amount of the transaction must be 1 unit-of-currency (100 = 1 kr). |
currency | string | no | Currency to be used in payment: ‘SEK’,‘EUR’,‘DKK’,‘NOK’,‘GBP’,‘USD’,'PLN', 'HRK'. Default ‘SEK’. |
language | string | no | Language in payment window. ‘SE’,’NO’,’DK’,’GB’, 'FI', 'PL', 'HR'. Default ‘SE’. |
accept_url | string | yes | URL where customer is redirected after successful payment. |
cancel_url | string | no | URL where customer is redirected when clicking cancel in payment window. |
callback_url | string | no | URL where payment gateway sends transaction data after successful payment. |
do_3d_secure | string | yes | ‘NO’ disables 3D-Secure. Please note that the banks liability shift is not active if 3D-secure is not used. Default ’YES’. |
pay_method | string | no | To control which payment methods to display in payment window. ‘PAYWIN’ displays all payment methods. ‘CARD’/ 'DEBITCARD'/'CREDITCARD' displays only card entry. ‘BANK’ displays only bank payment. 'INVOICE' displays only invoice payment,'SWISH' displays only swish payment. Default ‘PAYWIN’. |
return_method | string | no | Method to call accept_url. ’POST’ or ’GET’. Default ’POST’. |
prompt_name_entry | string | no | Control if cardholder name entry should be displayed in payment window. ‘YES’ activates fields. Default ‘NO’. |
result_redirect | string | no | ‘NO’ means that customer is displayed a web page after successful payment instead of being redirected to accept_url. Default ‘YES’. |
create_subscription | string | no | ‘YES’ means that an extra parameter ‘subscription_trans_id’ is sent to accept and callback-url if payment is successful. This is a reference to the card number that can be used later to debit the card. Please note that this requires support at the acquiring bank. |
posenv | string | no | Used to define where the transaction originates. This is important to match the acquiring agreement. ‘SSL’, ‘MAIL’, ‘TELEPHONE’ Default: ‘SSL’ |
capture_now | string | no | ‘YES’ means that the payment is flagged for automatic debit. No separate call for debit is required. Default ‘NO’. |
customer_name | string | no | The full name of the customer. |
customer_street1 | string | no | Street address of customer. |
customer_street2 | string | no | Street address of customer |
customer_zipcode | string | no | Zip code of customer. |
customer_city | string | no | Customers city. |
oiTypes | string | no |
Names of columns for order rows described left to right. Names are separated by ';' (semi colon). Valid names are:
AMOUNT, DESCRIPTION, ITEMID, ITEMPRICE, QUANTITY, DISCOUNT, VATPERCENT
|
oiRow(1..n) | string | no | Contains the order row for the payment in the same order as oiTypes. Each row is described by "oiRow1", "oiRow2" and so on. |
mac | string | no | SHA-256 checksum calculated as the example below. |
Example call
<html> <body> <form action="https://<psp-url>/pay" method="post"> <input type="hidden" name="merchant_id" value="1007"> <input type="hidden" name="order_id" value="WebOrder-2023"> <input type="hidden" name="amount" value="1000"> <input type="hidden" name="currency" value="SEK"> <input type="hidden" name="accept_url" value="https://www.butiken.com/store/show_receipt?order_id=WebOrder-2023"> <input type="hidden" name="callback_url" value="https://payment.butiken.com/notification"> <input type="hidden" name="pay_method" value="PAYWIN"> <input type="hidden" name="mac" value="0a87b7f2c02f661d9bc982de586346f5dfd6ce0017cf8cdf74067c6518704639"> </form> </body> </html>
Flow Chart
Order Rows
Column description
Column name | Description |
AMOUNT * | The total amount (without vat) of all items in the row (minus discount if present) |
DESCRIPTION * | The description of the product |
ITEMID | Specific ID for the product |
ITEMPRICE | Price for one item (without vat) |
QUANTITY | Quantity of items |
DISCOUNT | Discount for this row, substract this value in the amount field |
VATPERCENT * | Valid values are: 2500, 1200, 600, 0 |
*Mandatory Fields
Example order rows
<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">
AMOUNT | DESCRIPTION | ITEMID | ITEMPRICE | QUANTITY | DISCOUNT | VATPERCENT |
8.00 | T-shirt blue | 12211 | 5.00 | 2 | 2.00 | 25.00 |
18.00 | T-shirt red | 12212 | 10.00 | 2 | 2.00 | 25.00 |
-1.00 | Discount | 0 | ||||
25.00 | Shipping fee | 0 |
Total amount that has to be sent to paywin is including VAT:
VAT Product 1: 8.00 * 0.25 = 2.00
VAT Product 2: 18.00 * 0.25 = 4.5
VAT Product 3: 0
VAT Product 4: 0
Round(6.5) = 7.00
Paywin amount = (800 + 1800 - 100 + 2500 + 700) = 5700
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:NAME | VALUE | NOTE |
trans_id | 2457 | |
merchant_id | 1007 | |
order_id | WebOrder-2023 | |
amount | 1000 | |
currency | SEK | |
mac | 2637ace2f7863540bd3eb477e1 4ee675b74eb8f38da18b9172f7 00d215f5afe2 | |
status | 0 | |
pay_method | visa | Shows the payment method the customer choosed.(card: visa/mc or bank: handelsbanken/sebprivate/sebbusiness/ nordea/swedbank) |
time | 2012-03-06 09:58:49 | |
error_message | Approved |
Card payments parameters:
NAME | VALUE | NOTE |
card_no | 422222......2222 | |
exp_mon | 12 | |
exp_year | 14 | |
approval_code | AB1624 |
Invoice payments parameters:
NAME | VALUE | NOTE |
invoice_number | 10006 | The invoice number generated. |
invoice_name | Kjell Börje Håkan Zerykier | |
invoice_street1 | Lillavan 7 | |
invoice_zipcode | 52230 | |
invoice_city | Tidaholm | |
invoice_update_delivery_address | NO | If set to YES the address returned is the updated address of consumer. |
Call to callback_url
Same parameters that is sent to accept_url is also sent to callback_url after a successful payment. This is sent directly from the payment gateway. Format of the data is in JSON, example:{ "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", }
The callback_url is also used for asynchronous reporting of sudden and unexpected changes to the payment state. This happens regularly for some payment types or when an unusual and unexpected error occurs in the payment processing. Format of the data is in JSON, for example an error due to a sudden cable break somewhere in the payment network may in response send the following:
{ "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:accept_url | https://www.butiken.com/store/show_receipt?order_id=WebOrder-2023 |
amount | 1000 |
callback_url | https://payment.butiken.com/notification |
currency | SEK |
merchant_id | 1007 |
order_id | WebOrder-2023 |
pay_method | PAYWIN |
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
On payments where capture_now is not set on the call to payment window, you can later call for a debit on the payment. (You can also debit payments through the administration interface.)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/capture
Parameter
Name | Format | Mandatory | Description |
merchant_id | string | yes | Merchants unique id. |
order_id | string | yes | Order-ID that were used during payment that will be debited. |
trans_id | string | yes | Transaction-id that were returned during the payment. |
amount | string | yes | Amount to debit. Must be 1 unit-of- currency (100 = 1 kr). |
mac | string | no | SHA-256 checksum. |
Response
{ "mac":"2637ace2f7863540bd3eb477e14ee675b74eb8f38da18b9172f700d215f5afe2", "status": "0", "error_message": "", }
API void payment
To void a reserved (authorized) amount without 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
Name | Format | Mandatory | Description |
merchant_id | string | yes | Merchants unique id. |
order_id | string | yes | Order-ID that were used during payment that will be debited. |
trans_id | string | yes | Transaction-id that were returned during the payment. |
amount | string | yes | Amount to debit. Must be 1 unit-of- currency (100 = 1 kr). |
mac | string | no | SHA-256 checksum. |
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
Name | Format | Mandatory | Description |
merchant_id | string | yes | Merchants unique id. |
order_id | string | yes | Order-ID that were used during payment that will be debited. |
trans_id | string | yes | Transaction-id that were returned during the payment. |
amount | string | yes | Amount to debit. Must be 1 unit-of- currency (100 = 1 kr). |
mac | string | no | SHA-256 checksum. |
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
Name | Format | Mandatory | Description |
merchant_id | string | yes | Merchants unique id. |
order_id | string | yes | Order-ID that were used during payment that will be debited. |
trans_id | string | yes | Transaction-id that were returned during the payment. |
amount | string | yes | Amount to debit. Must be 1 unit-of- currency (100 = 1 kr). |
mac | string | no | SHA-256 checksum. |
Response
{ "trans_id":"" "mac":"2637ace2f7863540bd3eb477e14ee675b74eb8f38da18b9172f700d215f5afe2", "status": "0", "error_message": "", }