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=