Paytrail - Integration guide


Revision History
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. Paytrail Connect API
4.1. Service availability
4.2. Service description
4.3. Interface description
4.3.1. Service location
4.3.2. REST Authentication
4.4. Authorization request
4.5. Confirming authorization
4.6. Charging a payment with a confirmed authorization
4.7. A1 Payment data specification
4.8. Receiving notification of a completed payment
4.9. Retrieving payment status
4.10. Accessing Paytrail account delivery address information
4.11. Deleting and invalidating an authorization
4.12. Sequence diagrams
5. Payment service
5.1. Introduction
5.2. REST interface (BETA)
5.2.1. Introduction
5.2.2. Interface use
5.2.3. Payment creation
5.2.4. Error handling
5.2.5. Error codes
5.2.6. PHP
5.2.7. Perl
5.3. Form interface
5.3.1. Introduction
5.3.2. Interface versions
5.3.3. Change versions
5.3.4. Fields to be sent to payment gateway
5.3.5. Calculating the payment fingerprint (AUTHCODE)
5.4. Receiving the Payment Receipt
5.4.1. Introduction
5.4.2. Authcode calculation
5.5. Payment page bypass
5.5.1. Introduction
5.5.2. Implementation
5.5.3. Payment method values
5.6. Payment method selection page embedding
5.6.1. Introduction
5.6.2. Versions
5.6.3. Embedding when using the REST interface
5.6.4. Embedding when using the form interface
5.6.5. Parameters
5.6.6. Localisation
5.7. Payment state queries
5.7.1. State query in HTML
5.7.2. Calculating the hash
5.8. Merchant API v1
5.8.1. Service description
5.8.2. Authentication
5.8.3. Accessing the API
5.8.4. Create Refund
5.8.5. Notify URL call
5.8.6. Refund cancellation
5.8.7. Settlements
5.8.8. Settlement details
5.8.9. Payment details
5.8.10. Refund details
6. Sales channels - For marketplaces
6.1. Channel description
6.2. Interface description
6.2.1. Common
6.2.2. Fields to send
6.3. Handling of payment information
6.3.1. Calculating checksum
6.3.2. Example of calculating the checksum
6.4. Testing
6.4.1. Test ID and channel certificate
7. Dynamic payment method banner
7.1. Showing available payment methods in the webshop
7.2. Creating a link to the banner
7.3. Examples of payment method banners

List of Figures

4.1. SMS PIN authorization for a single charge from Paytrail account
4.2. SMS PIN authorization for Paytrail account delivery address data
5.1. Payment page
5.2. Payment creation with the REST interface
5.3. Creating a payment
5.4. Payment method selection page embedding
5.5. Status flow diagram for bank payments
5.6. Status flow diagram for invoices (Collector)
5.7. Status flow diagram for cards

List of Tables

4.1. Parameters for the authorization request
4.2. Valid parameter values
4.3. Parameters
4.4. Parameters
4.5. Return Value
4.6. Return value
5.1. Error codes: Payment creation
5.2. Field descriptions
5.3. Form interface: Fields to be sent to payment gateway with interface version E1
5.4. Payment method IDs for payment page bypass
5.5. MODE values
5.6. Form interface: Product details for interface version E1
5.7. Form interface: Fields to be sent to payment gateway with interface version S1
5.8. Payment method IDs for payment page bypass
5.9. MODE values
5.10. Fields to be sent to payment gateway with interface version E1
5.11. Fields to be sent to payment gateway with interface version S1
5.12. Receipt contains these fields
5.13. Field explanations
5.14. Possible values for payment method
5.15. Example of calculation
5.16. Possible values for payment method
5.17. Form field description
5.18. Example of calculation
5.19. Required headers
5.20. Signature parameters
5.21. General HTTP responses
5.22. General error codes and workarounds
5.23. Parameters
5.24. Return codes and workarounds
5.25. Parameters sent with each notify call
5.26. Refund statuses
5.27. Return codes and workarounds
5.28. Parameters
5.29. Structure and detailed information on returned values
5.30. Resource specific error messages
5.31. Parameters
5.32. Structure and detailed information on returned values
5.33. Resource specific error messages
5.34. Parameters
5.35. Resource specific error messages
5.36. Parameters
5.37. Resource specific error messages
6.1. Fields to be sent to the payment gateway
6.2. Payment method IDs for payment page bypass
6.3. Product rows
6.4. Description for fields
6.5. Product rows
6.6. Values for AUTHCODE calculation

List of Examples

4.1. Calculating the content MD5 in PHP
4.2. HMAC-SHA256 signature calculation in PHP
4.3. POST /connectapi/authorizations
4.4. Example HTTP Request
4.5. Example HTTP Response
4.6. POST /connectapi/authorizations/{id}/confirmation
4.7. Example HTTP Request
4.8. Example HTTP Response
4.9. POST /connectapi/authorizations/{id}/charges
4.10. Example HTTP Request
4.11. Example HTTP Response after immediate charging
4.12. Example HTTP Response after requiring customer interaction
4.13. Payment Interface: A1 Field Specification
4.14. Example A1 Payment JSON
4.15. GET /connectapi/authorizations/{id}/charges/{id}
4.16. GET /connectapi/authorizations/{id}/deliveryAddresses
4.17. Example HTTP Request
4.18. Example HTTP Response
4.19. DELETE /authorizations/{id}
4.20. Example HTTP Request
4.21. Example HTTP Response
5.1. Payment creation with the REST interface; XML request
5.2. Payment creation with the REST interface; XML response
5.3. Payment creation with the REST interface; JSON request
5.4. Payment creation with the REST interface; JSON response
5.5. Payment creation with the REST interface; XML request, light version
5.6. REST service error message in XML format
5.7. REST service error message in JSON format
5.8. Using the payment service PHP class
5.9. Using the payment service PHP class without contact and product data
5.10. Confirming payment receipt with PHP class
5.11. Calculating the payment fingerprint with form data for interface version E1
5.12. Calculating the payment fingerprint with form data for interface version S1
5.13. Payment method selection page embedding with JSON interface
5.14. Payment method selection page embedding with form interface
5.15. The state query HTML form
5.16. Example of calculation
5.17. Example of signature calculation for refund creation
5.18. JSON message structure with invalid API name
5.19. Example request
5.20. Example response
5.21. Example request
5.22. Example response
5.23. Example request
5.24. Example response
5.25. Example request
5.26. Example response
6.1. Example
7.1. Example of the banner URL