5.2. Form interface

5.2.1. Introduction

This chapter describes how a web shop 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.2. Creating a payment

Creating a payment

5.2.2. Interface versions

Latest and recommended API version is E2. You can still find the documentation for previous API versions S1 and E1 from Deprecated API page.

5.2.3. Migration guide

5.2.3.1. Updates E1 → E2 and S1 → E2

Interface version E2 has replaced the previous versions E1 and S1. E2 is extensible which means that it can be used with or without product and delivery contact data. Interface version upgrade requires definition of fields used in payment creation and return call in fields PARAMS_IN and PARAMS_OUT. Interface version E2 also provides more data when returning from payment process to web shop.

Some of the fields have been renamed or removed but all features supported in E1 and S1 interfaces are still available. Aslo Validation of fields is stricter than with previous versions. Check list of changed fields from the table below.

Table 5.1. Changed payment creation fields comparing E2 to older interfaces

Change typeOld interfaceOld field nameNew E2 Field namenotes
Field renamedE1, S1ORDER_DESCRIPTIONMSG_UI_MERCHANT_PANEL 
Field renamedE1, S1RETURN_ADDRESSURL_SUCCESS 
Field renamedE1, S1CANCEL_ADDRESSURL_CANCEL 
Field renamedE1, S1NOTIFY_ADDRESSURL_NOTIFY 
Field renamedE1, S1CULTURELOCALE 
Field renamedE1, S1PRESELECTED_METHODPAYMENT_METHODS 
Field renamedE1CONTACT_CELLNOPAYER_PERSON_PHONE 
Field renamedE1CONTACT_EMAILPAYER_PERSON_EMAIL 
Field renamedE1CONTACT_FIRSTNAMEPAYER_PERSON_FIRSTNAME 
Field renamedE1CONTACT_LASTNAMEPAYER_PERSON_LASTNAME 
Field renamedE1CONTACT_COMPANYPAYER_COMPANY_NAME 
Field renamedE1CONTACT_ADDR_STREETPAYER_PERSON_ADDR_STREET 
Field renamedE1CONTACT_ADDR_ZIPPAYER_PERSON_ADDR_POSTAL_CODE 
Field renamedE1CONTACT_ADDR_CITYPAYER_PERSON_ADDR_TOWN 
Field renamedE1CONTACT_ADDR_COUNTRYPAYER_PERSON_ADDR_COUNTRY 
Field renamedE1INCLUDE_VATVAT_IS_INCLUDED 
Field renamedE1ITEM_NOITEM_ID 
Field renamedE1ITEM_AMOUNTITEM_QUANTITY 
Field renamedE1ITEM_PRICEITEM_UNIT_PRICE 
Field renamedE1ITEM_TAXITEM_VAT_PERCENT 
Field renamedE1ITEM_DISCOUNTITEM_DISCOUNT_PERCENT 
Field removedE1, S1TYPE- 
Field removedE1, S1PENDING_ADDRESS- 
Field removedE1, S1MODE-Payment page bypass is implemented using field PAYMENT_METHODS
Field removedE1, S1VISIBLE_METHODS-Payment page method visibility selection is implemented using field PAYMENT_METHODS
Field removedE1, S1GROUP- 
Field removedE1CONTACT_TELNO- 
Field removedE1ITEMS- 
New field  PARAMS_INDefines fields sent to payment gateway and used in authcode calculation.
New field  PARAMS_OUT Defines fields returned as a part of URL_SUCCESS, URL_CANCEL and URL_NOTIFY and used in return authcode calculation.
New field  ALGDefines algorithm used in authcode calculation.