Paywin

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

Authentication using a checksum based on parameter values and a secret key

Parameters

Name Format Mandatory Description
merchant_id string yes Merchants unique id.
order_id string yes Merchants order id. Unique id generated by the merchants system.
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 no ‘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’ 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. Required for invoice payments.
customer_street1 string no Street address of customer. Required for invoice payments.
customer_street2 string no Street address of customer
customer_zipcode string no Zip code of customer. Required for invoice payments.
customer_city string no Customers city. Required for invoice payments.
oiTypes string no Names of columns for order rows described left to right. Names are seperated by ';' (semi colon). Valid names are: AMOUNT, DESCRIPTION, ITEMID, ITEMPRICE, QUANTITY, DISCOUNT, VATPERCENT See description: here
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>

Flowchart

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
ITEMIDSpecific ID for the product
ITEMPRICEPrice for one item (without vat)
QUANTITYQuantity of items
DISCOUNTDiscount 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.00T-shirt blue122115.0022.0025.00
18.00T-shirt red1221210.0022.0025.00
-1.00Discount0
25.00Shipping fee0
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",
}

MAC calculation

Sort all parameters in alphabetic order based on the parameter name:

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
Copy all parameter values to a buffer:
https://www.butiken.com/store/show_receipt?order_id=WebOrder- 20231000https://payment.butiken.com/notificationSEK1007WebOrder-2023PAYWIN
Append the merchants secret:
X85LmHiJ98

https://www.butiken.com/store/show_receipt?order_id=WebOrder- 20231000https://payment.butiken.com/notificationSEK1007WebOrder-2023PAYWINX85LmHiJ98
Calculate SHA-256-sum on the string buffer:
0a87b7f2c02f661d9bc982de586346f5dfd6ce0017cf8cdf74067c6518704639

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.)

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

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 void payment

To void a reserved (authorized) amount wihout using the administration interface it's also possible to call it 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 voided.
trans_id string yes Transaction-id that were returned during the payment.
amount string yes Amount to void. 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.

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 credited.
trans_id string yes Transaction-id that were returned during the payment.
amount string yes Amount to credit. 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:

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

Parameters

Name Format Mandatory Description
merchant_id string yes Merchants unique id.
order_id string yes Unique order-id.
trans_id string yes subscription_trans_id that was returned during the payment.
amount string yes Must be 1 unit-of-currency (100 = 1 kr).
currency string yes Default: ‘SEK’
capture_now string yes ‘YES’, means the card is automatically debited after successful authorization. Default: ‘NO’
mac string no SHA-256 checksum.
Response
{
    "trans_id":""
    "mac":"2637ace2f7863540bd3eb477e14ee675b74eb8f38da18b9172f700d215f5afe2",
    "status": "0",
    "error_message": "",
}