Introduction

Finnish Banks provides access to all major domestic online banking options in Finland through a single integration, creating one of the most comprehensive and seamless payment experiences.

Supported Countries

• Finland

Supported Currencies

• EUR

REST 1.0 API

Payment (Deposit) Flow

1. Generate a sessionToken
   
   See Authentication for details.

2. Perform the payment by sending a /payment request with its mandatory parameters, including:

• userTokenId
• amount
• currency
• paymentOption.alternativePaymentMethod class containing:
  • paymentMethod: “apmgw_Finnish_Banks“
• billingAddress class containing:
  • country
  • email
  • address
  • city
  • zip
• deviceDetails class containing: ipAddress

Example /payment Request

{
   "sessionToken":  "<sessionToken from /getSessionToken>",  
    "merchantId":
    "merchantSiteId":"<merchantSiteId>",
    "clientRequestId":"<unique request ID in merchant system>",
    "clientUniqueId":"<unique transaction ID in merchant system>",
    "userTokenId":"<unique customer identifier in merchant system>",
    "currency": "EUR",
    "amount": "123",
    "paymentOption": {
        "alternativePaymentMethod": {
            "paymentMethod": "apmgw_Finnish_Banks"
        }
    },
    "deviceDetails": {
        "ipAddress": "<customer's IP address>"
    },
    "billingAddress": {
        "address": "22 Main Street",
        "city": "Helsinki",
        "zip": "00100",
        "country": "FI",
        "email": "[email protected]"
    },
    "timeStamp":"<YYYYMMDDHHmmss>",
    "checksum":"<YYYYMMDDHHmmss>"
}

The response generates and returns redirectUrl to redirect the customer to the payment page as well as a userPaymentOptionId (UPO) for use in future transactions.

Example /payment Response

{
    "internalRequestId": 451967111,
    "status": "SUCCESS",
    "errCode": 0,
    "reason": "",
    "merchantId": "5634436935940029474",
    "merchantSiteId": "242181",
    "version": "1.0",
    "clientRequestId": "20260306155625",
    "sessionToken": "cfe1a1f8cc5647588f7c9ebf6f9c0e310111",
    "clientUniqueId": "20180327175242",
    "orderId": "462180111",
    "userTokenId": "test12",
    "paymentOption": {
        "redirectUrl": "https://pay.paytrail.com/pay/4a711ebd-df72-4a7a-a472-9eca79d0fd39",
        "userPaymentOptionId": "230584127111",
        "card": {}
    },
    "transactionStatus": "REDIRECT"
}

For supported "finishBanks_bic" parameter values, see Appendix.
 

Example

 "paymentOption": {
        "alternativePaymentMethod": {
            "paymentMethod": "apmgw_Finnish_Banks",
            "finishBanks_bic": "62"
        }
    },

After the transaction is processed, Nuvei sends a Direct Merchant Notification (DMN) that includes the result of the transaction to the urlDetails.notificationUrl, which Nuvei recommends including in the /payment request.

Example DMN Response – Status=APPROVED

ppp_status=OK&Status=APPROVED&ExErrCode=0&ErrCode=0&errApmCode=0&errApmDescription=&errScCode=0&errScDescription=&Reason=&ReasonCode=0&PPP_TransactionID=43432221&userid=ScMigrationTest3&merchant_unique_id=97c10831-d399-48d7-8ea5-41f89619d2fa6&customData=anca.gheorghitanu&productId=test_name_1&first_name=John&last_name=Doe&email=ivanp%40abv.bg&currency=EUR&pmDisplayName=OP-Pohjola+%28Osuuspankki%29&customField1=meccabingo.com&customField2=a2db82db-8186-44bb-a6d9-cb9f8f7ea25e&customField3=&customField4=&customField5=&customField6=&customField7=&customField8=&customField9=&customField10=&customField11=&customField12=&customField13=&customField14=&customField15=rnk_pr01&invoice_id=&address1=Test+Address&address2=&country=Finland&state=&city=Ontario&zip=M6T+1J1&phone1=%2B14161238888&phone2=&phone3=&client_ip=127.0.0.1&nameOnCard=&cardNumber=&bin=&noCVV=&acquirerId=&acquirerBank=PAYTRAIL-PI&expMonth=&expYear=&Token=&tokenId=&AuthCode=&AvsCode=&Cvv2Reply=&shippingCountry=FI&shippingState=&shippingCity=Ontario&shippingAddress=Test+Address&shippingZip=M6T+1J1&shippingFirstName=John&shippingLastName=Doe&shippingPhone=%2B14161238888&shippingCell=%2B14161238888&shippingMail=ivanp%40abv.bg&total_discount=0.00&total_handling=0.00&total_shipping=0.00&total_tax=0.00&buyButtonProductBundleId=&merchant_site_id=242181&merchant_status=&action=&requestVersion=&message=APPROVED&merchantLocale=en_US&unknownParameters=&payment_method=apmgw_Finnish_Banks&ID=&merchant_id=5634436935940029474&responseTimeStamp=2024-07-24.13%3A39%3A48&buyButtonProductId=&webMasterId=&appliedPromotions=&uniqueCC=&transactionType=Sale&externalEmail=&cardCompany=&eci=&user_token_id=TeoPy&user_token=auto&userPaymentOptionId=2153305131&TransactionID=2610000000000044829&externalTransactionId=2fa7de8e-49c2-11ef-97b8-9f02177390fe&APMReferenceID=75781FC4A9AD588B3CC746682FACCE2A&orderTransactionId=24747601&totalAmount=5.00&dynamicDescriptor=static+test&item_name_1=test_name_1&item_number_1=&item_amount_1=5.00&item_quantity_1=1&item_discount_1=0.00&item_handling_1=0.00&item_shipping_1=0.00&feeAmount=&amountWithoutFee=&houseNumber=&customCurrency=&externalToken_blockedCard=&externalToken_cardAcquirerId=&externalToken_cardAcquirerName=&externalToken_cardBin=&externalToken_cardBrandId=&externalToken_cardBrandName=&externalToken_cardExpiration=&externalToken_cardLength=&externalToken_cardMask=&externalToken_cardName=&externalToken_cardTypeId=&externalToken_cardTypeName=&externalToken_clubName=&externalToken_creditCompanyId=&externalToken_creditCompanyName=&externalToken_extendedCardType=&externalToken_Indication=&externalToken_tokenValue=&externalToken_tokenProvider=&ECIRaw=&cryptogram=&maskedNetworkTokenNumber=&upoRegistrationDate=20240724&type=DEPOSIT&clientRequestId=&relatedTransactionId=&apmPayerInfo=%5B%5D&sessionId=4f6d61e092d82faa26f2e0052253&responsechecksum=b11799728e2e06889cf6be672f12a873&advanceResponseChecksum=3da1f98c459f2655a231317e2cc7e39e

User Experience

1. The user is redirected to the page to select a bank.
   
2. The user logs into the bank account and approves payment.
3. The user gets redirected back to the merchant website.

Testing

The following table provides credentials for use in testing.

Bank	Credentials
Nordea	No credentials needed.
POP Pankki	Username: 11111111
Säästöpankki	Password: 123456
OmaSP	Security code: 123456
Aktia	Username: 12345678 Password: 123456 Security code: 1234
S-Pankki	Username: 12345678 Password: 9999 Security code: 1234

Appendix

The following table provides supported values for the "finishBanks_bic" parameter.

Bank	Value
Nordea	60
OP	61
Danske Bank	62
Ålandsbanken	64
Handelsbanken	65
S-Pankki	67
Aktia	298
POP Pankki	299
Säästöpankki	300
Oma Säästöpankki	322