Nordea Connect API documentation

API

Here you will find the documentation related to API management, i.e. being able to manage and retrieve data related to transactions and recurring payments. To process transactions, please visit our Payment Window & Nordea Connect Checkout documentation.

Nordea Connect requires TLS 1.2 or above to access the API.

All the documentation below is usable for merchants who are not directly PCI DSS compliant – if you are looking to collect and process card details directly, please contact our integration team (psp[a]nordea.com).

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 password can be set in the admin console: 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.

Transaction

Through the API you can display one (show transaction) or several transactions (list transactions) as well as update an existing transaction, which has not been processed.

Show Transaction

To show a transaction you need to do a GET to https://api.nordeaconnect.com/v1/transactions/[transactionID]

curl
ruby
php
net

EXAMPLE REQUEST
      
      curl --user 3:password https://api.nordeaconnect.com/v1/transactions/443
      
      EXAMPLE RESPONSE
      
      {
        "amount" : "480.0",
        "card_holder" : "Anna Andersson",
        "card_number" : "*****************1111",
        "card_type" : "VISA",
        "cost" : { "fixed_fee" : 0,
          "percentual_exchange_fee" : 0,
          "percentual_fee" : 0,
          "total" : "0.0"
        },
        "created_at" : "2018-12-17T13:41:07Z",
        "currency" : "SEK",
        "customer" : null,
        "error" : null,
        "error_url" : "https://nordeaconnect.com/payment-error",
        "id" : 443,
        "merchant_id" : 3,
        "metadata" : {
          "products" : [ "awesomeness","coolness"],
          "user" : { "email" : "justmyemail@nordeaconnect.com"}
        },
        "payment_ref" : null,
        "ref" : null,
        "refunds" : [  ],
        "status" : "approved",
        "stored_card" : null,
        "subscription" : null,
        "success_url" : "https://nordeaconnect.com/payment-ok?status=A",
        "template_id" : 10,
        "test" : false,
        "transaction_type" : null,
        "webhooks" : [  ]
      }

EXAMPLE REQUEST
      
      transaction = NordeaConnect::CreditCard::Transaction.get(8176)
      
      EXAMPLE RESPONSE
      
      [{"title"=>"T-shirt"}, {"title"=>"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"=>"0.025", "fixed_fee"=>"2.5", "percentual_exchange_fee"=>"0.035", "total"=>"46.0"},
        @stored_card=nil,
        @customer={"id"=>3052},
        @subscription=nil>

EXAMPLE REQUEST
      
      $transaction = nordeaconnect\api\transaction::get(443);
      
      EXAMPLE RESPONSE
      
      Array
      (
      [id] => 443
      [created_at] => 2018-12-17T13:41:07Z
      [merchant_id] => 3
      [amount] => 480.0
      [payment_ref] =>
        [ref] =>
        [card_holder] => Anna Andersson
      [card_number] => *****************1111
      [test] =>
        [metadata] => Array
      (
      [user] => Array
      (
      [email] => justmyemail@nordeaconnect.com
      )
      
      [products] => Array
      (
      [0] => awesomeness
      [1] => coolness
      )
      
      )
      
      [currency] => SEK
      [status] => approved
      [card_type] => VISA
      [transaction_type] =>
        [template_id] => 10
      [error] =>
        [cost] => Array
      (
      [percentual_fee] => 0
      [fixed_fee] => 0
      [percentual_exchange_fee] => 0
      [total] => 0.0
      )
      
      [success_url] => https://nordeaconnect.com/payment-ok?status=A
      [error_url] => https://nordeaconnect.com/payment-error
      [stored_card] =>
        [customer] =>
        [subscription] =>
        [refunds] => Array
      (
      )
      
      [webhooks] => Array
      (
      )
      
      )

EXAMPLE REQUEST
      
      curl --user 3:password https://api.nordeaconnect.com/v1/transactions/443
      
      EXAMPLE RESPONSE
      
      {
        "amount" : "480.0",
        "card_holder" : "Anna Andersson",
        "card_number" : "*****************1111",
        "card_type" : "VISA",
        "cost" : { "fixed_fee" : 0,
          "percentual_exchange_fee" : 0,
          "percentual_fee" : 0,
          "total" : "0.0"
        },
        "created_at" : "2018-12-17T13:41:07Z",
        "currency" : "SEK",
        "customer" : null,
        "error" : null,
        "error_url" : "https://nordeaconnect.com/payment-error",
        "id" : 443,
        "merchant_id" : 3,
        "metadata" : {
          "products" : [ "awesomeness","coolness"],
          "user" : { "email" : "justmyemail@nordeaconnect.com"}
        },
        "payment_ref" : null,
        "ref" : null,
        "refunds" : [  ],
        "status" : "approved",
        "stored_card" : null,
        "subscription" : null,
        "success_url" : "https://nordeaconnect.com/payment-ok?status=A",
        "template_id" : 10,
        "test" : false,
        "transaction_type" : null,
        "webhooks" : [  ]
      }

To list transactions you need to do a GET to https://api.nordeaconnect.com/v1/transactions that will return a list of your transactions. The default limit is 10.

To get transactions for a specific customer: GET to: https://api.nordeaconnect.com/v1/customers/[customerID]/transactions

To get transactions for a specific subscription: GET to: https://api.nordeaconnect.com/v1/subscriptions/[subscriptionID]/transactions

Transactions support filters on: amount, card_holder, card_number, card_type, created_at, currency, customer_id, error_url, href_token, id, payment_ref, status, stored_card_id, subscription_id, success_url, template_id, test, transaction_type and updated_at.

EXAMPLE REQUEST
      
      curl -X GET --user 3:custom00 'https://api.nordeaconnect.com/v1/transactions?limit=2&offset=1'
      
      EXAMPLE RESPONSE
      
      [
        {
          "amount" : "1.0",
          "card_holder" : "Anna Andersson",
          "card_number" : "411111******1111",
          "card_type" : "VISA",
          "cost" : {
            "fixed_fee" : "2.5",
            "percentual_exchange_fee" : "0.035",
            "percentual_fee" : "0.025",
            "total" : "2.56"
          },
          "created_at" : "2018-07-22T16:42:10Z",
          "currency" : "eur",
          "customer" : null,
          "error" : null,
          "error_url" : null,
          "id" : 6643,
          "merchant_id" : 3,
          "metadata" : {
            "products" : [ {
              "id" : "1",
              "name" : "Nice Shoe",
              "price" : "1.00",
              "qty" : "1",
              "url" : "http://mysite.com/product/1"
            } ],
            "user" : { "email" : "jd@email.com" }
          },
          "payment_ref" : "1785",
          "ref" : null,
          "refunds" : [  ],
          "status" : "approved",
          "stored_card" : null,
          "subscription" : null,
          "success_url" : null,
          "template_id" : null,
          "test" : true,
          "transaction_type" : "credit_card",
          "webhooks" : [ {
            "created_at" : "2018-07-22T16:42:10Z",
            "data_format" : null,
            "email" : "info@nordeaconnect.com",
            "http_method" : null,
            "id" : 18031,
            "response" : null,
            "trigger" : "payment",
            "type" : "Email",
            "url" : null
          } ]
        },
        {...}
      ]

# EXAMPLE REQUEST
      
      transactions = NordeaConnect::CreditCard::Transaction.all(limit: 2, offset: 4)
      
      
      # EXAMPLE RESPONSE
      
      [
        [{"title"=>"T-shirt"}, {"title"=>"Shoes"}]},
          @currency="sek",
          @status="approved",
          @card_type="VISA",
          @transaction_type="credit_card",
          @cost={"percentual_fee"=>"0.025", "fixed_fee"=>"2.5", "percentual_exchange_fee"=>"0.035", "total"=>"46.0"},
          @stored_card=nil,
          @customer={"id"=>3052},
          @subscription=nil>,
        [{"title"=>"T-shirt"}, {"title"=>"Shoes"}]},
          @currency="sek",
          @status="approved",
          @card_type="VISA",
          @transaction_type="credit_card",
          @cost={"percentual_fee"=>"0.025", "fixed_fee"=>"2.5", "percentual_exchange_fee"=>"0.035", "total"=>"46.0"},
          @stored_card=nil,
          @customer={"id"=>3052},
          @subscription=nil>
      ]

EXAMPLE REQUEST
      
      $transaction = nordeaconnect\api\transaction::index(10,0);
      
      EXAMPLE RESPONSE
      
      Array
      (
        [0] => Array
        (
          [id] => 7541
          [created_at] => 2018-08-04T19:54:43Z
          [merchant_id] => 3
          [amount] => 10.0
          [payment_ref] => 56203
          [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] =>
          [customer] =>
          [subscription] =>
          [refunds] => Array
          (
          )
      
          [webhooks] => Array
          (
          )
        )
      )
      ...

EXAMPLE REQUEST
      
      var transactions = Transaction.List(3,0);
      
      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:39:47.2978516Z",
          "currency" : "eur",
          "customer" : null,
          "encrypted" : null,
          "error" : null,
          "error_url" : null,
          "id" : 1,
          "merchant_id" : 0,
          "metadata" : null,
          "payment_ref" : "123",
          "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
        }...
      ]

Update Transaction

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

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_holder	stringThe name on the charged credit card
card_number	stringA card number ex. 41111111111111
card_cvv	stringCVV code
card_expiry	stringExpiration date of the credit card in the format MMYY
currency	stringThe 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_type	stringVISA, MASTERCARD, STORED_CARD (if the transaction is done using a stored card), etc
encrypted	stringA comma separated string for the params that you send encrypted. Ex. “card_number,card_cvv”
items	Array of items objectsItems
metadata	objectMetadata
amount	decimalThe transaction amount ex. 12.00
vat_amount	decimalThe VAT amount for the transaction ex. 3.00
customer_ref	stringThe Merchant specific user/customer ID
process	booleanShould 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:

id	integerId of the transaction
created_at	datetimeEx. 2018-04-25T10:20:48Z (UTC)
merchant_id	stringID of Merchant
amount	decimalThe transaction amount ex. 12.00
vat_amount	decimalThe vat amount for the transaction ex. 3.00
payment_ref	stringThe Merchant order/payment ID
card_holder	stringThe name on the charged credit card
card_number	stringA masked card number ex. 411111****1111
card_expiry	stringMMYY ex. 0120
test	booleanWhether the transaction is a test transaction.
currency	stringThe 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)
status	stringStatus of the api transaction. pending – created but not yet processed approved authorized declined failed
card_type	stringVISA, MASTERCARD, etc. (STORED_CARD if the transaction is done with stored card)
payment_request	objectThe payment request from the Merchant
template_id	intHosted Page template ID
error	objectFor example: `error: { name: 'errors.card_number.missing', code: 118, description: 'Card number is missing' }`
cost	objectThe cost of transaction `{"percentual_fee":0,"fixed_fee":0,"percentual_exchange_fee":0,"total":"0.0", "vat_rate": 0.25}`
success_url	stringURL after successful transaction. Can contain Liquid.
error_url	stringURL after unsuccessful transaction. Can contain Liquid.
metadata	objectMerchant specific Metadata
refund	arrayAn array with refunds objects where the token value is used for making transactions with the stored card
stored_card	objectIf the transaction has a stored card connected it will have a token value that is used for making transactions with the stored card
customer	objectCustomer that owns the transaction
transaction_type	stringcredit_card/stored_card/recurring
subscription	objectThe connected subscription
webhooks	arrayA list of Webhooks related to the transaction
href	stringA HTTP link to a payment page where the customer can finish a payment. Ex. https://pay.nordeaconnect.com/v1/form/hrr5sEwz0y-XgcYOyNXhew
Items	Array of items objectsitems
payment_details	objectpayment_details
payment_method	stringCan be any of the following: credit_card, recurring, stored, invoice, swish, paypal, bank
processed_at	datetimeThe exact time when the payment was confirmed. Ex. 2018-04-25T10:20:48Z (UTC)

Capture

To capture a previously authorized transaction, you need to PUT data to https://api.nordeaconnect.com/v1/transactions/[transactionID]/capture

You can capture a transaction when it has previously been authorized. Authorization is achieved by passing authorize = true when creating a transaction.

The params you can send to capture an authorized transaction:

amount

decimal *required The transaction amount ex. 12.00. Can be lower that the authorized original amount.

Capture works for all card-based payment methods (e.g. Visa/MC, ApplePay, MobilePay).

Refund

Refund through API is supported for all payment methods except AfterPay where the refund is performed on the item level. You can refund either the whole payment or parts of the payment. E-payment only supports one refund (partial or whole).

The refund object consists of the following params:

id	intThe refund ID
created_at	datetimeEx. 2018-04-25T10:20:48Z (UTC)
amount	decimalThe refunded amount
reason	stringThe reason for refunding the card holder
transaction	objectThe connected transaction object

Create Refund

To create a refund you need to POST to the url https://api.nordeaconnect.com/v1/refunds.

Parameters to send:

transaction_id	int *required ID for the transaction to refund
amount	decimal *required The amount to refund. E.g. “5.00”
reason	string *required The reason for the refund. E.g. “Cancelled order”

Create Refund Example

curl
ruby
php
.NET

EXAMPLE REQUEST
      
      curl -X POST --data "transaction_id=7510&amount=5.00&reason=cancelled%20order" --user 3:password 'https://api.nordeaconnect.com/v1/refunds'
      
      EXAMPLE RESPONSE
      
      {
        "amount" : "5.0",
        "reason" : "test",
        "ref" : null,
        "id" : 49,
        "created_at" : "2018-08-04T18:04:21Z",
        "transaction" : {
          "id" : 7510
        }
      }

# REQUEST EXAMPLE
      
          attributes = {
            transaction_id: 8176,
            amount: '725.00',
            reason: 'Customer cancelled order'
          }
      
          refund = NordeaConnect::CreditCard::Refund.create(attributes)
      
      # RESPONSE EXAMPLE
      
      8176}>

EXAMPLE REQUEST
      
      $data = array(
        "transaction_id" => "1",
        "amount" => "10.00",
        "reason" => "wrong order"
      );
      
      $res = nordeaconnect\api\refund::create($data);
      
      EXAMPLE RESPONSE

EXAMPLE REQUEST
      
      var refdata = DateTimeOffset.Now.Ticks.ToString();
      var postData = new List();
      postData.Add(new KeyValuePair("transaction_id", "1"));
      postData.Add(new KeyValuePair("amount", "1.00"));
      postData.Add(new KeyValuePair("reason", refdata));
      postData.Add(new KeyValuePair("locale", "en"));
      
      var res = Refund.Create(postData);
      
      EXAMPLE RESPONSE
      
      {
        "amount" : "1.00",
        "created_at" : "2018-08-06T17:59:25.756836Z",
        "id" : 100,
        "reason" : "635429519656083985",
        "transaction" : null,
        "transaction_id" : 1
      }

Show Refund

To show a refund you need to GET to the url https://api.nordeaconnect.com/v1/refunds/[transactionID].

Show Refund example

curl
ruby
php
.NET

EXAMPLE REQUEST
      
      curl --user 3:password https://api.nordeaconnect.com/v1/refunds/30
      
      EXAMPLE RESPONSE
      
      {
        "amount" : "171.5",
        "created_at" : "2018-05-21T09:32:40Z",
        "id" : 30,
        "reason" : "Cancelled order",
        "ref" : null,
        "transaction" : { "id" : 1571 }
      }

# REQUEST EXAMPLE
      
      refund = NordeaConnect::CreditCard::Refund.get(493)
      
      # RESPONSE EXAMPLE
      
      8176}>

EXAMPLE REQUEST
      
      $res = nordeaconnect\api\refund::get(1);
      
      EXAMPLE RESPONSE

EXAMPLE REQUEST
      
      var res = Refund.Get(1);
      
      EXAMPLE RESPONSE
      
      {
        "amount" : "10.00",
        "created_at" : "2018-08-06T17:58:02.8828125Z",
        "id" : 1,
        "reason" : "test refund",
        "transaction" : null,
        "transaction_id" : 1
      }

List Refund

To list refunds you need to do a GET to https://api.nordeaconnect.com/v1/refunds that will return a list of your refunds. The default limit is 10. Please note that you will get the ten oldest refunds unless you specify a time range.

You can filter on the following things using these params:

status

approved
pending
failed

For example, filter[status]=approved will list all (default 10) of your approved refunds.

If you are not filtering on status, the API will return refunds regardless of their status.

created_at

For example,

filter[created_at]=20180101..20180131 will fetch refunds created between a certain date
filter[created_at]=..20180131 will fetch refunds up until a certain date
filter[created_at]=20180101.. will fetch refunds starting from a certain date
filter[created_at]=20180930T084821 will fetch refunds matching the exact date/time

amount

filter[amount]=100..1000 will fetch refunds where amount is between 100-1000 (including 100 and 1000)
filter[amount]=..1000 will fetch refunds where amount is less than or equal to 1000 (including 1000)
filter[amount]=100.. will fetch refunds where amount is greater than or equal to 100 (including 100)

reason

filter[reason] will allow you to filter on any reason codes matching the inserted value.
For example, filter[reason]=return order, will return all refunds that match this reason field. With the value * you will get all reason values. If you write for example re* you will get all refund values that start with “re”.

Please note that refunds cannot be filtered by test or live currently. This means that you will get all refunds matching above filtering criteria regardless of if they are test or live transactions.

In the response you will get the test/prod status in transaction object test (true/false):

To fetch more refunds than the default ten, add the param limit to the GET call and specify the amount of refunds you would like (e.g. 1500 / month).

Example

Let’s say we want to get all refunds done in the past month (January 2021):

You will need basic auth (your merchant ID and API password, which you can find in the Nordea Connect Merchant Portal in the Integration tab).

In that case, the GET call would look like this:

https://api.nordeaconnect.com/v1/refunds/?filter[created_at]=20210101..20210131&limit=99999

Broken down, the params would be:

filter[created_at]= 20210101..20210131

limit=99999

The response we get looks like this:

The response includes the following params:

id	Refund ID
created_at	Time when the refund was requested
processed_at	Time when the refund was executed
amount	The refunded amount
reason	The reason for the refund
ref	Not in use
cost	Not in use
status	The status of the transaction
response	The response from the payment system when the refund request is executed
transaction	Transaction includes the transaction object, which the refund is connected to

Tokenize Card

Nordea Connect does not support storing a card through API. To store a card (also called tokenization) you need to create a payment using Nordea Connect’s Payment Window or Checkout solution. The param customer_ref needs to be used to enable stored card.

When a card is stored you can use the provided token and make a token-based transaction for that stored card. Token-based payments use the token as card number and “STORED_CARD” instead of card type (ex. VISA). Stored card can only be used for recurring payments if the token-based transaction is initiated through API.

This is the stored card object:

id	intThe ID of the stored card
created_at	datetimeCreated date (UTC)
token	stringThe unique ID that can be used to make transactions
card_number	stringThe masked version of the credit card number.
currency	stringThe currency code
expires	datetimeEx. 2018-05-31T23:59:59Z (UTC)
merchant_id	intThe Merchant ID
customer	objectCustomer that owns the stored card

Show Tokenized Card

By doing a GET request to https://api.nordeaconnect.com/v1/stored_cards/[transactionID]

curl
ruby
php
net

EXAMPLE REQUEST
      
      curl --user 3:password https://api.nordeaconnect.com/v1/stored_cards/954
      
      EXAMPLE RESPONSE
      
      {
        "card_holder" : "name name",
        "card_number" : "411111******1111",
        "created_at" : "2018-08-04T17:23:05Z",
        "currency" : "SEK",
        "customer" : { "id" : 2923 },
        "expires" : "2018-01-31T23:59:59Z",
        "id" : 954,
        "merchant_id" : 3,
        "ref" : null,
        "status" : "active",
        "test" : true,
        "token" : "31407172985450590"
      }

# EXAMPLE REQUEST
      
      stored_card = NordeaConnect::CreditCard::StoredCard.get(1076)
      
      # RESPONSE EXAMPLE
      
      3073}>

EXAMPLE REQUEST
      
      $stored_card = nordeaconnect\api\stored_card::get(1);
      
      EXAMPLE RESPONSE
      
      Array
      (
        [id] => 1
        [created_at] => 2018-08-05T08:17:50Z
        [token] => 31407226670131682
        [card_holder] => php sdk
        [card_number] => 411111******1111
        [status] => active
        [currency] => EUR
        [expires] => 2018-01-31T23:59:59Z
        [ref] =>
        [merchant_id] => 3
        [test] => 1
        [customer] => Array
        (
          [id] => 2947
        )
      
      )

EXAMPLE REQUEST
      
      var res = StoredCard.Get(1);
      
      EXAMPLE RESPONSE
      
      {
        "card_cvv" : "200",
        "card_holder" : ".net sdk",
        "card_number" : "411111******1111",
        "card_type" : "VISA",
        "created_at" : "2018-08-06T17:45:53.1767579Z",
        "currency" : "eur",
        "customer" : null,
        "customer_id" : 0,
        "customer_ref" : null,
        "encrypted" : null,
        "expires" : "0001-01-01T00:00:00",
        "id" : 1,
        "merchant_id" : 0,
        "status" : "complete",
        "test" : true,
        "token" : "esuyrh9c467bconwenc"
      }

List Tokenized Cards

By doing a GET request to https://api.nordeaconnect.com/v1/stored_cards you will get all stored cards for a Merchant.

You can also get the stored cards for a specific customer by doing a GET to: https://api.nordeaconnect.com/v1/customers/[customerID]/stored_cards

Stored cards support filters on: card_holder, card_number, card_type, created_at, currency, customer_id, expires, id, status, test, token and updated_at.

curl
ruby
php
net

EXAMPLE REQUEST
      
      #All cards for a Merchant:
      curl --user 3:password https://api.nordeaconnect.com/v1/stored_cards
      
      #All cards for a customer:
      curl --user 3:password https://api.nordeaconnect.com/v1/customers/2923/stored_cards
      
      EXAMPLE RESPONSE
      
      [
        {
          "card_holder" : "name name",
          "card_number" : "411111******1111",
          "created_at" : "2018-08-04T17:23:05Z",
          "currency" : "SEK",
          "customer" : { "id" : 2923 },
          "expires" : "2018-01-31T23:59:59Z",
          "id" : 954,
          "merchant_id" : 3,
          "ref" : null,
          "status" : "active",
          "test" : true,
          "token" : "31407172985450590"
        }
      ]

# REQUEST EXAMPLE
      
      stored_cards = NordeaConnect::CreditCard::StoredCard.all(limit: 2, offset: 4)
      
      # RESPONSE EXAMPLE
      
      [
        2513}>,
        2203}>
      ]

EXAMPLE REQUEST
      
      $stored_cards = nordeaconnect\api\stored_card::index(2,0);
      
      EXAMPLE RESPONSE
      
      Array
      (
        [0] => Array
        (
        [id] => 974
        [created_at] => 2018-08-05T08:17:50Z
        [token] => 31407226670131682
        [card_holder] => php sdk
        [card_number] => 411111******1111
        [status] => active
        [currency] => EUR
        [expires] => 2018-01-31T23:59:59Z
        [ref] =>
        [merchant_id] => 3
        [test] => 1
        [customer] => Array
        (
          [id] => 2947
        )
      
      )
      
      [1] => Array
      (
      ...

EXAMPLE REQUEST
      
      var res = StoredCard.List(3,0);
      
      EXAMPLE RESPONSE
      
      [
        {
          "card_cvv" : "200",
          "card_holder" : ".net sdk",
          "card_number" : "411111******1111",
          "card_type" : "VISA",
          "created_at" : "2018-08-06T17:49:46.5722657Z",
          "currency" : "eur",
          "customer" : null,
          "customer_id" : 0,
          "customer_ref" : null,
          "encrypted" : null,
          "expires" : "0001-01-01T00:00:00",
          "id" : 1,
          "merchant_id" : 0,
          "status" : "complete",
          "test" : true,
          "token" : "ksfyw8h467c957"
        }...
      ]

Update Tokenized Card

By doing a PUT request to https://api.nordeaconnect.com/v1/stored_cards/1 you can update the card information.

Parameters to send:

status

string *required active/inactive/deleted

Delete Tokenized Card

To delete a stored card, you need to do a DELETE request to a specific stored card using this URL https://api.nordeaconnect.com/v1/stored_cards/954

curl
ruby
php
net

EXAMPLE REQUEST
      
      curl -X DELETE --user 3:password https://api.nordeaconnect.com/v1/stored_cards/954
      
      EXAMPLE RESPONSE
      
      {
        "card_holder" : "name name",
        "card_number" : "411111******1111",
        "created_at" : "2018-08-04T17:23:05Z",
        "currency" : "SEK",
        "customer" : { "id" : 2923 },
        "expires" : "2018-01-31T23:59:59Z",
        "id" : 954,
        "merchant_id" : 3,
        "ref" : null,
        "status" : "deleted",
        "test" : true,
        "token" : "31407172985450590"
      }

file to be uploaded

EXAMPLE REQUEST
      
      $res = nordeaconnect\api\stored_card::delete(976);
      
      EXAMPLE RESPONSE
      
      Array
      (
        [id] => 976
        [created_at] => 2018-08-05T08:26:38Z
        [token] => 31407227198478378
        [card_holder] => php sdk
        [card_number] => 411111******1111
        [status] => deleted
        [currency] => EUR
        [expires] => 2018-01-31T23:59:59Z
        [ref] =>
        [merchant_id] => 3
        [test] => 1
        [customer] => Array
        (
          [id] => 2949
        )
      
      )

EXAMPLE REQUEST
      
      var res = StoredCard.Delete(1);
      
      EXAMPLE RESPONSE
      
      {
        "card_cvv" : "200",
        "card_holder" : ".net sdk",
        "card_number" : "411111******1111",
        "card_type" : "VISA",
        "created_at" : "2018-08-06T17:54:31.381836Z",
        "currency" : "eur",
        "customer" : null,
        "customer_id" : 0,
        "customer_ref" : null,
        "encrypted" : null,
        "expires" : "0001-01-01T00:00:00",
        "id" : 1,
        "merchant_id" : 0,
        "status" : "deleted",
        "test" : true,
        "token" : "dafklgjd0r98gd0ugjl"
      }

Using a Tokenized Card through API

This section is only applicable for recurring payments, where you as a merchant run your own billing plan/subscription schedule, executing the subscription on your side. For each payment that you want to process, please send in an API call to the following endpoint:

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

Mandatory params

amount	decimal The transaction amount e.g. 12.00, NOTE: must always include two decimals and a dot
currency	string 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_ref	string A unique order ID from the merchant internal order/payment data (length 1-12)
hash	string 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.
test	boolean 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.
card_number	stringThe token for the card is sent in using the `card_number` param
card_type	stringSend in value `stored_card`

Example

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>

Billing Plan

A subscription plan, called Billing plan in the Merchant portal, is a template for recurring payments, which are automatically executed by Nordea Connect.

This is the Billing plan object:

id	intPlan ID
created_at	datetimeEx. 2018-04-25T10:36:33Z (UTC)
interval_unit	stringdays / months
periods	intHow many periods to run this plan. 0 = forever
setup_fees	objectStarts costs of a plan `{"eur":"0","sek":"0"}`
interval	intHow often a interval unit should be executed. Ex. every 1 month.
prices	objectPrice for each subscription transaction `{"eur":"10","sek":"100"}`
status	stringactive,cancelled
name	stringName of plan
description	stringDescription of plan
trial_length	intAmount of days before the first transaction. 0 = no trial.
merchant_id	intId of Merchant account

Billing plans can also be created and/or edited in the Nordea Connect Merchant Portal. Currently, you can only update an existing Billing Plan through the Merchant Portal. Updating an individual subscription is possible through the API.

Create Plans

To create a Billing plan you need to POST to the following url https://api.nordeaconnect.com/v1/plans

Parameters to send:

interval_unit	string *required days / months
periods	intHow many periods to run this plan. 0 = forever
interval	int *required How often a interval unit should be executed. Ex. every 1 month.
prices	object *required Price for each Merchant available currency as a JSON string `{"eur":"10","sek":"100"}`
name	string *required Name of plan
description	stringDescription of plan
trial_length	intAmount of days before the first transaction. 0 = no trial.
setup_fees	objectSetup fee for each Merchant available currency as a JSON string `{"eur":"10","sek":"100"}`

Show Plan

To display a specific Billing Plan you need to GET the following url https://api.nordeaconnect.com/v1/plans/[PlanID]

Change the PlanID to your own Billing Plan ID. You can get the Billing Plan ID either through the Nordea Connect Merchant Portal (section: Billing plans) or through the API response either through creating a plan or listing plans.

List Plans

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

Plans support filters on: created_at, description, id, interval, interval_unit, name, periods, ref, status, trial_length and updated_at.

IDs

There are four different IDs that can be generated in connection to recurring payments: Billing plan ID, customer ID, subscription ID and stored card ID.

Billing Plan ID
plan_id
ID identifying a specific Billing Plan.

Subscription ID
subscription_id
The specific ID a customer receives for a particular subscription tied to a particular Billing plan.

Customer ID
customer_id
An ID specifying a specific customer. The customer ID can also contain information about stored card IDs and/or subscriptions connected to a customer.

Stored card ID
stored_card_id
ID for a stored card token. Used to show/list stored cards for a specific customer or merchant.

Individual Subscription

Subscriptions are recurring payments connected to a Billing plan. They have information about customer, stored card and other data.

This is the Subscription object:

id	intSubscription ID
created_at	datetimeEx. 2018-04-25T10:36:33Z (UTC)
debt	decimalAdditional purchases or discounts that should be added (or subtracted if negative) from the price of the subscription in the next charge.
interval_unit	stringdays / months
periods_left	intNumber of transactions before subscription ends.
total_periods	intNumber of transactions in subscription.
interval	intHow often a interval unit should be executed. Ex. every 1 month.
price	decimalPrice for each transaction
status	stringactive,cancelled
next_at	datetimeNext date and time for execution (UTC)
customer	objectCustomer that owns the subscription
plan	objectThe plan connected to the subscription
stored_card	objectThe stored card connected to the subscription
subscription_quantity	intA number that says how many times the cost of the plan that should processed.
items	arrayAn array of subscription unique items
retry_count	intA number of failed transactions for the subscription. Ex. when a card has expired and cannot be processed.

Show Subscription

To show a specific subscription you need to GET the following url https://api.nordeaconnect.com/v1/subscriptions/[SubscriptionID]

Change [SubscriptionID] to the ID of your specific subscription. You can get the Subscription ID from the Nordea Connect Merchant Portal by navigating to Billing Plans and selecting the Billing Plan. There you will see the active subscription IDs listed.

You will also get the subscription ID back in the API response when creating a subscription (it is returned as the first param “id”).

List Subscription

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

You can also get the subscriptions for a specific customer by doing a GET to: https://api.nordeaconnect.com/v1/customers/[subscriptionID]/subscriptions

Update Subscription

To update a subscription you need to PUT the following url https://api.nordeaconnect.com/v1/subscriptions/[subscriptionID].

Parameters to send:

debt	decimalAdditional purchases or discounts that should be added (or subtracted if negative) from the price of the subscription in the next charge.
plan_id	stringThe ID of the plan. You can move a subscription between plans.
status	string`active` for making this subscription active, or `cancelled` to make it passive and non active.
subscription_quantity	intA number that says how many times the cost of the plan that should processed. This could be used as a licence factor when the plan cost A amount and the customer want to subscribe to A * the number of licenses (the multiplier) for each period.
metadata	objectYour own custom data in JSON format
stored_card_id	intThe id for a previously stored card. Update this to change the underlying card for a subscription
items	objectAn array of subscription unique items

Customer

A customer is an object that represents an owner of a transaction, stored card or subscription.

This is the customer object:

created_at	datetimeEx. 2018-04-25T10:20:48Z (UTC)
id	intThe ID of the customer
ref	stringThe Merchant internal ID for the customer. If not specified upon creation, it will be generated by Nordea Connect.
metadata	objectCustom Metadata

Show Customer

To show a specific customer you need to do a GET to the url https://api.nordeaconnect.com/v1/customers/[customerID].

List Customers

To list customers you need to GET to the url https://api.nordeaconnect.com/v1/customers.

Customers support filters on: created_at, id, ref and updated_at.

Create Customer

To create customers you need to POST to the url https://api.nordeaconnect.com/v1/customers.

Both ref and metadata are optional but highly recommended to be used. The customer ref will be created for you if you don’t specify it.

Parameters to send:

ref	stringThe Merchant internal ID for the customer. If not specified upon creation, it will be generated by Nordea Connect.
metadata	objectCustom Metadata

Update Customer

To update the metadata of a customer you need to PUT to the url https://api.nordeaconnect.com/v1/customers/[customerID].

Parameters to send:

metadata

objectCustom Metadata

Webhook Templates

A webhook template is connected to a Merchant and will serve as a reporting template for sending e-mails or HTTP requests connected to payments.

This is the webhook template object:

id	intThe webhook template ID
created_at	datetimeEx. 2018-04-25T10:20:48Z (UTC)
url	decimalTarget URL for a HTTP webhook. Can contain Liquid.
trigger	stringThe event triggering the webhook. Can be either of `none` `payment` `payment_success` `payment_error` `refund` `payment_form` `subscription_started` `subscription_success` `subscription_error` `card_stored` `card_updated` `change_address` `webhook_exhausted`
type	stringThe type can be either of `custom_http` `email` `receipt`
merchant_id	intThe Merchant id
email	stringThe destination e-mail if type is e-mail or receipt. Can contain Liquid.
http_method	stringPOST, GET, PATCH, PUT, when using custom HTTP webhook.
data_format	stringjson, xml or form_post, when using custom HTTP webhook.
body	stringHTML Contents of e-mail or payload of HTTP webhook (JSON, XML or Form post). Can contain Liquid.
custom_headers	stringCan contain Liquid. Example: key=value key2=value2
sender	stringE-mail of the sending person. Can contain Liquid.

Create Webhook Template

To create a webhook template you need to POST to the url https://api.nordeaconnect.com/v1/webhook_templates.

Parameters to send:

url	decimalTarget URL for a HTTP webhook. Can contain Liquid.
trigger	string *required The event triggering the webhook. Can be any of the following `none` `payment` `payment_success` `payment_error` `refund` `payment_form` `subscription_started` `subscription_success` `subscription_error` `card_stored` `card_updated` `change_address` `webhook_exhausted`
type	string *required The type can be `"type": "Webhook::ReceiptWebhook"` `"type": "Webhook::EmailWebhook"` `"type": "Webhook::CustomHttpWebhook"`
merchant_id	int *required The Merchant id
email	stringThe destination e-mail if type is e-mail or receipt. Can contain Liquid.
http_method	stringPOST, GET, PATCH, PUT, when using custom HTTP webhook.
data_format	stringjson, xml or form_post, when using custom HTTP webhook.
body	string *required HTML Contents of e-mail or payload of HTTP webhook (JSON, XML or Form post). Can contain Liquid.
custom_headers	stringCan contain Liquid. Example: key=value key2=value2
sender	stringE-mail of the sending person. Can contain Liquid.

Show Webhook Template

To show a webhook template you need to GET to the url https://api.nordeaconnect.com/v1/webhook_templates/1.

List Webhook Template

To show a webhook template you need to GET to the url https://api.nordeaconnect.com/v1/webhook_templates.

Update Webhook Template

To update a webhook template you need to PUT to the url https://api.nordeaconnect.com/v1/webhook_templates/1.

Parameters to send:

url	decimalTarget URL for a HTTP webhook. Can contain Liquid.
trigger	The event triggering the webhook. Can be any of the following `none` `payment` `payment_success` `payment_error` `refund` `payment_form` `subscription_started` `subscription_success` `subscription_error` `card_stored` `card_updated` `change_address` `webhook_exhausted`
type	stringThe type can be either of `custom_http` `email` `receipt`
merchant_id	intThe Merchant id
email	stringThe destination e-mail if type is e-mail or receipt. Can contain Liquid.
http_method	stringPOST, GET, PATCH, PUT, when using custom HTTP webhook.
data_format	stringjson, xml or form_post, when using custom HTTP webhook.
body	string *required HTML Contents of e-mail or payload of HTTP webhook (JSON, XML or Form post). Can contain Liquid.
custom_headers	stringCan contain Liquid. Example: key=value key2=value2
sender	stringE-mail of the sending person. Can contain Liquid.

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

Extendability

Many objects have child resources such as customer and stored card. To minimize the object graph being sent over REST calls you can choose to add full objects by specifying to extend them in the url:

Example:

To show the full transaction object in a refund GET: https://api.nordeaconnect.com/v1/refunds/1?extend=transaction

To show both customer and plan to a subscription GET: https://api.nordeaconnect.com/v1/subscriptions/1?extend=customer,plan

You can also extend specific attributes for an object like this: https://api.nordeaconnect.com/v1/subscriptions/1?extend=customer.ref,plan.id

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 & Nordea Connect Checkout 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.

id	intWebhook ID
created_at	datetimeEx. 2018-04-25T10:36:33Z (UTC)
type	stringWebhook type, ex: CustomHttp
response	objectThe 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_method	stringWhich method that were used, ex. POST, GET
email	stringSender address in a e-mail Webhook
url	stringURL in a Custom Http Webhook
trigger	stringWhat event to trigger Webhook, ex. payment_error
data_format	stringJSON, 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.

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

artno	string (maxlength 50) *required Article number
description	string (maxlength 150) *required Description about the item
amount	integer *required The total price of all the items
qty	string *required The item quantity
vat	string *required VAT rate, ex 25 (No verification or or calculation is made)
discount	stringDiscount of the products (No verification or or calculation is made)

Example

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

Payment Links

The Payment Links provide a simple method for suggesting payments by sharing a simple URL. Every transaction that is not finished will have a HREF attribute which is a HTTP link that can be sent to customers using e-mail or instant messaging. The link is a useful tool to have customers complete an unfinished payment that was abandoned or one that the merchant has prepared earlier.

When a customer clicks on the link that looks like this: https://pay.nordeaconnect.com/v1/form/hrr5ssWg0y-XgcYOyNXhew, they will end up in a Payment Window form that is set up by the merchant and prepared with all the order details like amount, currency, metadata, webhooks etc. When the customer has finished the payment he/she will be redirected to the success_url that was used in the original POST that created the transaction earlier. The same goes with an unsuccessful payment where the customer will end up in the error_url.

To find the HREF url, you will need to search in the Admin console to find the transaction and then expand the panel to find the url among all the other transaction data. Another option is to prepare the transaction in the API and and the get the HREF in the API call response and pass that link to the customer.

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 Code	Description
1	errors.credit_card.missing	Credit card is missing
2	errors.credit_card_details.missing	Credit card details are missing
3	errors.terminal_id.invalid	Terminal ID is invalid
4	errors.provider_ref.processed	Provider reference processed
209	errors.ssn_or_country.missing	The country is missing
211	errors.missing_or_invalid.ssn	SSN error – missing SSN or invalid format
212	errors.missing_or_too_long.first_name	First Name error – missing first name or first name too long
213	errors.missing_or_too_long.last_name	Last Name error – missing last name or last name too long
214	errors.invalid.email	E-mail error – invalid e-mail format
215	errors.missing_or_invalid.phone_number	Cell phone number error – cell phone number missing or invalid characters
216	errors.missing_or_too_long.address_1	Address line 1 error – missing address or address line 1 too long
217	errors.missing.address_2	Address line 2 error – address line 2 too long
218	errors.missing_or_too_long.city	City error – city is missing or value too long
219	errors.missing_or_too_long.zip_code	Zip code error – zip code missing or value too long
220	errors.missing_or_invalid.country_code	Country code error – missing or invalid country code
221	errors.missing_or_invalid.amount_error	Amount error – missing amount or invalid value
222	errors.too_long.transaction_id	Transaction id error – value is too long
223	errors.must_be_submitted.ssn	SSN must be submitted
224	errors.invoice.credit_approval_failed	Credit approval failed
225	errors.invoice.credit_check	Credit check (SSN not found)
226	errors.invoice.credit_not_approved	Credit not approved
227	errors.invoice.amount.requested.lower_than_minimum_purchase_amount	Amount requested is lower than minimum purchase amount
228	errors.invoice.amount.requested.higher_than_maximum_purchase_amount	Amount requested is higher than maximum purchase amount
229	errors.invoice.amount.maximal_decimal	Amount value can have maximal {0} decimal places
230	errors.invoice.item.maximal_decimal	Item amount value can have maximal {0} decimal places
231	errors.item.total_amount_error	Total amount error – the total amount of items must be higher than zero
232	errors.item.notes_to_long	Notes error – notes for an item is too long
233	errors.missing_or_too_long.order_reference	Order reference error – missing order reference or it is too long
234	errors.invoice.account_error	Account class error – missing account class or invalid account class value
235	errors.invoice.account_class_error	Account 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
236	errors.order.reference.error	Order reference error – missing order reference or it is too long
237	errors.invoice.credit_decision_process_failed	Credit decision process failed
238	errors.helper.ssn.invalid_format	SSN error – invalid format
239	errors.helper.ssn.must_be_submitted	SSN must be submitted
240	errors.helper.ssn.for_sweden_must_be_12_digits	SSN for Sweden must be 12 digits
241	errors.helper.ssn.address_is_available	Not available – SSN is valid but no address is available
242	errors.helper.ssn.have_a_value	Account number or SSN must have a value
243	errors.service_not_available	Service not available for the specified country
244	errors.invoice.no_account_exists	No account exists – use Approve Invoice/Loan first
245	errors.invoice.purchase_for_different_country	You are trying to make a purchase for different country, than what is assigned to branch market
246	errors.invoice.payment_terms_error	Payment terms error – specified payment terms code does not exist
247	errors.invoice.account_number_error	Account number error – invalid value
248	errors.invoice.account_was_overdrawn	Max. amount for the account was overdrawn
249	errors.invoice.execute.against.this.account	Cannot execute return against this account
250	errors.password_length	Password length must be at least 6 characters
251	errors.customer_not_found	Customer not found! Probably due to customer with SSN = {0} is not client of {1}
252	errors.request.json_error	API request error
253	errors.request.bad_format	Bad format of request data. For example, the data is not in valid JSON format.
254	errors.items.not_array	Items is not an array
255	errors.items.description_missing	Item description is missing
256	errors.items.notes_missing	Items notes is missing
257	errors.items.amount_missing	Amount is missing
258	errors.items.description_too_long	Items description is too long
259	errors.items.amount_not_valid	Items amount is not valid
260	errors.items.transaction_amount_mismatch	Items total amounts does not match transaction amount
261	errors.rules_parser.declined	Declined 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
262	errors.request.json_errors	Something is wrong with the JSON object
263	errors.invoice.denied_to_purchase	Customers are blocked for purchases by collector, please contact collector for more information.
264	errors.invoice.credit_check_denied	The credit check is not approved
265	errors.invoice.address_not_found	Address cannot be found for the specified customer
266	errors.invoice.reservation_not_approved	Reservation is not approved
267	errors.invoice.invalid_registration_number	Registration number is not in a correct format
268	errors.invoice.agreement_rules_validation_failed	Something with the use of the API is against the agreement with collector, please contact collector for information.
269	errors.invoice.unhandled_exception	If an unhandled error occurs, an unhandled exception will be thrown. In cases of these errors contact collector for help
270	errors.invoice.purchase_amount_greater_than_max_credit_amount	The 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
271	errors.invoice.activation_of_invoice_denied	Activation of an invoice is denied
274	errors.invoice.article_not_found	An 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.
275	errors.invoice.article_not_found_based_on_unitprice	Cannot locate the specified article based on the specified unit price. Make sure an article with the specified unit price exists
276	errors.invoice.authorization_failed	Could not authorize the request, check your login credentials. Please contact the collector for more help
277	errors.invoice.countrycode_mismatch_with_customer_address	The specified country code for the customer’s address doesn’t match the country code specified in the (base) request
278	errors.invoice.countrycode_mismatch_with_delivery_address	The specified country code for the customer’s delivery address doesn’t match the country code specified in the (base) request
279	errors.invoice.countrycode_mismatch_with_invoice_address	The specified country code for the customer’s invoice address doesn’t match the country code specified in the (base) request
282	errors.invoice.email_is_missing	The delivery method was set to email but the email field was not present in the request
283	errors.invoice.invalid_countrycode	Can be thrown when you try to request an address from another country than the one you are registered in
284	errors.invoice.invalid_credit_time_usage	Credit time cannot be used for the specific invoice type
285	errors.invoice.invalid_currency_code	The 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
286	errors.invoice.invalid_delivery_address_usage	Private customers aren’t allowed to have different invoice addresses and deliver addresses, they must be the same
287	errors.invoice.invalid_invoice_status	A pending invoice cannot be cancelled based on the stage it is in
288	errors.invoice.invalid_product_code	The product code cannot be found or the product is inactive
289	errors.invoice.invalid_quantity	The quantity of an article is too low or too high compared to the quantity or quantity left on the article
291	errors.invoice.invalid_transaction_amount	The 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)
292	errors.invoice.invoice_duedate_already_extended	The due date of the invoice has already been extended
293	errors.invoice.invoice_exceeds_available_reservation	The purchase sum of the invoice exceeds the available reservation amount
294	errors.invoice.invoice_extended_date_in_past	Attempting to extend due date by specifying a date in the past
295	errors.invoice.invoice_invalid_type	Invoice 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)
296	errors.invoice.invoice_not_found	When the specified invoice number cannot be found. When trying to credit an invoice the invoice is already credited or not activated
297	errors.invoice.invoice_type_is_not_allowed_to_be_used	You aren’t allowed to use the specified invoice type
298	errors.invoice.mixed_currency	The article’s currency doesn’t match the currency on the invoice
299	errors.invoice.mobile_phone_is_missing	The mobile phone is missing, which is needed because of the chosen notification type
300	errors.invoice.not_allowed_to_send_notification_by_email	You aren’t allowed to send the specific invoice type by email
301	errors.invoice.not_allowed_to_send_notification_by_mail	You aren’t allowed to send the specific invoice type by postal mail
303	errors.invoice.purchase_not_found	An invoice cannot be found
305	errors.invoice.reservation_not_found	There was no reservation for the specified customer
306	errors.invoice.total_amount_must_be_positive	The amount of an invoice must be positive
308	errors.invoice.unique_article_not_found	When 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
309	errors.invoice.validation_activation_option_value	The Activation Option field was not one of its allowed values
310	errors.invoice.validation_address1_length	The Address 1 field was too long
311	errors.invoice.validation_address2_length	The Address 2 field was too long
312	errors.invoice.validation_amount_parsing	The 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)
313	errors.invoice.validation_amount_range	The amount field was not within its allowed range
314	errors.invoice.validation_amount_required	The amount field was not present in the request
315	errors.invoice.validation_article_id_length	The ArticleId field was too long
316	errors.invoice.validation_article_id_required	An article is missing the ArticleId
317	errors.invoice.validation_article_list_required	The ArticleList field was not present in the request
318	errors.invoice.validation_cell_phone_number_length	The CellPhoneNumber field was too long
319	errors.invoice.validation_city_length	The City field was too long
320	errors.invoice.validation_city_required	The City field was not present in the request
321	errors.invoice.validation_client_ip_address_length	The ClientIpAddress field was too long
322	errors.invoice.validation_client_ip_address_required	The ClientIpAddress field was not present in the request
323	errors.invoice.validation_coaddress_length	The CoAddress field was too long
324	errors.invoice.validation_company_name_length	The CompanyName field was too long
325	errors.invoice.validation_cost_center_length	The CostCenter field was too long
326	errors.invoice.validation_country_code_length	The CountryCode field was too long
327	errors.invoice.validation_country_code_required	The CountryCode field was not present in the request
328	errors.invoice.validation_credit_date_required	The CreditDate field was not present in the request
329	errors.invoice.validation_credit_time_out_of_range	Credit time is out of range, can only be between 0 and 99
330	errors.invoice.validation_currency_length	The Currency field was too long
331	errors.invoice.validation_currency_invalid	The 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
332	errors.invoice.validation_currency_required	The Currency field was not present in the request
333	errors.invoice.validation_customer_number_length	The CustomerNumber field was too long
334	errors.invoice.validation_delivery_address_required	The DeliveryAddress field was not present in the request
335	errors.invoice.validation_description_length	The Description field was too long
336	errors.invoice.validation_email_invalid	The e-mail address is not a valid e-mail address
337	errors.invoice.validation_email_length	The Email field was too long. Can only be a maximum of 256 characters
338	errors.invoice.validation_error	Input data is not correct
339	errors.invoice.validation_first_name_length	The FirstName field was too long
340	errors.invoice.validation_gender_value	The Gender field was not one of its allowed values
341	errors.invoice.validation_invoice_address_required	The InvoiceAddress field was not present in the request
342	errors.invoice.validation_invoice_delivery_method_value	The InvoiceDeliveryMethod field was not one of its allowed values
343	errors.invoice.validation_invoice_number_length	The InvoiceNo field was too long
344	errors.invoice.validation_invoice_number_required	The InvoiceNo field was not present in the request
345	errors.invoice.validation_invoice_type_value	The InvoiceType field was not one of its allowed values
346	errors.invoice.validation_last_name_length	The LastName field was too long
347	errors.invoice.validation_order_date_required	The OrderDate field was not present in the request
348	errors.invoice.validation_order_number_length	The OrderNo field was too long
349	errors.invoice.validation_password_required	The Password field was not present in the request.
350	errors.invoice.validation_phone_number_length	The PhoneNumber field was too long
351	errors.invoice.validation_postal_code_length	The PostalCode field was too long
352	errors.invoice.validation_postal_code_required	The PostalCode field was not present in the request
353	errors.invoice.validation_quantity_range	The Quantity field was not within its allowed range
354	errors.invoice.validation_quantity_required	An article is missing its Quantity
355	errors.invoice.validation_reference_length	The Reference field was too long
356	errors.invoice.validation_registration_number_length	The RegNo field was too long
357	errors.invoice.validation_registration_number_required	The RegNo field was not present in the request
358	errors.invoice.validation_reserved_amount_parsing	The ReservedAmount field could not be parsed
359	errors.invoice.validation_reserved_amount_range	The ReservedAmount field was not within its allowed range
360	errors.invoice.validation_reserved_amount_required	The ReservedAmount field was not present in the request
361	errors.invoice.validation_unit_price_parsing	The UnitPrice field could not be parsed
362	errors.invoice.validation_unit_price_range	The UnitPrice field was not within its allowed range
363	errors.invoice.validation_username_required	The Username field was not present in the request
364	errors.invoice.validation_vat_parsing	The Vat field could not be parsed
365	errors.invoice.validation_vat_range	The Vat field was not within its allowed range
366	errors.invoice.validation_vat_required	The Vat field was not present in the request
367	errors.invoice.article_exists_but_other_information	Article can’t be added because an existing article exists but with another VAT
368	errors.invoice.customer_purchase_progress	A simultaneous purchase is already being processed for the customer
400	errors.stored_card.expires.missing	Stored card expiration date missing
2084	errors.trustly.message_id_duplicate	Message id duplicate
2085	errors.trustly.invalid_credentials	Credentials are invalid
2086	errors.trustly.malformed_notificationurl	The NotificationURL sent in the request is malformed. It must be a valid http(s) address
2087	errors.trustly.invalid_ip	The IP attribute sent is invalid. Only one IP address can be sent
2088	errors.trustly.insufficient_funds	The merchant does not have enough balance on his/her Trustly account to execute the refund
2089	errors.trustly.disabled_user	The user account is disabled
2090	errors.ssn_token.failed	SSN token failed
2091	errors.metadata.invalid	Metadata is invalid
2301	errors.item.missing_or_too_long.description	Description error – the description of an item is missing or is too long
2502	errors.items.vat_missing	Item vat is missing or not valid
2503	errors.items.artno_missing	Item artno is missing
2511	errors.items.qty_missing	Item quantity is missing or not valid
2512	errors.items.notes_too_long	Items notes are too long
2610	errors.rules_parser.skip_webhook	Rule parsers are skipped
4001	errors.stored_card.store.declined	Card could not be stored
4002	errors.stored_card.token.invalid	Stored card token is invalid

More Information

Identify Payment type

To identify the payment type, you can use the transaction_type parameter. This can contain the following values:

after_pay	AfterPay
apple_pay	Apple Pay
bank	Online banking (FI)
credit_card	Credit card
mobile_pay_online	MobilePay
paypal	PayPal
siirto	Siirto
swish	Swish
stored_card	Stored card
vipps	Vipps

If you are interested in card-scheme payments, the parameter card_type might be useful. It contains the following values:

visa	Visa
mastercard	MasterCard
maestro	Maestro
electron	Electron
debit_mastercard	Debit MasterCard
visa_debit	Visa Debit
amex	American Express
diners	Diners
uk_maestro	UK Maestro
stored_card	Stored Card

Please note that approved ApplePay, MobilePay and Vipps transactions change to card transactions, whilst pending/failed/declined transactions show as ApplePay, MobilePay and Vipps transactions. Please use the parameter wallet_type for ApplePay, MobilePay and Vipps transactions to detect the payment method.

The parameter wallet_type can contain the following values:

apple_pay	ApplePay
mobile_pay	MobilePay
vipps	Vipps

Accepted currencies

sek	Swedish Krona
cad	Canadian Dollar
cny	Chinese Yuan
cop	Colombian Peso
czk	Czech Republic Koruna
dkk	Danish Krone
hkd	Hong Kong Dollar
huf	Hungarian Forint
isk	Icelandic Króna
inr	Indian Rupee
ils	Israeli New Sheqel
jpy	Japanese Yen
kes	Kenyan Shilling
krw	South Korean Won
kwd	Kuwaiti Dinar
lvl	Latvian Lats
myr	Malaysian Ringgit
mxn	Mexican Peso
mad	Moroccan Dirham
omr	Omani Rial
nzd	New Zealand Dollar
nok	Norwegian Krone
pab	Panamanian Balboa
qar	Qatari Rial
rub	Russian Ruble
sar	Saudi Riyal
sgd	Singapore Dollar
zar	South African Rand
chf	Swiss Franc
thb	Thai Baht
ttd	Trinidad and Tobago Dollar
aed	United Arab Emirates Dirham
gbp	British Pound Sterling
usd	US Dollar
twd	New Taiwan Dollar
vef	Venezuelan Bolívar
ron	Romanian Leu
try	Turkish Lira
eur	Euro
uah	Ukrainian Hryvnia
pln	Polish Zloty
brl	Brazilian Real

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.

Technical documentation

API

Authentication

HTTP Response Codes

Object Graph

Transaction

Show Transaction

List Transactions Example

Update Transaction

Transaction Object

Capture

Refund

Create Refund

Create Refund Example

Show Refund

Show Refund example

List Refund

status

created_at

amount

reason

Example

Tokenize Card

Show Tokenized Card

List Tokenized Cards

Update Tokenized Card

Delete Tokenized Card

Using a Tokenized Card through API

Example

Billing Plan

Create Plans

Show Plan

List Plans

IDs

Individual Subscription

Show Subscription

List Subscription

Update Subscription

Customer

Show Customer

List Customers

Create Customer

Update Customer

Webhook Templates

Create Webhook Template

Show Webhook Template

List Webhook Template

Update Webhook Template

Pagination

Filtering

Extendability

Metadata

Webhooks

Items

Payment Links

Error Messages

More Information

Identify Payment type

Accepted currencies

Language

FAQ