• Jump to main content
  • Solutions
    Here's what we have to offer.
    We actually don’t refer to our products as products, but solutions. Because that is exactly what they are. Solutions to make your e-commerce checkout easy and user-friendly for your customers.

    Each solution has its own distinct characteristics and benefits. So, which one is right for you and your e-business? It entirely depends on your needs, expectations and preferences. Take a close look at the solutions available – and get a lot wiser.
    • Nordea Connect CheckoutA complete, out-of-the-box solution for merchants who want it super simple.
    • Payment WindowA simple Nordea Connect-hosted payment window easily integrated to your website.
    • APIsA set of tools to manage payment related tasks or design and build a checkout experience to your wishes.
    • Payment MethodsThe payment options available.
    • FeaturesThe key features and benefits.
    • PricesWhat we charge for Nordea Connect.
  • Resources
    ready_set_install
    Here's to you, developer – basically, everything you need to know about Nordea Connect integration and setup.
    • PlatformsE-commerce platforms and website builders.
    • DocumentationIn-depth integration guides and walkthroughs.
  • Stories
  • Knowledge
  • Contact
  • Help Centre
  • Login
  • Get Started

Technical documentation

Payment through API

Nordea Connect supports payment through API for card payments and Swish. This documentation contains information about how to initiate card/Swish payments. If you are looking for documentation regarding managing transactions, Billing plans or other transaction data trough API, please check our Management API documentation.

Please note that you need to be PCI DSS compliant to initiate card payments through API, if you directly collect and transmit card data from your backend to Nordea Connect.

Authentication

Nordea Connect API calls are made via our REST endpoints and the user is identified using Basic Auth. The user name is your Merchant ID and the password can be set in the Nordea Connect Merchant Portal: https://access.nordeaconnect.com/en/settings

HTTP Response Codes

The HTTP answer of a successful call is always HTTP 200 and contains the same JSON as with a GET call. A bad call will return HTTP 40x with a JSON error response.

Object Graph

In many cases the response does not contain full object graph but just a simple object like ..”customer”:{“id”:1}..
In this case you can extend the object using Extendability.

Default parameters

Please consult the relevant section for additional mandatory parameters depending on the type of transaction and payment method.

amountdecimal The transaction amount e.g. 12.00, NOTE: must always include two decimals and a dot
currencystring Payment currency (sek, cad, cny, cop, czk, dkk, hkd, huf, isk, inr, ils, jpy, kes, krw, kwd, lvl, myr, mxn, mad, omr, nzd, nok, pab, qar, rub, sar, sgd, zar, chf, thb, ttd, aed, gbp, usd, twd, vef, ron, try, eur, uah, pln, brl)
payment_refstring A unique order ID from the merchant internal order/payment data (length 1-12)
hashstring Hash recipe: MD5(merchant_id + payment_ref + customer_ref + amount + currency + test + secret). More details can be found in the Nordea Connect Merchant Portal under the Integration tab.
testboolean Parameter which decides whether the transaction is in test or production. With test = true, the transaction will run in test, with test = false, the transaction will be live.

Payment using card details

To create a transaction using card details you need to do a POST with the default params and the additional mandatory params below to https://api.nordeaconnect.com/v1/transactions

card_holderstringThe name on the charged credit card. Not required if process = false.
card_cvvstringCVV code. Not required if process = false.
card_expirystringExpiration date of the credit card in the format MMYY. Not required if process = false.
card_numberstringThe card number.
card_typestringVISA, MASTERCARD etc.
  • curl
  • ruby
  • php
  • .NET
EXAMPLE REQUEST
      
      curl -X POST --data "card_number=4111111111111111&card_expiry=0116&card_holder=name%20name&card_type=visa&amount=5.00&payment_ref=53dfaa67&card_cvv=200&currency=sek&hash=6bd88f621553edcf0c553f91bf6fb797" --user exampleuser:Pa55w0rd 'https://api.nordeaconnect.com/v1/transactions'
      
      
      EXAMPLE RESPONSE
      
      {
        "amount" : "5.0",
        "vat_amount": "0.2",
        "card_holder" : "name name",
        "card_number" : "411111******1111",
        "card_type" : "VISA",
        "cost" : {
          "fixed_fee" : "2.5",
          "percentual_exchange_fee" : "0.035",
          "percentual_fee" : "0.025",
          "total" : "2.8"
        },
        "authorize": false,
        "href": "https://pay.nordeaconnect.com/v1/form/Av6lK7OItURlSvYZ6pQ",
        "created_at" : "2018-08-04T15:45:11Z",
        "currency" : "sek",
        "customer" : null,
        "error" : null,
        "success_url": "",
        "error_url": "",
        "id" : 7510,
        "merchant_id" : 3,
        "metadata" : null,
        "payment_ref" : "53dfaa67",
        "ref" : null,
        "refunds" : [  ],
        "status" : "approved",
        "stored_card" : null,
        "subscription" : null,
        "success_url" : null,
        "template_id" : 123,
        "test" : true,
        "transaction_type" : "credit_card",
        "webhooks" : [],
        "items": [],
        "client_info": {
          "raw_user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/60.0.3112.113 Safari/537.36",
          "browser": "Chrome",
          "version": "60.0.3112.113",
          "platform": "Macintosh",
          "ip": "59.21.2.160",
          "accept_language": "en-GB,en;q=0.8,en-US;q=0.6,sv;q=0.4"
        },
        "response_hash": "6b5f0b8687dbbc25ff1e579ac10a0d48",
        "request_hash": "f42e350aca7a37600973b2b3143e2917",
        "payment_details": {
          "id": 1,
          "card_number": "411111******1111",
          "card_holder": "name name",
          "card_type": "MASTERCARD",
          "customer_number": null,
          "personal_number": null,
          "first_name": null,
          "last_name": null,
          "zip": null,
          "country_code": null,
          "country": null,
          "address": null,
          "city": null,
          "bank_name": null,
          "bank_acc_lastdigits": null,
          "phone": null,
          "ssn": null,
          "card_issuer": "WESTPAC BANKING CORPORATION",
          "credit_or_debit": "debit",
          "card_country_code": "AU",
          "campaign": null,
          "segmentation": "b2c",
          "address_1": null,
          "address_2": null,
          "swish_number": null,
          "email": null
        }
      }
<pre><code class="language-ruby"># EXAMPLE REQUEST
      
      attributes = {
        amount: '725.00',
        currency: 'sek',
        payment_ref: 'order-1146',
        hash: '6bd88f621553edcf0c553f91bf6fb797',
        card_holder: 'Test User',
        card_number: '4111 1111 1111 1111',
        card_expiry: '1016',
        card_cvv: '200',
        card_type: 'visa',
      }
      
      transaction = NordeaConnect::CreditCard::Transaction.create(attributes)
      
      # EXAMPLE RESPONSE
      
      [{"title"=&gt;"T-shirt"}, {"title"=&gt;"Shoes"}]},
        @validation_context=nil,
        @hash="7234484a4ca9ea19f594b7fda7268562",
        @id=8176,
        @created_at="2018-08-07T13:38:37Z",
        @merchant_id=10,
        @test=false,
        @status="approved",
        @transaction_type="credit_card",
        @cost={"percentual_fee"=&gt;"0.025", "fixed_fee"=&gt;"2.5", "percentual_exchange_fee"=&gt;"0.035", "total"=&gt;"46.0"},
        @stored_card=nil,
        @customer={"id"=&gt;3052},
        @subscription=ni&gt;l
      </code></pre>
<pre><code class="language-php">EXAMPLE REQUEST
      
      $payment = array(
        "card_number" =&gt; "4111111111111111",
        "card_holder" =&gt; "php sdk",
        "card_expiry" =&gt; "0116",
        "card_cvv" =&gt; "200",
        "card_type" =&gt; "VISA",
        "amount" =&gt; "10.00",
        "payment_ref" =&gt; $ref,
        "currency" =&gt; "eur",
        "test" =&gt; "true",
        "hash" =&gt; md5(configuration::$app_settings['username'].$ref."10.00".configuration::$app_settings['secret'])
      );
      
      $transaction = nordeaconnect\api\transaction::create($payment);
      
      EXAMPLE RESPONSE
      
      Array
      (
        [id] =&gt; 7543
        [created_at] =&gt; 2018-08-04T20:02:32Z
        [merchant_id] =&gt; 3
        [amount] =&gt; 10.0
        [payment_ref] =&gt; 99485
        [ref] =&gt;
        [card_holder] =&gt; php sdk
        [card_number] =&gt; 411111******1111
        [test] =&gt; 1
        [metadata] =&gt;
        [currency] =&gt; eur
        [status] =&gt; approved
        [card_type] =&gt; VISA
        [transaction_type] =&gt; credit_card
        [template_id] =&gt;
        [error] =&gt;
        [cost] =&gt; Array
        (
          [percentual_fee] =&gt; 0.025
          [fixed_fee] =&gt; 2.5
          [percentual_exchange_fee] =&gt; 0.035
          [total] =&gt; 3.1
        )
      
        [success_url] =&gt;
        [error_url] =&gt;
        [stored_card] =&gt;
        [customer] =&gt;
        [subscription] =&gt;
        [refunds] =&gt; Array
        (
        )
      
        [webhooks] =&gt; Array
        (
        )
      
      )
      </code></pre>
<pre><code class="language-c">EXAMPLE REQUEST
      
      var payment_ref = DateTimeOffset.Now.Ticks.ToString();
      var postData = new List();
      var encryptedCard = "4111111111111111".RSAEncrypt();
      
      postData.Add(new KeyValuePair("amount", "10.00"));
      postData.Add(new KeyValuePair("payment_ref", payment_ref));
      postData.Add(new KeyValuePair("card_expiry", "0116"));
      postData.Add(new KeyValuePair("card_holder", ".net sdk"));
      postData.Add(new KeyValuePair("card_cvv", "200"));
      postData.Add(new KeyValuePair("card_number", encryptedCard));
      postData.Add(new KeyValuePair("card_type", "VISA"));
      postData.Add(new KeyValuePair("currency", "sek"));
      postData.Add(new KeyValuePair("hash", (Settings.ApiUsername + payment_ref + "10.00" + "sek" + Settings.ApiSecret).ToMD5()));
      postData.Add(new KeyValuePair("encrypted", "card_number"));
      
      var transaction = Transaction.Create(postData);
      
      EXAMPLE RESPONSE
      
      {
        "amount" : "10.00",
        "card_cvv" : "200",
        "card_holder" : ".net sdk",
        "card_number" : "411111******1111",
        "card_type" : "VISA",
        "cost" : {
          "fixed_fee" : "2.5",
          "percentual_exchange_fee" : "0.035",
          "percentual_fee" : "0.025",
          "total" : "2.8"
        },
        "created_at" : "2018-08-06T17:41:50.8261719Z",
        "currency" : "sek",
        "customer" : null,
        "encrypted" : "card_number",
        "error" : null,
        "error_url" : null,
        "id" : 1,
        "merchant_id" : 3,
        "metadata" : null,
        "payment_ref" : "635429509106230469",
        "payment_request" : null,
        "refund" : null,
        "status" : "complete",
        "stored_card" : null,
        "subscription" : null,
        "success_url" : null,
        "template_id" : 1,
        "test" : true,
        "transcation_type" : null,
        "webhooks" : null
      }</code></pre>

Payment using tokenized card

To create a transaction using tokenized card you need to do a POST with the default params and the additional mandatory params below to https://api.nordeaconnect.com/v1/transactions

Additional mandatory parameters

card_numberstringThe token for the card is sent in using the card_number param
card_typestringSend in value stored_card
  • curl
  • ruby
  • php
  • .NET
EXAMPLE REQUEST
      
      curl -X POST --data "card_number=cc583309-0fe2-417d-a7e9-84da476a6596&card_type=stored_card&amount=5.00&payment_ref=53dfaa67&currency=sek&hash=6bd88f621553edcf0c553f91bf6fb797" --user exampleuser:Pa55w0rd 'https://api.nordeaconnect.com/v1/transactions'
      
      
      EXAMPLE RESPONSE
      
      {
        "amount" : "5.0",
        "vat_amount": "0.2",
        "card_holder" : "name name",
        "card_number" : "411111******1111",
        "card_type" : "VISA",
        "cost" : {
          "fixed_fee" : "2.5",
          "percentual_exchange_fee" : "0.035",
          "percentual_fee" : "0.025",
          "total" : "2.8"
        },
        "authorize": false,
        "href": "https://pay.nordeaconnect.com/v1/form/Av6lK7OItURlSvYZ6pQ",
        "created_at" : "2018-08-04T15:45:11Z",
        "currency" : "sek",
        "customer" : null,
        "error" : null,
        "success_url": "",
        "error_url": "",
        "id" : 7510,
        "merchant_id" : 3,
        "metadata" : null,
        "payment_ref" : "53dfaa67",
        "ref" : null,
        "refunds" : [  ],
        "status" : "approved",
        "stored_card" : null,
        "subscription" : null,
        "success_url" : null,
        "template_id" : 123,
        "test" : true,
        "transaction_type" : "credit_card",
        "webhooks" : [],
        "items": [],
        "client_info": {
          "raw_user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/60.0.3112.113 Safari/537.36",
          "browser": "Chrome",
          "version": "60.0.3112.113",
          "platform": "Macintosh",
          "ip": "59.21.2.160",
          "accept_language": "en-GB,en;q=0.8,en-US;q=0.6,sv;q=0.4"
        },
        "response_hash": "6b5f0b8687dbbc25ff1e579ac10a0d48",
        "request_hash": "f42e350aca7a37600973b2b3143e2917",
        "payment_details": {
          "id": 1,
          "card_number": "411111******1111",
          "card_holder": "name name",
          "card_type": "MASTERCARD",
          "customer_number": null,
          "personal_number": null,
          "first_name": null,
          "last_name": null,
          "zip": null,
          "country_code": null,
          "country": null,
          "address": null,
          "city": null,
          "bank_name": null,
          "bank_acc_lastdigits": null,
          "phone": null,
          "ssn": null,
          "card_issuer": "WESTPAC BANKING CORPORATION",
          "credit_or_debit": "debit",
          "card_country_code": "AU",
          "campaign": null,
          "segmentation": "b2c",
          "address_1": null,
          "address_2": null,
          "swish_number": null,
          "email": null
        }
      }
<pre><code class="language-ruby"># EXAMPLE REQUEST
      
      attributes = {
        amount: '725.00',
        currency: 'sek',
        payment_ref: 'order-1146',
        hash: '6bd88f621553edcf0c553f91bf6fb797',
        card_number: 'cc583309-0fe2-417d-a7e9-84da476a6596',
        card_type: 'stored_card',
      }
      
      transaction = NordeaConnect::CreditCard::Transaction.create(attributes)
      
      # EXAMPLE RESPONSE
      
      [{"title"=&gt;"T-shirt"}, {"title"=&gt;"Shoes"}]},
        @validation_context=nil,
        @hash="7234484a4ca9ea19f594b7fda7268562",
        @id=8176,
        @created_at="2018-08-07T13:38:37Z",
        @merchant_id=10,
        @test=false,
        @status="approved",
        @transaction_type="credit_card",
        @cost={"percentual_fee"=&gt;"0.025", "fixed_fee"=&gt;"2.5", "percentual_exchange_fee"=&gt;"0.035", "total"=&gt;"46.0"},
        @stored_card=nil,
        @customer={"id"=&gt;3052},
        @subscription=ni&gt;l
      </code></pre>
<pre><code class="language-php">EXAMPLE REQUEST
      
      $payment = array(
        "card_number" =&gt; "cc583309-0fe2-417d-a7e9-84da476a6596",
        "card_type" =&gt; "stored_card",
        "amount" =&gt; "10.00",
        "payment_ref" =&gt; $ref,
        "currency" =&gt; "eur",
        "test" =&gt; "true",
        "hash" =&gt; md5(configuration::$app_settings['username'].$ref."10.00".configuration::$app_settings['secret'])
      );
      
      $transaction = nordeaconnect\api\transaction::create($payment);
      
      EXAMPLE RESPONSE
      
      Array
      (
        [id] =&gt; 7543
        [created_at] =&gt; 2018-08-04T20:02:32Z
        [merchant_id] =&gt; 3
        [amount] =&gt; 10.0
        [payment_ref] =&gt; 99485
        [ref] =&gt;
        [card_holder] =&gt; php sdk
        [card_number] =&gt; 411111******1111
        [test] =&gt; 1
        [metadata] =&gt;
        [currency] =&gt; eur
        [status] =&gt; approved
        [card_type] =&gt; VISA
        [transaction_type] =&gt; credit_card
        [template_id] =&gt;
        [error] =&gt;
        [cost] =&gt; Array
        (
          [percentual_fee] =&gt; 0.025
          [fixed_fee] =&gt; 2.5
          [percentual_exchange_fee] =&gt; 0.035
          [total] =&gt; 3.1
        )
      
        [success_url] =&gt;
        [error_url] =&gt;
        [stored_card] =&gt;
        [customer] =&gt;
        [subscription] =&gt;
        [refunds] =&gt; Array
        (
        )
      
        [webhooks] =&gt; Array
        (
        )
      
      )
      </code></pre>
<pre><code class="language-c">EXAMPLE REQUEST
      
      var payment_ref = DateTimeOffset.Now.Ticks.ToString();
      var postData = new List();
      var encryptedCard = "4111111111111111".RSAEncrypt();
      
      postData.Add(new KeyValuePair("amount", "10.00"));
      postData.Add(new KeyValuePair("payment_ref", payment_ref));
      postData.Add(new KeyValuePair("card_number", cc583309-0fe2-417d-a7e9-84da476a6596));
      postData.Add(new KeyValuePair("card_type", "stored_card"));
      postData.Add(new KeyValuePair("currency", "sek"));
      postData.Add(new KeyValuePair("hash", (Settings.ApiUsername + payment_ref + "10.00" + "sek" + Settings.ApiSecret).ToMD5()));
      postData.Add(new KeyValuePair("encrypted", "card_number"));
      
      var transaction = Transaction.Create(postData);
      
      EXAMPLE RESPONSE
      
      {
        "amount" : "10.00",
        "card_cvv" : "200",
        "card_holder" : ".net sdk",
        "card_number" : "411111******1111",
        "card_type" : "VISA",
        "cost" : {
          "fixed_fee" : "2.5",
          "percentual_exchange_fee" : "0.035",
          "percentual_fee" : "0.025",
          "total" : "2.8"
        },
        "created_at" : "2018-08-06T17:41:50.8261719Z",
        "currency" : "sek",
        "customer" : null,
        "encrypted" : "card_number",
        "error" : null,
        "error_url" : null,
        "id" : 1,
        "merchant_id" : 3,
        "metadata" : null,
        "payment_ref" : "635429509106230469",
        "payment_request" : null,
        "refund" : null,
        "status" : "complete",
        "stored_card" : null,
        "subscription" : null,
        "success_url" : null,
        "template_id" : 1,
        "test" : true,
        "transcation_type" : null,
        "webhooks" : null
      }</code></pre>

Swish payment

To create a Swish payment you need to do a POST with the default params and the additional mandatory params below to https://api.nordeaconnect.com/v1/transactions

Api Swish

Transaction

Optional parameters to send

merchant_idstring Your unique Merchant ID, which can be found in the Nordea Connect Merchant Portal in the Integration tab.
vat_amountdecimalThe vat amount for the transaction ex. 3.00
testbooleanWhether the transaction is a test transaction. Defaults false
success_urlstring A URL to the page where the Consumer is redirected after a successful transaction. Can contain Liquid.
error_urlstring A URL to the page where the Consumer is redirected after a unsuccessful transaction. Can contain Liquid.
metadataobjectMerchant custom Metadata
store_cardbooleantrue/false if you want to store the card
plan_idintThe ID of the subscription plan.
start_datedateThe first date of a new subscription. Ex: 2020-01-01 (YYYY-MM-DD)
customer_refstringThe Merchant specific user/customer ID
webhookobjectYou can specify a custom Webhook for a transaction. For example sending e-mail or POST to your backend.
encryptedstringA comma separated string containing the params you have encrypted. Ex: “card_number,card_holder,card_cvv”
processbooleanShould be false if you want to process the payment at a later stage. You will not need to send in card data (card_number, card_cvv, card_holder, card_expiry) in this case.
template_idint Hosted Page template ID
authorizebooleanauthorize = true, means that the transaction should be reserved (Authorized).
itemsArray of items objectsitems
payment_detailsobjectpayment_details
payment_methodstringCan be any of the following: credit_card, recurring, stored, invoice, swish, paypal, bank

Hash calculation

Nordea Connect uses a hash string to identify the merchant and validate the API call.

The hash recipe is:
MD5(merchant_id + payment_ref + customer_ref + amount + currency + test + secret)

The ingredients of the hash recipe are:

merchant_id (integer): Your merchant id (this can be found in the Integration tab in the Nordea Connect Merchant Portal)
payment_ref (string): A generated unique order id from your web shop
customer_ref (string): A unique id for your customer – ignore if you are not sending in a customer ref
amount (string): Must include two digits, example 10.00
currency (string): An ISO 4214 currency code, must be in lower case (ex. eur)
test (string): “test” if transaction is in test mode, otherwise empty string “”
secret (string): Unique merchant specific string

Let’s assume we have the following data for our hash recipe:

merchant_id (integer): 09024
payment_ref (string): 12345678
customer_ref (string): 891
amount (string): 10.00
currency (string): dkk
test (string): test
secret (string): $2a/sdf0W556fDi3wr320FUASng.

The example hash string would in this case look like this:
090241234567889110.00dkktest$2a/sdf0W556fDi3wr320FUASng.

In this case, the MD5 hash you get should be:
1c6332f03717fdf960078b32c45a5771

Please note especially the following:

  • In the above example, we are initiating a test transaction. If this transaction would have been a live transaction, the has string would look like this: 090241234567889110.00dkk$2a/sdf0W556fDi3wr320FUASng.
  • Sometimes, the secret might end with a special character, as in the example above. Please make sure you copy the entire string.

Important when storing a card/subscribing to a plan

In some cases the card can not be stored, but we will still try to charge it. This means that the transaction might be successful even though the card can not be stored.

Always check the response to see if there is a stored_card (or subscription), which will be missing if the card could not be stored.

Create a Transaction with a stored card

In a Stored Card payment you need to have the token as card_number and STORED_CARD as card_type. The response will have a Stored Card object with the ID of the card used.

  • curl
  • ruby
  • php
  • net
EXAMPLE REQUEST
      
      curl -X POST --data "card_number=31407340575815445&card_type=STORED_CARD&amount=5.00&payment_ref=53e479ea&card_cvv=000&currency=sek&hash=e914a186f79333a9f4166b17c6dc791d&test=true" --user 3:password 'https://api.nordeaconnect.com/v1/transactions'
      
      EXAMPLE RESPONSE
      
      {
        "amount" : "5.0",
        "card_holder" : "635429445753750000",
        "card_number" : "411111******1111",
        "card_type" : "VISA",
        "cost" : {
          "fixed_fee" : "2.5",
          "percentual_exchange_fee" : "0.035",
          "percentual_fee" : "0.025",
          "total" : "2.8"
        },
        "created_at" : "2018-08-08T07:20:01Z",
        "currency" : "sek",
        "customer" : { "id" : 3026 },
        "error" : null,
        "error_url" : null,
        "id" : 8237,
        "merchant_id" : 3,
        "metadata" : null,
        "payment_ref" : "53e479ea",
        "ref" : null,
        "refunds" : [  ],
        "status" : "approved",
        "stored_card" : { "id" : 1055 },
        "subscription" : null,
        "success_url" : null,
        "template_id" : null,
        "test" : true,
        "transaction_type" : "stored_card",
        "webhooks" : [  ]
      }
file to be uploaded
EXAMPLE REQUEST
      
      $payment = array(
      "card_number" => "31407340575815445",
      "card_cvv" => "000",
      "card_type" => "STORED_CARD",
      "amount" => "10.00",
      "payment_ref" => "123",
      "currency" => "eur",
      "test" => "true",
      "hash" => md5(configuration::$app_settings['username'].$ref."10.00".configuration::$app_settings['secret'])
      );
      
      $transaction = nordeaconnect\api\transaction::create($payment);
      
      EXAMPLE RESPONSE
      
      Array
      (
        [id] => 7543
        [created_at] => 2018-08-04T20:02:32Z
        [merchant_id] => 3
        [amount] => 10.0
        [payment_ref] => 99485
        [ref] =>
        [card_holder] => php sdk
        [card_number] => 411111******1111
        [test] => 1
        [metadata] =>
        [currency] => eur
        [status] => approved
        [card_type] => VISA
        [transaction_type] => credit_card
        [template_id] =>
        [error] =>
        [cost] => Array
        (
          [percentual_fee] => 0.025
          [fixed_fee] => 2.5
          [percentual_exchange_fee] => 0.035
          [total] => 3.1
        )
      
        [success_url] =>
        [error_url] =>
        [stored_card] =>
        (
          [id] => 1055
        )
        [customer] =>
        [subscription] =>
        [refunds] => Array
        (
        )
      
        [webhooks] => Array
        (
        )
      
      )
      
EXAMPLE REQUEST
      
      var payment_ref = DateTimeOffset.Now.Ticks.ToString();
      var postData = new List();
      
      postData.Add(new KeyValuePair("amount", "10.00"));
      postData.Add(new KeyValuePair("payment_ref", payment_ref));
      postData.Add(new KeyValuePair("test", "true"));
      postData.Add(new KeyValuePair("card_cvv", "000"));
      postData.Add(new KeyValuePair("card_number", "31407340575815445"));
      postData.Add(new KeyValuePair("card_type", "STORED_CARD"));
      postData.Add(new KeyValuePair("currency", "sek"));
      postData.Add(new KeyValuePair("locale", "en"));
      postData.Add(new KeyValuePair("hash", (Settings.ApiUsername + payment_ref + "10.00" + "sek" + Settings.ApiSecret).ToMD5()));
      
      var transaction = Transaction.Create(postData);
      
      EXAMPLE RESPONSE
      
      {
        "amount" : "5.0",
        "card_holder" : "635429445753750000",
        "card_number" : "411111******1111",
        "card_type" : "VISA",
        "cost" : {
          "fixed_fee" : "2.5",
          "percentual_exchange_fee" : "0.035",
          "percentual_fee" : "0.025",
          "total" : "2.8"
        },
        "created_at" : "2018-08-08T07:20:01Z",
        "currency" : "sek",
        "customer" : { "id" : 3026 },
        "error" : null,
        "error_url" : null,
        "id" : 8237,
        "merchant_id" : 3,
        "metadata" : null,
        "payment_ref" : "53e479ea",
        "ref" : null,
        "refunds" : [  ],
        "status" : "approved",
        "stored_card" : { "id" : 1055 },
        "subscription" : null,
        "success_url" : null,
        "template_id" : null,
        "test" : true,
        "transaction_type" : "stored_card",
        "webhooks" : [  ]
      }

Update Transaction

To update a transaction with card details using the API, you need to PUT data to https://api.nordeaconnect.com/v1/transactions/1

You can update a transaction when it has previously been created and is not in approved status. For example, you can create a transaction and send in process = false to prepare but not process the actual payment. The next step would be to either pass the href link to the customer to proceed the payment in a payment window, or to make an API payment using this update call.

The parameters you can send to update a transaction:

card_holderstringThe name on the charged credit card
card_numberstringA card number ex. 41111111111111
card_cvvstringCVV code
card_expirystringExpiration date of the credit card in the format MMYY
currencystringThe currency (SEK, CAD, CNY, COP, CZK, DKK, HKD, HUF, ISK, INR, ILS, JPY, KES, KRW, KWD, LVL, MYR, MXN, MAD, OMR, NZD, NOK, PAB, QAR, RUB, SAR, SGD, ZAR, CHF, THB, TTD, AED, GBP, USD, TWD, VEF, RON, TRY, EUR, UAH, PLN, BRL)
card_typestringVISA, MASTERCARD, STORED_CARD (if the transaction is done using a stored card), etc
encryptedstringA comma separated string for the params that you send encrypted. Ex. “card_number,card_cvv”
itemsArray of items objectsitems
metadataobjectMetadata
amountdecimalThe transaction amount ex. 12.00
vat_amountdecimalThe VAT amount for the transaction ex. 3.00
customer_refstringThe Merchant specific user/customer ID
processbooleanShould be false if you want to process the payment at a later stage. You will not need to send in card data (card_number, card_cvv, card_holder, card_expiry) in this case.

You can update the Metadata property of an already processed transaction by passing metadata and process = false.

The submitted data will be merged with existing Metadata for that transaction.

By sending, for example: {"shop_order": {"id": "123123"}} as Metadata to the update method, you can connect your internal shop order ID to the Nordea Connect admin view.

Transaction object

A transaction contains JSON with the following data:

idintegerId of the transaction
created_atdatetimeEx. 2018-04-25T10:20:48Z (UTC)
merchant_idstringID of Merchant
amountdecimalThe transaction amount ex. 12.00
vat_amountdecimalThe vat amount for the transaction ex. 3.00
payment_refstringThe Merchant order/payment ID
card_holderstringThe name on the charged credit card
card_numberstringA masked card number ex. 411111****1111
card_expirystringMMYY ex. 0120
testbooleanWhether the transaction is a test transaction.
currencystringThe currency (SEK, CAD, CNY, COP, CZK, DKK, HKD, HUF, ISK, INR, ILS, JPY, KES, KRW, KWD, LVL, MYR, MXN, MAD, OMR, NZD, NOK, PAB, QAR, RUB, SAR, SGD, ZAR, CHF, THB, TTD, AED, GBP, USD, TWD, VEF, RON, TRY, EUR, UAH, PLN, BRL)
statusstringStatus of the api transaction.

  • pending – created but not yet processed
  • approved
  • authorized
  • declined
  • failed
card_typestringVISA, MASTERCARD, etc. (STORED_CARD if the transaction is done with stored card)
payment_requestobjectThe payment request from the Merchant
template_idintHosted Page template ID
errorobjectFor example:

error: {
         name: 'errors.card_number.missing',
         code: 118,
         description: 'Card number is missing'
       }
costobjectThe cost of transaction

{"percentual_fee":0,"fixed_fee":0,"percentual_exchange_fee":0,"total":"0.0", "vat_rate": 0.25}
success_urlstringURL after successful transaction. Can contain Liquid.
error_urlstringURL after unsuccessful transaction. Can contain Liquid.
metadataobjectMerchant specific Metadata
refundarrayAn array with refunds objects where the token value is used for making transactions with the stored card
stored_cardobjectIf the transaction has a stored card connected it will have a token value that is used for making transactions with the stored card
customerobjectCustomer that owns the transaction
transaction_typestringcredit_card/stored_card/recurring
subscriptionobjectThe connected subscription
webhooksarrayA list of Webhooks related to the transaction
hrefstringA HTTP link to a payment page where the customer can finish a payment. Ex. https://pay.nordeaconnect.com/v1/form/hrr5sEwz0y-XgcYOyNXhew
ItemsArray of items objectsitems
payment_detailsobjectpayment_details
payment_methodstringCan be any of the following: credit_card, recurring, stored, invoice, swish, paypal, bank
processed_atdatetimeThe exact time when the payment was confirmed. Ex. 2018-04-25T10:20:48Z (UTC)

Encryption

Transaction data can be encrypted with a public RSA key for better security. The public RSA key can be found in the Nordea Connect Merchant Portal’s Integration tab. The parameter “encrypted” must also be sent and contain the names of the encrypted parameters such as “card_number,card_cvv,card_holder,card_expiry,card_type”. You would also need to base64 encode the string both before and after encryption, i.e. base64_encode( encrypt( base64_encode( actual_value ) ) ).

Transaction statuses

Nordea Connect supports the following transaction statuses:

  • Pending
    A transaction always starts as a Pending transaction and will only alter after a customer has attempted to pay. If successful, it will be approved (or authorised). The transaction will stay as pending if the customer cancels the payment in Payment Window/Nordea Connect Checkout. It will change to failed/declined if the customer attempts to pay and is unsuccessful. By default, a consumer will be taken back to the Payment Window/Nordea Connect Checkout if the attempt is unsuccessful. This flow can also be changed on request, to take the customer directly back to your webshop if a payment attempt fails.
  • 3DS pending
    The customer has been redirected to the 3DS server to authorise their card payment.
  • Approved
    Money has been drawn from the customer and the transaction is processed.
  • Authorised
    A cover reservation has been made on the customer’s card. You need to capture the transaction through API or in the Nordea Connect Merchant Portal in order to process the transaction.
  • Failed/Declined
    A pending transaction might become failed/declined depending on the payment method used. This usually indicates that the customer has either cancelled the payment or it has been denied by the payment method provider.

Nordea Connect does not have a cancelled transaction status.

  • Transactions cancelled by a customer will either be displayed as pending, failed or declined.
  • If a customer cancels at the Payment Window stage, the transaction will be displayed as pending.
  • If the customer cancels the payment at a later stage, the payment will be displayed as failed/declined depending on the payment method provider.

Please note, that once a transaction is approved (paid) its status will no longer change. All other transaction statuses might update depending on the customer’s behaviour.

The diagram below outlines the transaction flow.

Pagination

While doing API calls you can use pagination to fetch parts of your data using limit, offset and start_id.

Pagination Example:

https://api.nordeaconnect.com/v1/transactions?limit=2&offset=20

ID range Example:

https://api.nordeaconnect.com/v1/transactions?start_id=1051&limit=15

Pagination information

Pagination of partial data can be achieved using the Content-Range header. The Content-Range show what part of the data-set that is being returned.

Content-Range:items 16-20/173

Order

You can order your resource list by using the order_by query parameter.

Order example

https://api.nordeaconnect.com/v1/transactions?order_by=amount

Descending order example

https://api.nordeaconnect.com/v1/transactions?order_by=amount:desc

Filtering

Filter
If you know what you are looking for, you can filter your result with the filter query parameter.

Strings and Booleans support equal and wildcard matches, e.g.:

  • filter[status]=approved
  • filter[card_number]=411*
  • filter[test]=true

Integers, Decimals and Dates supports equal matches, as well as up to, from, and ranges, e.g.:

  • filter[amount]=..1000 will fetch resources where amount is less than or equal to 1000
  • filter[amount]=100.. will fetch resources where amount is greater than or equal to 100
  • filter[created_at]=20180101..20180131 will fetch resources created in January 2018 (from the first up until the 31st)
  • filter[created_at]=20180930T084821 will fetch resources with exact date and time value

Metadata filters

  • filter[metadata.customer.name]=anna will fetch resources where metadata contains a customer which have a name that is anna
  • filter[metadata.customer]=* will fetch resources where metadata have a customer object
  • filter[metadata.products.0.name]=* will fetch the first resources from the products array

Filter example:

https://api.nordeaconnect.com/v1/transactions?filter[test]=false&filter[amount]100..&filter[created_at]=20180101..20181231

Subscription payment

Get started

Nordea Connect supports recurring payments for cards. As a merchant, you have two options:

1. Set up a Billing Plan either in the Nordea Connect Merchant Portal or through API, where Nordea Connect will execute the recurring payments on your behalf

2. Utilize our tokenized card functionality and build your own subscription engine allowing you to control the recurring payment schedule

If you are looking to create a payment using the Nordea Connect subscription engine, you will need to send all the params required for either initiating a payment using card details or through tokenized card. In addition, you will also need the param plan_id, which is the ID of your Billing plan. It is visible in the Merchant Portal in the tab “Billing plans”.

Unless a free trial period is setup, the first subscription fee is debited at the same time as the transaction is processed. Please see the example below.

 

Example

  • curl
  • ruby
  • php
  • .NET
EXAMPLE REQUEST
      
      curl -X POST --data "card_number=4111111111111111&card_expiry=0116&card_holder=name%20name&card_type=visa&amount=5.00&payment_ref=53dfaa67&card_cvv=200&currency=sek&hash=6bd88f621553edcf0c553f91bf6fb797&plan_id=561" --user exampleuser:Pa55w0rd 'https://api.nordeaconnect.com/v1/transactions'
      
      
      EXAMPLE RESPONSE
      
      {
        "amount" : "5.0",
        "vat_amount": "0.2",
        "card_holder" : "name name",
        "card_number" : "411111******1111",
        "card_type" : "VISA",
        "cost" : {
          "fixed_fee" : "2.5",
          "percentual_exchange_fee" : "0.035",
          "percentual_fee" : "0.025",
          "total" : "2.8"
        },
        "authorize": false,
        "href": "https://pay.nordeaconnect.com/v1/form/Av6lK7OItURlSvYZ6pQ",
        "created_at" : "2018-08-04T15:45:11Z",
        "currency" : "sek",
        "customer" : null,
        "error" : null,
        "success_url": "",
        "error_url": "",
        "id" : 7510,
        "merchant_id" : 3,
        "metadata" : null,
        "payment_ref" : "53dfaa67",
        "ref" : null,
        "refunds" : [  ],
        "status" : "approved",
        "stored_card" : null,
        "subscription" : null,
        "success_url" : null,
        "template_id" : 123,
        "test" : true,
        "transaction_type" : "credit_card",
        "webhooks" : [],
        "items": [],
        "client_info": {
          "raw_user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/60.0.3112.113 Safari/537.36",
          "browser": "Chrome",
          "version": "60.0.3112.113",
          "platform": "Macintosh",
          "ip": "59.21.2.160",
          "accept_language": "en-GB,en;q=0.8,en-US;q=0.6,sv;q=0.4"
        },
        "response_hash": "6b5f0b8687dbbc25ff1e579ac10a0d48",
        "request_hash": "f42e350aca7a37600973b2b3143e2917",
        "payment_details": {
          "id": 1,
          "card_number": "411111******1111",
          "card_holder": "name name",
          "card_type": "MASTERCARD",
          "customer_number": null,
          "personal_number": null,
          "first_name": null,
          "last_name": null,
          "zip": null,
          "country_code": null,
          "country": null,
          "address": null,
          "city": null,
          "bank_name": null,
          "bank_acc_lastdigits": null,
          "phone": null,
          "ssn": null,
          "card_issuer": "WESTPAC BANKING CORPORATION",
          "credit_or_debit": "debit",
          "card_country_code": "AU",
          "campaign": null,
          "segmentation": "b2c",
          "address_1": null,
          "address_2": null,
          "swish_number": null,
          "email": null
        }
      }
<pre><code class="language-ruby"># EXAMPLE REQUEST
      
      attributes = {
        amount: '725.00',
        currency: 'sek',
        payment_ref: 'order-1146',
        hash: '6bd88f621553edcf0c553f91bf6fb797',
        card_holder: 'Test User',
        card_number: '4111 1111 1111 1111',
        card_expiry: '1016',
        card_cvv: '200',
        card_type: 'visa',
        plan_id: '651',
      }
      
      transaction = NordeaConnect::CreditCard::Transaction.create(attributes)
      
      # EXAMPLE RESPONSE
      
      [{"title"=&gt;"T-shirt"}, {"title"=&gt;"Shoes"}]},
        @validation_context=nil,
        @hash="7234484a4ca9ea19f594b7fda7268562",
        @id=8176,
        @created_at="2018-08-07T13:38:37Z",
        @merchant_id=10,
        @test=false,
        @status="approved",
        @transaction_type="credit_card",
        @cost={"percentual_fee"=&gt;"0.025", "fixed_fee"=&gt;"2.5", "percentual_exchange_fee"=&gt;"0.035", "total"=&gt;"46.0"},
        @stored_card=nil,
        @customer={"id"=&gt;3052},
        @subscription=ni&gt;l
      </code></pre>
<pre><code class="language-php">EXAMPLE REQUEST
      
      $payment = array(
        "card_number" =&gt; "4111111111111111",
        "card_holder" =&gt; "php sdk",
        "card_expiry" =&gt; "0116",
        "card_cvv" =&gt; "200",
        "card_type" =&gt; "VISA",
        "plan_id" =&gt; "651",
        "amount" =&gt; "10.00",
        "payment_ref" =&gt; $ref,
        "currency" =&gt; "eur",
        "test" =&gt; "true",
        "hash" =&gt; md5(configuration::$app_settings['username'].$ref."10.00".configuration::$app_settings['secret'])
      );
      
      $transaction = nordeaconnect\api\transaction::create($payment);
      
      EXAMPLE RESPONSE
      
      Array
      (
        [id] =&gt; 7543
        [created_at] =&gt; 2018-08-04T20:02:32Z
        [merchant_id] =&gt; 3
        [amount] =&gt; 10.0
        [payment_ref] =&gt; 99485
        [ref] =&gt;
        [card_holder] =&gt; php sdk
        [card_number] =&gt; 411111******1111
        [test] =&gt; 1
        [metadata] =&gt;
        [currency] =&gt; eur
        [status] =&gt; approved
        [card_type] =&gt; VISA
        [transaction_type] =&gt; credit_card
        [template_id] =&gt;
        [error] =&gt;
        [cost] =&gt; Array
        (
          [percentual_fee] =&gt; 0.025
          [fixed_fee] =&gt; 2.5
          [percentual_exchange_fee] =&gt; 0.035
          [total] =&gt; 3.1
        )
      
        [success_url] =&gt;
        [error_url] =&gt;
        [stored_card] =&gt;
        [customer] =&gt;
        [subscription] =&gt;
        [refunds] =&gt; Array
        (
        )
      
        [webhooks] =&gt; Array
        (
        )
      
      )
      </code></pre>
<pre><code class="language-c">EXAMPLE REQUEST
      
      var payment_ref = DateTimeOffset.Now.Ticks.ToString();
      var postData = new List();
      var encryptedCard = "4111111111111111".RSAEncrypt();
      
      postData.Add(new KeyValuePair("amount", "10.00"));
      postData.Add(new KeyValuePair("payment_ref", payment_ref));
      postData.Add(new KeyValuePair("card_expiry", "0116"));
      postData.Add(new KeyValuePair("card_holder", ".net sdk"));
      postData.Add(new KeyValuePair("card_cvv", "200"));
      postData.Add(new KeyValuePair("card_number", encryptedCard));
      postData.Add(new KeyValuePair("card_type", "VISA"));
      postData.Add(new KeyValuePair("currency", "sek"));
      postData.Add(new KeyValuePair("hash", (Settings.ApiUsername + payment_ref + "10.00" + "sek" + Settings.ApiSecret).ToMD5()));
      postData.Add(new KeyValuePair("encrypted", "card_number"));
      postData.Add(new KeyValuePair("encrypted", "plan_id"));
      
      var transaction = Transaction.Create(postData);
      
      EXAMPLE RESPONSE
      
      {
        "amount" : "10.00",
        "card_cvv" : "200",
        "card_holder" : ".net sdk",
        "card_number" : "411111******1111",
        "card_type" : "VISA",
        "cost" : {
          "fixed_fee" : "2.5",
          "percentual_exchange_fee" : "0.035",
          "percentual_fee" : "0.025",
          "total" : "2.8"
        },
        "created_at" : "2018-08-06T17:41:50.8261719Z",
        "currency" : "sek",
        "customer" : null,
        "encrypted" : "card_number",
        "error" : null,
        "error_url" : null,
        "id" : 1,
        "merchant_id" : 3,
        "metadata" : null,
        "payment_ref" : "635429509106230469",
        "payment_request" : null,
        "refund" : null,
        "status" : "complete",
        "stored_card" : null,
        "subscription" : null,
        "success_url" : null,
        "template_id" : 1,
        "test" : true,
        "transcation_type" : null,
        "webhooks" : null
      }</code></pre>

Metadata

Metadata is custom schemaless information that you can choose to send in to Nordea Connect. It can be information about the customer, the product or about campaigns or offers.

The metadata can be used to customize your hosted payment window or sending personalized receipts to your customers in a webhook.

Example of metadata:

{
        "products":[
        {
          "id":"1",
          "name":"Nice Shoe",
          "price":"100.00",
          "qty":"1",
          "url":"http://mysite.com/product/1"
        }
        ],
        "user":{
          "email":"jd@email.com"
        }
      }

The values like products, 1, name, are optional and can be named freely by the Merchant. These will be shown in the transaction lists so you can analyze transactions based on metadata and get a comprehensive understanding of your sales.

Why Metadata?

One of the most important benefits of using Nordea Connect is the power of the data that you can send with the payment. The more data you send in the more parameters you have to create custom payment flows and analyze transaction data to see what are your best selling items, services and products.

Popular parameters are:

  • Order information (price, vat, categories, materials, tags)
  • Platform specs (iPhone/Android, OS version, screen size, locale)
  • Application specs (version number, tokens, sessions)
  • Customer information (location, language)

All sent in data can be visualized in your dashboard in graphs or charts so that you easy can follow up and analyze your sales. Nordea Connect understands that making relevant and important business decisions starts with knowing your customers habits, likes and preferences. Incorporating metadata into the payment gives you the best chance to optimize your checkout, A/B test and bring intelligence into your business.

Updating the transaction with shop order ID

By using the API, you can update the Metadata property of an already processed transaction by passing metadata and process = false.

The submitted data will be merged with existing Metadata for that transaction.

By sending, for example: {"shop_order": {"id": "123123"}} as Metadata to the update method, you can connect your internal shop order ID to the Nordea Connect admin view.

Liquid and Metadata

Liquid is an open-source, Ruby-based template language created by Shopify. It is a well-known framework and is used to load dynamic content on storefronts.

Liquid uses a combination of tags, objects, and filters to load dynamic content. They are used inside the Nordea Connect Payment Window payment form to display information from the payment data and make the template dynamic for each customer, product or transaction.

The official documentation can be found here: https://github.com/Shopify/liquid/wiki/Liquid-for-Designers

You can output information in your metadata to your Payment Window Form or in a Receipt Webhook using Liquid syntax. Using the example above, this is the way to output it:

Product name: {{ transaction.metadata['products'].first.name }}
      Product quantity: {{ transaction.metadata['products'].first.qty }}

To loop all products:

{%for item in transaction.metadata['products']%}
      <li>
        Name: {{ item['name'] }},
        Price: {{ item['price'] }} {{transaction.amount | upcase }},
        Quantity {{ item['qty'] }}
      </li>
      {% endfor %}

Liquid syntax is used within webhooks and Payment Windows. Please go to Payment Window to see the full white list of liquid elements

Webhooks

A webhook is a messaging service that is executed before or after a transaction. You can add one or more webhooks in the Admin console or specify a custom webhook for a transaction. The data that sent varies depending on the context, read more under triggers to see what data to expect.

idintWebhook ID
created_atdatetimeEx. 2018-04-25T10:36:33Z (UTC)
typestringWebhook type, ex: CustomHttp
responseobjectThe http response, ex: { "code":"400", "body":"Bad request (GET and HEAD requests may not contain a request body)", "message":"Bad Request", "error":"Net::HTTPBadRequest" }
http_methodstringWhich method that were used, ex. POST, GET
emailstringSender address in a e-mail Webhook
urlstringURL in a Custom Http Webhook
triggerstringWhat event to trigger Webhook, ex. payment_error
data_formatstringJSON, form_data or XML

Show Webhooks

To show a webhook with ID 1 you need to GET the following url https://api.nordeaconnect.com/v1/webhooks/1

List Webhooks

To show a list of webhooks you need to GET the following url https://api.nordeaconnect.com/v1/webhooks

Creating Webhooks in a transaction

Webhooks can either be created from a template in the Admin console, or custom attached to each transaction call from the Merchant shop. When creating custom Webhooks you define it using JSON described in the examples below:

Sending E-mail:

{"trigger":"payment_success","email":"myname@domain.com"}

Custom HTTP:

{"url":"https://mybackend.com/confirmOrderFromNordeaConnect","trigger":"payment_success","http_method":"post","data_format":"form_data"}

Or as an Array:

[{"trigger":"payment_success","email":"myname@domain.com"},{"url":"https://mybackend.com/confirmOrderFromNordeaConnect","trigger":"payment_success","http_method":"post","data_format":"form_data"}]

trigger can be:

  • payment_success – (after a successful transaction, data sent: a transaction object)
  • payment_error – (after a failed transaction, data sent: a transaction object)
  • payment_form – (when an hosted window is loaded, data sent: a transaction object)
  • payment – (after any transaction regardless of status, data sent: a transaction object)
  • refund – (after a refund, data sent: a transaction object)
  • subscription_started – (when a new subscription is created, data sent: a subscription object)
  • card_stored – (when a new card is stored, data sent: a stored_card object)
  • card_updated – (when a card is updated, data sent: a stored_card object)
  • webhook_exhausted – (when a Webhook didn’t reach it’s destination after retries, data sent: a webhook object)
  • change_address – (after a shipping address is changed, data sent: a transaction object)
  • none – (manual execution in the Nordea Connect Rule Engine)

http_method can be:

  • post
  • get
  • put
  • patch
  • delete

data_format can be:

  • json
  • xml
  • form_data

Important

Custom http webhooks will not follow redirects. Make sure to point them directly at your endpoint.

If you are using the https protocol, your SSL certificate must be valid for the webhook to work.

If the webhook encounters a “500 error” from your endpoint it will retry 20 times for approximately 2 days. If it doesn’t succeed during this timeframe you will receive a warning in the dashboard. Any other error will create a notification in the dashboard immediately.

NOTE: When notifications are created in the dashboard you will also be receiving an alert email. Opt-out is possible by unchecking “Get Email Alerts” in Settings > Administrators.

  • ruby
  • php
  • net
file to be uploaded
//Fetching the incoming transaction data
      
      $transaction = webhook::get($path);
// Fetches and parses the incoming transaction.
      // This example is coming from a WebAPI Post action and uses the ControllerContext for data
      
      var transaction = Webhook.GetWebhook(this.ControllerContext.Request);

Automatic job retry

Webhooks will retry failures up to 20 times, with an exponential backoff using the formula (retry_count ** 4) + 15 + (rand(30) * (retry_count + 1)) (i.e. 15, 16, 31, 96, 271, … seconds + a random amount of time).

It will perform 20 retries over approximately 3 days. Assuming you deploy a bug fix within that time, the job will get retried and successfully processed. After 20 times, Webhooks will move that job to the Dead Job queue, and create a notification on the Merchant dashboard.

Liquid and Receipt Webhooks

Liquid is an open-source, Ruby-based template language created by Shopify. It is a well-known framework and is used to load dynamic content on storefronts.

Liquid uses a combination of tags, objects, and filters to load dynamic content. They are used inside the Nordea Connect Payment Window payment form to display information from the payment data and make the template dynamic for each customer, product or transaction.

The official documentation can be found here: https://github.com/Shopify/liquid/wiki/Liquid-for-Designers

You can output information in your receipt Webhook using Liquid syntax. Using the example above, this is the way to output it:

Product name: {{ transaction.metadata['products'].first.name }}
      Product quantity: {{ transaction.metadata['products'].first.qty }}  %p To loop all products:
{%for item in transaction.metadata['products']%}
        <li>
          Name: {{ item['name'] }},
          Price: {{ item['price'] }} {{transaction.amount | upcase }},
          Quantity {{ item['qty'] }}
        </li>
      {% endfor %}  %strong For Refunds

You can send a refund confirmation using the After Refund event with the Receipt webhook. There you can output the refunded amount like this:

Hi, here is your refund confirmation for order:
      {{ transaction.payment_ref }}
      Amount:
      {{ transaction.refunds.last.amount }}
      Reason:
      {{ transaction.refunds.last.reason }}
      

Items

Items makes it possible to send product info about the items into a payment. This items array is required for invoice payments and can also be used in subscriptions to add additional product charges intop of the Plan amount.

This data is required if the transaction is of type invoice

artnostring (maxlength 50) *required Article number
descriptionstring (maxlength 150) *required Description about the item
amountinteger *required The total price of all the items
qtystring *required The item quantity
vatstring *required VAT rate, ex 25 (No verification or or calculation is made)
discountstringDiscount of the products (No verification or or calculation is made)

Example

[{"artno": "001", "amount": 1, "description": "user license2", "qty": 1, "vat": 25, "discount": 0}]

Testing cards & Swish

Card payments and Swish payments feature a mock flow, where you either land on the success url or error url, depending on e.g. the CVC code used for card payments. Please note that the card payments flow does not include the 3DS step, which is present in production.

For Swish, you can enter any 10-digit number starting with 07 to simulate a successful transaction.

All accounts registered through nordeaconnect.com feature card payments and Swish by default.

To create test transactions you need to send in a test card number, and also a CVV code that can simulate different responses.

Test card numbers:

VISA4111111111111111
VISA4012888888881881
VISA4222222222222
MASTERCARD5555555555554444
MASTERCARD5105105105105100
DINERS30569309025904
AMEX378282246310005

Test CVV codes:

When in test mode (test=true) you can use CVV codes to simulate different responses. Anything else will lead to Approved.

200ACCEPTED
201DECLINED
202CVV INVALID
203EXPIRED

Test expiry dates:

When in test mode (test=true) you can use specific expiry dates to simulate failed recurring card payments.

0137errors.payment.declined
0237errors.card.expired

More information

TLS

TLS 1.0 was released in 1999, making it a nearly two-decade-old protocol. It has been known to be vulnerable to attacks—such as BEAST and POODLE—for years, in addition to supporting weak cryptography, which doesn’t keep modern-day connections sufficiently secure. TLS 1.0 and SSL are deprecated since June 30 2018.

Examples:

  • .NET: System.Net.ServicePointManager.SecurityProtocol = SecurityProtocolType.Tls12;
  • PHP: curl_setopt ($setuploginurl, CURLOPT_SSLVERSION, 6);
  • Ruby: ctx.ssl_version = :TLSv1_2
  • Curl: curl --tlsv1.2 https://api.nordeaconnect.com/v1/transactions
  • JS: secureProtocol: "TLSv1_2_method"

3D-Secure

Nordea Connect understands the need to incorporate best business practices in security. That’s why we’ve made it easy for Merchants to implement 3D Secure or “3 Domain Secure” as the industry standard identity check solution to minimize chargebacks from fraudulent credit cards, all included in our simple pricing. 3D-Secure refers to second authentication factor products such as Verified by Visa, MastercardⓇSecureCode™ and American Express SafekeyⓇ.

NOTE: While you can create your own payment experience, We strongly recommend using our Payment Window solution to save time in implementing 3D-Secure and client side encryption to your checkout procedure.

Important note on API Card Payments

In order to process card payments either by storing or transfer without storing, you would need full PCI DSS compliance.

Please make use of the stored cards functionality to facilitate API based card payments.

Supported card types

Where are they used?

You need to POST the card type name as card_type parameter

Default card types that you will have access to are VISA and Mastercard, but the other such as AMEX, JCB and Diners are on separate contracts. Contact support for more information about card types.

visaVisa
mastercardMasterCard
maestroMaestro
electronElectron
debit_mastercardDebit MasterCard
visa_debitVisa Debit
amexAmerican Express
dinersDiners
uk_maestroUK Maestro
stored_cardStored Card
paypalPayPal
swishSwish

Accepted currencies

sekSwedish Krona
cadCanadian Dollar
cnyChinese Yuan
copColombian Peso
czkCzech Republic Koruna
dkkDanish Krone
hkdHong Kong Dollar
hufHungarian Forint
iskIcelandic Króna
inrIndian Rupee
ilsIsraeli New Sheqel
jpyJapanese Yen
kesKenyan Shilling
krwSouth Korean Won
kwdKuwaiti Dinar
lvlLatvian Lats
myrMalaysian Ringgit
mxnMexican Peso
madMoroccan Dirham
omrOmani Rial
nzdNew Zealand Dollar
nokNorwegian Krone
pabPanamanian Balboa
qarQatari Rial
rubRussian Ruble
sarSaudi Riyal
sgdSingapore Dollar
zarSouth African Rand
chfSwiss Franc
thbThai Baht
ttdTrinidad and Tobago Dollar
aedUnited Arab Emirates Dirham
gbpBritish Pound Sterling
usdUS Dollar
twdNew Taiwan Dollar
vefVenezuelan Bolívar
ronRomanian Leu
tryTurkish Lira
eurEuro
uahUkrainian Hryvnia
plnPolish Zloty
brlBrazilian Real

Error messages

We aim to send as many insightful and helpful error messages to you as possible, both in numeric, data and human readable.

{
        name: 'errors.card_number.missing',
        code: 118,
        description: 'Card number is missing'
      }

Simulate errors:

To simulate error messages send this json in your metadata. Use one of the following formats:

{
        "nordeaconnect_instructions": {
          "fail_as_code":"errors.invoice.address_not_found"
         }
      }
      
{
        "nordeaconnect_instructions": {
          "fail_as_message":"do not honour"
        }
      }

List of error messages:

Error Code  Technical Error CodeDescription
1errors.credit_card.missingCredit card is missing
2errors.credit_card_details.missingCredit card details are missing
3errors.terminal_id.invalidTerminal ID is invalid
4errors.provider_ref.processedProvider reference processed
209errors.ssn_or_country.missingThe country is missing
211errors.missing_or_invalid.ssnSSN error – missing SSN or invalid format
212errors.missing_or_too_long.first_nameFirst Name error – missing first name or first name too long
213errors.missing_or_too_long.last_nameLast Name error – missing last name or last name too long
214errors.invalid.emailE-mail error – invalid e-mail format
215errors.missing_or_invalid.phone_numberCell phone number error – cell phone number missing or invalid characters
216errors.missing_or_too_long.address_1Address line 1 error – missing address or address line 1 too long
217errors.missing.address_2Address line 2 error – address line 2 too long
218errors.missing_or_too_long.cityCity error – city is missing or value too long
219errors.missing_or_too_long.zip_codeZip code error – zip code missing or value too long
220errors.missing_or_invalid.country_codeCountry code error – missing or invalid country code
221errors.missing_or_invalid.amount_errorAmount error – missing amount or invalid value
222errors.too_long.transaction_idTransaction id error – value is too long
223errors.must_be_submitted.ssnSSN must be submitted
224errors.invoice.credit_approval_failedCredit approval failed
225errors.invoice.credit_checkCredit check (SSN not found)
226errors.invoice.credit_not_approvedCredit not approved
227errors.invoice.amount.requested.lower_than_minimum_purchase_amountAmount requested is lower than minimum purchase amount
228errors.invoice.amount.requested.higher_than_maximum_purchase_amountAmount requested is higher than maximum purchase amount
229errors.invoice.amount.maximal_decimalAmount value can have maximal {0} decimal places
230errors.invoice.item.maximal_decimalItem amount value can have maximal {0} decimal places
231errors.item.total_amount_errorTotal amount error – the total amount of items must be higher than zero
232errors.item.notes_to_longNotes error – notes for an item is too long
233errors.missing_or_too_long.order_referenceOrder reference error – missing order reference or it is too long
234errors.invoice.account_errorAccount class error – missing account class or invalid account class value
235errors.invoice.account_class_errorAccount Class error – specified AccountNumber has a different AccountClas / Account class error – missing account class or invalid account class value / Account class error – specified account class does not exist
236errors.order.reference.errorOrder reference error – missing order reference or it is too long
237errors.invoice.credit_decision_process_failedCredit decision process failed
238errors.helper.ssn.invalid_formatSSN error – invalid format
239errors.helper.ssn.must_be_submittedSSN must be submitted
240errors.helper.ssn.for_sweden_must_be_12_digitsSSN for Sweden must be 12 digits
241errors.helper.ssn.address_is_availableNot available – SSN is valid but no address is available
242errors.helper.ssn.have_a_valueAccount number or SSN must have a value
243errors.service_not_availableService not available for the specified country
244errors.invoice.no_account_existsNo account exists – use Approve Invoice/Loan first
245errors.invoice.purchase_for_different_countryYou are trying to make a purchase for different country, than what is assigned to branch market
246errors.invoice.payment_terms_errorPayment terms error – specified payment terms code does not exist
247errors.invoice.account_number_errorAccount number error – invalid value
248errors.invoice.account_was_overdrawnMax. amount for the account was overdrawn
249errors.invoice.execute.against.this.accountCannot execute return against this account
250errors.password_lengthPassword length must be at least 6 characters
251errors.customer_not_foundCustomer not found! Probably due to customer with SSN = {0} is not client of {1}
252errors.request.json_errorAPI request error
253errors.request.bad_formatBad format of request data. For example, the data is not in valid JSON format.
254errors.items.not_arrayItems is not an array
255errors.items.description_missingItem description is missing
256errors.items.notes_missingItems notes is missing
257errors.items.amount_missingAmount is missing
258errors.items.description_too_longItems description is too long
259errors.items.amount_not_validItems amount is not valid
260errors.items.transaction_amount_mismatchItems total amounts does not match transaction amount
261errors.rules_parser.declinedDeclined by rule engine. For example, if you have implemented a specific rule to accept e.g. only debit cards, the rule engine will decline all credit cards with this error code
262errors.request.json_errorsSomething is wrong with the JSON object
263errors.invoice.denied_to_purchaseCustomers are blocked for purchases by collector, please contact collector for more information.
264errors.invoice.credit_check_deniedThe credit check is not approved
265errors.invoice.address_not_foundAddress cannot be found for the specified customer
266errors.invoice.reservation_not_approvedReservation is not approved
267errors.invoice.invalid_registration_numberRegistration number is not in a correct format
268errors.invoice.agreement_rules_validation_failedSomething with the use of the API is against the agreement with collector, please contact collector for information.
269errors.invoice.unhandled_exceptionIf an unhandled error occurs, an unhandled exception will be thrown. In cases of these errors contact collector for help
270errors.invoice.purchase_amount_greater_than_max_credit_amountThe total amount of an invoice or reservation cannot be greater than your maximum credit limit or the maximum credit limit for the country the purchase is made in
271errors.invoice.activation_of_invoice_deniedActivation of an invoice is denied
274errors.invoice.article_not_foundAn article cannot be found. Both article id and description specified must be the same that was used during AddInvoice. If more than one article with the same article id but different unit price is added to the invoice, the unit price of the article must be specified.
275errors.invoice.article_not_found_based_on_unitpriceCannot locate the specified article based on the specified unit price. Make sure an article with the specified unit price exists
276errors.invoice.authorization_failedCould not authorize the request, check your login credentials. Please contact the collector for more help
277errors.invoice.countrycode_mismatch_with_customer_addressThe specified country code for the customer’s address doesn’t match the country code specified in the (base) request
278errors.invoice.countrycode_mismatch_with_delivery_addressThe specified country code for the customer’s delivery address doesn’t match the country code specified in the (base) request
279errors.invoice.countrycode_mismatch_with_invoice_addressThe specified country code for the customer’s invoice address doesn’t match the country code specified in the (base) request
282errors.invoice.email_is_missingThe delivery method was set to email but the email field was not present in the request
283errors.invoice.invalid_countrycodeCan be thrown when you try to request an address from another country than the one you are registered in
284errors.invoice.invalid_credit_time_usageCredit time cannot be used for the specific invoice type
285errors.invoice.invalid_currency_codeThe specified currency cannot be used. This exception can be thrown if you are registered in a country where the specified currency is not allowed to be used
286errors.invoice.invalid_delivery_address_usagePrivate customers aren’t allowed to have different invoice addresses and deliver addresses, they must be the same
287errors.invoice.invalid_invoice_statusA pending invoice cannot be cancelled based on the stage it is in
288errors.invoice.invalid_product_codeThe product code cannot be found or the product is inactive
289errors.invoice.invalid_quantityThe quantity of an article is too low or too high compared to the quantity or quantity left on the article
291errors.invoice.invalid_transaction_amountThe amount may exceeds the total invoice amount, or the number of decimals has more than two digits after decimal (Can only have two digits after decimal)
292errors.invoice.invoice_duedate_already_extendedThe due date of the invoice has already been extended
293errors.invoice.invoice_exceeds_available_reservationThe purchase sum of the invoice exceeds the available reservation amount
294errors.invoice.invoice_extended_date_in_pastAttempting to extend due date by specifying a date in the past
295errors.invoice.invoice_invalid_typeInvoice may be of the wrong type, some actions are not allowed to be performed on specific invoices. For example, you cannot extend the due date on an invoice that is not a direct invoice (delivered in the package)
296errors.invoice.invoice_not_foundWhen the specified invoice number cannot be found. When trying to credit an invoice the invoice is already credited or not activated
297errors.invoice.invoice_type_is_not_allowed_to_be_usedYou aren’t allowed to use the specified invoice type
298errors.invoice.mixed_currencyThe article’s currency doesn’t match the currency on the invoice
299errors.invoice.mobile_phone_is_missingThe mobile phone is missing, which is needed because of the chosen notification type
300errors.invoice.not_allowed_to_send_notification_by_emailYou aren’t allowed to send the specific invoice type by email
301errors.invoice.not_allowed_to_send_notification_by_mailYou aren’t allowed to send the specific invoice type by postal mail
303errors.invoice.purchase_not_foundAn invoice cannot be found
305errors.invoice.reservation_not_foundThere was no reservation for the specified customer
306errors.invoice.total_amount_must_be_positiveThe amount of an invoice must be positive
308errors.invoice.unique_article_not_foundWhen an article with the same article id is found several times but has different unit prices. The unit price must be specified also to locate the specific article
309errors.invoice.validation_activation_option_valueThe Activation Option field was not one of its allowed values
310errors.invoice.validation_address1_lengthThe Address 1 field was too long
311errors.invoice.validation_address2_lengthThe Address 2 field was too long
312errors.invoice.validation_amount_parsingThe unit price or other kinds of amount fields could not be parsed. Make sure the amount is a decimal value and the number of decimals do not have more than two digits after decimal (Can only have two digits after decimal)
313errors.invoice.validation_amount_rangeThe amount field was not within its allowed range
314errors.invoice.validation_amount_requiredThe amount field was not present in the request
315 errors.invoice.validation_article_id_lengthThe ArticleId field was too long
316errors.invoice.validation_article_id_requiredAn article is missing the ArticleId
317errors.invoice.validation_article_list_requiredThe ArticleList field was not present in the request
318errors.invoice.validation_cell_phone_number_lengthThe CellPhoneNumber field was too long
319errors.invoice.validation_city_lengthThe City field was too long
320errors.invoice.validation_city_requiredThe City field was not present in the request
321errors.invoice.validation_client_ip_address_lengthThe ClientIpAddress field was too long
322errors.invoice.validation_client_ip_address_requiredThe ClientIpAddress field was not present in the request
323errors.invoice.validation_coaddress_lengthThe CoAddress field was too long
324errors.invoice.validation_company_name_lengthThe CompanyName field was too long
325errors.invoice.validation_cost_center_lengthThe CostCenter field was too long
326errors.invoice.validation_country_code_lengthThe CountryCode field was too long
327errors.invoice.validation_country_code_requiredThe CountryCode field was not present in the request
328errors.invoice.validation_credit_date_requiredThe CreditDate field was not present in the request
329errors.invoice.validation_credit_time_out_of_rangeCredit time is out of range, can only be between 0 and 99
330errors.invoice.validation_currency_lengthThe Currency field was too long
331errors.invoice.validation_currency_invalidThe specified currency may not be supported or is of an incorrect format (ISO 4217). Currency need to be at least three characters long and follow ISO 4217, e.g.SEK, DKK, NOK and EUR etc
332errors.invoice.validation_currency_requiredThe Currency field was not present in the request
333errors.invoice.validation_customer_number_lengthThe CustomerNumber field was too long
334errors.invoice.validation_delivery_address_requiredThe DeliveryAddress field was not present in the request
335errors.invoice.validation_description_lengthThe Description field was too long
336errors.invoice.validation_email_invalidThe e-mail address is not a valid e-mail address
337errors.invoice.validation_email_lengthThe Email field was too long. Can only be a maximum of 256 characters
338errors.invoice.validation_errorInput data is not correct
339errors.invoice.validation_first_name_lengthThe FirstName field was too long
340errors.invoice.validation_gender_valueThe Gender field was not one of its allowed values
341errors.invoice.validation_invoice_address_requiredThe InvoiceAddress field was not present in the request
342errors.invoice.validation_invoice_delivery_method_valueThe InvoiceDeliveryMethod field was not one of its allowed values
343errors.invoice.validation_invoice_number_lengthThe InvoiceNo field was too long
344errors.invoice.validation_invoice_number_requiredThe InvoiceNo field was not present in the request
345errors.invoice.validation_invoice_type_valueThe InvoiceType field was not one of its allowed values
346errors.invoice.validation_last_name_lengthThe LastName field was too long
347errors.invoice.validation_order_date_requiredThe OrderDate field was not present in the request
348errors.invoice.validation_order_number_lengthThe OrderNo field was too long
349errors.invoice.validation_password_requiredThe Password field was not present in the request.
350errors.invoice.validation_phone_number_lengthThe PhoneNumber field was too long
351errors.invoice.validation_postal_code_lengthThe PostalCode field was too long
352errors.invoice.validation_postal_code_requiredThe PostalCode field was not present in the request
353errors.invoice.validation_quantity_rangeThe Quantity field was not within its allowed range
354errors.invoice.validation_quantity_requiredAn article is missing its Quantity
355errors.invoice.validation_reference_lengthThe Reference field was too long
356errors.invoice.validation_registration_number_lengthThe RegNo field was too long
357errors.invoice.validation_registration_number_requiredThe RegNo field was not present in the request
358errors.invoice.validation_reserved_amount_parsingThe ReservedAmount field could not be parsed
359errors.invoice.validation_reserved_amount_rangeThe ReservedAmount field was not within its allowed range
360errors.invoice.validation_reserved_amount_requiredThe ReservedAmount field was not present in the request
361errors.invoice.validation_unit_price_parsingThe UnitPrice field could not be parsed
362errors.invoice.validation_unit_price_rangeThe UnitPrice field was not within its allowed range
363errors.invoice.validation_username_requiredThe Username field was not present in the request
364errors.invoice.validation_vat_parsingThe Vat field could not be parsed
365errors.invoice.validation_vat_rangeThe Vat field was not within its allowed range
366errors.invoice.validation_vat_requiredThe Vat field was not present in the request
367errors.invoice.article_exists_but_other_informationArticle can’t be added because an existing article exists but with another VAT
368errors.invoice.customer_purchase_progressA simultaneous purchase is already being processed for the customer
400errors.stored_card.expires.missingStored card expiration date missing
2084errors.trustly.message_id_duplicateMessage id duplicate
2085errors.trustly.invalid_credentialsCredentials are invalid
2086errors.trustly.malformed_notificationurlThe NotificationURL sent in the request is malformed. It must be a valid http(s) address
2087errors.trustly.invalid_ipThe IP attribute sent is invalid. Only one IP address can be sent
2088errors.trustly.insufficient_fundsThe merchant does not have enough balance on his/her Trustly account to execute the refund
2089errors.trustly.disabled_userThe user account is disabled
2090errors.ssn_token.failedSSN token failed
2091errors.metadata.invalidMetadata is invalid
2301errors.item.missing_or_too_long.descriptionDescription error – the description of an item is missing or is too long
2502errors.items.vat_missingItem vat is missing or not valid
2503errors.items.artno_missingItem artno is missing
2511errors.items.qty_missingItem quantity is missing or not valid
2512errors.items.notes_too_longItems notes are too long
2610errors.rules_parser.skip_webhookRule parsers are skipped
4001errors.stored_card.store.declinedCard could not be stored
4002errors.stored_card.token.invalidStored card token is invalid

Language

The API supports responses in Swedish and English so if you specify locale=sv or locale=en either as a parameter that you send in or int the query you will receive error messages in the desired language.

FAQ

Looking for an answer to your question?
Head over to our Help Centre for more detailed frequently asked questions.

  • Payment through API
    • Authentication
    • HTTP Response Codes
    • Object Graph
  • Default parameters
    • Payment using card details
      • Example
    • Payment using tokenized card
      • Additional mandatory parameters
      • Example
    • Swish payment
      • Transaction
        • Optional parameters to send
        • Hash calculation
        • Update Transaction
        • Transaction object
        • Encryption
      • Transaction statuses
        • Pagination
          • Filtering
            • Subscription payment
              • Get started
              • Example
            • Metadata
              • Webhooks
                • Items
                  • Testing cards & Swish
                    • More information
                      • TLS
                      • Supported card types
                      • Accepted currencies
                      • Error messages
                      • Language
                    • FAQ
                      C
                      • Company
                        • Contact
                        • Privacy Policy
                        • Accessibility Statement
                        • Terms of service
                        • Cookies
                      • Solutions
                        • Nordea Connect Checkout
                        • Payment Window
                        • API
                        • Prices
                      • Resources
                        • Documentation
                        • Plugins & SDKs
                        • Status page
                        • Help Center
                      • Get started now!
                      Nordea Connect Logo in white font

                      Home  -  Resources  -  Documentation  -  Payment through API

                      © 2021 Nordea Bank Oyj, Satamaradankatu 5, 00020
                      NORDEA, Helsinki. Y-tunnus: 2858394-9, BIC: NDEAFIHH
                      +46 771 404445
                      nc.support@nordea.com
                      sitemap.xml