S2S API

New payment V4 S2S (server-to-server)

Introduction

Maksuturva's payment API can be called in two ways:

  • Preferred: payment parameters are sent as a server-to-server request, authenticated with HTTP Basic Auth

  • Deprecated: payment parameters are sent via payer's browser as a form submission and authenticated with a hash

This document describes the preferred server-to-server request.

General documentation related to payment API can be found here:

Payment process with S2S API

  1. A  new payment request (NewPaymentExtended.pmt, HTTP FORM POST) is sent by the webstore software (with no payer browser intervention).

  2. The server-to-server request is authenticated by using standard Basic Authentication Header.

    1. Use merchant's seller_id as the username and secret key as the password for Basic Auth Header.

    2. Do not calculate hash! That is, leave out parameters pmt_hash and pmt_hashversion. They are obsolete and totally ignored in new payment requests using Basic Authentication and can be omitted.

  3. The response is in XML document with root element "pmt".

    1. These values are usually the same as in the request: pmt_version, pmt_id, pmt_reference, pmt_amount, pmt_currency

    2. pmt_paymenturl

      1. This is the address where the payer can be redirected instantly to continue the payment process

      2. or this address could be used as "payment link" that is sent to the payer for example by email

      3. or this link can be shown somewhere in the webstore.

    <pmt>
        <pmt_version>0004</pmt_version>
        <pmt_id>Q8F7XYM9Q8UF1JVFZLE6</pmt_id>
        <pmt_reference>00000001234567890120</pmt_reference>
        <pmt_amount>123,00</pmt_amount>
        <pmt_currency>EUR</pmt_currency>
        <pmt_paymenturl>https://www.maksuturva.fi/Pay.pmt?ST=BS35116e87d26762c605c59a7612d115836ccae45d00000000000000650941760!</pmt_paymenturl>
    </pmt>
  4. Payer is redirected to the pmt_paymenturl.

  5. When the payer returns to the webstore after payment, use Payment Status Query to validate the payment since the return message won't be hash validated as we cannot calculate the hash without the pmt_hashversion.

 1 point extra info

New payment request: http://docs.maksuturva.fi/en/html/pages/3_3_payment.html

Server-to-server requests are sent to address
https://payments.maksuturva.fi/NewPaymentExtended.pmt and 
https://payments.maksuturva.fi/PaymentStatusQuery.pmt

All server-to-server requests use UTF-8 charset.