Paytrail - Integration guide

v4.6

Revision History
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 payment.verkkomaksut.fi to payment.paytrail.com
  • 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. Form interface
5.2.1. Introduction
5.2.2. Interface versions
5.2.3. Migration guide
5.3. E2
5.3.1. Fields to be sent to payment gateway
5.3.2. Calculating the payment fingerprint (AUTHCODE)
5.3.3. Receiving the Payment Receipt with interface version E2
5.3.4. RETURN_AUTHCODE calculation
5.4. Selection and visibility of payment methods
5.4.1. Introduction
5.4.2. Payment method values
5.5. REST interface (BETA)
5.5.1. Introduction
5.5.2. Interface use
5.5.3. Payment creation
5.5.4. Error handling
5.5.5. Error codes
5.5.6. PHP
5.5.7. Perl
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

Chapter 1. Introduction

This documentation describes all available integration methods to the services of Paytrail.

Chapter 2. Terminology

Merchant - A customer of Paytrail; runs the web application in which the Paytrail services are used. The merchant sells a product or service online to its customers.

Customer - A consumer, the customer of a merchant, the person making a payment.

Paytrail account - the personal account of a customer that holds the customer's tokenised payment card details and address details.

Paytrail Connect API - the interface used to gain access to Paytrail accounts.

Paytrail Payment Service - Service that allows customers to pay for purchases to the Merchant. Includes all popular payment methods in Finland.

Paytrail Sales Channel - Channel where multiple merchants can sell their products in one location (like an online marketplace or mall). This allows the customer to buy from several different merchants and make only one payment.

Chapter 3. Test credentials

The Payment Service is testable using merchant id 13466 and merchant secret 6pKF4jkv97zmqBJ3ZL8gUw5DfT2NMQ. These test credentials work with form interface, REST interface and payment method selection page embedding.

Shopify gateway is testable using merchant id 13466 and Shopify token d3d86c09e781a00dda469e420166623f67a618e6.

The test credentials for the Finnish banks and credit cards are listed below. They can be used with the test credentials to test the complete payment process without making any real payments.

Nordea
  ID: 123456
  Password: 1234

Osuuspankki
  User ID: 123456
  Password: 7890
  Keynumber: Any number

Danske Bank
  Use your own user ID for testing. Payments will not be charged on your bank account.

Ålandsbanken
  User ID: 12345678
  ID code: 1234

Handelsbanken
  User ID: System fills it for you
  ID code: System fills it for you

Aktia
  User ID: 12345678
  Password: 123456
  Security code: 1234

POP Pankki
  User ID: Bank's web site will provide these for you
  Password: Bank's web site will provide these for you
  Security code: Bank's web site will provide these for you

Säästöpankki
  User ID: Bank's web site will provide these for you
  Password: Bank's web site will provide these for you
  Security code: Bank's web site will provide these for you

S-Pankki
  User ID: 12345678
  Password: 9999
  Security code: 1234

Visa
  Card number: 4925000000000004
  Expiry: > today
  CVC: any 3 digits

MasterCard
  Card number: 5413000000000000
  Expiry: > today
  CVC: any 3 digits

American Express
  Card number: 375700000000002
  Expiry: > today
  CVC: any 3 digits
        
  Card transaction errors can be simulated by setting the payment amount in following way.
  The amount ranges 0.01 to 0.99 and 1.01 to 1.99 will always make the credit card to return a response code that is not OK.
  These ranges will return their decimal parts as the response code, e.g. the amount 1.52 triggers the response code 52.
  Paytrail will consider the payments that receive an error code as failed payments.

Oma Säästöpankki
   User ID: Bank's web site will provide these for you
   Password: Bank's web site will provide these for you
   Security code: Bank's web site will provide these for you

  Remember that Paytrail also sets a minimum limit for payment amount that is 0,65 €.

    

Chapter 4. Paytrail Connect API

4.1. Service availability

Paytrail Connect API is available for merchants that have an active Paytrail account agreement. If you encounter any problems during the API integration, don't hesitate to contact our technical support at .

Note

Testing Paytrail Connect API is done using each merchant's own credentials. There are no separate test credentials for Connect API. The payments are made with real cards and real money, but it is possible to refund them in the Merchant's Panel after testing.

4.2. Service description

Paytrail Connect API (later referred to as API) is used to access a Paytrail account directly from the webshop. To access a Paytrail account from the payment method selection page, please refer to Payment Service documentation.

The image below illustrates how to create a one-click buying experience using the API.

4.3. Interface description

This section of the documentation contains the technical description of the API.

Paytrail Connect API is an HTTP API for accessing customers' Paytrail accounts. Merchants can use it to ask a customer's permission to charge via Paytrail account, to query delivery address information, and to submit new payments via Paytrail account.

4.3.1. Service location

Paytrail Connect API is available at

https://account.paytrail.com

4.3.2. REST Authentication

Each HTTP request is authenticated by sending an authorization header.

Using an invalid authorization header will result in HTTP 403 (Forbidden).

All malformed resource creations that fail input validation will result in HTTP 400 (Bad request).

All supported methods per resource are documented. Calling the resources with undocumented methods results in HTTP 405 (Method not allowed).

The mandatory HTTP headers and their contents are detailed below.

4.3.2.1. Timestamp header

Timestamp: 2012-12-31T12:00:00+02:00

The timestamp of the request.

4.3.2.2. Content-MD5 header

Content-MD5: ubewX5M7uzz64zskr7FThQ==

All requests using the API must include a Base64 encoded MD5 hash of their request body contents to verify that the content hasn't been changed.

Example 4.1. Calculating the content MD5 in PHP

$content = '{"authSecret":"1234"}';
$contentHash = base64_encode(hash('md5', $content, true));
// Hash will be 'm/+9rBseCrTRRSJChVP9Kw=='

4.3.2.3. Authorization header

Authorization: PaytrailConnectAPI 13466:9tUzOligooAdSZI+neokVKDtXx/g/PJFVy3X945E57s=

The authorization header must contain a signature that is a Base64 encoded SHA-256 HMAC of important request details and the merchant's secret value. Below is an example of the signature calculation routine in PHP.

Example 4.2. HMAC-SHA256 signature calculation in PHP

// Shared secret in this example: "6pKF4jkv97zmqBJ3ZL8gUw5DfT2NMQ"

$signature = base64_encode(hash_hmac(
    "SHA256",
    implode("\n", array(
        "POST",                        // HTTP method used for request
        "/connectapi/authorizations" , // Resource being accessed
        "PaytrailConnectAPI 13466",    // API name and merchant id
        "2012-12-31T12:00:00+02:00",   // Timestamp
        "m/+9rBseCrTRRSJChVP9Kw==",    // Base64 encoded MD5 of request body
    )),
    "6pKF4jkv97zmqBJ3ZL8gUw5DfT2NMQ",  // Merchant secret
    true                               // use raw binary output from hash_hmac()
));

// Signature will be bL///v1z99+fhnVDfXCrI/6fNdrtULTYiMxgQFVFCOA=

4.4. Authorization request

Authorization can be seen as a permission from the customer to let the caller of the API, e.g. a webshop, access their Paytrail account. More specifically, it is a means to ask the Paytrail account owner's consent for charge access to the stored payment method or for read access to delivery addresses.

If the resource is created and the caller receives HTTP 201, that newly created Authorization resource is ready to be confirmed with the PIN code that was sent to the Paytrail account owner.

Example 4.3. POST /connectapi/authorizations

Request body
{
    "authKey": string,
    "authType": string,
    "access": [ array of strings ],
    "validity": string,
    "locale": string
}

HTTP Status codes

201: On successful authorization request using requested authentication method

400: Bad Request


The following table gives more information on the content of the request. The m/o column indicates if the parameter is mandatory or optional.

Table 4.1. Parameters for the authorization request

NameTypem/oDescription
authKeystringmKey to identify a Paytrail account. e.g. email address.
authTypestringmAuthentication process for confirming the Paytrail account owner and their consent.
accessarray of stringsmPaytrail account owner is requested to authorize the API caller to do these actions.
validitystringmValidity period of the requested authorization. At the moment only "singleCharge" is supported. Reserved for recurring payment use case when the Paytrail account can be charged multiple times with one authorization from account owner.
localestringmThe locale of the Paytrail account owner, e.g. fi_FI.

Table 4.2. Valid parameter values

authTypeTriggered authentication process
email+smspinIf the provided authKey belongs to an active Paytrail account, its owner receives a PIN code via SMS.
accessm/oAccess to be requested from the Paytrail account owner during the authorization process
chargeoPaytrail account owner is asked to let the API caller charge the Paytrail account's default payment method.
deliveryAddressoPaytrail account owner is asked to reveal the delivery addresses they have verified to be valid.
validityThe duration of the requested authorization
singleChargeAccess for deliveryAddress is valid for 1 hour after confirming or until a charge is placed. After creating the charge, the authorization resource is invalidated.
Locale 
fi_FIFinnish in Finland
en_USUS English
se_SVSwedish in Sweden

Example 4.4. Example HTTP Request

POST /connectapi/authorizations HTTP/1.1
Timestamp: 2012-12-31T12:00:00+02:00
Content-MD5: ubewX5M7uzz64zskr7FThQ==
Authorization: PaytrailConnectAPI 13466:jmTwcsZlYKM9TuglR0nyNjWXNW8iLWGNvuSJfuvT+9k=

{
    "authType": "email+smspin",
    "authKey": "emma.example@paytrail.com",
    "access": ["deliveryAddress", "charge"],
    "validity": "singleCharge",
    "locale": "fi_FI"
}

Example 4.5. Example HTTP Response

HTTP/1.1 201 Created
Location: /connectapi/authorizations/AXJD28237XSDHJS18928

4.5. Confirming authorization

The authorization resources must be confirmed before they become usable. This is done by creating a confirmation resource for the authorization.

Example 4.6. POST /connectapi/authorizations/{id}/confirmation

request body
{
    "authSecret": string
}

HTTP Status codes

201: Confirmation succeeded

400: Confirmation failed due to given JSON being malformed or authSecret left blank

404: Not confirmed. Request failed. Either wrong authSecret was supplied or authorization resource does not exist


Table 4.3. Parameters

NameTypem/oDescription
authSecretStringmThe secret value provided to the Paytrail account owner via SMS to authorize requested access.

Example 4.7. Example HTTP Request

POST /connectapi/authorizations/AXJD28237XSDHJS18928/confirmation HTTP/1.1
Timestamp: 2012-12-31T12:00:00+02:00
Content-MD5: ubewX5M7uzz64zskr7FThQ==
Authorization: PaytrailConnectAPI 13466:/YT5YGOUA17wK6qSeyQyrLqcGsUKflRkeWu/2q7NI2g=

{
    "authSecret": "1234"
}

Example 4.8. Example HTTP Response

HTTP/1.1 201 Created

4.6. Charging a payment with a confirmed authorization

Once the authorization resource with charge access is confirmed, a payment can be charged from the Paytrail account while the authorization is valid. The Paytrail account owner is notified by SMS immediately after charging.

Charge process can be either immediate or delayed:

  • immediate, HTTP 201 response: payment is completed and the payment method is charged
  • delayed, HTTP 202 response: payment details have been accepted for processing but user interaction in Paytrail account is needed to complete payment. Possible reasons:
    1. Insufficient funds, or other reason prevented authorization on the payment method
    2. Missing payment method in Paytrail account
    3. Large payment amount triggered an identification check
    4. New delivery address triggered an identification check

In case of 202 and the delayed process, the API caller should instruct or redirect the customer to complete the payment at the location returned in userActionURL.

Example 4.9. POST /connectapi/authorizations/{id}/charges

Request body
{
    payment: { payment data according to A1 specification }
}
HTTP Status Codes

201: On successful charging

202: User action is needed

400: Address or payment data is malformed, not accepted or missing

404: Authorization does not exist


Table 4.4. Parameters

NameTypem/oDescription
paymentstructm

JSON struct containing the payment to be charged. The contents of the struct is defined in the A1 payment data specification.

Also contains the return URLs:

success – only used for returning the user, no information about payment

cancel – only used for returning the user, no information about payment

notify – called by Paytrail as soon as there is sufficient information (before or after user return), as described below


Example 4.10. Example HTTP Request

POST /connectapi/authorizations/AXJD28237XSDHJS18928/charges HTTP/1.1
Timestamp: 2012-12-31T12:00:00+02:00
Content-MD5: ubewX5M7uzz64zskr7FThQ==
Authorization: PaytrailConnectAPI 13466:ZNcGFgz3bWCvIEV05wyBKCQUcW85ZLazTZz8HxhvJHE=

{
    payment: { payment data according to A1 specification }
}

Example 4.11. Example HTTP Response after immediate charging

HTTP/1.1 201 Created
Location: /connectapi/authorizations/AXJD28237XSDHJS18928/charges/FF1236757632ASDF

Example 4.12. Example HTTP Response after requiring customer interaction

HTTP/1.1 202 Accepted
Location: /connectapi/authorizations/AXJD28237XSDHJS18928/charges/FF1236757632ASDF

{
    "payment": {
        "orderNumber": "MY-ORDER-123",
        "status": "created",
        "userActionUrl": "https://account.paytrail.com/fi_FI/svt/entry/connectapi/token/872a37ab1cf21ad805579266ad7a2ec3929eb50146fa491935e2d3a1aa0813"
    }
}

4.7. A1 Payment data specification

This part describes the JSON payment data to be sent along POST .../charges requests. If a parameter is not mandatory, it can be empty or omitted from the payment data.

Example 4.13. Payment Interface: A1 Field Specification

{
"payment": {
    "type": "object",
    "properties": {
        "paymentAmount": {
            "type": "number",
            "required": "true",
            "description": "The amount charged from the customer, which might include a VAT. If payment data contains product rows, those row amounts do not affect the charged amount
            and they are only for informative purpose. Amount should be the sum of all product's totalRowAmounts.",
            "minimum": 0,65
        },
        "currency": {
            "type": "string",
            "required": "true",
            "description": "Valid values described in ISO 4217. At the moment only allowed currency is "EUR",
            "pattern": "^EUR$"
        },
        "orderNumber": {
            "type": "string",
            "required": "true",
            "description": "Can be used to identify payments in Merchant's Panel.",
            "minLength": 1,
            "maxLength": 64
        },
        "urlSet": {
            "type": "object",
            "properties": {
                "successUrl": {
                    "type": "string",
                    "required": "true",
                    "description": "URL where the customer is redirected after successful payment. The webshop should generate an identifier into the URL to distiguish a payment to be confirmed.",
                    "minLength": 11,
                    "maxLength": 2048,
                },
                "cancelUrl": {
                    "type": "string",
                    "required": "true",
                    "description": "URL where the customer is redirected after a failed or cancelled payment.",
                    "minLength": 11,
                    "maxLength": 2048,
                },
                    "notifyUrl": {
                    "type": "string",
                    "required": "true",
                    "description": "URL to be called when the payment has been marked as paid. This URL is called with same GET parameters as successUrl when the payment is marked as paid.
                    Note that notifyUrl request is done by Paytrail server and customer's browser session is not available. NotifyUrl request is normally done within a couple of minutes
                    from completing the payment.",
                    "minLength": 11,
                    "maxLength": 2048,
                }
            }
        },
        "locale": {
            "type": "string",
            "required": "true",
            "description": "Affects the language and how amounts and dates are shown on Paytrail account website if user is redirected there for interaction. Available locales are fi_FI,
            sv_SE and en_US.",
            "minLength": 5,
            "maxLength": 5,
            "pattern": "^[a-z]{2}_[A-Z]{2}$"
        },
        "deliveryAddress": {
            "type": "object",
            "required": "true",
            "description": "",
            "properties": {
                "firstName": {
                    "type": "string",
                    "required": "true",
                    "description": "",
                    "minLength": 1,
                    "maxLength": 64
                },
                "lastName": {
                    "type": "string",
                    "required": "true",
                    "description": ""
                    "minLength": 1,
                    "maxLength": 64
                },
                "street": {
                    "type": "string",
                    "required": "true",
                    "description": "Address line",
                    "minLength": 1,
                    "maxLength": 64
                },
                "postalCode": {
                    "type": "string",
                    "required": "true",
                    "description": "",
                    "minLength": 1,
                    "maxLength": 64
                },
                "postalOffice": {
                    "type": "string",
                    "required": "true",
                    "description": "",
                    "minLength": 1,
                    "maxLength": 64
                },
                "country": {
                    "type": "string",
                    "required": "true",
                    "description": "Two characters. Defined in ISO-3166-1"
                    "pattern": "^[A-Z]{2}$"
                }
            }
        },
        "products": {
            "type": "array",
            "required": "true",
            "description": "",
            "maxItems": 500,
            "items": {
                "code": {
                    "type": "string",
                    "required": "false",
                    "description": "Optional product number. This is shown in Merchant's Panel with the product. This might help in associating the product rows to actual products.",
                    "minLength": 1,
                    "maxLength": 16
                },
                "name": {
                    "type": "string",
                    "required": "true",
                    "description": "Free field for product name. Product name will be shown in Merchant's Panel",
                    "minLength": 1,
                    "maxLength": 64
                },
                "quantity": {
                    "type": "number",
                    "required": "true",
                    "description": "Number of products. Usually the value is 1. Can be decimal of format 0.00"
                },
                "unitPrice": {
                    "type": "number",
                    "required": "true",
                    "description": "A price for a single product. Price may be negative to signify a discount. Payment total must be positive ant the format is 0.00. The amounts are for
                    informative purposes only and do not affect the payment total charged from the customer."
                },
                "totalRowAmount": {
                    "type": "number",
                    "required": "true",
                    "description": "This field is used to display row total to the customer. This field must contain the calculated total of quantity * unitPrice to avoid any precision
                    errors when displaying values to customer."
                },
                "vatPercent": {
                    "type": "number",
                    "required": "true",
                    "description": "Vat percent e.g. 25. Supports also decimals like 12.5"
                }
            }
        }
    }
}

Example 4.14. Example A1 Payment JSON

{
    "payment": {
        "paymentAmount": 39.99,
        "currency": "EUR",
        "orderNumber": "ORD12345",
        "urlSet": {
            "successUrl": "https://www.examplewebshop.com/success",
            "cancelUrl": "https://www.examplewebshop.com/cancel",
            "notifyUrl": "https://www.examplewebshop.com/notify"
        },
        "locale": "en_US",
        "deliveryAddress": {
            "firstName": "Penny",
            "lastName": "Paytrail",
            "street": "Lutakonaukio 7",
            "postalCode": "40100",
            "postalOffice": "Jyväskylä",
            "country": "FI"
        },
        "products": [
            {
                "code": "PX923423",
                "name": "Book: How to implement PaytrailConnectAPI",
                "quantity": 1,
                "unitPrice": 39.99,
                "totalRowAmount": 39.99,
                "vatPercent": 24
            }
        ]
    }
}

4.8. Receiving notification of a completed payment

Paytrail will notify the webshop as soon as the payment has been charged. This notify URL should only respond to Paytrail.

4.9. Retrieving payment status

In addition to Paytrail notifying the merchant of payment status, the merchant may inquire payment status.

Example 4.15. GET /connectapi/authorizations/{id}/charges/{id}

HTTP Status Codes

200: Success

404: No such payment or authorization


Table 4.5. Return Value

NameTypeDescription
paymentstruct

Status is one of the following:

  • new
  • created
  • authorized
  • confirmed
  • charged
  • notified
  • canceled

where charged and notified indicate success


Example HTTP response body
HTTP/1.1 200 OK

{
    "payment": {
        "orderNumber": "MY-ORDER-123",
        "status": "notified"
    }
}

4.10. Accessing Paytrail account delivery address information

Once the authorization with deliveryAddress access is confirmed, Paytrail account delivery address information can be retrieved while the authorization is valid. The delivery address information could be used e.g. to prefill order forms in webshops.

Example 4.16. GET /connectapi/authorizations/{id}/deliveryAddresses

HTTP Status Codes

200: On successfully retrieving delivery address array, even an empty one

404: Authorization is not yet confirmed or is invalidated or has no deliveryAddress access


Table 4.6. Return value

NameTypeDescription
deliveryAddressesarray of structsarray of JSON structs containing the delivery addresses which the owner of the Paytrail account has verified in their account settings.
phonestringPhone number associated with the Paytrail account
emailstringEmail address associated with the Paytrail account

Response body
{
    deliveryAddresses: [
        {
            "firstName": string,
            "lastName": string,
            "street": string,
            "postalCode": string,
            "postalOffice": string,
            "country": string
        }
    ],
    "phone": string,
    "email": string
}
        

Example 4.17. Example HTTP Request

GET /connectapi/authorizations/AXJD28237XSDHJS18928/deliveryAddresses HTTP/1.1
Timestamp: 2012-12-31T12:00:00+02:00
Content-MD5: ubewX5M7uzz64zskr7FThQ==
Authorization: PaytrailConnectAPI 13466:/YT5YGOUA17wK6qSeyQyrLqcGsUKflRkeWu/2q7NI2g=

Example 4.18. Example HTTP Response

HTTP/1.1 200 OK

{
    "deliveryAddresses": [
        {
            "firstName": "Emma",
            "lastName": "Example",
            "street": "Lutakonaukio 7",
            "postalCode": "40100",
            "postalOffice": "Jyväskylä",
            "country": "FI"
        }
    ],
    "phone": "3584011111111",
    "email": "emma.example@paytrail.com"
}

4.11. Deleting and invalidating an authorization

Authorizations can be invalidated and deleted by deleting the resource.

Example 4.19. DELETE /authorizations/{id}

HTTP Status Codes

204: Authorization was deleted

404: Invalid authorization state or authorization does not exist


Example 4.20. Example HTTP Request

DELETE /connectapi/authorizations/AXJD28237XSDHJS18928 HTTP/1.1
Timestamp: 2012-12-31T12:00:00+02:00
Content-MD5: ubewX5M7uzz64zskr7FThQ==
Authorization: PaytrailConnectAPI 13466:EFjhnqj4fKUQ/ySGgnllL+aB9PsXGcandzKgzMWapK0=

Example 4.21. Example HTTP Response

HTTP/1.1 204 No Content

4.12. Sequence diagrams

The following diagrams describe the process of using the Paytrail Connect API.

Figure 4.1. SMS PIN authorization for a single charge from Paytrail account

SMS PIN authorization for a single charge from Paytrail account

Figure 4.2. SMS PIN authorization for Paytrail account delivery address data

SMS PIN authorization for Paytrail account delivery address data

Chapter 5. Payment service

5.1. Introduction

Figure 5.1. Payment page

Payment page

Payment service integration is done by either implementing a payment button, or by embedding a selection of payment methods in a web shop to enable the immediate payment of an order. The information of completed payment is instantly relayed back to the web shop.

There are two integration types for implementing the Paytrail payment service.

With the REST interface the payment is created in advance by a XML or JSON request, and the interface responds with a payment token and a URL address. To complete the payment, the customer is redirected to the URL address. The REST interface can thus be used to send a payment link to the customer by e.g. email.

When using the FORM interface, the payment data is created as a form on the web applications page. The consumer sends this form to the payment service. The payment is then completed in the web browser as an immediate result of the customer's actions.

Payment page bypass option for FORM interface allows bypassing the Paytrail payment page and can be used to implement bank payment buttons directly in a web shop.

The payment method page embedding can be used together with either of these implementations to display the payment method selection directly in a web shop. Implementing the embedded payment method selection page is done by adding a short JavaScript call to the page.

5.2. Form interface

5.2.1. Introduction

This chapter describes how a web shop communicates with the payment gateway with Form interface. When using the FORM interface, the payment data is created as a form on the web applications page. The consumer sends this form to the payment service. The payment is then completed in the web browser as an immediate result of the customer's actions.

Figure 5.2. Creating a payment

Creating a payment

5.2.2. Interface versions

Latest and recommended API version is E2. You can still find the documentation for previous API versions S1 and E1 from Deprecated API page.

5.2.3. Migration guide

5.2.3.1. Updates E1 → E2 and S1 → E2

Interface version E2 has replaced the previous versions E1 and S1. E2 is extensible which means that it can be used with or without product and delivery contact data. Interface version upgrade requires definition of fields used in payment creation and return call in fields PARAMS_IN and PARAMS_OUT. Interface version E2 also provides more data when returning from payment process to web shop.

Some of the fields have been renamed or removed but all features supported in E1 and S1 interfaces are still available. Aslo Validation of fields is stricter than with previous versions. Check list of changed fields from the table below.

Table 5.1. Changed payment creation fields comparing E2 to older interfaces

Change typeOld interfaceOld field nameNew E2 Field namenotes
Field renamedE1, S1ORDER_DESCRIPTIONMSG_UI_MERCHANT_PANEL 
Field renamedE1, S1RETURN_ADDRESSURL_SUCCESS 
Field renamedE1, S1CANCEL_ADDRESSURL_CANCEL 
Field renamedE1, S1NOTIFY_ADDRESSURL_NOTIFY 
Field renamedE1, S1CULTURELOCALE 
Field renamedE1, S1PRESELECTED_METHODPAYMENT_METHODS 
Field renamedE1CONTACT_CELLNOPAYER_PERSON_PHONE 
Field renamedE1CONTACT_EMAILPAYER_PERSON_EMAIL 
Field renamedE1CONTACT_FIRSTNAMEPAYER_PERSON_FIRSTNAME 
Field renamedE1CONTACT_LASTNAMEPAYER_PERSON_LASTNAME 
Field renamedE1CONTACT_COMPANYPAYER_COMPANY_NAME 
Field renamedE1CONTACT_ADDR_STREETPAYER_PERSON_ADDR_STREET 
Field renamedE1CONTACT_ADDR_ZIPPAYER_PERSON_ADDR_POSTAL_CODE 
Field renamedE1CONTACT_ADDR_CITYPAYER_PERSON_ADDR_TOWN 
Field renamedE1CONTACT_ADDR_COUNTRYPAYER_PERSON_ADDR_COUNTRY 
Field renamedE1INCLUDE_VATVAT_IS_INCLUDED 
Field renamedE1ITEM_NOITEM_ID 
Field renamedE1ITEM_AMOUNTITEM_QUANTITY 
Field renamedE1ITEM_PRICEITEM_UNIT_PRICE 
Field renamedE1ITEM_TAXITEM_VAT_PERCENT 
Field renamedE1ITEM_DISCOUNTITEM_DISCOUNT_PERCENT 
Field removedE1, S1TYPE- 
Field removedE1, S1PENDING_ADDRESS- 
Field removedE1, S1MODE-Payment page bypass is implemented using field PAYMENT_METHODS
Field removedE1, S1VISIBLE_METHODS-Payment page method visibility selection is implemented using field PAYMENT_METHODS
Field removedE1, S1GROUP- 
Field removedE1CONTACT_TELNO- 
Field removedE1ITEMS- 
New field  PARAMS_INDefines fields sent to payment gateway and used in authcode calculation.
New field  PARAMS_OUT Defines fields returned as a part of URL_SUCCESS, URL_CANCEL and URL_NOTIFY and used in return authcode calculation.
New field  ALGDefines algorithm used in authcode calculation.


5.3. E2

5.3.1. Fields to be sent to payment gateway

5.3.1.1. Interface version E2

Following form describes fields to be sent to payment gateway.

Payment gateway address is https://payment.paytrail.com/e2

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

Field necessity is marked in column Required/Optional. Some optional columns have default values which are used if no value is provided in payment data.

Note

Values may not contain "|" characters (pipe, vertical bar). 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.

Warning

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.

Table 5.2. Form interface: Fields to be sent to payment gateway with interface version E2

Field nameDescriptionRequired/OptionalDefault valueNotes
MERCHANT_IDMerchant ID is the merchant identification number given by Paytrail.R For testing use 13466.
CURRENCYCurrency.OEUROnly EUR is accepted.
URL_SUCCESSURL where customer is redirected after successful payment.R PARAMS_OUT are added to URL_SUCCESS
URL_CANCELURL where customer is redirected after failed or cancelled payment.R PARAMS_OUT are added to URL_CANCEL
ORDER_NUMBEROrder number is used to identify one transaction.R  
AMOUNTPrice is given in euros and cents. Price is given without currency type and decimals are separated with a dot. Price must contain two decimals.R/- AMOUNT or minimum of one order row with ITEM_UNIT_PRICE is required to define payment total. Minimum price accepted by the service is 0.65€.
PARAMS_INComma separated list of fields used in AUTHCODE calculation.R Only values listed in this field are shown in payment data.
PARAMS_OUTComma separated list of fields used in return AUTHCODE calculation.R Only values listed in this field are returned as a part of URL_SUCCESS/URL_CANCEL. Has to contain values PAYMENT_ID, ORDER_NUMBER, TIMESTAMP and STATUS
ALGAlgorithm used in AUTHCODE calculation.O1Available values 1 = "SHA-256"
AUTHCODEPayment fingerprintR AUTHCODE is calculated by joining all fields listed in PARAMS_IN. Fields are joined by placing the "|" character (pipe, vertical bar) 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.
URL_NOTIFYURL 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.O PARAMS_OUT_NOTIFY are added to URL_CANCEL
PARAMS_OUT_NOTIFY (Not yet available)Comma separated list of fields used in notify RETURN_AUTHCODE calculation.O 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.
LOCALEThe default language of payment method selection page.Ofi_FIAvailable locales are "fi_FI", "sv_SE" and "en_US". The default locale is "fi_FI".
REFERENCE_NUMBERReference number to be delivered to payment method provider's service.O 

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.

PAYMENT_METHODS 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. For more information, see Selection and visibility of payment methods O Use requires agreement on use with Paytrail.
VAT_IS_INCLUDEDWhether VAT is included in prices given in ITEM records.O Available values 1 = VAT is included, 0 = VAT is not included. If using the Collector payment method, the value MUST be 1. Collector will not be available if the value is 0.
MSG_SETTLEMENT_PAYERMessage to consumers bank statement or credit card bill if supported by payment method.O  
MSG_SETTLEMENT_MERCHANT (Not yet available)Message to merchants bank statement if supported by payment method.O  
MSG_UI_PAYMENT_METHODMessage shown in payment method provider page. Currently this is supported by Osuuspankki, Visa (Nets), MasterCard (Nets), American Express (Nets) and Diners Club (Nets).O Not all payment methods support showing the message.
MSG_UI_MERCHANT_PANELMessage shown in Merchant's Panel.O  

In addition to these, payer details can be brought to Paytrail service using the following fileds.

Table 5.3. Form interface: Payer for interface version E2

Field nameDescriptionRequired / OptionalDefaultNotes
PAYER_PERSON_FIRSTNAMEPayer's first name.O  
PAYER_PERSON_LASTNAMEPayer's last name.O  
PAYER_PERSON_EMAILPayer's email.O Email is validated, no MX validation
PAYER_PERSON_PHONEPayer's telephone number.O  
PAYER_PERSON_ADDR_STREETPayer's street address.O  
PAYER_PERSON_ADDR_POSTAL_CODEPayer's postal code.O  
PAYER_PERSON_ADDR_TOWNPayer's town.O  
PAYER_PERSON_ADDR_COUNTRYPayer's country.O ISO_3166-2
PAYER_COMPANY_NAMEPayer's company.O  

In addition to these, 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]). Payment total must be positive. Total sum of the product prices must be at least 0.65€.

Table 5.4. Form interface: Product details for interface version E2

Field nameDescriptionRequired / OptionalDefaultNotes
ITEM_TITLE[N]Free field for product name.O/R Required if product rows are included in data.
ITEM_ID[N]Product id.O  
ITEM_QUANTITY[N]Quantity of products.O1If a decimal number such as 0.5 is used, the Collector payment method will be hidden.
ITEM_UNIT_PRICE[N]The price for a single product.O/R Required if product rows are included in data. If VAT_IS_INCLUDED value is 0, this is price not including VAT. Price may be negative value if discount is given.
ITEM_VAT_PERCENT[N]Vat percent used for product.O/R Required if product rows are included in data.
ITEM_DISCOUNT_PERCENT[N]Item discount.O0Percent is a number between 0 and 100.
ITEM_TYPE[N]Type of the product.O1Available values 1 = normal, 2 = shipment cost, 3 = handling cost.

Table 5.5. Validation of fields

Field nameFormMax length
MERCHANT_IDNumeric11
CURRENCYOnly allowed value is EUR3
URL_SUCCESSValid URL including http(s)2048
URL_CANCELValid URL including http(s)2048
ORDER_NUMBER0-9, a-z, A-Z and ()[]{}*+-_,. As regular expression '/^[0-9a-zA-Z()\[\]{}*+\-_,. ]{1,64}$/'64
AMOUNTFloat between 0.65 and 49999910
PARAMS_IN0-9, A-Z, [],_4096
PARAMS_OUT0-9, A-Z, [],_255
ALGOnly allowed value is 12
AUTHCODE0-9, A-Z64
URL_NOTIFYValid URL including http(s)2048
PARAMS_OUT_NOTIFY (Not yet available)0-9, A-Z, [],_255
LOCALEAllowed values are fi_FI, sv_SE and en_US. As regular expression '/^[a-z]{1,2}[_][A-Z]{1,2}$/'5
REFERENCE_NUMBERAlphanumeric, either numeric value complying Finnish reference number standard or numeric Finnish reference number in international RF format (e.g. 1232 or RF111232)20
PAYMENT_METHODS0-9 and ,64
VAT_IS_INCLUDEDAllowed values 0 and 11
MSG_SETTLEMENT_PAYERUnicode alphabets and ()[]{}*+-_,."' As regular expression '/^[\pL-0-9- "\', ()\[\]{}*+\-_,.]*$/u'255
MSG_SETTLEMENT_MERCHANTUnicode alphabets and ()[]{}*+-_,."' See regular expression from MSG_SETTLEMENT_PAYER255
MSG_UI_PAYMENT_METHODUnicode alphabets and ()[]{}*+-_,."' See regular expression from MSG_SETTLEMENT_PAYER255
MSG_UI_MERCHANT_PANELUnicode alphabets and ()[]{}*+-_,."' See regular expression from MSG_SETTLEMENT_PAYER255
PAYER_PERSON_FIRSTNAMEUnicode alphabets and ()[]{}*+-_,:&!?@#$£=*;~/"'. As regular expression '/^[\pL-0-9- "\',()\[\]{}*\/+\-_,.:&!?@#$£=*;~]*$/u'64
PAYER_PERSON_LASTNAMEUnicode alphabets and ()[]{}*+-_,:&!?@#$£=*;~/"'. See regular expression from PAYER_PERSON_FIRSTNAME64
PAYER_PERSON_EMAILlocal-part@domain, max lenght for local part is 64255
PAYER_PERSON_PHONE0-9, +-64
PAYER_PERSON_ADDR_STREETUnicode alphabets128
PAYER_PERSON_ADDR_POSTAL_CODE0-9, a-z, A-Z16
PAYER_PERSON_ADDR_TOWNUnicode alphabets and ()[]{}*+-_,:&!?@#$£=*;~/"'. See regular expression from PAYER_PERSON_FIRSTNAME64
PAYER_PERSON_ADDR_COUNTRYa-z, A-Z2
PAYER_COMPANY_NAMEUnicode alphabets and ()[]{}*+-_,:&!?@#$£=*;~/"'. See regular expression from PAYER_PERSON_FIRSTNAME128
ITEM_TITLE[N]Unicode alphabets and ()[]{}*+-_,:&!?@#$£=*;~/"'. See regular expression from PAYER_PERSON_FIRSTNAME255
ITEM_ID[N]0-9, a-z, A-Z16
ITEM_QUANTITY[N]Float10
ITEM_UNIT_PRICE[N]Float between 0 and 499 999,9910
ITEM_VAT_PERCENT[N]Float between 0 and 10010
ITEM_DISCOUNT_PERCENT[N]Float10
ITEM_TYPE[N]Allowed values are 1, 2 and 31

5.3.2. Calculating the payment fingerprint (AUTHCODE)

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

Example 5.1. Calculating the payment fingerprint with form data for interface version E2 including all optional fields

This example covers sending payment information in the most complete form. This form is placed in the web shop by the payment method selection. The form shows the payment button currently in use and moves customer to payment service payment selection page when clicked. All fields are listed in this example, including optional unnecessary fields for better clarity. They can be removed from the form.

<form action="https://payment.paytrail.com/e2" method="post">
  <input name="MERCHANT_ID" type="hidden" value="13466">
  <input name="CURRENCY" type="hidden" value="EUR">
  <input name="URL_SUCCESS" type="hidden" value="http://www.example.com/success">
  <input name="URL_CANCEL" type="hidden" value="http://www.example.com/cancel">
  <input name="ORDER_NUMBER" type="hidden" value="123456">
  <input name="PARAMS_IN" type="hidden" value="MERCHANT_ID,CURRENCY,URL_SUCCESS,URL_CANCEL,ORDER_NUMBER,PARAMS_IN,PARAMS_OUT,URL_NOTIFY,LOCALE,REFERENCE_NUMBER,PAYMENT_METHODS,VAT_IS_INCLUDED,MSG_UI_MERCHANT_PANEL,PAYER_PERSON_FIRSTNAME,PAYER_PERSON_LASTNAME,PAYER_PERSON_EMAIL,PAYER_PERSON_PHONE,PAYER_PERSON_ADDR_STREET,PAYER_PERSON_ADDR_POSTAL_CODE,PAYER_PERSON_ADDR_TOWN,PAYER_PERSON_ADDR_COUNTRY,PAYER_COMPANY_NAME,ITEM_TITLE[0],ITEM_ID[0],ITEM_QUANTITY[0],ITEM_UNIT_PRICE[0],ITEM_VAT_PERCENT[0],ITEM_DISCOUNT_PERCENT[0],ITEM_TITLE[1],ITEM_ID[1],ITEM_QUANTITY[1],ITEM_UNIT_PRICE[1],ITEM_VAT_PERCENT[1],ITEM_DISCOUNT_PERCENT[1],ITEM_TYPE[1],ALG">
  <input name="PARAMS_OUT" type="hidden" value="ORDER_NUMBER,PAYMENT_ID,AMOUNT,CURRENCY,PAYMENT_METHOD,TIMESTAMP,STATUS">
  <input name="URL_NOTIFY" type="hidden" value="http://www.example.com/notify">
  <input name="LOCALE" type="hidden" value="en_US">
  <input name="REFERENCE_NUMBER" type="hidden" value="">
  <input name="PAYMENT_METHODS" type="hidden" value="">
  <input name="VAT_IS_INCLUDED" type="hidden" value="1">
  <input name="MSG_UI_MERCHANT_PANEL" type="hidden" value="Order 123456">
  <input name="PAYER_PERSON_FIRSTNAME" type="hidden" value="John">
  <input name="PAYER_PERSON_LASTNAME" type="hidden" value="Doe">
  <input name="PAYER_PERSON_EMAIL" type="hidden" value="john.doe@example.com">
  <input name="PAYER_PERSON_PHONE" type="hidden" value="01234567890">
  <input name="PAYER_PERSON_ADDR_STREET" type="hidden" value="Test street 1">
  <input name="PAYER_PERSON_ADDR_POSTAL_CODE" type="hidden" value="608009">
  <input name="PAYER_PERSON_ADDR_TOWN" type="hidden" value="Test town">
  <input name="PAYER_PERSON_ADDR_COUNTRY" type="hidden" value="AA">
  <input name="PAYER_COMPANY_NAME" type="hidden" value="Test company">
  <input name="ITEM_TITLE[0]" type="hidden" value="Product 101">
  <input name="ITEM_ID[0]" type="hidden" value="101">
  <input name="ITEM_QUANTITY[0]" type="hidden" value="2">
  <input name="ITEM_UNIT_PRICE[0]" type="hidden" value="300.00">
  <input name="ITEM_VAT_PERCENT[0]" type="hidden" value="15.00">
  <input name="ITEM_DISCOUNT_PERCENT[0]" type="hidden" value="50">
  <input name="ITEM_TYPE[0]" type="hidden" value="1">
  <input name="ITEM_TITLE[1]" type="hidden" value="Product 202">
  <input name="ITEM_ID[1]" type="hidden" value="202">
  <input name="ITEM_QUANTITY[1]" type="hidden" value="4">
  <input name="ITEM_UNIT_PRICE[1]" type="hidden" value="12.50">
  <input name="ITEM_VAT_PERCENT[1]" type="hidden" value="0">
  <input name="ITEM_DISCOUNT_PERCENT[1]" type="hidden" value="0">
  <input name="ITEM_TYPE[1]" type="hidden" value="1">
  <input name="ALG" type="hidden" value="1">
  <input name="AUTHCODE" type="hidden" value="70221C35F61EAAAAFD1A42E32426467D6DDB37411CFEEEAFD1E03782F26E77F8">
  <input type="submit" value="Pay here">
</form>
            

Table 5.6. Fields to be sent to payment gateway with interface version E2

Field nameValue
Merchant authentication hash6pKF4jkv97zmqBJ3ZL8gUw5DfT2NMQ
MERCHANT_ID13466
CURRENCYEUR
URL_SUCCESShttp://www.example.com/success
URL_CANCELhttp://www.example.com/cancel
ORDER_NUMBER123456
PARAMS_INMERCHANT_ID,CURRENCY,URL_SUCCESS,URL_CANCEL,ORDER_NUMBER,PARAMS_IN,PARAMS_OUT,URL_NOTIFY,LOCALE,REFERENCE_NUMBER,PAYMENT_METHODS,VAT_IS_INCLUDED,MSG_UI_MERCHANT_PANEL,PAYER_PERSON_FIRSTNAME,PAYER_PERSON_LASTNAME,PAYER_PERSON_EMAIL,PAYER_PERSON_PHONE,PAYER_PERSON_ADDR_STREET,PAYER_PERSON_ADDR_POSTAL_CODE,PAYER_PERSON_ADDR_TOWN,PAYER_PERSON_ADDR_COUNTRY,PAYER_COMPANY_NAME,ITEM_TITLE[0],ITEM_ID[0],ITEM_QUANTITY[0],ITEM_UNIT_PRICE[0],ITEM_VAT_PERCENT[0],ITEM_DISCOUNT_PERCENT[0],ITEM_TITLE[1],ITEM_ID[1],ITEM_QUANTITY[1],ITEM_UNIT_PRICE[1],ITEM_VAT_PERCENT[1],ITEM_DISCOUNT_PERCENT[1],ITEM_TYPE[1],ALG
PARAMS_OUTORDER_NUMBER,PAYMENT_ID,AMOUNT,CURRENCY,PAYMENT_METHOD,TIMESTAMP,STATUS
URL_NOTIFYhttp://www.example.com/notify
LOCALEen_US
REFERENCE_NUMBER 
PAYMENT_METHODS 
VAT_IS_INCLUDED1
MSG_UI_MERCHANT_PANELOrder 123456
MSG_UI_MERCHANT_PANELOrder 123456
PAYER_PERSON_FIRSTNAMEJohn
PAYER_PERSON_LASTNAMEDoe
PAYER_PERSON_EMAILjohn.doe@example.com
PAYER_PERSON_PHONE01234567890
PAYER_PERSON_ADDR_STREETTest street 1
PAYER_PERSON_ADDR_POSTAL_CODE608009
PAYER_PERSON_ADDR_TOWNTest town
PAYER_PERSON_ADDR_COUNTRYAA
PAYER_COMPANY_NAMETest company
ITEM_TITLE[0]Product 101
ITEM_ID[0]Product 101
ITEM_QUANTITY[0]2
ITEM_UNIT_PRICE[0]300.00
ITEM_VAT_PERCENT[0]15.00
ITEM_DISCOUNT_PERCENT[0]50
ITEM_TYPE[0]1
ITEM_TITLE[1]Product 101
ITEM_ID[1]202
ITEM_QUANTITY[1]4
ITEM_UNIT_PRICE[1]12.50
ITEM_VAT_PERCENT[1]0
ITEM_DISCOUNT_PERCENT[1]0
ITEM_TYPE[1]1
ALG1
AUTHCODE46ACCD7AE91ED504668662AA267E6C1ACAFA18C3670EF043D321778F5746FE3F

Now the string to be used for AUTHCODE calculation is formed by joining the fields above:

6pKF4jkv97zmqBJ3ZL8gUw5DfT2NMQ|13466|EUR|http://www.example.com/success|http://www.example.com/cancel|123456|MERCHANT_ID,CURRENCY,URL_SUCCESS,URL_CANCEL,ORDER_NUMBER,PARAMS_IN,PARAMS_OUT,URL_NOTIFY,LOCALE,REFERENCE_NUMBER,PAYMENT_METHODS,VAT_IS_INCLUDED,MSG_UI_MERCHANT_PANEL,PAYER_PERSON_FIRSTNAME,PAYER_PERSON_LASTNAME,PAYER_PERSON_EMAIL,PAYER_PERSON_PHONE,PAYER_PERSON_ADDR_STREET,PAYER_PERSON_ADDR_POSTAL_CODE,PAYER_PERSON_ADDR_TOWN,PAYER_PERSON_ADDR_COUNTRY,PAYER_COMPANY_NAME,ITEM_TITLE[0],ITEM_ID[0],ITEM_QUANTITY[0],ITEM_UNIT_PRICE[0],ITEM_VAT_PERCENT[0],ITEM_DISCOUNT_PERCENT[0],ITEM_TITLE[1],ITEM_ID[1],ITEM_QUANTITY[1],ITEM_UNIT_PRICE[1],ITEM_VAT_PERCENT[1],ITEM_DISCOUNT_PERCENT[1],ITEM_TYPE[1],ALG|ORDER_NUMBER,PAYMENT_ID,AMOUNT,CURRENCY,PAYMENT_METHOD,TIMESTAMP,STATUS|http://www.example.com/notify|en_US|||1|Order 123456|John|Doe|john.doe@example.com|01234567890|Test street 1|608009|Test town|AA|Test company|Product 101|101|2|300.00|15.00|50|1|Product 202|202|4|12.50|0|0|1|1

SHA-256 sum is counted from this string (note uppercase): 46ACCD7AE91ED504668662AA267E6C1ACAFA18C3670EF043D321778F5746FE3F


Example 5.2. Calculating the payment fingerprint with form data for interface version E2 including minimum set of fields

This is an example of minimum implementation of E2 interface as only required fields are included.

<form action="https://payment.paytrail.com/e2" method="post">
  <input name="MERCHANT_ID" type="hidden" value="13466">
  <input name="CURRENCY" type="hidden" value="EUR">
  <input name="URL_SUCCESS" type="hidden" value="http://www.example.com/success">
  <input name="URL_CANCEL" type="hidden" value="http://www.example.com/cancel">
  <input name="ORDER_NUMBER" type="hidden" value="123456">
  <input name="AMOUNT" type="hidden" value="350.00">
  <input name="PARAMS_IN" type="hidden" value="MERCHANT_ID,CURRENCY,URL_SUCCESS,URL_CANCEL,ORDER_NUMBER,AMOUNT,PARAMS_IN,PARAMS_OUT">
  <input name="PARAMS_OUT" type="hidden" value="PAYMENT_ID,TIMESTAMP,STATUS">
  <input name="AUTHCODE" type="hidden" value="DAA49553843682987B8A03AE1D616DA34A7F596C2B333C4713ECE2745B663896">
  <input type="submit" value="Pay here">
</form>
            

Table 5.7. Fields to be sent to payment gateway with interface version E2 with only required fields

Field nameValue
Merchant authentication hash6pKF4jkv97zmqBJ3ZL8gUw5DfT2NMQ
MERCHANT_ID13466
URL_SUCCESShttp://www.example.com/success
URL_CANCELhttp://www.example.com/cancel
ORDER_NUMBER123456
AMOUNT350.00
PARAMS_INMERCHANT_ID,URL_SUCCESS,URL_CANCEL,ORDER_NUMBER,AMOUNT,PARAMS_IN,PARAMS_OUT
PARAMS_OUTPAYMENT_ID,TIMESTAMP,STATUS
AUTHCODEDAA49553843682987B8A03AE1D616DA34A7F596C2B333C4713ECE2745B663896

Now the string to be used for AUTHCODE calculation is formed by joining the fields above:

6pKF4jkv97zmqBJ3ZL8gUw5DfT2NMQ|13466|http://www.example.com/success|http://www.example.com/cancel|123456|350.00|MERCHANT_ID,URL_SUCCESS,URL_CANCEL,ORDER_NUMBER,AMOUNT,PARAMS_IN,PARAMS_OUT|PAYMENT_ID,TIMESTAMP,STATUS

SHA-256 sum is counted from this string (note uppercase): DAA49553843682987B8A03AE1D616DA34A7F596C2B333C4713ECE2745B663896


5.3.3. Receiving the Payment Receipt with interface version E2

Payment receipt includes fields defined in PARAMS_OUT. Receipt always includes values PAYMENT_ID, TIMESTAMP, STATUS and RETURN_AUTHCODE.

After the payment has been successfully completed, the customer is redirected to the URL defined in the previous stage (URL_SUCCESS). If the payment was cancelled, the customer is directed to the cancelled payment URL (URL_CANCEL).

The notification address (URL_NOTIFY) is called when Paytrail marks the payment as completed. Typically this happens within a few minutes after redirecting the customer to URL_SUCCESS. If the customer does not return to Paytrail's service from the bank's service, the information on successful payment will not be immediately available. In this case URL_NOTIFY will be called immediately when that information has arrived. Usually the information arrives within 24 hours. URL_NOTIFY call includes parameters defined in PARAMS_OUT_NOTIFY.

The receipt carries unique return information that is used to verify the validity of the receipt and that the payment was actually successful. Return authentication AUTHCODE is compared to the hash calculated and if the values match, the payment receipt was not tampered.

In return AUTHCODE calculation, fields are joined using the "|" character (pipe, vertical bar) as separator. Authcode calculation fields are joined in the order defined in PARAMS_OUT field. Merchant hash is appended to the string.

Table 5.8. Receipt contains these fields

Field nameDescriptionNotes
ORDER_NUMBERThis is the same order number that was sent to the Payment Gateway.Value is always included.
PAYMENT_IDUnique id for payment.Value is always included.
AMOUNTPayment totalValue is always included. AMOUNT equals the value provided in payment creation.
CURRENCYCurrency. 
PAYMENT_METHODPayment method which was selected at payment method page (or preselected with value PAYMENT_METHODS).Value is empty is no payment method has been selected.
TIMESTAMP Timestamp generated by the Payment Gateway that is used to calculate the return authentication hash. Timestamp is in UNIX format, i.e. seconds from 1/1/1970. Value is always included.
STATUSIt is used to verify the validity of a successful payment.Possible values PAID and CANCELLED.
SETTLEMENT_REFERENCE_NUMBERThis is the same reference number that was sent to the Payment Gateway or the reference number generated by Paytrail. 
RETURN_AUTHCODE Return authentication hash is a checksum value. If the checksum matches the calculated one, the payment has been completed and the information has not been modified after sending. Value is always included.


5.3.4. RETURN_AUTHCODE calculation

Table 5.9. Example of calculation

ORDER_NUMBERORDER-12345
PAYMENT_ID123456789012
AMOUNT200.00
TIMESTAMP1491896573
STATUSPAID
Merchant authentication hash6pKF4jkv97zmqBJ3ZL8gUw5DfT2NMQ


Combining these fields using the "|" character as separator, the following string is formed: ORDER-12345|123456789012|200.00|1491896573|PAID|6pKF4jkv97zmqBJ3ZL8gUw5DfT2NMQ

Calculating the SHA-256 hash of this string, we get (note uppercase): 86CC6A9B9433D3AC1D8D1B8D21ED87DA3ABE2E980D3F826D1901FEF0925F5D03

If the calculated hash equals the one received from the Payment Gateway (RETURN_AUTHCODE), the receipt is correct.

5.4. Selection and visibility of payment methods

5.4.1. Introduction

This chapter introduces payment method specific settings: field PAYMENT_METHODS for selecting and hiding methods and list of special payment method specific restrictions in teh table below.

Field PAYMENT_METHODS is a 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.

Payment page bypass is a premium feature that enables the selection of the payment method already in the web shop. When using bypass, the customer is directed to the selected payment service without visibly passing through Paytrail's service.

5.4.2. Payment method values

Table 5.10. Available payment method IDs

Method nameIDTypeSpecial settings
Nordea1Finnish bank 
Osuuspankki2Finnish bank 
Danske Bank3Finnish bank 
Ålandsbanken5Finnish bank 
Handelsbanken6Finnish bank 
PayPal9debit/credit card Only available as interface; requires own agreement with PayPal and is hidden until credentials are saved in Merchant's Panel
S-Pankki10Finnish bank 
Klarna Invoice11Invoice Hidden if PAYER_PERSON_PHONE is not defined. Only available as interface; requires own agreement with Klarna and is hidden until credentials are saved in Merchant's Panel. Payment fails if product details or payer details (name, address, phone number) are missing
Klarna Installment12Invoice Hidden if PAYER_PERSON_PHONE is not defined. Only available as interface; requires own agreement with Klarna and is hidden until credentials are saved in Merchant's Panel. Payment fails if product details or payer details (name, address, phone number) are missing
Jousto18InvoiceHidden if amount is less than 20 € or greater than 5000 €
Visa30debit/credit card 
MasterCard31debit/credit card 
Diners Club34credit card 
JCB35debit/credit card 
Paytrail account36debit/credit card 
Aktia50Finnish bank 
POP Pankki51Finnish bank 
Säästöpankki52Finnish bank 
Visa (Nets)53debit/credit card 
MasterCard (Nets)54debit/credit card 
Diners Club (Nets)55credit card 
American Express (Nets)56credit card 
MobilePay58debit/credit card 
Collector Bank60invoice Hidden if VAT_IS_INCLUDED value is not 1, ITEM_AMOUNT[n] is not whole number, amount is greater than 5000 €, product details are missing. Payment fails if payer details (name, address) are missing
Oma Säästöpankki61Finnish bank 


5.5. REST interface (BETA)

5.5.1. Introduction

Note

REST interface is a beta feature. If you have questions about it, please contact .

Note

REST interface does not support payment page bypass.

Paytrail payment REST interface can be used to create a payment with a server-to-server request and thus limits usage less than the form interface. With the REST interface, the payment is created in advance by sending payment data as an XML or JSON message over HTTPS. Service returns the response message in the corresponding format.

We provide a PHP class that implements this interface. The interface is described more closely in the following chapters.

When using the form interface the payment data is sent from a customer's browser to Paytrail service, but when using the REST interface customer's server sends the payment data to Paytrail service in XML or JSON format. The response message is returned in the same format.

When using the REST interface, the data that is sent to the payment service must always be UTF-8 encoded.

Figure 5.3. Payment creation with the REST interface

Payment creation with the REST interface

5.5.2. Interface use

When using the REST service, always include the following headers:

Content-Type
Sent message type. The message can be sent either in XML or JSON format. Corresponding types are application/xml and application/json.
X-Verkkomaksut-Api-Version
Interface version. The current REST interface version is "1".

Each request sent to the interface must be verified with Basic authentication (Authorization header). Basic authentication sends the Merchant ID as a username and the Merchant secret as a password.

5.5.3. Payment creation

Paytrail payment service REST interface allows for creating a payment in advance with a simple HTTP POST request, which sends the payment data as an XML or JSON message. The request returns an order number, payment ID (token) and URL-address for making a payment. In a typical case, a webshop creates a payment with the REST interface at the end of an order process, and redirects the customer to the returned URL.

Service address: https://payment.paytrail.com/api-payment/create

The root name of the sent XML message is payment. The parameters for creating a payment are as follows:

orderNumber
(all characters[64], required) Order number. Order number is a string of characters identifying the customer's purchase.
referenceNumber
(number[22], optional) Reference number to be sent 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.
description
(all characters[65 000], optional) Any data about the order in text format can be sent to the payment system. The most usual pieces of data are customer name and contact information and order product information. They are shown in the Merchant's Panel in payment details.
currency
(upper case[3], required) Payment currency. Value must be EUR for Finnish banks, otherwise the payment will not be accepted.
locale
(all characters[5], optional) Localisation defines default language for the payment method selection page and presentation format for the sums. Available localisations are "fi_FI" , "sv_SE" and "en_US". The default localisation is “fi_FI”.
urlSet
(required)
success
(all characters[2048], required) User is redirected to this URL after a successful payment to Paytrail.
failure
(all characters[2048], required) User is redirected to this URL after a cancelled or failed payment.
notification
(all characters[2048], required) Paytrail makes a request to this URL when the payment is marked as successful. The address is requested with the same GET parameters as the success address was when the payment was made. Notification request is typically executed within a few minutes from the payment.
orderDetails
(optional) Either orderDetails or payment sum price has to be specified. orderDetails record contains payer details and detailed order rows. We recommend using the orderDetails record whenever it is possible. If the orderDetails record is not supplied, invoice and instalment payment methods are not available and payer and order row details are not available in the Merchant's Panel. Payment method fees can only be used when the orderDetails record is used. Without orderDetails record the order details cannot be shown on the payment method selection page.
includeVat
(0/1, required) VAT included -field shows if the product row prices include value added tax. Value 1 means that VAT is included in the shown price, and 0 that it will be added. Therefore, use 1, if the prices in your webshop include value added tax and 0 if the prices do not include value added tax. If Collector payment method is used, then the value should be 1, or the payment method is hidden from the payment method selection page.
contact
(required)
firstName
(all characters [64], required) Customer's first name.
lastName
(all characters [64], required) Customer's surname.
companyName
(all characters[128], optional) Company name.
email
(all characters[255], required) Customer's email address.
telephone
(all characters[64], optional) Customer's telephone number.
mobile
(all characters[64], optional) Customer's mobile number.
address
(required)
street
(all characters [64], required) Customer's street address.
postalCode
(all characters[16], required) Customer's postal code.
postalOffice
(all characters[64], required) Customer's post office.
country
(capital letters[2], required) Customer's country. The data is sent in ISO-3166-1 format. For example, Finnish is FI and Swedish is SE. The data is used to verify credit history, and is thus required.
products
(required)
product (recurring element [1,500])
title
(all characters[255], required) Product name in free format. The product title is shown in the Merchant's Panel and on Klarna service invoices on a product row. Product details are shown also on the payment method selection page.
code
(all characters[16], optional) Optional product number.
amount
(decimal number[10], required) If an order has several same products, you can enter the number of products here instead of having separate rows for each. Usually this field contains the value 1. If Collector payment method is used, the value should be an integer. If a decimal such as 0.5 is used, Collector payment method is hidden from the payment method selection page.
price
(decimal number[10], required) Price for one product. If the field payment.orderDetails.includeVat = 0, the price excludes VAT. If the value is 1, the price includes VAT. The price can also be negative if you want to add discounts to the service. However, the total amount of the product rows must always be at least 0.65.
vat
(decimal number[10], required) Tax percentage for a product.
discount
(decimal number[10], optional) If you have reduced the product price, you can show the discount percentage as a figure between 0 and 100 in this field. Default is 0.
type
(integer[1], optional) A type can be specified for the product row. 1: normal product row, 2: shipping, 3: handling. 1 can be used for all rows, but shipping and handling costs cannot be differentiated from the other rows. Default is 1.
price
(decimal number[10], optional) Payment total. Send either exact payment data (orderDetails) or the payment total to the service. If you send only the payment total price, (Klarna and Collector) invoice and instalment payment methods are not available and order details cannot be shown in the Merchant's Panel. We recommend using orderDetails record whenever it is possible. The value of price must be >= 0.65.

The service responds to request in the same format (XML or JSON) as it was received. Return record root element is also called payment and it contains the following records:

orderNumber
(all characters[64]) The order number sent on the request is returned as such.
token
(lower and upper case and numbers[64]) Token is 64 characters long, specifying identifier for the payment, which is valid for 14 days or until the payment has been made. Token is needed as such with the payment method selection page embedding.
url
(all characters) Address to which the customer is directed for making the payment. The URL also includes the token, which is used as a payment identifier.

Note

The example XML and JSON messages have been wrapped and indented to make the message more readable. Messages returned by the interface do not contain such formatting.

Example 5.3. Payment creation with the REST interface; XML request

<?xml version="1.0" encoding="UTF-8"?>
<payment>
  <orderNumber>12345678</orderNumber>
  <currency>EUR</currency>
  <locale>fi_FI</locale>
  <urlSet>
    <success>https://www.esimerkkikauppa.fi/sv/success</success>
    <failure>https://www.esimerkkikauppa.fi/sv/failure</failure>
    <pending></pending>
    <notification>https://www.esimerkkikauppa.fi/sv/notify</notification>
  </urlSet>
  <orderDetails>
    <includeVat>1</includeVat>
    <contact>
      <telephone>041234567</telephone>
      <mobile>041234567</mobile>
      <email>tester@esimerkkikauppa.fi</email>
      <firstName>Simon</firstName>
      <lastName>Seller</lastName>
      <companyName></companyName>
      <address>
        <street>Test street 1</street>
        <postalCode>12340</postalCode>
        <postalOffice>Helsinki</postalOffice>
        <country>FI</country>
      </address>
    </contact>
    <products>
      <product>
        <title>Example product</title>
        <code>XX-123</code>
        <amount>1.00</amount>
        <price>99.00</price>
        <vat>23.00</vat>
        <discount>0.00</discount>
        <type>1</type>
      </product>
      <product>
        <title>Example product 2</title>
        <code>XX-456</code>
        <amount>2.50</amount>
        <price>19.90</price>
        <vat>23.00</vat>
        <discount>0.00</discount>
        <type>1</type>
      </product>
    </products>
  </orderDetails>
</payment>
          

Example 5.4. Payment creation with the REST interface; XML response

<?xml version="1.0" encoding="UTF-8"?>
<payment>
  <orderNumber>12345678</orderNumber>
  <token>[SECRET TOKEN STRING GENERATED BY API]</token>
  <url>https://payment.paytrail.com/payment/load/token/[SECRET TOKEN STRING GENERATED BY API]</url>
</payment>
          

Example 5.5. Payment creation with the REST interface; JSON request

{
  "orderNumber": "12345678",
  "currency": "EUR",
  "locale": "fi_FI",
  "urlSet": {
    "success": "https://www.esimerkkikauppa.fi/sv/success",
    "failure": "https://www.esimerkkikauppa.fi/sv/failure",
    "pending": "",
    "notification": "https://www.esimerkkikauppa.fi/sv/success"
  },
  "orderDetails": {
    "includeVat": "1",
    "contact": {
      "telephone": "041234567",
      "mobile": "041234567",
      "email": "tester@esimerkkikauppa.fi",
      "firstName": "Simon",
      "lastName": "Seller",
      "companyName": "",
      "address": {
        "street": "Test street 1",
        "postalCode": "12340",
        "postalOffice": "Helsinki",
        "country": "FI"
      }
    },
    "products": [
      {
        "title": "Example product",
        "code": "XX-123",
        "amount": "1.00",
        "price": "99.00",
        "vat": "23.00",
        "discount": "0.00",
        "type": "1"
      },
      {
        "title": "Example product 2",
        "code": "XX-456",
        "amount": "2.50",
        "price": "19.90",
        "vat": "23.00",
        "discount": "0.00",
        "type": "1"
      }
    ]
  }
}
          

Example 5.6. Payment creation with the REST interface; JSON response

{
  "orderNumber": "12345678",
  "token": "[SECRET TOKEN STRING GENERATED BY API]",
  "url": "https://payment.paytrail.com/payment/load/token/[SECRET TOKEN STRING GENRATED BY API]"
}
          

Example 5.7. Payment creation with the REST interface; XML request, light version

Note

This example describes the interface usage without orderDetails. Please note that the orderDetails record is recommended whenever it is possible. Without the orderDetails record, payment subscriber details and specified product rows cannot be shown in the Merchant's Panel and invoice and instalment payment methods are not supported. In addition, payment method fees are available only when using the orderDetails record.
<?xml version="1.0" encoding="UTF-8"?>
<payment>
  <orderNumber>12345678</orderNumber>
  <currency>EUR</currency>
  <locale>fi_FI</locale>
  <urlSet>
    <success>https://www.esimerkkikauppa.fi/sv/success</success>
    <failure>https://www.esimerkkikauppa.fi/sv/failure</failure>
    <pending></pending>
    <notification>https://www.esimerkkikauppa.fi/sv/notify</notification>
  </urlSet>
  <price>99.00</price>
</payment>
          

5.5.4. Error handling

If the sent request is incorrect or there is an error in interface usage, the interface returns an error message. The error message is in XML or JSON format depending on the request data type (Content-Type header). If the data type is incorrect or it was not read, the error message is returned in XML format. Return message for an incorrect request is returned with HTTP error code 400.

Error message XML root element is called error. Error message returns the following records:

errorCode
(character string) Error code. Error code is an unambiguous character string that describes the error. Possible error codes are listed in table error codes.
errorMessage
(character string) Error description. Error description is a description of the error in chosen localisation. The error description is not to be shown to customers using the service.

Example 5.8. REST service error message in XML format

<?xml version="1.0" encoding="UTF-8"?>
<error>
  <errorCode>invalid-order-number</errorCode>
  <errorMessage>Missing or invalid order number</errorMessage>
</error>
          

Example 5.9. REST service error message in JSON format

{
  errorCode: 'invalid-order-number',
  errorMessage: 'Missing or invalid order number'
}
          

5.5.5. Error codes

Table 5.11. Error codes: Payment creation

Error codeDescription
invalid-content-typeIn HTTP POST request the Content-Type header contains an incorrect type. Allowed types are application/xml and application/json.
invalid-data-xmlError in processing received XML data or XML invalid.
invalid-data-jsonError in processing received JSON data or JSON invalid.
invalid-order-numberOrder number (orderNumber) missing or incorrect.
invalid-reference-numberSent reference number (referenceNumber) incorrect. Reference number must conform to the reference number standard.
invalid-reference-number-usedSent reference number (referenceNumber) incorrect. The reference number has been used for another payment.
invalid-descriptionOrder description (description) incorrect.
invalid-url-setRequired data structure urlSet not specified or incorrect.
invalid-url-successRequired return address for successful payment (success) in data structure urlSet missing or incorrect.
invalid-url-failureRequired return address for failed payment (failure) in data structure urlSet missing or incorrect.
invalid-url-pendingReturn address for pending payment (pending) in data structure urlSet incorrect.
invalid-url-notificationNotify address (notification) in data structure urlSet missing or incorrect.
invalid-currencyCurrency not specified or incorrect. Only "EUR" is supported.
invalid-localeLocalisation incorrect. Allowed options are "fi_FI", "en_US" and "sv_SE".
missing-order-details-and-priceOrder details (orderDetails) or payment sum (price) must be specified. Your request did not contain either of them.
order-details-and-price-definedOnly one of the required records, either order details (orderDetails) or payment sum (price) needs to be specified. Your request includes both records.
invalid-vat-modeIncluding Value Added Tax (includeVat) not specified or incorrect.
invalid-contactOrder details did not contain contact information (contact) or record was incorrect.
invalid-contact-telephoneIncorrect contact person's telephone number (telephone).
invalid-contact-mobileIncorrect contact person's mobile phone number (mobile).
invalid-contact-first-nameIncorrect or missing contact person's first name (firstName).
invalid-contact-last-nameIncorrect or missing contact person's surname (firstName).
invalid-contact-company-nameIncorrect contact person's company name (companyName).
invalid-contact-emailIncorrect or missing contact person's email address (email).
invalid-contact-addressIncorrect or missing contact person's address record (address).
invalid-contact-addressIncorrect or missing contact person's address record street address (street).
invalid-contact-postal-codeIncorrect or missing contact person's address record postal code (postalCode).
invalid-contact-postal-officeIncorrect or missing contact person's address record post office (postalOffice).
invalid-contact-countryIncorrect or missing contact person's address record country (country).
invalid-productsIncorrect or missing product record (products).
invalid-products-amountIncorrect number of product records in products record (products). There must be at least 1 product and at most 500 products.
invalid-product-titleIncorrect or missing product name (title) in product record.
invalid-product-codeIncorrect product code (code) in product record.
invalid-product-amountIncorrect or missing number of products (amount) in product record.
invalid-product-priceIncorrect or missing product price (price) in product record.
invalid-product-vatIncorrect or missing Value Added Tax (vat) in product record.
invalid-product-discountIncorrect discount percentage (discount) in product record.
invalid-product-typeIncorrect product type (type) in product record.
invalid-priceIncorrect payment sum (price).
invalid-total-priceProduct row total too low or too high.

5.5.6. PHP

When the payment service is integrated to an application developed in PHP, the easiest way to implement the payment service is to use our module, which connects to Paytrail payment service JSON interface.

Downloadable files:

Example 5.10. Using the payment service PHP class

<?php

require_once "Paytrail_Module_Rest.php";

// An object is created to model all payment return URLs
$urlset = new Paytrail_Module_Rest_Urlset(
    "https://www.demoshop.com/sv/success", // return URL for successful payment
    "https://www.demoshop.com/sv/failure", // return URL for failed payment
    "https://www.demoshop.com/sv/notify",  // URL for payment confirmation from Paytrail server
    ""  // pending url is not in use
);

// An object is created to model payer's data
$contact = new Paytrail_Module_Rest_Contact(
    "Test",                             // first name
    "Person",                           // surname
    "test.person@democompany.com",      // email address
    "Test street 1",                    // street address
    "12340",                            // postal code
    "Helsinki",                         // post office
    "FI",                               // country (ISO-3166)
    "040123456",                        // telephone number
    "",                                 // mobile phone number
    "Demo Company Ltd"                  // company name
);

// Payment creation
$orderNumber = "1";                     // Use distinguished order number
$payment = new Paytrail_Module_Rest_Payment_E1($orderNumber, $urlset, $contact);

// Adding one or more product rows to the payment
$payment->addProduct(
    "Test product", // product title
    "01234",        // product code
    "1.00",         // product quantity
    "19.90",        // product price (per piece)
    "23.00",        // Tax percentage
    "0.00",         // Discount percentage
    Paytrail_Module_Rest_Product::TYPE_NORMAL // Product type
);

// Changing payment default settings
// Changing payment method selection page language into English here
// The default language is Finnish. See other options from PHP class
$payment->setLocale("en_US");

// Sending payment to Paytrail service and handling possible errors
$module = new Paytrail_Module_Rest(13466, "");
try {
    $result = $module->processPayment($payment);
}
catch (Paytrail_Exception $e) {
    // processing the error
    // Error description available $e->getMessage()
    die("Error in creating payment to Paytrail service");
}

// Using the URL Paytrail returned for the desired payment method
// User is immediately directed to the received address
header("Location: {$result->getUrl()}");
?>
          

Example 5.11. Using the payment service PHP class without contact and product data

<?php

require_once "Paytrail_Module_Rest.php";

// An object is created to model all payment return addresses
$urlset = new Paytrail_Module_Rest_Urlset(
    "https://www.demoshop.com/sv/success", // return address for successful payment
    "https://www.demoshop.com/sv/failure", // return address for failed payment
    "https://www.demoshop.com/sv/notify",  // address for payment confirmation from Paytrail server
    ""  // pending url not in use
);

// Payment creation
$orderNumber = "1";                     // Use distinguished order number
$price = 99.00;                         // Total  (incl. VAT)
$payment = new Paytrail_Module_Rest_Payment_S1($orderNumber, $urlset, $price);

// Changing payment default settings
// Changing payment method selection page language into English here
// The default language is Finnish. See other options from PHP class
$payment->setLocale("en_US");

// Sending payment to Paytrail service and handling possible errors
$module = new Paytrail_Module_Rest(13466, "");
try {
    $result = $module->processPayment($payment);
}
catch (Paytrail_Exception $e) {
    // processing the error
    // Error description available $e->getMessage()
    die("Error in creating payment to Paytrail service");
}

// Using the URL Paytrail returned for the desired payment method
// User is immediately directed to the received address
header("Location: {$result->getUrl()}");
?>
          

Example 5.12. Confirming payment receipt with PHP class

require_once "Paytrail_Module_Rest.php";

$module = new Paytrail_Module_Rest(13466, "");
if ($module->confirmPayment($_GET["ORDER_NUMBER"], $_GET["TIMESTAMP"], $_GET["PAID"], $_GET["METHOD"], $_GET["RETURN_AUTHCODE"])) {
    // Payment receipt is valid
    // If needed, the used payment method can be found from the variable $_GET["METHOD"]
    // and order number for the payment from the variable $_GET["ORDER_NUMBER"]
}
else {
    // Payment receipt was not valid, possible payment fraud attempt
}
          

5.5.7. Perl

Warning

Paytrail is not involved in developing the Perl module and is not responsible for it. Perl module is Perl license (Artistic or GPL) program code.

The latest Perl module is available at http://search.cpan.org/dist/Finance-Bank-SuomenVerkkomaksut/

5.6. Payment method selection page embedding

5.6.1. Introduction

When Paytrail payment service has been integrated using either REST interface or form interface, the payment process can be shortened and made easier from the customer's point of view by implementing payment method selection embedding. In this case the payment methods are available directly at the end of a webshop's order process instead of having to move first to Paytrail service to select the payment method.

Figure 5.4. Payment method selection page embedding

Payment method selection page embedding

The payment method selection page embedding is easy to implement once the payment service has been first integrated with REST or form interface. It can be enabled by adding a small JavaScript code to the payment button page. We recommend adding the code to the end of the page before the closing body tag. In this case JavaScript is run last without slowing down page rendering.

This feature degrades gracefully: even if JavaScript is disabled by the customer's browser, the original payment button will still appear on the payment page just as it was shown before adding JavaScript code.

JavaScript interface offers two methods; one is used for the chosen payment interface. initWithToken request is used for the REST implementation and initWithForm request is used for the form interface implementation.

Note

Payment method selection page embedding widget uses jQuery in order to enable cross-browser compatibility. The module downloads jQuery library version 1.7 automatically from Google cloud services if jQuery is not available or jQuery version is unsupported. Required jQuery version is 1.4.3 or later.

5.6.2. Versions

5.6.3. Embedding when using the REST interface

initWithToken(string elementId, string token, object options)
string elementId
Id value for the html element describing an optional view for moving to the payment selection. This element is replaced with the payment method selection page widget once the widget has been downloaded. If JavaScript is not enabled, the customer will see this optional view, which typically is a direct link ("Pay here" button) to the payment method selection page.
string token
The REST interface returns a token value, which is sent as a parameter to the request.
object options
Options is a data structure, which allows adding extra parameters for the design and functionality of the payment method selection page widget. The parameters are described in chapter parameters.

Example 5.13. Payment method selection page embedding with JSON interface

<p id="payment">
  <a href="https://payment.paytrail.com/payment/load/token/0123456789abcdefg">Go to payments</a>
</p>

...

<script type="text/javascript" src="//payment.paytrail.com/js/payment-widget-v1.0.min.js"></script>
<script type="text/javascript">
SV.widget.initWithToken('payment', '0123456789abcdefg', {charset: 'ISO-8859-1'});
</script>
          

5.6.4. Embedding when using the form interface

initWithForm(string formId, object options)
string formId
The form element id value data is sent to the payment service. The form element is replaced with a payment selection element once it has been downloaded. If JavaScript is not enabled, the customer can send this form normally and go to the payment selection page. Therefore, remember to keep a visible send button in the form.
object options
Options is a data structure, which allows adding extra parameters for the design and functionality of the payment method selection page widget. The parameters are described in chapter parameters.

Example 5.14. Payment method selection page embedding with form interface

<form id="payment">
  <input type="hidden" name="MERCHANT_ID" value="12345" />
  ...
  <input type="submit" value="Go to payments" />
</form>

...

<script type="text/javascript" src="//payment.paytrail.com/js/payment-widget-v1.0.min.js"></script>
<script type="text/javascript">
SV.widget.initWithForm('payment', {charset:'ISO-8859-1'});
</script>
          

5.6.5. Parameters

The last parameter of initWithToken and initWithForm is an object named options. This object can be used to customise the design and functionality of the payment method selection widget. All parameters of the options structure are optional and their default values are presented in parenthesis.

charset
Character set for the page. Supported character sets are "UTF-8" and "ISO-8859-1". Parameter is not required for the REST implementation. (Default: "UTF-8").
debug
The widget can be set to test mode with this parameter (value 1). When in test mode the widget reports its functionality to the FireBug tool (default: 0)
defaultLocale
Default localisation for the widget. Supported localisations are da_DK, de_DE, et_EE, en_US, fr_FR, no_NO, ru_RU, fi_FI and sv_SE.
height
Widget height in pixels. 0 is also an acceptable value, the widget height is then automatically determined based on the content. If the widget height is set too small for the content to fit in, a vertical scroll bar is shown in the widget (default: 0)
locales
List of the available localisations. See supported localisations in defaultLocale field description. (default: all available localisations are shown in alphabetical order)
widgetId
You can define the widget element's root-id manually if you wish to handle the element dynamically, or the default id is in use. (default: "sv-widget")
width
Widget width in pixels. (default: 500)

5.6.6. Localisation

The payment method selection page embedding supports the following localisations: fi_FI (Finnish), en_US (English), da_DK (Danish), de_DE (German), et_EE (Estonian), fr_FR (French), ru_RU (Russian) and sv_SE (Swedish). The traditional payment method selection page supports fi_FI (Finnish), en_US (English) and sv_SE (Swedish).

Note

Payment method provider services only support localisations fi_FI, en_US and sv_SE or a subset of those. If the customer has selected such a localisation that is not supported by the payment method provider service, localisation en_US is preferred.

5.7. Payment state queries

5.7.1. State query in HTML

The state of an unique payment can be checked with a HTML-form.

Webshop developers can implement a button next to an order to allow checking of the state of the payment for any order directly from Paytrail's service. This way the merchant can be sure whether the payment was successfully completed in case the information has not reached the webshop otherwise. This kind of situation can occur for example when the customer's browser crashes before returning to the webshop.

Table 5.12. Form field description

Variable nameDescriptionFormatMax lengthRequired/Optional
MERCHANT_IDMerchant ID is sent to the merchant after registration.N11R
ORDER_NUMBERThis is the same order number that was generated in the webshop and sent to the Payment Gateway.AN50R
AUTHCODEThe request fingerprint. The calculation of the fingerprint is described later.AN32R
VERSIONThe current version value is "2".N1R
CULTUREThe service is available in Finnish, Swedish and English. The valid values for this field are "fi_FI", "sv_SE" and "en_US".AN8O

Example 5.15. The state query HTML form

    
<form action="https://payment.paytrail.com/check-payment" method="post">
    <input name="MERCHANT_ID" type="hidden" value="..." />
    <input name="ORDER_NUMBER" type="hidden" value="..." />
    <input name="AUTHCODE" type="hidden" value="..." />
    <input name="VERSION" type="hidden" value="..." />
    <input name="CULTURE" type="hidden" value="..." />
    <input name="submit" type="submit" value="Check payment state" />
</form>
      

5.7.2. Calculating the hash

Hash is calculated from a string which combines Merchant Authentication Code, Merchant ID and order number. All variables are separated by "&". Hash is calculated from this string using MD5, and the result is then transformed to a 32 character hexadecimal string and converted to upper case letters.

Example 5.16. Example of calculation

Table 5.13. Example of calculation

Field namevalue
Merchant Authentication Code6pKF4jkv97zmqBJ3ZL8gUw5DfT2NMQ
MERCHANT_ID13466
ORDER_NUMBER15153

Combine previous fields:

6pKF4jkv97zmqBJ3ZL8gUw5DfT2NMQ&13466&15153

Calculate MD5: eea431ef1c0a17d0045ab2ac39d118cf. Lower case letters to upper case: EEA431EF1C0A17D0045AB2AC39D118CF.


5.8. Merchant API v1

5.8.1. Service description

Paytrail Merchant API is a REST service for merchants where they can create and cancel refunds, opt to receive updates for any status changes of a refund and fetch settlement, payment and refund details. If you encounter any problems during the API integration, don't hesitate to contact our technical support at .

Service address: https://api.paytrail.com/merchant/v1/

5.8.2. Authentication

API requests are authenticated through HTTP authentication. See Authorization header description for details.

5.8.3. Accessing the API

5.8.3.1. Headers

Table 5.14. Required headers

HeaderDescription
TimestampRequest timestamp. Must be the same as what is used for signature calculation.
Content-MD5Base64 encoded MD5 sum for the request body contents.
Authorization Authentication details. Format: PaytrailMerchantAPI <merchant id>:<signature>. The signature is a BASE64 encoding of binary SHA256 HMAC of request details using merchant secret as the private key. Calculation formula:
base64_encode(
    hmac_sha256_binary(
        :requestMethod + "\n" +
            :url + "\n" +
            "PaytrailMerchantAPI " + :merchantId + "\n" +
            :timestamp + "\n" +
            :base64ContentMd5,
        :merchantSecret
    )
)
                                

Example 5.17. Example of signature calculation for refund creation

Table 5.15. Signature parameters

Field nameValue
API key (Merchant ID)13466
Merchant secret6pKF4jkv97zmqBJ3ZL8gUw5DfT2NMQ
Timestamp2015-05-01T12:00:00+0200
Order number15153
URL/merchant/v1/payments/15153/refunds
MethodPOST
Content
{
   "email": "john.doe@mycustomer.com",
   "notifyUrl": "https://example.com/notify",
   "rows": [
      {
         "amount": 1599,
         "description": "Long sleeve shirt",
         "vatPercent": 2400
      }
   ]
}
                                    
Note that there are no newlines before or after first and last curly braces. Newline character here is \n.

Calculated signature: W4P34H0xiTB202rsjtZIsMlEPQLRoS60d26KKl0zwZo=


5.8.3.2. Responses

The API has general responses that may be returned for all of the API queries.

Table 5.16. General HTTP responses

CodeDescription
HTTP 202Accepted + Location header indicating created resource + No content in body
HTTP 204No content + No specific headers + No content in body
HTTP 400Bad request (invalid JSON)
HTTP 403Forbidden (invalid API name or invalid signature)
HTTP 404Not found
HTTP 405Method not allowed
HTTP 503Service temporarily unavailable

The response body is a JSON message when a status code 4xx or 5xx is returned.

Table 5.17. General error codes and workarounds

Error code string and HTTP codeDescriptionWorkaround
invalid-signature (HTTP 403)Signature is not validCheck signature calculation
invalid-api-name (HTTP 403)API name is not validCheck that API name is PaytrailMerchantAPI
merchant-inactive (HTTP 403)Merchant specified in API key is inactivePlease contact customer support
refunds-not-enabled (HTTP 403)Merchant does not have Refunds enabledPlease contact customer support
invalid-json (HTTP 400)JSON parsing failedCheck that JSON input is valid
service-unavailable (HTTP 503)Refunding service is currently unavailablePlease try again later

Example 5.18. JSON message structure with invalid API name

{
  "error": {
    "title": "invalid-api-name",
    "description": "API name is not valid",
    "workaround": "Check that API name is PaytrailMerchantAPI"
  }
}
                        

5.8.4. Create Refund

5.8.4.1. Request

POST /merchant/v1/payments/:orderNumber/refunds

Refunds are created using order numbers as identifiers. Merchants must use unique order numbers for Paytrail Merchant API to be able to link each refund to a single payment. The customer will be sent an email upon successful refund creation.

Table 5.18. Parameters

NameTypeRequired/OptionalDescription
emailstringr/o When specified, the given email will be used for the refund. Required if the payment was made through the S1 interface if payment is not paid using card (email is not required for card payments).
rowsarray [1:500]r
amount
(integer, required) How much money to refund in cents (>0 – 2 000 000) with VAT included. The payment must have this much money left to refund, and for the right VAT percent, in case E1 or E2 interface with product rows was used.
vatPercent
(integer, required/not allowed) Which VAT percent to allocate the refund to, expressed in fractions of a hundred (0 – 10 000).
description
(string [2000], optional) Description for the refund shown as product row name. This is visible to the customer as well.
notifyUrlstringoValid webhook URL to call when a refund's status updates

Table 5.19. Return codes and workarounds

Code string and HTTP codeDescriptionWorkaround
HTTP 202Successful refund request, refund was created 
invalid-refund-rows (HTTP 400)The amount of rows to refund is invalidCheck that you have at least one and less than the maximum amount of refund rows in your request
invalid-amount (HTTP 400)A row sum is invalidCheck that all refund rows have sums and that the sums conform to requirements
invalid-vat-percent (HTTP 400)A VAT percent is invalidCheck that all refund rows have VAT percents for E1 or E2 payments and that they conform to requirements
invalid-description (HTTP 400)Description is too longCheck that none of your descriptions is longer than the maximum length
invalid-notify-url (HTTP 400)Notify URL is not a valid URLCheck your notify URLs
invalid-key (HTTP 400)An unknown key was encounteredCheck that your refund rows don't contain any extra keys
missing-email (HTTP 400) There was no email given for S1 payment refund request (email is mandatory for bank and Collector refunds) Add customer's email address to the refund request
invalid-interface (HTTP 400)Payments with older simple interface version 1 or 3 can't be refundedUse our newer payment interface so that you can create refunds in the future
nonunique-payment-identifier (HTTP 400)Multiple payments could be found for the same order numberMake sure your order numbers are unique
payment-not-found (HTTP 404)No payment was found with given order numberCheck that your order number matches a payment made through our system
payment-interface-type-does-not-support-refunding (HTTP 405)Refund request was made against a payment of unsupported interface typeCheck that the refund request was made against a payment made via Paytrail and not via a third party payment service
payment-method-does-not-support-refunding (HTTP 405)Refund request was made against a payment of unsupported payment methodCheck that the refund request was made for a payment made with method which supports refunding
payment-status-does-not-support-refunding (HTTP 405)Payment was in invalid state for refund to be madeCheck that the payment is in successfully completed state

5.8.5. Notify URL call

Paytrail calls the notify URL with a GET request when the refund status changes. The received notification must be acknowledged by responding with an HTTP status in the 200-299 range. Status updates will be sent in the order they occur. If an update is not acknowledged by the receiving end, subsequent updates to that refund are postponed until next retry round. Updates will be retried after 1, 3, 6, 10, 15, 21, 28, 36, 45 and 55 hours, after which the notification is discarded. This may cause some updates to be skipped if the notification URL endpoint cannot be contacted within 55 hours.

Table 5.20. Parameters sent with each notify call

NameDescription
refundTokenRefund's token
oldStatusRefund's previous status
newStatusRefund's new status
signatureSignature to ensure the update comes from Paytrail. Calculation: sha256(:refundToken + '|' + :oldStatus + '|' + :newStatus + '|' + :merchantSecret)

Table 5.21. Refund statuses

Status stringDescription
createdRefund created. Never used as newStatus, since notify is not sent when refund is created
consumer-data-collectedCustomer's IBAN has been received
waiting-credit-card-refund-processRefund is created and waiting for credit card processor to accept or reject the refund request
settlement-startedRefund has been added to outgoing settlements
completed Refund has been paid to the customer and in case of bank or collector refund reduced from merchant's settlements
cancelled-by-merchantRefund was cancelled by the merchant
cancelled-by-timeoutRefund was not accepted by the customer within the time limit of 30 days, or there have not been enough payments within 60 days to cover the refund sum
cancelled-by-terminationRefund was cancelled when the merchant's contract with Paytrail was terminated
failedCredit card refund process has failed and refund is cancelled

Figure 5.5. Status flow diagram for bank payments

Status flow diagram for bank payments

Figure 5.6. Status flow diagram for invoices (Collector)

Status flow diagram for invoices (Collector)

Figure 5.7. Status flow diagram for cards

Status flow diagram for cards

5.8.6. Refund cancellation

DELETE /merchant/v1/refunds/:refundToken

The customer will be notified of a successful refund cancellation by email. DELETE is not allowed for card refunds. Response in case of card refund is 405.

Table 5.22. Return codes and workarounds

Code string and HTTP codeDescriptionWorkaround
HTTP 204Refund was cancelled successfully 
refund-not-found (HTTP 404)Refund was not found with given tokenCheck that you gave a non-empty token that points to an existing refund
invalid-refund-status (HTTP 405)Refund cannot be cancelled from its current stateCheck refund's status from Merchant's Panel. Note that DELETE is not allowed for card refunds. Response in case of card refund is 405.

5.8.7. Settlements

GET /merchant/v1/settlements?fromDate=from&toDate=to

Returns settlements created between selected timespan.

Table 5.23. Parameters

NameTypeMandatory/OptionalFormatDescription
fromdatemandatoryyyyy-mm-ddInvalid date format or invalid time span will return empty response (404 and invalid-date-format error)
todatemandatoryyyyy-mm-ddInvalid date format or invalid time span will return empty response (404 and invalid-date-format error)

Table 5.24. Structure and detailed information on returned values

Parameter nameDatatypeFormatOccurenceMax length/valueValue contains
 array 1 This is the main level array that contains all found settlement objects
 hash 0-N A settlement object
idstring 164 
referenceNumbernumber 132 
settledAmountnumber 150000000How much money was settled to merchant? Amount is in the currency's smallest unit. e.g. in Euro cents
settledAtdatetimestamp1null / dateWhen the settlement was paid to merchant's bank account. Can be null if it's not yet paid.
currencystring 13ISO 3 letter symbol for settlement currency e.g. "EUR"

Example 5.19. Example request


GET /merchant/v1/settlements?fromDate=2015-01-01&amp;toDate=2015-02-01 HTTP/1.1
Timestamp: 2012-12-31T12:00:00+0200
Content-MD5: <base64 encoded 24 characters>
Authorization: PaytrailMerchantAPI <merchant id>: <base64 encoded 44 characters>

                

Example 5.20. Example response


HTTP/1.1 200 OK
Content-Type: application/json
[
    {
        "id": "1234567",
        "referenceNumber": "123456123456",
        "settledAt": "2015-03-05",
        "settledAmount": 7865,
        "currency": "EUR"
    }
]

                

Table 5.25. Resource specific error messages

Error code stringHTTP statusDescriptionWorkaround
invalid-date-range404Invalid date rangeCheck that date range is not over two months
invalid-date-format404Invalid date formatCheck that date format is correct (yyyy-mm-dd)

5.8.8. Settlement details

GET /merchant/v1/settlements/:id

Returns settlement details.

Table 5.26. Parameters

NameTypeMandatory/OptionalDescription
idstringmandatorySettlement whose details are requested

Table 5.27. Structure and detailed information on returned values

Parameter nameDatatypeFormatOccurenceMax length/valueValue contains
 hash 1 A settlement object
idstring 164 
referenceNumbernumber 132 
settledAmountnumber 150000000How much money was settled to merchant? Amount is in the currency's smallest unit. e.g. in Euro cents
settledAtdatetimestamp1null / dateWhen the settlement was paid to merchant's bank account. Can be null if it's not yet paid.
currencystring 13ISO 3 letter symbol for settlement currency e.g. "EUR"
 array   This is the main level array that contains all found payment objects
payments  1-N a payment object
idnumber 112 
referenceNumbernumber 132 
orderNumberstring 164 
createdAtdatetimestamp1date 
statusstring 1  Possible values: "waiting payment", "paid", "cancelled", "waiting acceptance"
paymentMethodIdnumber 1 Payment method id, see available methods from selection and visibility of payment methods
payerNamestring 132Payer name, only available for bank payments
amounts  1 Payment amounts object
originalnumber 150000000Amount provided in payment data from web shop
chargednumber 150000000Charged amount
settlednumber 150000000Amount settled to merchant
currencystring 13ISO 3 letter symbol for settlement currency e.g. "EUR"
consumerFees  1 Payment consumer fees object
paymentMethodnumber 150000000Payment method fee
currencystring 13ISO 3 letter symbol for settlement currency e.g. "EUR"
merchantFees  1 Payment merchant fees object
transactionnumber 150000000Transaction fee
provisionnumber 150000000Provision
currencystring 13ISO 3 letter symbol for settlement currency e.g. "EUR"
paymentServiceProviderstring 1  Possible values: "Paytrail"
paymentServiceTypestring 1  Possible values: "collecting", "direct"
refunds  0-N A refund object (refunds linked to payment)
 array   This is the main level array that contains all found refund objects
idstring 164 
createdAtdatetimestamp1date 
statusstring 1  Possible values: "created", "account linked", "settlement linked", "balancing created", "settlement created", "completed", "cancelled by merchant", "cancelled by timeout", "cancelled by termination"
paymentIdnumber 112 
updatedAtdatetimestamp1null / date 
originalAmountnumber 150000000Original fee
settledAmountnumber 150000000Amount settled to merchant
merchantFees  1 Payment merchant fees object
transactionFeenumber 150000000Transaction fee
currencystring 13ISO 3 letter symbol for settlement currency e.g. "EUR"
settlementIdstring 164 
refundsstring 0-N A refund object (refunds linked to settlement)
 array   This is the main level array that contains all found refund objects
idstring 164 
createdAtdatetimestamp1date 
statusstring 1  Possible values: "created", "account linked", "settlement linked", "balancing created", "settlement created", "completed", "cancelled by merchant", "cancelled by timeout", "cancelled by termination"
paymentIdnumber 112 
updatedAtdatetimestamp1null / date 
originalAmountnumber 150000000Original fee
settledAmountnumber 150000000Amount settled to merchant
merchantFees  1 Payment merchant fees object
transactionFeenumber 150000000Transaction fee
currencystring 13ISO 3 letter symbol for settlement currency e.g. "EUR"
settlementIdstring 164 

Example 5.21. Example request


GET /merchant/v1/settlements/123451234512345 HTTP/1.1
Timestamp: 2012-12-31T12:00:00+0200
Content-MD5: <base64 encoded 24 characters>
Authorization: PaytrailMerchantAPI <merchant id>: <base64 encoded 44 characters>

            

Example 5.22. Example response


HTTP/1.1 200 OK
Content-Type: application/json
{
    "id": "1234567",
    "referenceNumber": "123456123456",
    "settledAt": "2015-03-05"
    "settledAmount": 7865,
    "currency": "EUR",
    "payments": [
        {
            "id": "176456276154",
            "referenceNumber": "10034",
            "orderNumber": "ORDER-2",
            "createdAt": "2015-01-02T12:00:03+00:00",
            "status": "paid",
            "paymentMethodId": 2,
            "payerName": "Teppo Teik\u00e4l\u00e4inen",
            "amounts": {
                "original": 10000,
                "charged": 10000,
                "settled": 9965,
                "currency": "EUR"
            },
            "consumerFees": {
                "paymentMethod": 0,
                "currency": "EUR"
            },
            "merchantFees": {
                "transaction": -35,
                "provision": 0,
                "currency": "EUR"
            },
            "paymentServiceProvider": "Paytrail",
            "paymentServiceType": "collecting",
            "settlementId": "1234567",
            "refunds": [
                {
                    "id": "DA2OTA4NWVmYTRiMDUyMWI4OGNkNjkxNzBh",
                    "createdAt": "2015-01-02T14:00:02+00:00",
                    "status": "created",
                    "paymentId": "176456276154",
                    "updatedAt": "2015-01-02T14:00:03+00:00",
                    "originalAmount": -2000,
                    "settledAmount": -2100,
                    "merchantFees": {
                        "transactionFee": -100
                    },
                    "currency": "EUR",
                    "settlementId": "1234567"
                }
            ]
        }
    ],
    "refunds": [
        {
            "id": "GbLhiDev1rNh3SnfjJVvevRExTPq15stFrVsqWKm",
            "createdAt": "2015-01-01T14:14:09+00:00",
            "status": "paid",
            "paymentId": "92736276154",
            "updatedAt": "2015-01-01T14:18:08+00:00",
            "originalAmount": -3000,
            "settledAmount": -3100,
            "merchantFees": {
                "transactionFee": -100
            },
            "currency": "EUR",
            "settlementId": "1234567"
        }
    ],
}

            

Table 5.28. Resource specific error messages

Error code stringHTTP statusDescriptionWorkaround
invalid-settlement-id404Invalid idCheck settlement id format

5.8.9. Payment details

GET /merchant/v1/payments/:id

Returns payment details.

Table 5.29. Parameters

NameTypeMandatory/OptionalDescription
idstringmandatoryPayment whose details are requested (customer's payment identification code without hyphen)

Example 5.23. Example request

        
GET /merchant/v1/payments/176456276153 HTTP/1.1
Timestamp: 2012-12-31T12:00:00+0200
Content-MD5: <base64 encoded 24 characters>
Authorization: PaytrailMerchantAPI <merchant id>:<base64 encoded 44 characters>

            

Example 5.24. Example response

        
HTTP/1.1 200 OK
Content-Type: application/json
{
	"id": "176456276154",
	"referenceNumber": "10034",
	"orderNumber": "ORDER-2",
	"createdAt": "2015-01-02T12:00:03+00:00",
	"status": "paid",
	"paymentMethodId": 2,
	"payerName": "Teppo Teikäläinen",
	"amounts": {
		"original": 10000,
 		"charged": 10000,
		"settled": 9965,
 		"currency": "EUR"
 	},
 	"consumerFees": {
		"paymentMethod": 0,
		"currency": "EUR"
 	},
 	"merchantFees": {
		"transaction": -35,
		"provision": 0,
		"currency": "EUR"
 	},
	"paymentServiceProvider": "Paytrail",
	"paymentServiceType": "collecting",
	"settlementId": "1234567",
	"refunds": [
	 	{
			"id": "DA2OTA4NWVmYTRiMDUyMWI4OGNkNjkxNzBh",
 			"createdAt": "2015-01-02T14:00:02+00:00",
			"status": "created",
			"paymentId": "176456276154",
			"updatedAt": "2015-01-02T14:00:03+00:00",
			"originalAmount": -2000,
			"settledAmount": -2100,
			"merchantFees": {
			 	"transactionFee": -100
			},
			"currency": "EUR",
 			"settlementId": "1234567"
	 	}
	]
}

            

Table 5.30. Resource specific error messages

Error code stringHTTP statusDescriptionWorkaround
invalid-consumer-payment-id404Invalid consumer payment idCheck consumer payment id - you can check the value from Merchant's Panel

5.8.10. Refund details

GET /merchant/v1/refunds/:id

Returns refund details.

Table 5.31. Parameters

NameTypeMandatory/OptionalDescription
idstringmandatoryRefund token whose details are requested

Example 5.25. Example request

                
GET /merchant/v1/refunds/DA2OTA4NWVmYTRiMDUyMWI4OGNkNjkxNzBh HTTP/1.1
Timestamp: 2012-12-31T12:00:00+0200
Content-MD5: <base64 encoded 24 characters>
Authorization: PaytrailMerchantAPI <merchant id>:<base64 encoded 44 characters>

            

Example 5.26. Example response

                
HTTP/1.1 200 OK
Content-Type: application/json
{
    "id": "DA2OTA4NWVmYTRiMDUyMWI4OGNkNjkxNzBh",
    "createdAt": "2015-01-02T14:00:02+00:00",
    "status": "created",
    "paymentId": "176456276154",
    "updatedAt": "2015-01-02T14:00:03+00:00",
    "originalAmount": -2000,
    "settledAmount": -2100,
    "merchantFees": {
        "transactionFee": -100
    },
    "currency": "EUR",
    "settlementId": "1234567"
}

            

Table 5.32. Resource specific error messages

Error code stringHTTP statusDescriptionWorkaround
invalid-refund-token404Invalid refund tokenCheck refund token - you can check the value from Merchant's Panel

Chapter 6. Sales channels - For marketplaces

6.1. Channel description

The sales channel enables purchasing different products from different merchants in a single payment via Paytrail's service. Each merchant in the sales channel must have a sales channel agreement with Paytrail.

The channel provider can define a formula for taking a commission from every product in the channel. This formula is included in the agreement between the channel provider and Paytrail and must be used by the channel provider.

Paytrail charges its own commission for every payment made via the channel. This commission is also defined in the agreement between Paytrail and the channel provider. The channel provider is responsible for ensuring that the combined commissions do not exceed the total payment amount.

Merchants using a sales channel can review their payments in the Merchant's Panel. Each merchant can only see their own products sold in a single purchase bundle.

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

METHOD_PRESELECT2ANO
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)

6.3. Handling of payment information

After the customer has paid for the order, they will be redirected to the address defined in the field RETURN_ADDRESS. If the payment was cancelled or unsuccessful, the customer will be directed to the address defined in the field CANCEL_ADDRESS.

The field NOTIFY_ADDRESS can also be used. This address is called automatically when Paytrail confirms the payment. Typically the notify address is called right before redirecting to the return address. However, it is possible that customer will not come back to Paytrail's service after the payment. In these cases the payment will be confirmed with a delay of one bank day when the notify address will be called by Paytrail. The call for notify address contains the same GET parameters that are used when redirecting to return address.

GET parameters used when redirecting to return and cancel addresses and when calling notify addresses are described below. The payment’s validity has to be checked using the GET parameters.

Table 6.5. Product rows

FieldInformationNameDescription
1.Order numberORDER_NUMBER This is the same order number that was sent to Paytrail by the sales channel. The order number will be used to individualize each payment.
2.TimestampTIMESTAMPTimestamp created by Paytrail. This is used for calculating the checksum. Timestamps are in UNIX format.
3.Payment signaturePAIDSignature created by Paytrail. This is returned only with a successful payment.
4.AuthenticationRETURN_AUTHCODE The checksum calculated by Paytrail. The sales channel can compare this against the checksum they have calculated. If the checksums match, payment information has been transferred correctly. The checksums may match even if the payment is cancelled or unsuccessful.

6.3.1. Calculating checksum

The checksum is calculated as follows:

1. Create a string by combining the field's order number, timestamp, payment signature and merchant certificate in this order. Insert a pipe character “|” between the fields. In case of an unsuccessful payment, the field payment signature will not be returned and it is not to be included in the string.

2. Calculate the checksum using an MD5 hash function on the created string.

3. The checksum is a 32-bit hexadecimal string. Replace lower case letters with uppercase letters.

6.3.2. Example of calculating the checksum

The checksum is calculated as described below.

Order number: 123456
Payment sign: F4SDGF23FS
Timestamp: 1176557554
Channel certificate: 12345678901234567890123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789012345678
Created string: 123456|1176557554|F4SDGF23FS|12345678901234567890123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789012345678

Calculated checksum in upper case: 7C597D787D71EFBBEC68275B5B9D13EF

If calculated checksum matches the value of RETURN_AUTHCODE, payment acknowledgment has arrived successfully.

6.4. Testing

6.4.1. Test ID and channel certificate

The sales channel can be tested with the ID and channel certificate shown below.

Channel ID: 123
Channel certificate: 12345678901234567890123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789012345678

Note

Additionally, all sent products must use merchant ID 13466 and channel commission class ID 1 when testing.

Example 6.1. Example

Below is an example of a form submit that sends payment order to Paytrail’s payment service.

<form action="https://payment.paytrail.com/channel-payment" method="post">
<input name="CHANNEL_ID" value="123">
<input name="ORDER_NUMBER" value="12345678">
<input name="CURRENCY" value="EUR">
<input name="RETURN_ADDRESS" value="https://www.example.com/ok">
<input name="CANCEL_ADDRESS" value="https://www.example.com/cancel">
<input name="NOTIFY_ADDRESS" value="https://www.example.com/notify">
<input name="VERSION" value="1">
<!-- CULTURE is optional -->
<!-- PRESELECTED_METHOD is optional -->

<!-- CONTACT_TELNO is optional -->
<!-- CONTACT_CELLNO is optional -->
<input name="CONTACT_EMAIL" value="example@example.com">
<input name="CONTACT_FIRSTNAME" value="Jane">
<input name="CONTACT_LASTNAME" value="Doe">
<!-- CONTACT_COMPANY is optional -->
<input name="CONTACT_ADDR_STREET" value="Teststreet 1">
<input name="CONTACT_ADDR_ZIP" value="43210">
<input name="CONTACT_ADDR_CITY" value="Helsinki">
<input name="CONTACT_ADDR_COUNTRY" value="FI">
<input name="INCLUDE_VAT" value="1" />
<input name="ITEMS" value="1">

<input name="ITEM_TITLE[0]" value="Example product 1">
<!-- ITEM_NO is optional -->
<input name="ITEM_AMOUNT[0]" value="1">
<input name="ITEM_PRICE[0]" value="10.00">
<input name="ITEM_TAX[0]" value="22.00">
<input name="ITEM_MERCHANT_ID[0]" value="13466">
<input name="ITEM_CP[0]" value="1">
<!-- ITEM_DISCOUNT is optional -->
<!-- ITEM_TYPE is optional -->
<input name="AUTHCODE" value="D40ABA779948475B9F8E59EAB0EB7A9B">
<input type="image" src="https://ssl.paytrail.com/logo/payhere_fin.jpg">
</form>

    

The last field AUTHCODE is calculated as described below.

Combine all the fields in the same order they appear at the form. Insert pipe character “|” between the fields. If some field is not sent, insert a blank string in its value’s place. This will result in two two or more pipe characters next to each other. The first field of the string has to be the channel certificate. AUTHCODE will be created from this string with MD5 function. The checksum will be a 32-bit hexadecimal string. Replace lower case letters with upper case letters.

Note

In this example character set UTF-8 is used. Paytrail supports character sets UTF-8 and ISO-8859-1. Calculation for AUTHCODE has to be done using same character set that is used when sending the form to Paytrail. Paytrail’s service will detect the used character set and use the same character set when calculating the checksum.

In the example above the values of fields are as described below.

Table 6.6. Values for AUTHCODE calculation

FieldValue
Channel certificate
12345678901234567890123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789012345678
Channel ID123
Order number12345678
CurrencyEUR
Return address / Successful paymenthttps://www.example.com/ok
Return address / Cancelled paymenthttps://www.example.com/cancel
Notify addresshttps://www.example.com/notify
Interface version1
Culture codefi_FI
Preselected method for Payment page bypass 
Payer’s telephone number 
Payer’s cellphone number+35812345678
Payer’s email addressexample@example.com
Payer’s first nameJane
Payer’s last nameDoe
Payer’s companyTest Ltd
Payer’s street addressTeststreet 1
Payer’s zip code43210
Payer’s cityHelsinki
Payer’s countryFI
Payer’s countryFI
Is VAT is included in price?1
Amount of items2
Product #1 nameExample product 1
Product #1 number12345
Product #1 amount1
Product #1 price10.00
Product #1 tax percent22.00
Product #1 merchant ID13466
Product #1 channel commission class ID1
Product #1 discount0
Product #1 type1
Product #2 nameExample product 2
Product #2 number12345
Product #2 amount2
Product #2 price5.00
Product #2 tax percent22.00
Product #2 merchant ID13466
Product #2 channel commission class ID1
Product #2 discount20.00
Product #2 type1

The string used to calculate AUTHCODE is created by combining fields above.

12345678901234567890123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789012345678|123|12345678|EUR|https://www.example.com/ok|https://www.example.com/cancel|https://www.example.com/notify|1|fi_FI|||+35812345678||example@example.com|Jane|Doe|Test Ltd|Teststreet 1|43210|Helsinki|FI|1|2|Example product 1|12345|1|10.00|22.00|13466|1|0|1|Example product 2|12346|2|5.00|22.00|13466|1|20.00|1

MD5 checksum in upper case 4FA11FF0D41C30B6F3A8AAEB814FD325


Chapter 7. Dynamic payment method banner

7.1. Showing available payment methods in the webshop

Paytrail offers a dynamic image (banner) of the payment methods available in the web store. The image is meant to be used on the front page of the store, and includes information of all payment methods available through Paytrail's service. If new payment methods are activated, the logos are automatically updated in the banner.

The dimensions and layout of the image can be modified with parameters type and cols. Type defines whether a horizontal or vertical image should be used. Cols defines the number of columns available in the image. Each column is used to show a single payment method. Some payment method images require 2 columns.

7.2. Creating a link to the banner

  • The URL of the image is https://img.paytrail.com/index.svm
  • Add the GET parameters id, type, cols, text and auth
  • id is the merchant ID (e.g. 13466)
  • type parameter accepts the following values: “vertical” or “horizontal"
  • cols defines the number of columns to use. The parameter accepts values from 2 to 20.
  • text parameter defines if the banner info text should be shown. The text currently says "Suomen Verkkomaksut on nyt Paytrail". The text is available in Finnish only. The text is shown at the bottom of a vertical banner or the right hand edge of a horizontal one. If the parameter is not used, the text is not shown. Values: 0 (text not shown) and 1 (text is shown).
  • auth is used to authenticate the merchant. Calculate as follows: 1. Form a string by combining the merchant ID and the merchant secret: e.g. 134666pKF4jkv97zmqBJ3ZL8gUw5DfT2NMQ 2. Calculate an MD5 sum using this string 3. The auth parameter should be the first 16 characters of the MD5 sum

Example 7.1. Example of the banner URL

  • The Demo merchant has a merchant id 13466 and a merchant secret 6pKF4jkv97zmqBJ3ZL8gUw5DfT2NMQ, so to calculate the MD5 sum the following string is used: 134666pKF4jkv97zmqBJ3ZL8gUw5DfT2NMQ
  • The resulting MD5 sum is f6483cce23771e8f9282cb6abbff9fe9
  • The first 16 characters are: f6483cce23771e8f
  • To form a vertical image with 2 columns and the text “Suomen Verkkomaksut on nyt Paytrail”, The URL is: https://img.paytrail.com/index.svm?id=13466&type=vertical&cols=2&text=1&auth=f6483cce23771e8f

7.3. Examples of payment method banners

https://img.paytrail.com/index.svm?id=13466&type=horizontal&cols=15&text=1&auth=f6483cce23771e8f

https://img.paytrail.com/index.svm?id=13466&type=horizontal&cols=6&text=0&auth=f6483cce23771e8f

https://img.paytrail.com/index.svm?id=13466&type=vertical&cols=4&text=0&auth=f6483cce23771e8f

https://img.paytrail.com/index.svm?id=13466&type=vertical&cols=2&text=1&auth=f6483cce23771e8f