Initiations

Initiations

Introduction

The A2A Payments API enables software vendors to develop cutting edge Account2Account payment solutions. Vendors can build software solutions (apps) enabling Landsbankinn's customers to pay directly from their accounts. This means that customers will be able, for example, to use an app from the vendor in question to transfer Icelandic krónur (ISK) from a bank account with Landsbankinn to bank accounts with domestic banks, without using other solutions offered by the bank, such as Landsbankinn app, online banking or a payment card.

This is somewhat equivalent to conventional online banking, but with limited payment features and payment rights. In Landsbankinn’s online bank, customers can view granted application accesses and revoke them as well.

The service requires an agreement with Landsbankinn and approval of both Landsbankinn's General Terms and Conditions and this site's Terms of use. Therefore the application to production environment is not automatically approved.

 

Using the API

  • Initially, the customer logs into the software solution and requests an authorization to Landsbankinn‘s service.
  • Once a customer has granted the software solution necessary access, the software utilises the access token for all subsequent actions, including viewing bank accounts and executing payments.
  • The grant lasts for 90 days and after that, a renewal is needed from the customer (step #1).

More information on authentication can be found in the FAQ section.

 

Scopes

The required scopes are:

customer
Authorization to access customer details, such as name and Id.No.
openid
Authorization to verify customer’s identification based on his/her approval.
payments
Authorization to initiate domestic payments from the customer’s bank accounts.
profile
Authorization to access user information, such as age and gender.

 

Required Headers for POST method

The x-request-id header is required to be sent to ensure idempotency of the initiation. In other words, to ensure that identical requests are not processed twice we require unique x-request-id header values within a 24 hours period from each client. If a call to the POST method is made with an x-request-id header that has been used in the last 24 hours by the same client the initiation will not be re-processed but instead the service will return a response with the location of the original payment initiation in the Location header.

X-Request-ID : ID of the request, unique to the call, as determined by the initiating party.
               It should be 1-35 chars in length and match the following regex '^[a-zA-Z0-9]+$'

 

Sandbox functionality

The purpose of the sandbox environment is for developers to be able to try the API before and while they use the API in production. The sandbox environment will be very simple to begin with, it has 6 users:

User Username Kennitala Primary account for payments Secondary account for payments Comment
Jón Gervimaður Gunnarsson JONGUNARS 0101809999 013826010180 015826010180  
Sigurður Gervimaður Ólafsson SIGGIOLAFS 0201809999     Any accounts will not be found
Guðmundur Gervimaður Einarsson GUDEINARS 0301809999 013826030180 015826030180 The primary account will not be of the right type
Guðrún Gervikona Gunnarsdóttir GUDGUNNARS 0401809999 013826040180 015826040180  
Anna Gervikona Einarsdóttir ANNAEINARS 0501809999 013826050180 015826050180 Has used up the daily limit on her primary account
Kristín Gervikona Ólafsdóttir KRISTOLAFS 0601809999 013826060180 015826060180  

 

In general the response to POST requests will be HTTP 201 with the location header with a url to get the initiation "/Payments/Initiations/{apiVersion}/CreditTransfers/BAA1234ABCDE1234"

 

curl -v -X POST https://apisandbox.landsbankinn.is/Payments/Initiations/v1/CreditTransfers \
-H 'Content-Type: application/json' \
-H 'apikey: CxOAVlDYSyw1bIyYbbvCAKVG1zEKp14E' \
-H 'X-Request-ID: 1234' \
-H "Authorization: Bearer $TOKEN" \
-d '{
    "EndToEndIdentification": "sandboxcase0",
    "DebtorAccount": {
        "OwnerId": "0101809999",
        "Id": "013826010180"
    },
    "DepositAccount": {
        "OwnerId": "0101809999",
        "Id": "013826010180"
    },
    "Amount": {
        "Currency": "ISK",
        "Amount": 10
    },
    "ExtendedReference": "extref"
}'
...
< HTTP/1.1 201 Created
< Location: /Payments/Initiations/v1/CreditTransfers/BAA1234ABCDE1234/
...

 

GET requests with id BAA1234ABCDE1234 will return

 

curl -X GET https://apisandbox.landsbankinn.is/Payments/Initiations/v1/CreditTransfers/BAA1234ABCDE1234 \
-H 'Accept: application/json' \
-H 'apikey: CxOAVlDYSyw1bIyYbbvCAKVG1zEKp14E' \
-H 'X-Request-ID: 1234' \
-H "Authorization: Bearer $TOKEN"
{
    "id": "BAA1234ABCDE1234 ",
    "paymentDate": "{{now}}",
    "status": "ACCC"
    "endToEndIdentification": "endToEndId",
    "debtorAccount": {
        "id": "{{id of primary account for calling user}}",
        "ownerId": "{{kennitala of calling user}}"
    },
    "depositAccount": {
        "id": "015826040180",
        "ownerId": "0401809999"
    },
    "amount": {
        "amount": 1,
        "currency": "ISK"
    },
    "extendedReference": "extendedReference",
}

GET requests for status on payment initiations with id BAA1234ABCDE1234 will return "ACCC"

All other GET requests will return 404 Not Found

In addition to validation and authorization errors, we will simulate resource errors happening in 4 cases to begin with:

Case 1
The valid account of SIGGIIOLAFS will not be found.
Case 2
The primary account of GUDEINARS will not be of the right type.
Case 3
All secondary accounts will have zero funds, and therefore return an error.
Case 4
The user ANNAEINARS will have already have used up her daily limit on her primary account.

 

Limitations

The Payment API has the following limitations in place:

  • Maximum payable amount is 200,000 ISK per customer per day (GMT)
    • This amount is global across all solutions that utilize this API
  • Only payable from payment accounts
  • Only domestic payee
  • Only ISK payments

 

List of errors and possible causes

The following are error status codes, descriptions and possible causes. This list can be used to map error codes and for troubleshooting.

Status Code Error Code Message Details
400 BadRequest ERR_80102_000 Your request could not be processed This is a generic error.
  InvalidAccountProduct ERR_80102_100 Invalid account for 3rd party transfer The debtor account(withdrawal account) is not of a valid type to use the payment initiation service.
  NonISKAmount ERR_80102_101 Only ISK payments are supported The currency specified in the request body is not ''ISK'', the Icelandic Króna. The service only supports payments in ISK and will throw this error if any other currency code is sent in the currency code field of the Payment Amount field.
  InvalidInitationId ERR_80102_102 Initiation Id cannot be empty string This error will occur when a GET request is attempted with an empty id parameter. Double-check that the initiation id is included in the request.
  ZeroOrNegativeAmount ERR_80102_103 The payment amount cannot be zero or negative The payment amount feel may not be negative or be zero. Check that the payment amount is correct and try again.
  OverDailyAmount ERR_80102_104 User exceeded daily amount limit This error occurs when the user has exceeded the daily payment limit or will do so by processing the current request.
  AmountUnavailable ERR_80102_105 The payment amount requested is not available in the debtor account This error occurs when the amount available in the debtor (user) account is lower than the requested payment amount.
  RequestIdHeaderMissing ERR_80102_106 x-request-id header is missing from request This error occurs when the x-request-id header is missing from the POST method to initiate payments.
  InvalidRequestHeader ERR_80102_107 x-request-id header is invalid This error occurs when the x-request-id header is invalid in the POST method to initiate payments.
401 Unauthorized ERR_80102_000 You are unauthorized to perform this action This is a generic error. Make sure you include the payments scope in your authorization request. Make sure that the token has not expired.
  AccountAccessDenied ERR_80102_110 Debtor account kennitala does not match user's kennitala This error occurs when the kennitala in the DebtorAccount.OwnerId field does not match the kennitala in the claims sent in the access token. Check that you are using the user's kennitala for the debtor (withdrawal) account.
  NotAuthorizedToPost ERR_80102_111 User is not authorized to create initiation The user is not alowed to use the payment initiation service to initiate new payments.
  NotAuthorizedToGet ERR_80102_112 User is unathorized to get initation When sending a GET request for a specific payment initiation this error occurs when the user associated with the initiation does not match the user claims in the access token. The particular initiation does not belong to the user.
404 NotFound ERR_80102_000 Resource not found This is a generic error.
  InitiationNotFound ERR_80102_120 Initiation not found When performing a GET request, no payment initiation cannot be found that matches the id parameter. Review the parameter and try again.
  DebtorAccountNotFound ERR_80102_121 Debtor account not found The debtor account (withdrawal account) cannot be found. Make sure that the account information is correct and try again.
500 InternalServerError ERR_80102_000 Internal Server Error This is a generic error.

 

Requirements

Technical requirements
The company must demonstrate that the bank's security requirements are met, i.e. by filling out the bank's questionnaire on software security and presenting other data requested by the bank. The company is responsible for ensuring that the information contained in the application for service separation is correct and reliable, and must inform the bank of any changes that may affect the customer's eligibility to fulfill the bank's requirements.
Business requirements
Requirements are according to Landsbankinn’s General Terms and Conditions. The company must therefore meet the same requirements as for the establishment of business with the bank.

 

Disclaimer

The customer base is restricted to individuals only, not companies. The third party is responsible for all actions made with customer’s access in the APIs. The company must ensure the security of information and traceability of user’s transactions performed in accordance with law, terms and conditions of the bank. All security measures are the responsibility of the company.

 

Approval process

The following approval process applies when an app is created using this product:

Sandbox
Auto approved
Production
Manually approved
 

 

Further information

 » Product site (in Icelandic)