Paytrail 101: Optimized Integration
We aim to make integrating Paytrail services as easy as possible for merchants. Choices made during the technical implementation have a radical impact on the user experience towards the merchant and the consumer.
Here are some best practices for integrating our payment service so that merchants can take full advantage of it from day one.
This guide is also available in Finnish as a presentation.
💡 We recommend you
- use aggregate settlements and handle refunds through Paytrail
- use payment page bypass to improve merchant’s payment conversion
- send extended information about the consumer to Paytrail to enable using all the payment methods
- use our Merchant API for creating refunds directly from the website management portal and modifying the settlement materials to satisfy your financial systems
Choosing the Right Interface
We recommend the E2 interface for payments due to its security and better features. E2 is our latest and greatest interface and the most flexible in terms of developing integrations. Among other things, E2 interface allows bypassing the payment page and defining custom return values.
Note the following essential fields in the E2 interface
ORDER_NUMBERrequired for targeting payments
PARAMS_INrequired for defining the data passed into Paytrail systems
PARAMS_OUTrequired for defining the data passed in return to the website
We also recommend the following optional fields
REFERENCE_NUMBERfor providing your reference number in single settlements or payments not settled by Paytrail (e.g. PayPal)
URL_NOTIFYfor enabling real-time payment confirmations and notifications
PAYMENT_METHODSfor bypassing the payment page and hiding payment methods
LOCALEfor defining the default language of the payment page
VAT_IS_INCLUDED = 1supported with all payment methods
PAYER_*fields contain payer information such as name, address and email, and should be used to enable all the payment methods and Sales Rescue features
ITEM_*fields contain the required product details to enable all the payment methods
Use Payment Page Bypass
We encourage you to use the payment page bypass to remove an additional step from the payment process. Usually, our payment service redirects the consumer to the payment page for selecting a payment method.
Using the bypass allows the merchant to display the payment methods on their website aligning the purchasing process with the merchant’s brand and improving the conversion.
We recommend using our Merchant API for initiating refunds from the site management portal for all payment methods. Merchant API supports initiating and cancelling both partial and full refunds.
Note that a refund can be initiated with any amount greater than zero and less or equal than the paid amount. Keep in mind the VAT included in the original payment.
notifyUrl field allows you to receive a confirmation when the refund has been completed or cancelled.
Daily settlements delivered via the Merchant API contain payments and refunds as single rows. You can search the settlements through REST endpoints in JSON format. The settlement data contains payments, refunds, and transaction fees.
You can also use the Merchant API for bookkeeping. The payment is created in Paytrail so that we use the invoice number as the order number (
ORDER_NUMBER). Settlement data is retrieved from the Merchant API and modified to match the settlement material provided by the bank (
ORDER_NUMBER = reference number from the bank). You may then pass the amended bank materials into the financial software. The settlement with the reference is booked into another account and excluded from the bookkeeping.
For example, the following HTTP request returns settlement IDs from the given period.
The following HTTP request returns full settlement details with the given settlement ID.