Paytrail - Integration guide


Revision History
Revision 5.72 July 2019
  • Added documentation about confirming payments through payment status query services.
Revision 5.611 June 2019
Revision 5.519 March 2019
  • Updated payment method requirements in Payment method values chapter.
  • Fixed wrongly calculated signature in Merchant API refund creation example.
  • Added mention about Merchant API charset (UTF-8).
  • Minor fixes to terms used in E2 and channel payment chapters.
Revision 5.423 October 2018
  • Updated card payment test instructions.
  • Added mention about refund location in create refund response.
  • Removed mention about ORDER_NUMBER being required in PARAMS_OUT as it is not required.
Revision 5.325 September 2018
  • Added documentation for new optional field EXPIRATION_FOR_PAYMENT_CREATION in E2 interface.
Revision 5.217 April 2018
  • Removed references to payment method Paytrail account which will be removed in June 2018.
Revision 5.127 March 2018
  • Updated E2 field validation.
Revision 5.012 December 2017
  • Removed Connect API documentation, API will be removed 2018.
Revision 4.921 November 2017
  • Updated E2 calculating the payment AUTHCODE examples.
Revision 4.831 October 2017
  • Updated channel documentation.
  • Updated E2 ITEM_ID validation.
Revision 4.710 October 2017
  • Updated E2 receipt value info.
Revision 4.619 September 2017
  • E2: Added recommendation not to use AMOUNT when order rows are provided.
Revision 4.513 June 2017
  • Added Shopify token for testing.
  • Added new interface version E2.
  • Added new payment method MobilePay (ID 58).
Revision 4.44 April 2017
  • Removed XML interface documentation. XML has been replaced with merchant API settlements.
  • Updated length of merchant API signature.
  • Fixed AMOUNT to be required with interface version S1.
  • Removed link to unsupported library.
Revision 4.321 February 2017
  • Removed link to unsupported library.
  • Added example image of form payment creation.
Revision 4.210 January 2017
  • Added American Express test credentials.
Revision 4.116 November 2016
  • Added credit card refund documentation to Merchant API section.
Revision 4.011 October 2016
  • Fixed authcode in E1 example.
  • Removed references to payment method Maestro (not in use).
  • Removed old Collector version (ID 19).
  • Added documentation for Merchant API settlement, payment and refund resources.
Revision 3.96 September 2016
  • Updated customer care phone number.
Revision 3.826 July 2016
  • Added payment method Oma Säästöpankki, PRESELECTED_METHOD 61.
Revision 3.73 May 2016
  • Fixed info about validity of REST token.
  • Added info about REST interface not supporting payment page bypass.
Revision 3.619 January 2016
  • Described vatPercent is not allowed in Merchant API create refund requests for payments done with S1.
Revision 3.515 December 2015
  • Added Collector Bank to payment method lists.
  • Status flow diagrams added for bank payment/invoice refunds.
Revision 3.427 October 2015
  • Added test credentials for Visa and MasterCard.
  • Added new error code refunds-not-enabled to Merchant API.
  • Payment method Tapiola (id 4) removed. Tapiola has merged with S-Pankki (id 10).
Revision 3.315 September 2015
  • Merchant API service address and warning text updated (pilot).
  • Merchant API and Connect API examples fixed.
  • Added link to Connect API Python library and Merchant API Ruby library.
  • Added Paytrail account ID to payment page bypass documentation.
  • Updated VISIBLE_METHOD field documentation.
  • Added new payment methods 53-57 (Nets).
  • Removed method 8 (Nets).
Revision 3.24 August 2015
  • Changed refund item amounts and VAT percentages to be given as integers instead of floats in Merchant API.
Revision 3.123 June 2015
  • Added the first version of Merchant API v1 documentation.
Revision 3.09 December 2014
  • Corrected timestamp format in Connect API examples.
  • Changed the name of the downloadable REST module zip package and omitted file paths in the archive.
  • Changed HTTP status received in error cases in REST documentation.
Revision 2.94 November 2014
  • Changed Sampo Pankki's name to Danske Bank.
  • Added test credentials for S-Pankki.
  • Added METHOD values for card methods 30-35 in payment notify.
  • Added test credentials for Aktia, Säästöpankki and POP Pankki.
  • Removed references to old Collector payment method (METHOD 13).
  • Removed supported browsers from payment method selection page embedding chapter.
  • Removed references to disabled payment methods Säästöpankit, paikallisosuuspankit, Aktia, Nooa (METHOD 7), Maestro (METHOD 32) and American Express (METHOD 33).
  • Moved form interface documentation from a PDF to the docbook (chapter 5.3).
  • Name of the payment method 8 is now Nets (previously Luottokunta).
  • Removed reference to old VAT base 23.
  • Stylized Payment service and Connect API chapters.
Revision 2.811 August 2014
  • Updated channel API documentation PDF to use the new company name and stylized the language in it.
  • Updated new name for Jousto (previously Joustoraha).
Revision 2.78 May 2014
  • Added the descriptions of email and phone parameters in returned delivery address JSON.
  • Fixed documentation on delivery address return HTTP codes
  • Corrected max length for product code field in A1 payment format to be 16 chars.
Revision 2.628 February 2014
  • Updated Paytrail Connect API documentation.
Revision 2.510 February 2014
  • Updated the Bookkeeping XML URLs.
  • Added a new element "payer" to the SVPayment datatype in the Bookkeeping XLM. This element needs to be taken into account when using the new URLs.
  • Added card payment method identifiers (30-35) tp payment page bypass documentation.
Revision 2.428 November 2013
  • Moved the test credentials to their own chapter, since the same ones are used in several places.
  • Added the bank test credentials to the test credentials chapter.
  • Added a know issues chapter to the form interface description. This was done, since there have been some changes, and they aren't reflected in the PDF.
  • Changed the minimum sum of a payment to be 0.65 euros.
  • Changed documentation of INCLUDE_VAT and ITEM_AMOUNT to reflect Collector requirements.
  • Changed the payment gateway URLs from to
  • Added the dynamic payment method banner documentation in English.
  • Moved the Bookkeeping XML API documentation to HTML format
  • Moved payment status query documentation to HTML format and documented support for new localisations
  • Moved first name and last name in separate fields in Connect API documentation.
Revision 2.34 June 2013
  • First version of Paytrail documentation.
  • Added Paytrail Connect API to documentation.
  • Added text to introduction and to payment service description.
Revision 2.229 October 2012
  • Removed references to Netposti payment method (no longer available)
  • Added information to PENDING_ADDRESS that it is not longer used.
  • Added information to payment method lists about replacing Collector-method (13) with new Collector method (19).
  • Added Joustoraha (18) to payment method lists where it was missing.
Revision 2.1.222 August 2012
  • Removed recurring payments documentation.
  • Updated REST API illustrations with English translations.
Revision 2.1.118 June 2012
  • Removed beta label from payment method selection page embedding documentation. Updated embed JavaScript URI.
Revision 2.11 December 2011
  • English documentation body ported to HTML. Most of the English documentation is still linked to old PDF files.
  • Fixed and updated payment method selection page embedding documentation.
  • Fixed REST API example
  • Fixed S1 form API example. PENDING_ADDRESS should be empty in the example, it had set value in the listing.
  • Added test credentials under payment service documentation.

Table of Contents

1. Introduction
2. Terminology
3. Test credentials
4. Payment service
4.1. Introduction
4.2. Form interface
4.2.1. Introduction
4.2.2. Interface versions
4.2.3. Migration guide
4.3. E2
4.3.1. Fields to be sent to payment gateway
4.3.2. Calculating the payment AUTHCODE
4.3.3. Receiving the Payment Receipt with interface version E2
4.3.4. RETURN_AUTHCODE calculation
4.4. Selection and visibility of payment methods
4.4.1. Introduction
4.4.2. Payment method values
4.5. REST interface (BETA)
4.5.1. Introduction
4.5.2. Interface use
4.5.3. Payment creation
4.5.4. Receiving the Payment Receipt
4.5.5. Error handling
4.5.6. Error codes
4.5.7. PHP
4.5.8. Perl
4.6. Payment method selection page embedding
4.6.1. Introduction
4.6.2. Versions
4.6.3. Embedding when using the REST interface
4.6.4. Embedding when using the form interface
4.6.5. Parameters
4.6.6. Localisation
4.7. Payment state queries
4.7.1. State query in HTML
4.7.2. Calculating the AUTHCODE
4.8. Merchant API v1
4.8.1. Service description
4.8.2. Authentication
4.8.3. Accessing the API
4.8.4. Create Refund
4.8.5. Notify URL call
4.8.6. Refund cancellation
4.8.7. Settlements
4.8.8. Settlement details
4.8.9. Payment details
4.8.10. Refund details
5. Sales channels - For marketplaces
5.1. Channel description
5.2. Interface description
5.2.1. Common
5.2.2. Fields to send
5.3. Handling of payment information
5.3.1. Calculating RETURN_AUTHCODE
5.3.2. Example of calculating the RETURN_AUTHCODE
5.4. Testing
5.4.1. Test ID and channel secret
6. Dynamic payment method banner
6.1. Showing available payment methods in the webshop
6.2. Creating a link to the banner
6.3. Examples of payment method banners

List of Figures

4.1. Payment page
4.2. Creating a payment
4.3. Payment creation with the REST interface
4.4. Payment method selection page embedding
4.5. Notifications from refunds
4.6. Status flow diagram

List of Tables

4.1. Changed payment creation fields comparing E2 to older interfaces
4.2. Form interface: Fields to be sent to payment gateway with interface version E2
4.3. Form interface: Payer for interface version E2
4.4. Form interface: Product details for interface version E2
4.5. Validation of fields
4.6. Fields to be sent to payment gateway with interface version E2
4.7. Fields to be sent to payment gateway with interface version E2 with only required fields
4.8. Receipt contains these fields
4.9. Example of calculation
4.10. Available payment method IDs
4.11. Error codes: Payment creation
4.12. Form field description
4.13. Example of calculation
4.14. Required headers
4.15. Signature parameters
4.16. General HTTP responses
4.17. General error codes and workarounds
4.18. Parameters
4.19. Return codes and workarounds
4.20. Parameters sent with each notify call
4.21. Refund statuses
4.22. Return codes and workarounds
4.23. Parameters
4.24. Structure and detailed information on returned values
4.25. Resource specific error messages
4.26. Parameters
4.27. Structure and detailed information on returned values
4.28. Resource specific error messages
4.29. Parameters
4.30. Resource specific error messages
4.31. Parameters
4.32. Resource specific error messages
5.1. Fields to be sent to the payment gateway
5.2. Payment method IDs for payment page bypass
5.3. Product rows
5.4. Description for fields
5.5. Product rows
5.6. Values for AUTHCODE calculation

List of Examples

4.1. Calculating the payment AUTHCODE with form data for interface version E2 including all optional fields
4.2. Calculating the payment AUTHCODE with form data for interface version E2 including minimum set of fields
4.3. Payment creation with the REST interface; XML request
4.4. Payment creation with the REST interface; XML response
4.5. Payment creation with the REST interface; JSON request
4.6. Payment creation with the REST interface; JSON response
4.7. Payment creation with the REST interface; XML request, light version
4.8. REST service error message in XML format
4.9. REST service error message in JSON format
4.10. Using the payment service PHP class
4.11. Using the payment service PHP class without contact and product data
4.12. Confirming payment receipt with PHP class
4.13. Payment method selection page embedding with JSON interface
4.14. Payment method selection page embedding with form interface
4.15. The state query HTML form
4.16. Example of calculation
4.17. Example of signature calculation for refund creation
4.18. JSON message structure with invalid API name
4.19. Example request
4.20. Example response
4.21. Example request
4.22. Example response
4.23. Example request
4.24. Example response
4.25. Example request
4.26. Example response
5.1. Example
6.1. Example of the banner URL