6.2. Interface description

6.2.1. Common

The Channel URL is https://payment.paytrail.com/channel-payment

The purchase bundle is sent to the service as a POST query. When a payment is completed, the customer will be redirected back to the return address defined by the payment channel. The parameters used to determine that payment has been successful are also sent to the return address.

6.2.2. Fields to send

The tables below describe the fields that should be sent to Paytrail’s payment service. If the maximum lengths are exceeded, the payment will not be accepted.

The format of the fields is N, F or AN. N stands for an integer value and F for decimal number. Decimal numbers have a maximum of two decimals. Decimal delimiter is a dot. AN stands for alphanumeric value meaning that the value of the field can include any characters. Supported character sets are UTF-8 or ISO-8859-1. Character sets cannot be mixed.

Note

No value for field should contain “|”, the vertical bar. Pipe characters should be replaced by another character before the data is sent to Paytrail’s payment service. If special characters have to be used in the return address, we recommend encoding the return address URL (e.g. function urlencode in PHP). E.g. pipe character has to be replaced with a string “%C7”.

Table column “Mandatory/Optional” tells if the field has to be sent or if it is optional. We recommend using the NOTIFY_ADDRESS field even though it's optional.

Table 6.1. Fields to be sent to the payment gateway

FieldNameMax lengthFormatMandatory / optional
Channel IDCHANNEL_ID11NM
Order numberORDER_NUMBER64ANM
CurrencyCURRENCY3ANM
Return address / Successful paymentRETURN_ADDRESS255ANM
Return address / Cancelled paymentCANCEL_ADDRESS255ANM
Notify addressNOTIFY_ADDRESS255ANM
Interface versionVERSION2NM
Culture code / Payment page languageCULTURE5ANO
Preselected payment method for Payment page bypass Payment methods

Table 6.2. Payment method IDs for payment page bypass

1Nordea
2Osuuspankki
3Danske Bank
5Ålandsbanken
6Handelsbanken
10S-Pankki
50Aktia
51POP Pankki
52Säästöpankki
53Visa (Nets)
54MasterCard (Nets)
61Oma Säästöpankki

PRESELECTED_METHOD2ANO
Authentication codeAUTHCODE32ANM
Payer’s telephone numberCONTACT_TELNO64ANO
Payer’s cellphone numberCONTACT_CELLNO64ANO
Payer’s email addressCONTACT_EMAIL255ANM
Payer’s first nameCONTACT_FIRSTNAME64ANM
Payer’s last nameCONTACT_LASTNAME64ANM
Payer’s companyCONTACT_COMPANY128ANO
Payer's street addressCONTACT_ADDR_STREET128ANM
Payer’s zip codeCONTACT_ADDR_ZIP16NM
Payer’s cityCONTACT_ADDR_CITY64ANM
Payer’s countryCONTACT_ADDR_COUNTRY2ANM
VAT is included in priceINCLUDE_VAT1NM
Amount of itemsITEMS8NM

Products in the payment bundle can be sent with the recurring fields described below.

Table 6.3. Product rows

FieldNameMax lengthFormatMandatory / optional
Product nameITEM_TITLE[X]255ANM
Product numberITEM_NO[X]16ANO
Amount of productsITEM_AMOUNT[X]10FM
Product priceITEM_PRICE[X]10FM
Tax percent for productITEM_TAX[X]10FM
Merchant ID of productITEM_MERCHANT_ID[X]8NM
Product’s channel commission class IDITEM_CP[X]10FM
Product’s discountITEM_DISCOUNT[X]10FO
Product typeITEM_TYPE[X]2NO

Table 6.4. Description for fields

FieldDescription
Channel IDChannel ID is an identifier given to the payment channel by Paytrail. Channel ID contains only numbers. (mandatory)
Order numberOrder number is a unique string for order. (mandatory)
CurrencyCurrency of the payment. The only allowed value is EUR. (mandatory)
Return address / Successful paymentAfter a successful payment, the customer will be redirected to the return address. (mandatory)
Return address / Cancelled paymentAfter cancelled or unsuccessful payment customer will be redirected to the cancel address. (mandatory)
Notify address After the payment is marked as successful, Paytrail will call the notify address and send the same GET parameters as when directing customer to RETURN_ADDRESS after a successful payment. (mandatory)
Interface versionVersion of payment interface. Channel interface is 1. (mandatory)
Culture code/Payment page language Culture affects the default language of Paytrail’s payment service page as well as the format of the displayed sum. Possible values are “fi_FI”, “sv_SE” and “en_US”. Default is “fi_FI”. (optional)
Preselected payment method for Payment page bypass If the payment method selection is done in the webshop, the payment method is delivered in this field. Paytrail's service can be bypassed when preselected payment method is delivered (PRESELECTED_METHOD). Use requires an additional agreement with Paytrail.
Authentication code Authentication code is a checksum calculated with MD5 algorithm. With authentication code we prevent the abuse of payments. Checksum is calculated from a string that contains all the information from the order and channel’s certificate. See example below. (mandatory)
Payer’s telephone numberPayer’s telephone number. (optional)
Payer’s cellphone numberPayer’s cellphone number. (optional)
Payer’s email addressPayer’s email address. (mandatory)
Payer’s first namePayer’s first name. (mandatory)
Payer’s last namePayer’s last name. (mandatory)
Payer’s companyPayer’s company. (optional)
Payer’s street addressPayer’s street address. (mandatory)
Payer’s zip codePayer’s zip code. (mandatory)
Payer’s cityPayer’s city. (mandatory)
Payer’s country Payer’s country. The value follows the ISO-3166-1 standard and it contains two letters. For example, Finland is FI and Sweden is SE. It does not matter if the value is in lower or upper case. (mandatory)
Is VAT is included in price? Do the prices in item rows include VAT or not. Value 1 means that VAT is included in given prices, value 0 means that given VAT has to be added to price. If your products are saved including VAT in your webshop, use value 1. If products are saved without VAT, use value 0. (mandatory)
Amount of itemsAmount of item rows. (mandatory)
Product nameFree-formatted name for the product. (mandatory)
Product number Optional product number that is displayed in the Merchant’s Panel with the product. Using this field may help find the right product. (optional)
Amount of products If the order includes several of the same products this field can be used to determine amount of them. This means that identical products do not need their own rows. (mandatory)
Product price Price of the product. If INCLUDE_VAT has value 0, value of this field is price without VAT. If INCLUDE_VAT has value 1, value of this field is price including VAT. Price has to be always positive. Discounts for products can be sent with the ITEM_DISCOUNT[X] field. (mandatory)
Tax percent for productVAT percent used for products. (mandatory)
Merchant ID of product One payment can contain products from several merchants. Every item row has to contain merchant ID of the product’s merchant. (mandatory)
Product’s channel commission class ID Payment channel may have several commission classes. Every product can have their own commission class. This allows different prices for premium merchants or smaller commission class for more expensive products. Paytrail will deliver commission class IDs to payment channel. Commission class IDs are defined in the contract between Paytrail and payment channel. (mandatory)
Products discount If product has a discount, this defines the discount percentage. The value can be between 0 and 100. Default value is 0. (optional)
Product type Type can be defined for every item row. Type 1 means normal product, 2 shipping, and 3 handling. Default value is 1. (optional)