Fields for the Interface


The following fields can be sent to payment gateway.

Payment gateway address is:

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

Required fields are marked with an asterisk (*). Some optional columns have default values which are used if no value is provided in payment data.

Values may not contain ‘|’ characters. 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.

Payment total is defined using AMOUNT or at least one order row ITEM_UNIT_PRICE. It is possible to use both but we strongly recommend not to use AMOUNT when order rows are provided.


Merchant identification number given by Paytrail. For testing use 13466.


EUR is the only accepted value and default.


URL where the customer is redirected after successful payment. PARAMS_OUT are added to URL_SUCCESS.


URL where customer is redirected after failed or cancelled payment. PARAMS_OUT are added to URL_CANCEL.


Used to identify one transaction.


Price is given in euros and cents without currency. Decimals are separated with a dot. Must contain two decimals. Interface accepts values between 0.65–499 999.99 €. Some payment methods have limitations for this value which you can check here.

If you need to receive transactions that are less than 0.65€, please contact our customer service


Comma separated list of fields used in AUTHCODE calculation. Only values listed in this field are shown in payment data.


Comma separated list of fields used in return AUTHCODE calculation. Only values listed in this field are returned as a part of URL_SUCCESS / URL_CANCEL. Has to contain values PAYMENT_ID, TIMESTAMP and STATUS.


Algorithm used in AUTHCODE calculation. Defaults to 1 (SHA-256).


Calculated by joining all fields listed in PARAMS_IN. Fields are joined by placing the | (pipe) character between each two fields. AUTHCODE is formed from this string by calculating a sum using the algorithm from field ALG. This sum is converted to its 64-character hexadecimal form and lowercase letters are capitalized.

See example of calculating the correct value here.


URL to be called when the payment has been marked as paid. This URL is called with parameters defined in PARAMS_OUT_NOTIFY when the payment is marked as paid. PARAMS_OUT_NOTIFY are added to URL_CANCEL.


Not yet available. Comma separated list of fields used in notify RETURN_AUTHCODE calculation. Only values listed in this field are returned as a part of URL_NOTIFY. If not included to payment data PARAMS_OUT is used as a part of URL_NOTIFY.


The default language of payment method selection page. Available locales are fi_FI (default), sv_SE and en_US.


Reference number to be delivered to payment method provider’s service. Given value is used only if user selected payment method is configured as interface (i.e. own direct agreement with payment method provider), otherwise the reference number is generated automatically by Paytrail.

Reference number must comply against Finnish reference number standard or be Finnish reference number in international RF format (e.g. 1232 or RF111232). For Osuuspankki, Ålandsbanken and S-Pankki RF formatted reference numbers are converted to numeric Finnish reference number format.

Single settlements are always made in the Finnish national reference standard. Paytrail does not create settlements using the RF reference standard.


Comma separated list of payment methods visible at payment method selection page. If only one is set the payment method page is bypassed and payer is directed to payment method provider page. Use requires agreement on use with Paytrail.


Whether VAT is included in prices given in ITEM records. This field is only used with ITEM records. If brought without, an error message is shown.

Available values are:

  • 1 (VAT is included, default)
  • 0 (VAT is not included).

If VAT_IS_INCLUDED = 0, payment service will calculate the sum to be charged from the customer based on the ITEM_UNIT_PRICE, ITEM_VAT_PERCENT, ITEM_QUANTITY, and ITEM_DISCOUNT_PERCENT values. This may lead to rounding differences between the website and the payment service. Please note that the calculation is done using two decimals.

If using the Collector payment method, the value must be 1. Collector will not be available if the value is 0.


Message to consumers bank statement or credit card bill if supported by payment method.


Not yet available. Message to merchants bank statement if supported by payment method.


Message shown in payment method provider page. Currently this is supported by Osuuspankki, Visa (Nets), MasterCard (Nets), American Express (Nets) and Diners Club (Nets). Not all payment methods support showing the message.


Message shown in Paytrail Merchant Panel.


Sets time when payment possibility is going to be expired for consumer. Payment can’t be done if consumer enters to payment page after given expiration time. Time is validated when entering payment page and payment is created. Expired time will cause payment not to be created and not to be shown in merchant portal. Consumer will get error message if payment was expired. This does not disallow consumer from staying on payment page or being redirected to payment methods or completing payments after being able to get to payment page. Default is ISO-8601 notation datetime with time zone (yyyy-mm-ddThh:mm:ss+-hh:mm).

Payer Information

Payer information can be brought to Paytrail service using the following fields.


Payer’s first name.


Payer’s last name.


Payer’s email. Email is validated, no MX validation.


Payer’s telephone number.


Payer’s street address.


Payer’s postal code.


Payer’s town.


Payer’s country. ISO-3166-2 formatted.


Payer’s company.

Product Information

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 the order rows can not exceed 500.

Required fields when product rows are included in the data are ITEM_TITLE, ITEM_UNIT_PRICE, and ITEM_VAT_PERCENT. These are marked with an asterisk (*). All items should be consistent. If one item has ITEM_ID, every item should have it.

Total sum of the product prices must be between 0.65 – 499 999.99 €. Some payment methods have limitations for this value which you can check here.

If you need to receive transactions that are less than 0.65€, please contact our customer service


Free field for the product name.


Optional product ID containing numbers only.


Optional quantity of products. Default is 1. If a decimal number such as 0.5 is used, the Collector payment method will be hidden.


The price for a single product with up to two decimals.

Value can be negative for individual products, but whole order total amount must be positive value.

If VAT_IS_INCLUDED = 0, this is price excluding VAT. Price may be negative value if discount is given.


VAT percent used for product.


Optional item discount. Percent is a number between 0–100. Default is 0.


Optional type of the product or its costs. Available values 1 (normal, default), 2 (shipment cost) 3 (handling cost).