New payment V4 S2S (server-to-server)

Introduction

Svea Payments' 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:

• About testing credentials

• Payment API parameters

  • when implementing as a server-to-server request, please ignore/omit hash-related fields!

• Payment Status Query

• Payment confirmation Call-backs

Skip to contents in this page

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 parameter pmt_hash . This parameter is 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_action>NEW_PAYMENT_EXTENDED</pmt_action> <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_sellercosts>0,00</pmt_sellercosts> <pmt_paymentmethod>FI01</pmt_paymentmethod> <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 web store after payment, you MUST use some mechanism to validate the payment confirmation and make sure it was not fabricated by a malicious user. You can use one of these methods for this validation:

   1. Use Payment Status Query instantly to validate the payment, especially when the payment confirmation message does not include hash. This is the case when the payment was initiated with S2S API and there was no information about hash version (pmt_hashversion) in the initial request.

   2. Validate pmt_hash from the payment confirmation message. If you included pmt_hashversion and pmt_keygeneration parameters in the original payment API request, there will be a hash present in the payment confirmation message to the web store, whether it comes from payer’s browser or as a call-back message directly from Svea’s server to the web store.

   3. You can do both. First b, then a. Hash algorithms have their weaknesses and this is the most secure way.