Overview
TLS and API communication
Nordea Connect require you to use TLS 1.1 or above to access the API due to security reasons. 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.
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
Partial data
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-Rangeheader. 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
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
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.
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.
Transaction
A transaction is a function to make payments using cards though the REST API. This is done using javaScript (nordeaconnect.js) or a server to server implementation. A Merchant is identified using Basic Auth and can do GET calls to fetch one or many transactions, or POST to create a transaction (a purchase).
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.
|
| 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: |
| cost | objectThe cost of transaction |
| 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) |
Show Transaction
To show a transaction you need to do a GET to https://api.nordeaconnect.com/v1/transactions/3 that will return a transaction with ID 3.
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" : [ ]
}List Transactions
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/3/transactions
To get transactions for a specific subscription: GET to: https://api.nordeaconnect.com/v1/subscription/3/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
}...
]Create Transaction
To create a transaction you need to do a POST to https://api.nordeaconnect.com/v1/transactions that will return a the newly created transaction in the same way as doing a GET.
Each param can be encrypted with the public RSA key for better security and lower PCI DSS requirements for the Merchant. 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 ) ) ).
For transactions with a stored card, the value “card_number” must be the token that the Merchant got in the store-response and the “card_type” must be “STORED_CARD”. So instead of a card number use the token and instead of “VISA” use “STORED_CARD”.
The parameters you can send to create a transaction:
| merchant_id | string *required The ID of the Merchant |
| amount | decimal *required The transaction amount ex. 12.00 |
| vat_amount | decimalThe vat amount for the transaction ex. 3.00 |
| payment_ref | string *required Merchant order/payment ID |
| card_holder | stringThe name on the charged credit card. Not required if process = false. |
| card_cvv | stringCVV code. Not required if process = false. |
| card_expiry | stringExpiration date of the credit card in the format MMYY. Not required if process = false. |
| card_number | stringThe card number. Not required if process = false. |
| test | booleanWhether the transaction is a test transaction. Defaults false |
| metadata | objectMerchant custom Metadata |
| currency | string *required The 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 |
| store_card | booleantrue/false if you want to store the card |
| plan_id | intThe ID of the subscription plan. |
| start_date | dateThe first date of a new subscription. Ex: 2020-01-01 (YYYY-MM-DD) |
| customer_ref | stringThe Merchant specific user/customer ID |
| hash | string *required The hash is a MD5 encoded string with some of your Merchant and order specific parameters, which is used to verify the payment, and make sure that it is not altered in any way. The Hash string usually includes: merchant_id,payment_ref,customer_ref,amount,currency,test,secret, and might vary depending on your settings. Note that you will need to view your Merchant specific hash settings in the Admin console.
|
| webhook | objectYou can specify a custom Webhook for a transaction. For example sending e-mail or POST to your backend. |
| encrypted | stringA comma separated string containing the params you have encrypted. Ex: “card_number,card_holder,card_cvv” |
| 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. |
| success_url | string *required A URL to the page where the user is redirected after a successful transaction. |
| template_id | int Hosted Page template ID |
| error_url | string *required A URL to the page where the user is redirected after a unsuccessful transaction. |
| authorize | booleanauthorize = true, means that the transaction should be reserved (Authorized). |
| 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 |
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.
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¤cy=sek&hash=6bd88f621553edcf0c553f91bf6fb797&test=true" --user 3:password '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": "https://admin.nordeaconnect.com/payment-ok",
"error_url": "https://admin.nordeaconnect.com/payment-error",
"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
}
}# EXAMPLE REQUEST
attributes = {
amount: '725.00',
currency: 'sek',
payment_ref: 'order-1146',
card_holder: 'Test User',
card_number: '4111 1111 1111 1111',
card_expiry: '1016',
card_cvv: '200',
card_type: 'VISA',
customer_ref: 'user_25',
metadata: {
products: [
{title: 'T-shirt'},
{title: 'Shoes'}
]i
}
}
transaction = NordeaConnect::CreditCard::Transaction.create(attributes)
# 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=ni>l
EXAMPLE REQUEST
$payment = array(
"card_number" => "4111111111111111",
"card_holder" => "php sdk",
"card_expiry" => "0116",
"card_cvv" => "200",
"card_type" => "VISA",
"amount" => "10.00",
"payment_ref" => $ref,
"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] =>
[customer] =>
[subscription] =>
[refunds] => Array
(
)
[webhooks] => Array
(
)
)
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("test", "true"));
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("locale", "en"));
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
}Create a Transaction with a stored card
In a Stored Card payment you need to have the
tokenas card_number andSTORED_CARDas card_type. The response will have a Stored Card object with the ID of the card used.
EXAMPLE REQUEST
curl -X POST --data "card_number=31407340575815445&card_type=STORED_CARD&amount=5.00&payment_ref=53e479ea&card_cvv=000¤cy=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 uploadedEXAMPLE 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_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
Metadataproperty 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.
Capture Transaction
To capture an previously authorized transaction, you need to PUT data to https://api.nordeaconnect.com/v1/transactions/1/capture
You can capture a transaction when it has previously been authorized. Authorization is achieved by passing authorize = true when creating a transaction using the API, Payment Window or NordeaConnect.js
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. |
Stored Card
To store a card though the API (also called tokenization) you need to POST data to https://api.nordeaconnect.com/v1/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).
| 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 Stored Card
By doing a GET request to https://api.nordeaconnect.com/v1/stored_cards/1 you will get the stored card with ID 1.
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 Stored 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/3/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.
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"
}...
]Create Stored Card
By doing a POST request to https://api.nordeaconnect.com/v1/stored_cards you can store the card information and receive a token for future transactions.
Parameters to send:
| card_number | string *required The masked version of the credit card number. |
| card_holder | string *required The name on the charged credit card |
| card_cvv | string *required CVV code |
| card_expiry | string *required Expiration date of the credit card in the format MMYY |
| currency | string *required The 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 | string *required VISA, MASTERCARD, STORED_CARD (if the transaction is done using a stored card), etc |
| customer_ref | stringMerchant specific customer ID. If this customer exists the card will be added to that customer. If it doesn’t exists a customer will be created. |
| customer_id | intNordea Connect specific customer ID. If this customer exists the card will be added to that customer. If it doesn’t exists an error will occur. |
| encrypted | stringA comma separated string for the params that you send encrypted. Ex. “card_number,card_cvv” |
| test | boolMust be true if you are using a test card number. |
To store card though the API you need to POST data to https://api.nordeaconnect.com/v1/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 the card number and “STORED_CARD” instead of card type (ex. VISA).
EXAMPLE REQUEST
curl -X POST --data "card_number=4111111111111111&card_expiry=0116&card_holder=name%20name&card_type=VISA&card_cvv=200¤cy=sek&test=true" --user 3:password 'https://api.nordeaconnect.com/v1/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"
}
# EXAMPLE REQUEST
attributes = {
card_holder: 'Jane Doe',
card_type: 'VISA',
card_number: '4111 1111 1111 1111',
card_cvv: '200',
card_expiry: '0916',
currency: 'SEK'
}
stored_card = NordeaConnect::CreditCard::StoredCard.create(attributes)
# EXAMPLE RESPONSE
3073}>
EXAMPLE REQUEST
$data = array(
"card_number" => "4111111111111111",
"card_holder" => "php sdk",
"card_expiry" => "0116",
"card_cvv" => "200",
"card_type" => "VISA",
"currency" => "eur",
"test" => "true"
);
$res = nordeaconnect\api\stored_card::create($data);
EXAMPLE RESPONSE
Array
(
[id] => 975
[created_at] => 2018-08-05T08:17:53Z
[token] => 31407226673424954
[card_holder] => 99221
[card_number] => 411111******1111
[status] => active
[currency] => EUR
[expires] => 2018-01-31T23:59:59Z
[ref] =>
[merchant_id] => 3
[test] => 1
[customer] => Array
(
[id] => 2948
)
)EXAMPLE REQUEST
var refdata = DateTimeOffset.Now.Ticks.ToString();
var postData = new List();
var encryptedCard = "4111111111111111".RSAEncrypt();
postData.Add(new KeyValuePair("card_expiry", "0116"));
postData.Add(new KeyValuePair("card_holder", refdata));
postData.Add(new KeyValuePair("test", "true"));
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("locale", "en"));
postData.Add(new KeyValuePair("encrypted", "card_number"));
var res = StoredCard.Create(postData);
EXAMPLE RESPONSE
{
"card_cvv" : "200",
"card_holder" : "635429515090009766",
"card_number" : "411111******1111",
"card_type" : "VISA",
"created_at" : "2018-08-06T17:51:49.209961Z",
"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" : "dkjsf7w6824yfwh97"
}Update Stored 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 Stored 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
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 uploadedEXAMPLE 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"
}Plan
A subscription plan is a payment template for recurring payments that automatically will be executed in Nordea Connect.
| 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 |
| interval | intHow often a interval unit should be executed. Ex. every 1 month. |
| prices | objectPrice for each subscription transaction |
| 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 |
The plans can be created and edited in the admin console.
Show Plan
To show a plan with ID 1 you need to GET the following url https://api.nordeaconnect.com/v1/plans/1
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.
Create Plans
To create a plan you need to POST 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 |
| name | string *required Name of plan |
| description | stringDescription of plan |
| trial_length | intAmount of days before the first transaction. 0 = no trial. |
Subscription
Subscriptions are recurring payments connected to a Plan. They have information about customer, stored card and other data.
| 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 subscription with ID 1 you need to GET the following url https://api.nordeaconnect.com/v1/subscriptions/1
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/3/subscriptions
Create Subscription
To create a subscriptions you need to POST the following url https://api.nordeaconnect.com/v1/subscriptions
You need to send one of stored_card_id, customer_ref or customer_id in order to connect a card to the subscription.
Parameters to send:
| plan_id | string *required The ID of the plan |
| start_date | dateThe first date of a subscription |
| stored_card_id | intID of stored card |
| customer_ref | stringMerchant specific customer ID. If this customer exists the card will be added to that customer. If it doesn’t exists a customer will be created. |
| customer_id | intNordea Connect specific customer ID. If this customer exists the card will be added to that customer. If it doesn’t exists an error will occur. |
| 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 |
| items | arrayAn array of subscription unique items |
Update Subscription
To update a subscriptions with ID 1 you need to PUT the following url https://api.nordeaconnect.com/v1/subscriptions/1.
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 | stringactive 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.
| 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 GET to the url https://api.nordeaconnect.com/v1/customers/1.
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 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/1.
Parameters to send:
| metadata | objectCustom Metadata |
Refund
A refund object is connected to a transaction where parts or the whole payment have been returned to the card holder.
| 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 |
Show Refund
To show a refund you need to GET to the url https://api.nordeaconnect.com/v1/refunds/1.
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
}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. Ex. 5.00 |
| reason | string *required The reason for the refund. Ex. “Cancelled order” |
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 RESPONSEEXAMPLE 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
}Webhook Templates
A Webhook template is connected to a Merchant and will server as a reporting template for sending e-mails or HTTP requests connected to payments.
| 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 |
| 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. |
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.
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 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 | string *required The type can be either of custom_http email receipt |
| merchant_id | int *required The Merchant id |
| 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. |
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 | 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 |
| 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. |
Helpers
Some help requests that can help you with the implementation.
Snn lookup
Lookup a Social Security number (Personnummer) https://api.nordeaconnect.com/v1/helpers/ssn/lookup.
This request is recommended to use if you want to use payment_method invoice
Parameters to send:
| ssn | string *required Social Security number (Personnummer). Ex: 192803104351 |
| country_code | string *required Use ISO 3166-1 alpha-3 codes, ex: SWE. |
| test | stringSets the action to be live or in test mode. test = true, only allows test ssn numbers, test = false, only allow real ssn numbers. |
{
"first_name": "Solbritt",
"last_name": "Jansson",
"address_1": "Danagatan 1",
"address_2": null,
"city": "Trångsund",
"zip": "14262",
"country": "SWE",
"ssn": "195203198089"
}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
Metadataproperty 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.
| 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 |
| 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.
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 RefundsYou 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 Details
Payment Details make it possible to send customer data. Payment data is perfect way to send specific information about a customer.
This data is required if the transaction is of type invoice
| ssn | string *required Social Security number (Personnummer). Ex: 192803104351 |
| phone | string *required Phone number |
| string *required Email adress | |
| customer_number | string (maxlength 150)Your custumer number |
| first_name | string (maxlength 150) *required The first name of the custumer |
| last_name | string (maxlength 150) *required The last name of the custumer |
| zip | string (maxlength 150) *required ZIP code |
| address_1 | string (maxlength 150) *required Primary address |
| address_2 | string (maxlength 150)Secondary address |
| city | string (maxlength 150) *required City |
| country_code | string *required Use ISO 3166-1 alpha-3 codes, ex: SWE. |
| company_name | string *required Company name, for b2b |
| segmentation | string *required Segmentation, b2c or b2b |
Supported Card Types
Where are they used?
You need to POST the card type name as
card_typeparameterDefault 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.
| 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 |
| paypal | PayPal |
| swish | Swish |
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 |
Test Cards
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:
| VISA | 4111111111111111 |
| VISA | 4012888888881881 |
| VISA | 4222222222222 |
| MASTERCARD | 5555555555554444 |
| MASTERCARD | 5105105105105100 |
| DINERS | 30569309025904 |
| AMEX | 378282246310005 |
Test CVV codes:
When in test mode (test=true) you can use CVV codes to simulate different responses. Anything else will lead to Approved.
| 200 | ACCEPTED |
| 201 | DECLINED |
| 202 | CVV INVALID |
| 203 | EXPIRED |
Test Expiry dates:
When in test mode (test=true) you can use specific expiry dates to simulate failed recurring card payments
| 0137 | errors.payment.declined |
| 0237 | errors.card.expired |
Test Customers
To create test invoice transactions you need to send in a test ssn number. Use different SSN numbers to simulate different responses.
Approved persons Sweden
| 195203198089 | string{“first_name”: “Solbritt”, “last_name”: “Jansson”, “address_1”: “Danagatan 1”, “address_2”: nil, “city”: “Trångsund”, “zip_code”: “14262”, “country”: “SWE”, “ssn”: “195203198089”} |
| 192803037999 | string{“first_name”: “Stig”, “last_name”: “Saleh”, “address_1”: “Lars Kaggsgatan 163 Lgh 1003”, “address_2”: nil, “city”: “Oxie”, “zip_code”: “23831”, “country”: “SWE”, “ssn”: “192803037999”} |
| 192803104351 | string{“first_name”: “Erik”, “last_name”: “Nygren”, “address_1”: “Hablingbo Prästgården 151 Lgh 1203”, “address_2”: nil, “city”: “Nynäshamn”, “zip_code”: “14931”, “country”: “SWE”, “ssn”: “192803104351”} |
| 192803290853 | string{“first_name”: “Erik”, “last_name”: “Karlsson”, “address_1”: “Sakrislundsvägen 45 Lgh 1001”, “address_2”: nil, “city”: “Ytterby”, “zip_code”: “44205”, “country”: “SWE”, “ssn”: “192803290853”} |
| 192805181332 | string{“first_name”: “Jonas”, “last_name”: “Olivares”, “address_1”: “Fröjel Stora Hajdes 717”, “address_2”: nil, “city”: “Spånga”, “zip_code”: “16345”, “country”: “SWE”, “ssn”: “192805181332”} |
| 192806225351 | string{“first_name”: “Gustaf”, “last_name”: “Roslin”, “address_1”: “Motalagatan 7 Lgh 1005”, “address_2”: nil, “city”: “Linköping”, “zip_code”: “58254”, “country”: “SWE”, “ssn”: “192806225351”} |
| 195202057674 | string{“first_name”: #RANDOM#, “last_name”: #RANDOM#, “address_1”: #RANDOM#, “address_2”: #RANDOM#, “city”: #RANDOM#, “zip_code”: #RANDOM#, “country”: “SWE”, “ssn”: “195202057674”} |
| 197003067985 | string{“first_name”: #RANDOM#, “last_name”: #RANDOM#, “address_1”: #RANDOM#, “address_2”: #RANDOM#, “city”: #RANDOM#, “zip_code”: #RANDOM#, “country”: “SWE”, “ssn”: “197003067985”} |
| 197108262366 | string{“first_name”: #RANDOM#, “last_name”: #RANDOM#, “address_1”: #RANDOM#, “address_2”: #RANDOM#, “city”: #RANDOM#, “zip_code”: #RANDOM#, “country”: “SWE”, “ssn”: “197108262366”} |
Denied persons Sweden
| 192806281719 | string{“first_name”: “Kent”, “last_name”: “Ludwig”, “address_1”: “Vindögatan 4 Lgh 1502”, “address_2”: nil, “city”: “Gärds Köpinge”, “zip_code”: “29197”, “country”: “SWE”, “ssn”: “192806281719”} |
| 192808219691 | string{“first_name”: “Alex John”, “last_name”: “Säll”, “address_1”: “Arkeologvägen 52”, “address_2”: nil, “city”: “Skillingaryd”, “zip_code”: “56830”, “country”: “SWE”, “ssn”: “192808219691”} |
| 192809162536 | string{“first_name”: “Erik”, “last_name”: “Wadman”, “address_1”: “Myrängsvägen 73 Lgh 1410”, “address_2”: nil, “city”: “Höllviken”, “zip_code”: “23638”, “country”: “SWE”, “ssn”: “192809162536”} |
| 192901107488 | string{“first_name”: “Kristina”, “last_name”: “Lindell”, “address_1”: “Östra Skolgatan 10”, “address_2”: nil, “city”: “Ödeshög”, “zip_code”: “59979”, “country”: “SWE”, “ssn”: “192901107488”} |
| 192901197497 | string{“first_name”: “Gustaf”, “last_name”: “Gustafsson”, “address_1”: “Spireav 1”, “address_2”: nil, “city”: “Stockholm”, “zip_code”: “11254”, “country”: “SWE”, “ssn”: “192901197497”} |
| 195807065627 | string{“first_name”: “Anne Malin”, “last_name”: “Samuelsson”, “address_1”: “Härsbackavägen 69 Lgh 1309”, “address_2”: nil, “city”: “Karlstad”, “zip_code”: “65226”, “country”: “SWE”, “ssn”: “195807065627”} |
Approved persons Norway
| 06073910828 | string{“first_name”: “Tester”, “last_name”: “Person”, “address_1”: “Startveien 56”, “address_2”: null, “city”: “FINNSNES”, “zip_code”: “9300”, “country”: “NOR”, “ssn”: “06073910828”} |
Approved persons Finland
| 071259999M | string{“first_name”: “Dmitri Jonatan”, “last_name”: “Casimirsson”, “address_1”: “Sepänkatu 11 A 1”, “address_2”: null, “city”: “KUOPIO”, “zip_code”: “70100”, “country”: “FIN”, “ssn”: “071259999M”} |
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 |