5.3. Form interface

5.3.1. Introduction

This chapter describes how a webshop communicates with the payment gateway with Form interface. When using the FORM interface, the payment data is created as a form on the web applications page. The consumer sends this form to the payment service. The payment is then completed in the web browser as an immediate result of the customer's actions.

Figure 5.3. Creating a payment

Creating a payment

5.3.2. Interface versions

Latest interface version are S1 and E1. Interface version S1 is somewhat easier to implement compared to version E1. S1 includes less data to be delivered to Paytrail service. E1 version implementation adds customer information (name, address, etc.) and detailed product information to S1 implementation.

Using interface version E1 over S1 gives these benefits:

  • Paytrail Merchant's Panel shows customer data and detailed product information with the payment data
  • Invoicing and instalment options (more specifically Klarna and Collector)
  • Payment method fees can be defined (fixed amount or percentage of price for a specified payment method).

5.3.3. Change versions

5.3.3.1. Updates 5.1 → E1 and 4.1 → S1

Interface version E1 has replaced the previous version 5.1 and interface version S1 has replaced previous version 4.1. Both extensions include the same set of changes (new fields). Interface version upgrade requires to include optional fields PENDING_ADDRESS, PRESELECTED_METHOD, MODE, VISIBLE_METHODS and GROUP in hash calculation. Please check the positions of these fields in the listing provided in next chapter. Return call (RETURN_ADDRESS or CANCEL_ADDRESS) implementation has not changed in this update.

5.3.4. Fields to be sent to payment gateway

5.3.4.1. Interface version E1

Following form describes fields to be sent to payment gateway. Field form is either A, N, AN or F:

Table 5.2. Field descriptions

FormDescription
AAlphabetic
NNumeric
ANAlphanumeric
FFloating point number. Floating point numbers are expressed with two decimals at most.


Supported character sets are UTF-8 and ISO-8859-1. These character sets cannot be mixed.

Field necessity is marked in column Required/Optional.

Note

Values may not contain "|" characters (pipe, vertical bar). These values must be removed or replaced by other character before sending to Paytrail service. If you need to use "|" in URLs, we recommend having URL parameter values encoded. Especially "|" must be replaced with string %7C.

Note

It is not recommended to use REFERENCE_NUMBER field unless there is a justifiable requirement for it. Field allows to pass a webshop generated reference number for reference payment through Paytrail service. Field value is only used with payment methods which are used with merchant's own contracts using only technical implementation from Paytrail. With other payment methods (or when REFERENCE_NUMBER is omitted) Paytrail always generates reference number automatically.

Table 5.3. Form interface: Fields to be sent to payment gateway with interface version E1

Field nameDescriptionFormMax lengthRequired/Optional
MERCHANT_IDMerchant ID is the merchant identification number given by Paytrail. Merchant ID consists of digits only and it can be found from material sent to merchant by Paytrail.N11R
ORDER_NUMBEROrder number is used to identify one transaction from another in the webshop software.AN64R
REFERENCE_NUMBERBy default, the reference number is generated automatically. For payment methods which are used as an interface, the reference number can be given in this field to be delivered to bank's service instead of the automatically generated one.N50O
ORDER_DESCRIPTIONAny additional written information can be sent to Payment Gateway. It can be used to store order information like customer address, product information, etc. Order description is only visible through Merchant's Panel.AN65000O
CURRENCYCurrency. Only EUR is accepted for Finnish banks and credit cards.A3R
RETURN_ADDRESSURL where customer is redirected after successful payment.AN2048R
CANCEL_ADDRESSURL where customer is redirected after failed or cancelled payment.AN2048R
PENDING_ADDRESSCurrently not in use.AN2048O
NOTIFY_ADDRESSURL to be called when the payment has been marked as paid. This URL is called with same GET parameters as RETURN_ADDRESS when the payment is marked as paid. Note that NOTIFY_ADDRESS request is done by Paytrail server and thus customer's browser session does not exist in this request. NOTIFY_ADDRESS request is normally made within a couple of minutes from completing the payment.AN2048O
TYPEInterface version. Newest versions are S1 and E1.AN3R
CULTURECulture affects the default language and how amounts are shown on payment method selection page. Available cultures are "fi_FI", "sv_SE" and "en_US". The default culture is "fi_FI".A5O
PRESELECTED_METHOD If payment method selection is done in the webshop, payment method is delivered in this field.

Table 5.4. Payment method IDs for payment page bypass

1Nordea
2Osuuspankki
3Danske Bank
5Ålandsbanken
6Handelsbanken
9Paypal
10S-Pankki
11Klarna, Invoice
12Klarna, Installment
18Jousto
30Visa
31MasterCard
34Diners Club
35JCB
36Paytrail account
50Aktia
51POP Pankki
52Säästöpankki
53Visa (Nets)
54MasterCard (Nets)
55Diners Club (Nets)
56American Express (Nets)
60Collector Bank
61Oma Säästöpankki

N2O
MODE Paytrail's service can be bypassed when preselected payment method is delivered (PRESELECTED_METHOD). Use requires agreement on use with Paytrail.

Table 5.5. MODE values

1Normal service
2Bypassing Paytrail's payment method selection page

N1O
VISIBLE_METHODSThis can be used to decide what payment methods are shown on the payment page. Payment method values are to be brought separated with comma. Values can be seen above in PRESELECTED_METHOD -section.AN64O
GROUPCurrently not in use.AN16O
CONTACT_TELNOPayer's telephone number.AN64O
CONTACT_CELLNOPayer cellphone number (optional, but using Klarna requires this or payer telephone number. If neither is defined Klarna will be hidden).AN64O (Using Klarna requires this or CONTACT_TELNO)
CONTACT_EMAILPayer's email.AN255R
CONTACT_FIRSTNAMEPayer's first name.AN64R
CONTACT_LASTNAMEPayer's last name.AN64R
CONTACT_COMPANYPayer's company.AN128O
CONTACT_ADDR_STREETPayer's street address.AN128R
CONTACT_ADDR_ZIPPayer's postal code.AN16R
CONTACT_ADDR_CITYPayer's city.AN64R
CONTACT_ADDR_COUNTRYPayer home country. Data is given using ISO-3166-1 standard values. For example, Finland is FI and Sweden is SE. These values are not case sensitive. This information is used for checking credit history and thus it is required.A2R
INCLUDE_VAT Whether VAT is included in prices given in ITEM records. Value 1 indicates that VAT is included in given price. Value 0 indicates that price does not include VAT. Use the webshop native value to avoid rounding errors. That means, if product prices are saved without VAT in the webshop software, use 0 and if prices are saved with VAT, use 1. If using the Collector payment method, the value MUST be 1. Collector will not be available if the value is 0. N1R
ITEMSNumber of order rows. Corresponding product rows must be given in form.N (max. 500)3R

In addition to these, order rows can be brought to Paytrail service using the following repetitive fields. First order item row is brought with index 0 (for example name of the first product in field ITEM_TITLE[0]). Number of item rows should match the value brought in field ITEMS.

Table 5.6. Form interface: Product details for interface version E1

Field nameDescriptionFormLength max.Required / Optional
ITEM_TITLE[N]Free field for product name. Product name will be shown in Merchant's Panel and it is used in Klarna service as a name for product.AN255R/O (ITEM TITLE or ITEM_NO is required)
ITEM_NO[N]Optional product number. This is shown in Merchant's Panel with the product. This might help fixing the product rows to actual products.AN16R/O (ITEM TITLE or ITEM_NO is required)
ITEM_AMOUNT[N] Number of products. Usually the value is 1 (required). If usind the Collector payment method, this value must be a whole number. If a decimal number such as 0.5 is used, the Collector payment method will be hidden. 1.0 is accepted. F10R
ITEM_PRICE[N]The price for a single product. If INCLUDE_VAT=0, this is price not including VAT. If INCLUDE_VAT=1, this price includes VAT. Price may be negative value if discount is given. Payment total must be positive. Total sum of the product prices must be at least 0.65€.F10R
ITEM_TAX[N]Tax percent used for product.F10R
ITEM_DISCOUNT[N]If discount is given, this field can be used. Percent is a number between 0 and 100. Default value is 0.F10O
ITEM_TYPE[N]Type can be defined for each product row. Type 1 means normal product row. Type 2 is used for shipment costs. Type 3 is used for handling costs. Default value is 1.N1O

5.3.4.2. Interface version S1

See field specification from chapter Interface version E1.

Table 5.7. Form interface: Fields to be sent to payment gateway with interface version S1

Field nameDescriptionFormLength max.Required / Optional
MERCHANT_IDMerchant ID is merchant identification number given by Paytrail. Merchant ID consists of digits only and it can be found from material sent to merchant by Paytrail.N11R
AMOUNTPrice is given in euros and cents. Price is given without currency type and decimals are separated with a dot. Price must contain two decimals. Example: 15.50. Minimum price accepted by the service is 0.65€.F10R
ORDER_NUMBEROrder number is used to identify one transaction from another in the webshop software.AN64R
REFERENCE_NUMBERBy default, the reference number is generated automatically. For payment methods which are used as an interface, the reference number can be given in this field to be delivered to bank's service instead of the automatically generated one.N50O
ORDER_DESCRIPTIONAny additional written information can be sent to Payment Gateway. It can be used to back up order information like customer address, product information etc. Order description is only visible through Merchant's Panel.AN65000O
CURRENCYCurrency. Only EUR is accepted for Finnish banks and credit cards.A3R
RETURN_ADDRESSURL where customer is redirected after successful payment.AN2048R
CANCEL_ADDRESSURL where customer is redirected after failed or cancelled payment.AN2048R
PENDING_ADDRESSCurrently not in use.AN2048O
NOTIFY_ADDRESSURL to be called when the payment has been marked as paid. This URL is called with same GET parameters as RETURN_ADDRESS when the payment is marked as paid. Note that NOTIFY_ADDRESS request is done by Paytrail server and so customer's browser session is not available in that call. NOTIFY_ADDRESS request is normally done within a couple of minutes from completing the payment.AN2048O
TYPEInterface version. Newest versions are S1 and E1.AN3R
CULTURECulture affects on default language and how amounts are shown on payment method selection page. Available cultures are "fi_FI", "sv_SE" and "en_US". The default culture is always "fi_FI".A5O
PRESELECTED_METHOD If payment method selection is done in the webshop, payment method is delivered in this field.

Table 5.8. Payment method IDs for payment page bypass

1Nordea
2Osuuspankki
3Danske Bank
5Ålandsbanken
6Handelsbanken
9Paypal
10S-Pankki
11Klarna, Invoice
12Klarna, Installment
18Jousto
30Visa
31MasterCard
34Diners Club
35JCB
36Paytrail account
50Aktia
51POP Pankki
52Säästöpankki
53Visa (Nets)
54MasterCard (Nets)
55Diners Club (Nets)
56American Express (Nets)
60Collector Bank
61Oma Säästöpankki

N2O
MODE Paytrail's service can be bypassed when preselected payment method is delivered (PRESELECTED_METHOD). Use requires agreement on use with Paytrail.

Table 5.9. MODE values

1Normal service
2Bypassing Paytrail's payment method selection page

N1O
VISIBLE_METHODSThis can be used to decide what payment methods are shown on the payment page. Payment method values are to be brought separated with comma. Values can be seen above in PRESELECTED_METHOD -section.AN64O
GROUPCurrently not in use.AN16O

5.3.5. Calculating the payment fingerprint (AUTHCODE)

AUTHCODE is calculated by joining all fields in the order they are described in this document. Fields are joined by placing the "|" character (pipe, vertical bar) between each two fields. If any of the fields is left out, empty string should be used. In this case the string will contain two or more adjacent "|" characters. AUTHCODE is formed from this string by calculating an MD5 sum. This sum is converted to its 32 character hexadecimal form and lowercase letters are capitalized.

Example 5.11. Calculating the payment fingerprint with form data for interface version E1

This example covers sending payment information in the most complete form. In this case we are using the interface version E1. We recommend using Paytrail gateway in the way described here. Example 2 is a simplified example which does not offer as many features as this one. This form is placed in the webshop by the payment method selection. The form shows the payment button currently in use and moves customer to payment service payment selection page when clicked. All fields are listed in this example, including optional unnecessary fields for better clarity. They can be removed from the form. Please note that in AUTHCODE calculation all fields, including optional parameters must always be used!

<form action="https://payment.paytrail.com/" method="post">
  <input name="MERCHANT_ID" type="hidden" value="13466">
  <input name="ORDER_NUMBER" type="hidden" value="123456">
  <input name="REFERENCE_NUMBER" type="hidden" value="">
  <input name="ORDER_DESCRIPTION" type="hidden" value="Testitilaus">
  <input name="CURRENCY" type="hidden" value="EUR">
  <input name="RETURN_ADDRESS" type="hidden" value="http://www.esimerkki.fi/success">
  <input name="CANCEL_ADDRESS" type="hidden" value="http://www.esimerkki.fi/cancel">
  <input name="PENDING_ADDRESS" type="hidden" value="">
  <input name="NOTIFY_ADDRESS" type="hidden" value="http://www.esimerkki.fi/notify">
  <input name="TYPE" type="hidden" value="E1">
  <input name="CULTURE" type="hidden" value="fi_FI">
  <input name="PRESELECTED_METHOD" type="hidden" value="">
  <input name="MODE" type="hidden" value="1">
  <input name="VISIBLE_METHODS" type="hidden" value="">
  <input name="GROUP" type="hidden" value="">
  <input name="CONTACT_TELNO" type="hidden" value="0412345678">
  <input name="CONTACT_CELLNO" type="hidden" value="0412345678">
  <input name="CONTACT_EMAIL" type="hidden" value="esimerkki@esimerkki.fi">
  <input name="CONTACT_FIRSTNAME" type="hidden" value="Matti">
  <input name="CONTACT_LASTNAME" type="hidden" value="Meikäläinen">
  <input name="CONTACT_COMPANY" type="hidden" value="">
  <input name="CONTACT_ADDR_STREET" type="hidden" value="Testikatu 1">
  <input name="CONTACT_ADDR_ZIP" type="hidden" value="40500">
  <input name="CONTACT_ADDR_CITY" type="hidden" value="Jyväskylä">
  <input name="CONTACT_ADDR_COUNTRY" type="hidden" value="FI">
  <input name="INCLUDE_VAT" type="hidden" value="1" />
  <input name="ITEMS" type="hidden" value="2">
  <input name="ITEM_TITLE[0]" type="hidden" value="Product #101">
  <input name="ITEM_NO[0]" type="hidden" value="101">
  <input name="ITEM_AMOUNT[0]" type="hidden" value="1">
  <input name="ITEM_PRICE[0]" type="hidden" value="10.00">
  <input name="ITEM_TAX[0]" type="hidden" value="22.00">
  <input name="ITEM_DISCOUNT[0]" type="hidden" value="0">
  <input name="ITEM_TYPE[0]" type="hidden" value="1">
  <input name="ITEM_TITLE[1]" type="hidden" value="Product #202">
  <input name="ITEM_NO[1]" type="hidden" value="202">
  <input name="ITEM_AMOUNT[1]" type="hidden" value="2">
  <input name="ITEM_PRICE[1]" type="hidden" value="8.50">
  <input name="ITEM_TAX[1]" type="hidden" value="22.00">
  <input name="ITEM_DISCOUNT[1]" type="hidden" value="0">
  <input name="ITEM_TYPE[1]" type="hidden" value="1">
  <input name="AUTHCODE" type="hidden" value="B5565364D8765E54A944084C0E9057F8">
  <input type="submit" value="Pay here">
</form>
            

Following form describes all fields for interface version E1 with values shown in form example.

Table 5.10. Fields to be sent to payment gateway with interface version E1

Field nameValue
Merchant authentication hash6pKF4jkv97zmqBJ3ZL8gUw5DfT2NMQ
MERCHANT_ID13466
ORDER_NUMBER123456
REFERENCE_NUMBER 
ORDER_DESCRIPTIONTest order
CURRENCYEUR
RETURN_ADDRESShttp://www.esimerkki.fi/success
CANCEL_ADDRESShttp://www.esimerkki.fi/cancel
PENDING_ADDRESS 
NOTIFY_ADDRESShttp://www.esimerkki.fi/notify
TYPEE1
CULTUREfi_FI
PRESELECTED_METHOD 
MODE1
VISIBLE_METHODS 
GROUP 
CONTACT_TELNO0412345678
CONTACT_CELLNO0412345678
CONTACT_EMAILesimerkki@esimerkki.fi
CONTACT_FIRSTNAMEMatti
CONTACT_LASTNAMEMeikäläinen
CONTACT_COMPANY 
CONTACT_ADDR_STREETTestikatu 1
CONTACT_ADDR_ZIP40500
CONTACT_ADDR_CITYJyväskylä
CONTACT_ADDR_COUNTRYFI
INCLUDE_VAT1
ITEMS2
ITEM_TITLE[0]Product #101
ITEM_NO[0]101
ITEM_AMOUNT[0]1
ITEM_PRICE[0]10.00
ITEM_TAX[0]22.00
ITEM_DISCOUNT[0]0
ITEM_TYPE[0]1
ITEM_TITLE[1]Product #202
ITEM_NO[1]202
ITEM_AMOUNT[1]2
ITEM_PRICE[1]8.50
ITEM_TAX[1]22.00
ITEM_DISCOUNT[1]0
ITEM_TYPE[1]1

Now the string to be used for AUTHCODE calculation is formed by joining the fields above:

6pKF4jkv97zmqBJ3ZL8gUw5DfT2NMQ|13466|123456||Testitilaus|EUR|http://www.esimerkki.fi/success|http://www.esimerkki.fi/cancel||http://www.esimerkki.fi/notify|E1|fi_FI||1|||0412345678|0412345678|esimerkki@esimerkki.fi|Matti|Meikäläinen||Testikatu 1|40500|Jyväskylä|FI|1|2|Product #101|101|1|10.00|22.00|0|1|Product #202|202|2|8.50|22.00|0|1

MD5 sum is counted from this string: b5565364d8765e54a944084c0e9057f8 (UTF-8) or 220ce506b90d1980f88e6522b525918c (ISO-8859-1)

Lowercase letters are then capitalized to get the final AUTHCODE value: B5565364D8765E54A944084C0E9057F8 (UTF-8) or 220CE506B90D1980F88E6522B525918C (ISO-8859-1)


Example 5.12. Calculating the payment fingerprint with form data for interface version S1

This example shows how to use the gateway service without additional payment information. In this case we are using interface version S1. In most cases the additional payment information should be used (see example above). This form is placed in the webshop by the payment method selection. The form shows the payment button currently in use and moves customer to payment service payment selection page when clicked. All fields are listed in this example, including optional unnecessary fields for better clarity. They can be removed from form. Please note that in AUTHCODE calculation all fields, including optional parameters must always be used!

<form action="https://payment.paytrail.com/" method="post">
  <input name="MERCHANT_ID" type="hidden" value="13466">
  <input name="AMOUNT" type="hidden" value="99.90">
  <input name="ORDER_NUMBER" type="hidden" value="123456">
  <input name="REFERENCE_NUMBER" type="hidden" value="">
  <input name="ORDER_DESCRIPTION" type="hidden" value="Testitilaus">
  <input name="CURRENCY" type="hidden" value="EUR">
  <input name="RETURN_ADDRESS" type="hidden" value="http://www.esimerkki.fi/success">
  <input name="CANCEL_ADDRESS" type="hidden" value="http://www.esimerkki.fi/cancel">
  <input name="PENDING_ADDRESS" type="hidden" value="">
  <input name="NOTIFY_ADDRESS" type="hidden" value="http://www.esimerkki.fi/notify">
  <input name="TYPE" type="hidden" value="S1">
  <input name="CULTURE" type="hidden" value="fi_FI">
  <input name="PRESELECTED_METHOD" type="hidden" value="">
  <input name="MODE" type="hidden" value="1">
  <input name="VISIBLE_METHODS" type="hidden" value="">
  <input name="GROUP" type="hidden" value="">
  <input name="AUTHCODE" type="hidden" value="270729B19016F94BE5263CA5DE95E330">
  <input type="submit" value="Siirry maksamaan">
</form>
            

The last hidden field, AUTHCODE, in the listing above is calculated as follows. Like in the example above, join form fields in the order they are mentioned in this document and use the "|" character (pipe, vertical bar) between the fields. The values used in this example are shown in the next table:

Table 5.11. Fields to be sent to payment gateway with interface version S1

Field nameValue
Merchant authentication hash6pKF4jkv97zmqBJ3ZL8gUw5DfT2NMQ
MERCHANT_ID13466
AMOUNT99.90
ORDER_NUMBER123456
REFERENCE_NUMBER 
ORDER_DESCRIPTIONTestitilaus
CURRENCYEUR
RETURN_ADDRESShttp://www.esimerkki.fi/success
CANCEL_ADDRESShttp://www.esimerkki.fi/cancel
PENDING_ADDRESS 
NOTIFY_ADDRESShttp://www.esimerkki.fi/notify
TYPES1
CULTUREfi_FI
PRESELECTED_METHOD 
MODE1
VISIBLE_METHODS 
GROUP 

Now the string to be used for AUTHCODE calculation is formed by joining the fields above:

6pKF4jkv97zmqBJ3ZL8gUw5DfT2NMQ|13466|99.90|123456||Testitilaus|EUR|http://www.esimerkki.fi/success|http://www.esimerkki.fi/cancel||http://www.esimerkki.fi/notify|S1|fi_FI||1||

MD5 sum is counted from this string: 270729b19016f94be5263ca5de95e330

Lowercase letters are then capitalized to get the final AUTHCODE value: 270729B19016F94BE5263CA5DE95E330

Please note that this exmple did not include any characters that are handled differently in charsets UTF-8 and ISO-8859-1. Because of this, the AUTHCODE is the same not depending on which charset is used.