Finland: Direct bank payment (via Paytrail)

With the PiA SDK, you can allow Finnish customers to pay with Paytrail direct bank transfers. It supports through 1 integration, the 10 main banks which are part of this direct payment scheme.

You can get more information about Paytrail via Netaxept from the Paytrail Getting Started Guide.

Pre-requisite to accept direct bank payments via Paytrail :

  • The merchant needs to sign a direct bank payments agreement with Netaxept and make sure these agreements are added in the Netaxept account.

  • App design: Bank icons are available in the resources folder (optional).

Specific information to initiate direct bank payments via Paytrail :

  • Merchant needs to use ServiceType = B while making the register call.

  • In Paytrail request customer email is manadatory that need to be sent in the register call to Netaxpet.In case merchant doesn´t send it, then Paytrail payment methods are not displayed in the terminal. When paymentMethodActionList includes Paytrail payment method name, then an error message is returned as “Missing customer Email ID”. Merchants can use dummy data for this. Check the Netaxept Paytrail SDK doc for more details.

  • Paytrail requires a unique reference number which is formulated according to Finnish reference number standard www.fkl.fi. For more information click here.

Here is the flow diagram for Paytrail payment:

Paytrail Payment Flow

Initializing a payment with Paytrail

For a Paytrail payment, create a paytrail-payment process providing merchant information (obtained from Netaxept) as shown below:

let merchantDetails = MerchantDetails.merchant(withID: merchantID, inTest: isTestMerchantID)

let paytrailPayment = PaymentProcess.paytrailPayment(
        withMerchant: merchantDetails) { [unowned self] callback in
            // Make the registration call and return the callback
       }

The SDK offers a declarative API to instantiate a controller for paytrail payment with result callbacks for success, cancellation and failure. Present this controller and handle the callbacks accordingly.


PiaSDK.controller(
    for: paytrailPayment,
    success: { piaController, transactionId in  },        // Commit the transaction with your merchant backend
    cancellation: { piaController, transactionId in },    // User canceled, rollback the transaction
    failure: { piaController, error in}    // Rollback transaction, check error object for detail. 
)

The following sample code demonstrates how registration results are returned to the SDK via callback. 


fun paytrailRegistrationCallback(piaCallback: (TransactionID, RedirectURL) -> Void) {

    // Make a paytrail registration request with your backend to retrieve a transactionID and redirectURL. 

    // Callback with `transactionID` and `redirectURL` obtained from your merchant backend
    callback(.success(withTransactionID: response.transactionId, redirectURL: response.redirectURL))

    // If registration request failed with your backend, callback the SDK with the error. 
    callback(.failure(error))
}

After the transaction has been registered, Netaxept will send back the url for performing the Paytrail payment which will be loaded inside a webView. The webView will look like below:

Paytrail Flow
Netaxept backend integration request body - Paytrail payment registration:
{
    "merchantId" : "integer", 
    "token" : "string",
    "orderNumber" : "string",
    "amount" : "integer",
    "currencyCode" : "string",  
    "redirectUrl" : "string",
    "serviceType" : "B",
    "paymentMethodActionList" : { 
        "PaymentMethod" : "bank selected by the customer, example PaytrailOPBankFinland or PaytrailAktiaFinland"
    },
    "customerEmail" : "string",
    "customerFirstName" : "string",
    "customerLastName" : "string",
    "customerAddress1" : "string",
    "customerPostCode" : "string",
    "customerTown" : "string",
    "customerCountry" : "string",
}

Note: Netaxept backend integration tips can be found in 5.4 Backend Tips, Request body - Paytrail payment registration section