Paytrail - Integration guide

v4.4

Revision History
Revision 4.44 April 2017
  • Removed XML interface documentation. XML has been replaced with merchant API settlements.
  • Updated length of merchant API signature.
  • Fixed AMOUNT to be required with interface version S1.
  • Removed link to unsupported library.
Revision 4.321 February 2017
  • Removed link to unsupported library.
  • Added example image of form payment creation.
Revision 4.210 January 2017
  • Added American Express test credentials.
Revision 4.116 November 2016
  • Added credit card refund documentation to Merchant API section.
Revision 4.011 October 2016
  • Fixed authcode in E1 example.
  • Removed references to payment method Maestro (not in use).
  • Removed old Collector version (ID 19).
  • Added documentation for Merchant API settlement, payment and refund resources.
Revision 3.96 September 2016
  • Updated customer care phone number.
Revision 3.826 July 2016
  • Added payment method Oma Säästöpankki, PRESELECTED_METHOD 61.
Revision 3.73 May 2016
  • Fixed info about validity of REST token.
  • Added info about REST interface not supporting payment page bypass.
Revision 3.619 January 2016
  • Described vatPercent is not allowed in Merchant API create refund requests for payments done with S1.
Revision 3.515 December 2015
  • Added Collector Bank to payment method lists.
  • Status flow diagrams added for bank payment/invoice refunds.
Revision 3.427 October 2015
  • Added test credentials for Visa and MasterCard.
  • Added new error code refunds-not-enabled to Merchant API.
  • Payment method Tapiola (id 4) removed. Tapiola has merged with S-Pankki (id 10).
Revision 3.315 September 2015
  • Merchant API service address and warning text updated (pilot).
  • Merchant API and Connect API examples fixed.
  • Added link to Connect API Python library and Merchant API Ruby library.
  • Added Paytrail account ID to payment page bypass documentation.
  • Updated VISIBLE_METHOD field documentation.
  • Added new payment methods 53-57 (Nets).
  • Removed method 8 (Nets).
Revision 3.24 August 2015
  • Changed refund item amounts and VAT percentages to be given as integers instead of floats in Merchant API.
Revision 3.123 June 2015
  • Added the first version of Merchant API v1 documentation.
Revision 3.09 December 2014
  • Corrected timestamp format in Connect API examples.
  • Changed the name of the downloadable REST module zip package and omitted file paths in the archive.
  • Changed HTTP status received in error cases in REST documentation.
Revision 2.94 November 2014
  • Changed Sampo Pankki's name to Danske Bank.
  • Added test credentials for S-Pankki.
  • Added METHOD values for card methods 30-35 in payment notify.
  • Added test credentials for Aktia, Säästöpankki and POP Pankki.
  • Removed references to old Collector payment method (METHOD 13).
  • Removed supported browsers from payment method selection page embedding chapter.
  • Removed references to disabled payment methods Säästöpankit, paikallisosuuspankit, Aktia, Nooa (METHOD 7), Maestro (METHOD 32) and American Express (METHOD 33).
  • Moved form interface documentation from a PDF to the docbook (chapter 5.3).
  • Name of the payment method 8 is now Nets (previously Luottokunta).
  • Removed reference to old VAT base 23.
  • Stylized Payment service and Connect API chapters.
Revision 2.811 August 2014
  • Updated channel API documentation PDF to use the new company name and stylized the language in it.
  • Updated new name for Jousto (previously Joustoraha).
Revision 2.78 May 2014
  • Added the descriptions of email and phone parameters in returned delivery address JSON.
  • Fixed documentation on delivery address return HTTP codes
  • Corrected max length for product code field in A1 payment format to be 16 chars.
Revision 2.628 February 2014
  • Updated Paytrail Connect API documentation.
Revision 2.510 February 2014
  • Updated the Bookkeeping XML URLs.
  • Added a new element "payer" to the SVPayment datatype in the Bookkeeping XLM. This element needs to be taken into account when using the new URLs.
  • Added card payment method identifiers (30-35) tp payment page bypass documentation.
Revision 2.428 November 2013
  • Moved the test credentials to their own chapter, since the same ones are used in several places.
  • Added the bank test credentials to the test credentials chapter.
  • Added a know issues chapter to the form interface description. This was done, since there have been some changes, and they aren't reflected in the PDF.
  • Changed the minimum sum of a payment to be 0.65 euros.
  • Changed documentation of INCLUDE_VAT and ITEM_AMOUNT to reflect Collector requirements.
  • Changed the payment gateway URLs from 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. REST interface (BETA)
5.2.1. Introduction
5.2.2. Interface use
5.2.3. Payment creation
5.2.4. Error handling
5.2.5. Error codes
5.2.6. PHP
5.2.7. Perl
5.3. Form interface
5.3.1. Introduction
5.3.2. Interface versions
5.3.3. Change versions
5.3.4. Fields to be sent to payment gateway
5.3.5. Calculating the payment fingerprint (AUTHCODE)
5.4. Receiving the Payment Receipt
5.4.1. Introduction
5.4.2. Authcode calculation
5.5. Payment page bypass
5.5.1. Introduction
5.5.2. Implementation
5.5.3. Payment method values
5.6. Payment method selection page embedding
5.6.1. Introduction
5.6.2. Versions
5.6.3. Embedding when using the REST interface
5.6.4. Embedding when using the form interface
5.6.5. Parameters
5.6.6. Localisation
5.7. Payment state queries
5.7.1. State query in HTML
5.7.2. Calculating the hash
5.8. Merchant API v1
5.8.1. Service description
5.8.2. Authentication
5.8.3. Accessing the API
5.8.4. Create Refund
5.8.5. Notify URL call
5.8.6. Refund cancellation
5.8.7. Settlements
5.8.8. Settlement details
5.8.9. Payment details
5.8.10. Refund details
6. Sales channels - For marketplaces
6.1. Channel description
6.2. Interface description
6.2.1. Common
6.2.2. Fields to send
6.3. Handling of payment information
6.3.1. Calculating checksum
6.3.2. Example of calculating the checksum
6.4. Testing
6.4.1. Test ID and channel certificate
7. Dynamic payment method banner
7.1. Showing available payment methods in the webshop
7.2. Creating a link to the banner
7.3. Examples of payment method banners

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.

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.

Notification procedure is further explained in E1 specification.

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 webshop to enable the immediate payment of an order. The information of completed payment is instantly relayed back to the webshop.

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 webshop.

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

5.2. REST interface (BETA)

5.2.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.2. Payment creation with the REST interface

Payment creation with the REST interface

5.2.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.2.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 the bank. If missing, Paytrail will generate one.
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.1. 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.2. 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.3. 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.4. 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.5. 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.2.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.6. 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.7. REST service error message in JSON format

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

5.2.5. Error codes

Table 5.1. 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.2.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.8. 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.9. 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.10. 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.2.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.3. Form interface

5.3.1. Introduction

This chapter describes how a webshop 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.3. Creating a payment

Creating a payment

5.3.2. Interface versions

Latest interface version are S1 and E1. Interface version S1 is somewhat easier to implement compared to version E1. S1 includes less data to be delivered to Paytrail service. E1 version implementation adds customer information (name, address, etc.) and detailed product information to S1 implementation.

Using interface version E1 over S1 gives these benefits:

  • Paytrail Merchant's Panel shows customer data and detailed product information with the payment data
  • Invoicing and instalment options (more specifically Klarna and Collector)
  • Payment method fees can be defined (fixed amount or percentage of price for a specified payment method).

5.3.3. Change versions

5.3.3.1. Updates 5.1 → E1 and 4.1 → S1

Interface version E1 has replaced the previous version 5.1 and interface version S1 has replaced previous version 4.1. Both extensions include the same set of changes (new fields). Interface version upgrade requires to include optional fields PENDING_ADDRESS, PRESELECTED_METHOD, MODE, VISIBLE_METHODS and GROUP in hash calculation. Please check the positions of these fields in the listing provided in next chapter. Return call (RETURN_ADDRESS or CANCEL_ADDRESS) implementation has not changed in this update.

5.3.4. Fields to be sent to payment gateway

5.3.4.1. Interface version E1

Following form describes fields to be sent to payment gateway. Field form is either A, N, AN or F:

Table 5.2. Field descriptions

FormDescription
AAlphabetic
NNumeric
ANAlphanumeric
FFloating point number. Floating point numbers are expressed with two decimals at most.


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

Field necessity is marked in column Required/Optional.

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.

Note

It is not recommended to use REFERENCE_NUMBER field unless there is a justifiable requirement for it. Field allows to pass a webshop generated reference number for reference payment through Paytrail service. Field value is only used with payment methods which are used with merchant's own contracts using only technical implementation from Paytrail. With other payment methods (or when REFERENCE_NUMBER is omitted) Paytrail always generates reference number automatically.

Table 5.3. Form interface: Fields to be sent to payment gateway with interface version E1

Field nameDescriptionFormMax lengthRequired/Optional
MERCHANT_IDMerchant ID is the merchant identification number given by Paytrail. Merchant ID consists of digits only and it can be found from material sent to merchant by Paytrail.N11R
ORDER_NUMBEROrder number is used to identify one transaction from another in the webshop software.AN64R
REFERENCE_NUMBERBy default, the reference number is generated automatically. For payment methods which are used as an interface, the reference number can be given in this field to be delivered to bank's service instead of the automatically generated one.N50O
ORDER_DESCRIPTIONAny additional written information can be sent to Payment Gateway. It can be used to store order information like customer address, product information, etc. Order description is only visible through Merchant's Panel.AN65000O
CURRENCYCurrency. Only EUR is accepted for Finnish banks and credit cards.A3R
RETURN_ADDRESSURL where customer is redirected after successful payment.AN2048R
CANCEL_ADDRESSURL where customer is redirected after failed or cancelled payment.AN2048R
PENDING_ADDRESSCurrently not in use.AN2048O
NOTIFY_ADDRESSURL to be called when the payment has been marked as paid. This URL is called with same GET parameters as RETURN_ADDRESS when the payment is marked as paid. Note that NOTIFY_ADDRESS request is done by Paytrail server and thus customer's browser session does not exist in this request. NOTIFY_ADDRESS request is normally made within a couple of minutes from completing the payment.AN2048O
TYPEInterface version. Newest versions are S1 and E1.AN3R
CULTURECulture affects the default language and how amounts are shown on payment method selection page. Available cultures are "fi_FI", "sv_SE" and "en_US". The default culture is "fi_FI".A5O
PRESELECTED_METHOD If payment method selection is done in the webshop, payment method is delivered in this field.

Table 5.4. Payment method IDs for payment page bypass

1Nordea
2Osuuspankki
3Danske Bank
5Ålandsbanken
6Handelsbanken
9Paypal
10S-Pankki
11Klarna, Invoice
12Klarna, Installment
18Jousto
30Visa
31MasterCard
34Diners Club
35JCB
36Paytrail account
50Aktia
51POP Pankki
52Säästöpankki
53Visa (Nets)
54MasterCard (Nets)
55Diners Club (Nets)
56American Express (Nets)
60Collector Bank
61Oma Säästöpankki

N2O
MODE Paytrail's service can be bypassed when preselected payment method is delivered (PRESELECTED_METHOD). Use requires agreement on use with Paytrail.

Table 5.5. MODE values

1Normal service
2Bypassing Paytrail's payment method selection page

N1O
VISIBLE_METHODSThis can be used to decide what payment methods are shown on the payment page. Payment method values are to be brought separated with comma. Values can be seen above in PRESELECTED_METHOD -section.AN64O
GROUPCurrently not in use.AN16O
CONTACT_TELNOPayer's telephone number.AN64O
CONTACT_CELLNOPayer cellphone number (optional, but using Klarna requires this or payer telephone number. If neither is defined Klarna will be hidden).AN64O (Using Klarna requires this or CONTACT_TELNO)
CONTACT_EMAILPayer's email.AN255R
CONTACT_FIRSTNAMEPayer's first name.AN64R
CONTACT_LASTNAMEPayer's last name.AN64R
CONTACT_COMPANYPayer's company.AN128O
CONTACT_ADDR_STREETPayer's street address.AN128R
CONTACT_ADDR_ZIPPayer's postal code.AN16R
CONTACT_ADDR_CITYPayer's city.AN64R
CONTACT_ADDR_COUNTRYPayer home country. Data is given using ISO-3166-1 standard values. For example, Finland is FI and Sweden is SE. These values are not case sensitive. This information is used for checking credit history and thus it is required.A2R
INCLUDE_VAT Whether VAT is included in prices given in ITEM records. Value 1 indicates that VAT is included in given price. Value 0 indicates that price does not include VAT. Use the webshop native value to avoid rounding errors. That means, if product prices are saved without VAT in the webshop software, use 0 and if prices are saved with VAT, use 1. If using the Collector payment method, the value MUST be 1. Collector will not be available if the value is 0. N1R
ITEMSNumber of order rows. Corresponding product rows must be given in form.N (max. 500)3R

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]). Number of item rows should match the value brought in field ITEMS.

Table 5.6. Form interface: Product details for interface version E1

Field nameDescriptionFormLength max.Required / Optional
ITEM_TITLE[N]Free field for product name. Product name will be shown in Merchant's Panel and it is used in Klarna service as a name for product.AN255R/O (ITEM TITLE or ITEM_NO is required)
ITEM_NO[N]Optional product number. This is shown in Merchant's Panel with the product. This might help fixing the product rows to actual products.AN16R/O (ITEM TITLE or ITEM_NO is required)
ITEM_AMOUNT[N] Number of products. Usually the value is 1 (required). If usind the Collector payment method, this value must be a whole number. If a decimal number such as 0.5 is used, the Collector payment method will be hidden. 1.0 is accepted. F10R
ITEM_PRICE[N]The price for a single product. If INCLUDE_VAT=0, this is price not including VAT. If INCLUDE_VAT=1, this price includes VAT. Price may be negative value if discount is given. Payment total must be positive. Total sum of the product prices must be at least 0.65€.F10R
ITEM_TAX[N]Tax percent used for product.F10R
ITEM_DISCOUNT[N]If discount is given, this field can be used. Percent is a number between 0 and 100. Default value is 0.F10O
ITEM_TYPE[N]Type can be defined for each product row. Type 1 means normal product row. Type 2 is used for shipment costs. Type 3 is used for handling costs. Default value is 1.N1O

5.3.4.2. Interface version S1

See field specification from chapter Interface version E1.

Table 5.7. Form interface: Fields to be sent to payment gateway with interface version S1

Field nameDescriptionFormLength max.Required / Optional
MERCHANT_IDMerchant ID is merchant identification number given by Paytrail. Merchant ID consists of digits only and it can be found from material sent to merchant by Paytrail.N11R
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. Example: 15.50. Minimum price accepted by the service is 0.65€.F10R
ORDER_NUMBEROrder number is used to identify one transaction from another in the webshop software.AN64R
REFERENCE_NUMBERBy default, the reference number is generated automatically. For payment methods which are used as an interface, the reference number can be given in this field to be delivered to bank's service instead of the automatically generated one.N50O
ORDER_DESCRIPTIONAny additional written information can be sent to Payment Gateway. It can be used to back up order information like customer address, product information etc. Order description is only visible through Merchant's Panel.AN65000O
CURRENCYCurrency. Only EUR is accepted for Finnish banks and credit cards.A3R
RETURN_ADDRESSURL where customer is redirected after successful payment.AN2048R
CANCEL_ADDRESSURL where customer is redirected after failed or cancelled payment.AN2048R
PENDING_ADDRESSCurrently not in use.AN2048O
NOTIFY_ADDRESSURL to be called when the payment has been marked as paid. This URL is called with same GET parameters as RETURN_ADDRESS when the payment is marked as paid. Note that NOTIFY_ADDRESS request is done by Paytrail server and so customer's browser session is not available in that call. NOTIFY_ADDRESS request is normally done within a couple of minutes from completing the payment.AN2048O
TYPEInterface version. Newest versions are S1 and E1.AN3R
CULTURECulture affects on default language and how amounts are shown on payment method selection page. Available cultures are "fi_FI", "sv_SE" and "en_US". The default culture is always "fi_FI".A5O
PRESELECTED_METHOD If payment method selection is done in the webshop, payment method is delivered in this field.

Table 5.8. Payment method IDs for payment page bypass

1Nordea
2Osuuspankki
3Danske Bank
5Ålandsbanken
6Handelsbanken
9Paypal
10S-Pankki
11Klarna, Invoice
12Klarna, Installment
18Jousto
30Visa
31MasterCard
34Diners Club
35JCB
36Paytrail account
50Aktia
51POP Pankki
52Säästöpankki
53Visa (Nets)
54MasterCard (Nets)
55Diners Club (Nets)
56American Express (Nets)
60Collector Bank
61Oma Säästöpankki

N2O
MODE Paytrail's service can be bypassed when preselected payment method is delivered (PRESELECTED_METHOD). Use requires agreement on use with Paytrail.

Table 5.9. MODE values

1Normal service
2Bypassing Paytrail's payment method selection page

N1O
VISIBLE_METHODSThis can be used to decide what payment methods are shown on the payment page. Payment method values are to be brought separated with comma. Values can be seen above in PRESELECTED_METHOD -section.AN64O
GROUPCurrently not in use.AN16O

5.3.5. Calculating the payment fingerprint (AUTHCODE)

AUTHCODE is calculated by joining all fields in the order they are described in this document. Fields are joined by placing the "|" character (pipe, vertical bar) between each two fields. If any of the fields is left out, empty string should be used. In this case the string will contain two or more adjacent "|" characters. AUTHCODE is formed from this string by calculating an MD5 sum. This sum is converted to its 32 character hexadecimal form and lowercase letters are capitalized.

Example 5.11. Calculating the payment fingerprint with form data for interface version E1

This example covers sending payment information in the most complete form. In this case we are using the interface version E1. We recommend using Paytrail gateway in the way described here. Example 2 is a simplified example which does not offer as many features as this one. This form is placed in the webshop 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. Please note that in AUTHCODE calculation all fields, including optional parameters must always be used!

<form action="https://payment.paytrail.com/" method="post">
  <input name="MERCHANT_ID" type="hidden" value="13466">
  <input name="ORDER_NUMBER" type="hidden" value="123456">
  <input name="REFERENCE_NUMBER" type="hidden" value="">
  <input name="ORDER_DESCRIPTION" type="hidden" value="Testitilaus">
  <input name="CURRENCY" type="hidden" value="EUR">
  <input name="RETURN_ADDRESS" type="hidden" value="http://www.esimerkki.fi/success">
  <input name="CANCEL_ADDRESS" type="hidden" value="http://www.esimerkki.fi/cancel">
  <input name="PENDING_ADDRESS" type="hidden" value="">
  <input name="NOTIFY_ADDRESS" type="hidden" value="http://www.esimerkki.fi/notify">
  <input name="TYPE" type="hidden" value="E1">
  <input name="CULTURE" type="hidden" value="fi_FI">
  <input name="PRESELECTED_METHOD" type="hidden" value="">
  <input name="MODE" type="hidden" value="1">
  <input name="VISIBLE_METHODS" type="hidden" value="">
  <input name="GROUP" type="hidden" value="">
  <input name="CONTACT_TELNO" type="hidden" value="0412345678">
  <input name="CONTACT_CELLNO" type="hidden" value="0412345678">
  <input name="CONTACT_EMAIL" type="hidden" value="esimerkki@esimerkki.fi">
  <input name="CONTACT_FIRSTNAME" type="hidden" value="Matti">
  <input name="CONTACT_LASTNAME" type="hidden" value="Meikäläinen">
  <input name="CONTACT_COMPANY" type="hidden" value="">
  <input name="CONTACT_ADDR_STREET" type="hidden" value="Testikatu 1">
  <input name="CONTACT_ADDR_ZIP" type="hidden" value="40500">
  <input name="CONTACT_ADDR_CITY" type="hidden" value="Jyväskylä">
  <input name="CONTACT_ADDR_COUNTRY" type="hidden" value="FI">
  <input name="INCLUDE_VAT" type="hidden" value="1" />
  <input name="ITEMS" type="hidden" value="2">
  <input name="ITEM_TITLE[0]" type="hidden" value="Product #101">
  <input name="ITEM_NO[0]" type="hidden" value="101">
  <input name="ITEM_AMOUNT[0]" type="hidden" value="1">
  <input name="ITEM_PRICE[0]" type="hidden" value="10.00">
  <input name="ITEM_TAX[0]" type="hidden" value="22.00">
  <input name="ITEM_DISCOUNT[0]" type="hidden" value="0">
  <input name="ITEM_TYPE[0]" type="hidden" value="1">
  <input name="ITEM_TITLE[1]" type="hidden" value="Product #202">
  <input name="ITEM_NO[1]" type="hidden" value="202">
  <input name="ITEM_AMOUNT[1]" type="hidden" value="2">
  <input name="ITEM_PRICE[1]" type="hidden" value="8.50">
  <input name="ITEM_TAX[1]" type="hidden" value="22.00">
  <input name="ITEM_DISCOUNT[1]" type="hidden" value="0">
  <input name="ITEM_TYPE[1]" type="hidden" value="1">
  <input name="AUTHCODE" type="hidden" value="B5565364D8765E54A944084C0E9057F8">
  <input type="submit" value="Pay here">
</form>
            

Following form describes all fields for interface version E1 with values shown in form example.

Table 5.10. Fields to be sent to payment gateway with interface version E1

Field nameValue
Merchant authentication hash6pKF4jkv97zmqBJ3ZL8gUw5DfT2NMQ
MERCHANT_ID13466
ORDER_NUMBER123456
REFERENCE_NUMBER 
ORDER_DESCRIPTIONTest order
CURRENCYEUR
RETURN_ADDRESShttp://www.esimerkki.fi/success
CANCEL_ADDRESShttp://www.esimerkki.fi/cancel
PENDING_ADDRESS 
NOTIFY_ADDRESShttp://www.esimerkki.fi/notify
TYPEE1
CULTUREfi_FI
PRESELECTED_METHOD 
MODE1
VISIBLE_METHODS 
GROUP 
CONTACT_TELNO0412345678
CONTACT_CELLNO0412345678
CONTACT_EMAILesimerkki@esimerkki.fi
CONTACT_FIRSTNAMEMatti
CONTACT_LASTNAMEMeikäläinen
CONTACT_COMPANY 
CONTACT_ADDR_STREETTestikatu 1
CONTACT_ADDR_ZIP40500
CONTACT_ADDR_CITYJyväskylä
CONTACT_ADDR_COUNTRYFI
INCLUDE_VAT1
ITEMS2
ITEM_TITLE[0]Product #101
ITEM_NO[0]101
ITEM_AMOUNT[0]1
ITEM_PRICE[0]10.00
ITEM_TAX[0]22.00
ITEM_DISCOUNT[0]0
ITEM_TYPE[0]1
ITEM_TITLE[1]Product #202
ITEM_NO[1]202
ITEM_AMOUNT[1]2
ITEM_PRICE[1]8.50
ITEM_TAX[1]22.00
ITEM_DISCOUNT[1]0
ITEM_TYPE[1]1

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

6pKF4jkv97zmqBJ3ZL8gUw5DfT2NMQ|13466|123456||Testitilaus|EUR|http://www.esimerkki.fi/success|http://www.esimerkki.fi/cancel||http://www.esimerkki.fi/notify|E1|fi_FI||1|||0412345678|0412345678|esimerkki@esimerkki.fi|Matti|Meikäläinen||Testikatu 1|40500|Jyväskylä|FI|1|2|Product #101|101|1|10.00|22.00|0|1|Product #202|202|2|8.50|22.00|0|1

MD5 sum is counted from this string: b5565364d8765e54a944084c0e9057f8 (UTF-8) or 220ce506b90d1980f88e6522b525918c (ISO-8859-1)

Lowercase letters are then capitalized to get the final AUTHCODE value: B5565364D8765E54A944084C0E9057F8 (UTF-8) or 220CE506B90D1980F88E6522B525918C (ISO-8859-1)


Example 5.12. Calculating the payment fingerprint with form data for interface version S1

This example shows how to use the gateway service without additional payment information. In this case we are using interface version S1. In most cases the additional payment information should be used (see example above). This form is placed in the webshop 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 form. Please note that in AUTHCODE calculation all fields, including optional parameters must always be used!

<form action="https://payment.paytrail.com/" method="post">
  <input name="MERCHANT_ID" type="hidden" value="13466">
  <input name="AMOUNT" type="hidden" value="99.90">
  <input name="ORDER_NUMBER" type="hidden" value="123456">
  <input name="REFERENCE_NUMBER" type="hidden" value="">
  <input name="ORDER_DESCRIPTION" type="hidden" value="Testitilaus">
  <input name="CURRENCY" type="hidden" value="EUR">
  <input name="RETURN_ADDRESS" type="hidden" value="http://www.esimerkki.fi/success">
  <input name="CANCEL_ADDRESS" type="hidden" value="http://www.esimerkki.fi/cancel">
  <input name="PENDING_ADDRESS" type="hidden" value="">
  <input name="NOTIFY_ADDRESS" type="hidden" value="http://www.esimerkki.fi/notify">
  <input name="TYPE" type="hidden" value="S1">
  <input name="CULTURE" type="hidden" value="fi_FI">
  <input name="PRESELECTED_METHOD" type="hidden" value="">
  <input name="MODE" type="hidden" value="1">
  <input name="VISIBLE_METHODS" type="hidden" value="">
  <input name="GROUP" type="hidden" value="">
  <input name="AUTHCODE" type="hidden" value="270729B19016F94BE5263CA5DE95E330">
  <input type="submit" value="Siirry maksamaan">
</form>
            

The last hidden field, AUTHCODE, in the listing above is calculated as follows. Like in the example above, join form fields in the order they are mentioned in this document and use the "|" character (pipe, vertical bar) between the fields. The values used in this example are shown in the next table:

Table 5.11. Fields to be sent to payment gateway with interface version S1

Field nameValue
Merchant authentication hash6pKF4jkv97zmqBJ3ZL8gUw5DfT2NMQ
MERCHANT_ID13466
AMOUNT99.90
ORDER_NUMBER123456
REFERENCE_NUMBER 
ORDER_DESCRIPTIONTestitilaus
CURRENCYEUR
RETURN_ADDRESShttp://www.esimerkki.fi/success
CANCEL_ADDRESShttp://www.esimerkki.fi/cancel
PENDING_ADDRESS 
NOTIFY_ADDRESShttp://www.esimerkki.fi/notify
TYPES1
CULTUREfi_FI
PRESELECTED_METHOD 
MODE1
VISIBLE_METHODS 
GROUP 

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

6pKF4jkv97zmqBJ3ZL8gUw5DfT2NMQ|13466|99.90|123456||Testitilaus|EUR|http://www.esimerkki.fi/success|http://www.esimerkki.fi/cancel||http://www.esimerkki.fi/notify|S1|fi_FI||1||

MD5 sum is counted from this string: 270729b19016f94be5263ca5de95e330

Lowercase letters are then capitalized to get the final AUTHCODE value: 270729B19016F94BE5263CA5DE95E330

Please note that this exmple did not include any characters that are handled differently in charsets UTF-8 and ISO-8859-1. Because of this, the AUTHCODE is the same not depending on which charset is used.


5.4. Receiving the Payment Receipt

5.4.1. Introduction

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

The notification address (NOTIFY_ADDRESS) is called when Paytrail marks the payment as completed. Typically this happens within a few minutes after redirecting the customer to RETURN_ADDRESS. 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 NOTIFY_ADDRESS will be called immediately when that information has arrived. Usually the information arrives within 24 hours. NOTIFY_ADDRESS call includes same GET-parameters as redirecting to RETURN_ADDRESS does.

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 hash is compared to the hash calculated by the webshop and if the values match, the payment receipt was not tampered.

In return authentication hash calculation, fields are joined using the "|" character (pipe, vertical bar) as separator. Merchant hash is appended to the string. When the payment is not successful, only fields 1, 2 and 5 are returned, and only fields 1, 2 and merchant hash are used in hash calculation.

Table 5.12. Receipt contains these fields

FieldVariable name
Order numberORDER_NUMBER
Time stamp of transactionTIMESTAMP
Paid Transcation IDPAID
Payment methodMETHOD
Return authentication hashRETURN_AUTHCODE


Table 5.13. Field explanations

FieldExplanation
Order numberThis is the same order number that was generated in the webshop and sent to the Payment Gateway
Timestamp of transaction 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.
Paid Transaction ID Paid Transcation ID number is generated by the Payment Gateway. It is used to verify the validity of a successful payment. If no Paid Transcation ID is received, the payment has not been completed.
Payment method Used payment method as an integer id. This is not returned if the payment was not succesful. The following payment methods are currently possible:

Table 5.14. Possible values for payment method

1Nordea
2Osuuspankki
3Danske Bank
5Ålandsbanken
6Handelsbanken
9Paypal
10S-Pankki
11Klarna, Invoice
12Klarna, Instalment
18Jousto
30Visa
31MasterCard
34Diners Club
35JCB
36Paytrail account
50Aktia
51POP Pankki
52Säästöpankki
53Visa (Nets)
54MasterCard (Nets)
55Diners Club (Nets)
56American Express (Nets)
60Collector Bank
61Oma Säästöpankki

Return authentication hash Return authentication hash is a checksum value which is compared to one calculated in webshop. If the checksum matches the calculated one, the payment has been completed and the information has not been modified after sending. The hash may be identical in both successful and failed transactions.


5.4.2. Authcode calculation

Table 5.15. Example of calculation

Order number15153
Timestamp of transaction1176557554
Paid Transaction IDF4SDGF23FS
Payment method1
Merchant authentication hash6pKF4jkv97zmqBJ3ZL8gUw5DfT2NMQ


Combining these fields using the "|" character as separator, the following string is formed: 15153|1176557554|F4SDGF23FS|1|6pKF4jkv97zmqBJ3ZL8gUw5DfT2NMQ

Calculating the MD5 hash of this string, we get: 191fae904a0b9a57ca30a35c715abaf9

Translating lower case to upper case: 191FAE904A0B9A57CA30A35C715ABAF9

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

5.5. Payment page bypass

5.5.1. Introduction

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

5.5.2. Implementation

PRESELECTED_METHOD defines the selected payment method, below are listed all the possible values for it. You only need to consider the payment methods that are active for your merchant ID. Active payment methods can be seen in the payment methods section in Merchant's Panel settings tab.

MODE field is used to tell Paytrail if bypass is used. Use value 2 for bypass.

5.5.3. Payment method values

Table 5.16. Possible values for payment method

1Nordea
2Osuuspankki
3Danske Bank
5Ålandsbanken
6Handelsbanken
9Paypal
10S-Pankki
11Klarna, Invoice
12Klarna, Installment
18Jousto
30Visa
31MasterCard
34Diners Club
35JCB
36Paytrail account
50Aktia
51POP Pankki
52Säästöpankki
53Visa (Nets)
54MasterCard (Nets)
55Diners Club (Nets)
56American Express (Nets)
60Collector Bank
61Oma Säästöpankki

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.17. 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.18. 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.19. 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.20. 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.21. 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.22. 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.23. 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 interface 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.24. 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 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.25. 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.26. 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.27. 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.28. 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.29. 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
settledAtdateyyyy-mm-dd1null / 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.30. 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.31. Parameters

NameTypeMandatory/OptionalDescription
idstringmandatorySettlement whose details are requested

Table 5.32. 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
settledAtdateyyyy-mm-dd1null / 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 
createdAtdateyyyy-mm-dd1null / date 
statusstring 1  Possible values: "waiting payment", "paid", "cancelled", "waiting acceptance"
paymentMethodIdnumber 1 Payment method id, see available methods from E1 specification
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 
createdAtdateyyyy-mm-dd1null / date 
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 
updatedAtdateyyyy-mm-dd1null / 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 
createdAtdateyyyy-mm-dd1null / date 
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 
updatedAtdateyyyy-mm-dd1null / 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.33. 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.34. 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.35. 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.36. 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.37. 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