NAV
shell javascript python

Introduction

Welcome to Bankson API! This documentation describes the endpoints Bankson offers. Samples for calling the API are given both with raw curl commands as well with the official Node.js.and Python libraries.

You can view code examples in the dark area to the right.

Authentication

To authorize, use this code:

var Client = require('bankson-js');
var client = new Client({
  bearerToken: '4fc79757419b539937b94f1bd0f6e315765bbde4'
});

// Or with API keys

var client = new Client({
  apiKey: '<my-api-key-uuid>',
  privateKey: 'BEGIN RSA PRIVATE KEY....'
});

# With shell, you can just pass the correct header with each request
curl https://api.bankson.fi
  -H "Authorization: Bearer 4fc79757419b539937b94f1bd0f6e315765bbde4"

from bankson import Bankson, RequestError

with open('/path/to/private_key_file') as privatefile:
  keydata = privatefile.read()
client = Bankson(api_key='<api key uuid>', private_key=keydata)

Make sure to replace 4fc79757419b539937b94f1bd0f6e315765bbde4 with the bearer token obtained by Oauth2.

All requests must include the Authorization header to identify the requests. You can either use API keys added per user from settings or using OAuth2.

API Keys

First add API key in Bankson settings. Make sure to save the private key securely, it won’t be stored anywhere by Bankson.

Use the private key to sign the API key for requests. Then add it to Authorization header: Authorization: BanksonRSA ApiKey=<apikey>, Timestamp=<unixepoch>, Signature=<sha256 base64 encoded>

OAuth2

Authorization is based on OAuth2 specification. The grant types used are authorization_code and refresh_token.

The endpoints are https://www.bankson.fi/oauth/authorize for showing the authorization dialog to the user and https://www.bankson.fi/oauth/token for fetching access_token and refresh_token.

Testing

List certificates in test environment

curl "https://api.bankson.fi/api/certificates"
  -H "Authorization: Bearer 4fc79757419b539937b94f1bd0f6e315765bbde4"
  -H "X-Bankson-Environment: Test"

var Client = require('bankson-js');
var client = new Client({
  bearerToken: '4fc79757419b539937b94f1bd0f6e315765bbde4',
  test: true
});
client.certificates.fetch().then(function(certificates) {
  // Do something with certificates
});

from bankson import Bankson, RequestError

with open('/path/to/private_key_file') as privatefile:
  keydata = privatefile.read()
client = Bankson(api_key='<api key uuid>', private_key=keydata, test=True)

Bankson has two environments, test and production. Both environments contain their own resources. When using test environment certificates all requests to banks are routed to the test environments provided by the banks. This way you can test integrations without using your actual bank account and money.

Make sure to specify X-Bankson-Environment header with the value Test to make bankson use test data.

User information

Get user information

curl "https://api.bankson.fi/me"
  -H "Authorization: Bearer 4fc79757419b539937b94f1bd0f6e315765bbde4"

var Client = require('bankson-js');
var client = new Client({
  bearerToken: '4fc79757419b539937b94f1bd0f6e315765bbde4'
});
client.me().then(function(resp) {
  console.log('Current user', resp.user);
});

from bankson import Bankson, RequestError

with open('/path/to/private_key_file') as privatefile:
  keydata = privatefile.read()
client = Bankson(api_key='<api key uuid>', private_key=keydata)
client.me()

The above command returns JSON structured like this:

{
  "user": {
    "id": 1,
    "environment_id": 1,
    "email": "john@example.com",
    "name": "John Doe",
    "created_at":"2016-05-23T21:08:16.211Z",
    "updated_at":"2016-05-23T21:08:16.211Z"
  },
  "environment": {
    "id": 1,
    "name": "Example Oy",
    "business_id": "1234567-1",
    "created_at": "2016-05-23T21:08:16.128Z",
    "updated_at": "2016-05-23T21:08:16.128Z",
    "bankAccounts": [{
      "id": 1,
      "certificate_id": 1,
      "environment_id": 1,
      "iban": "FI4819503000000010",
      "bic": "NDEAFIHH",
      "contract_id": "11111111",
      "created_at":"2016-05-23T21:08:16.503Z",
      "updated_at":"2016-05-23T21:08:16.503Z",
      "balance": null,
      "balance_date": null,
      "test": true
    }],
    "subscription": false
  }
}

This endpoint shows information about the logged in user and associated organization.

HTTP Request

GET https://api.bankson.fi/me

Certificates

Certificates are used to communicate and authenticate to bank API’s.

List certificates

curl "https://api.bankson.fi/certificates"
  -H "Authorization: Bearer 4fc79757419b539937b94f1bd0f6e315765bbde4"

var Client = require('bankson-js');
var client = new Client({
  bearerToken: '4fc79757419b539937b94f1bd0f6e315765bbde4'
});
client.certificates.fetch().then(function(certificates) {
  // do something with certificates
});

from bankson import Bankson, RequestError

with open('/path/to/private_key_file') as privatefile:
  keydata = privatefile.read()
client = Bankson(api_key='<api key uuid>', private_key=keydata)
client.certirifcates.list()

JSON response

[{
  "id": 1,
  "environment_id": 1,
  "bank_customer_id": "11111111",
  "bank_target_id": "11111111A1",
  "bic": "NDEAFIHH",
  "certificate_type": "signing",
  "created_at": "2016-05-23T21:08:16.493Z",
  "updated_at": "2016-05-23T21:08:16.493Z",
  "test": true,
  "not_after": "2017-04-16T09:04:04.000Z",
  "not_before": "2015-04-16T09:04:04.000Z",
  "subject": "C=FI/CN=Nordea Demo Certificate/serialName=5780860238"
}]

Returns a list of all certificates associated with the organization.

HTTP Request

GET https://api.bankson.fi/certificates

Upload certificate

curl "https://api.bankson.fi/certificates/upload" -X POST
  -H "Authorization: Bearer 4fc79757419b539937b94f1bd0f6e315765bbde4"
  -H "Content-Type: multipart/form-data"
  -F customer_id=11111111
  -F target_id=11111111A1
  -F pin=WSNDEA1234
  -F bic=NDEAFIHH
  -F certificate=@WSNDEA1234.p12

var Client = require('bankson-js')
  , fs = require('fs');

var client = new Client({
  bearerToken: '4fc79757419b539937b94f1bd0f6e315765bbde4'
});
client.certificates.upload(
  fs.createReadStream('WSNDEA1234.p12'),
  { customer_id: '11111111', target_id: '11111111A1', pin: 'WSNDEA1234', bic: 'NDEAFIHH' }
}).then(function(certificate) {
  // certificate uploaded
});

from bankson import Bankson, RequestError

with open('/path/to/private_key_file') as privatefile:
  keydata = privatefile.read()
client = Bankson(api_key='<api key uuid>', private_key=keydata)
client.certificates.upload(open('WSNDEA1234.p12', 'rb'), { 'customer_id': '11111111', 'target_id': '11111111A1', 'pin': 'WSNDEA1234', 'bic': 'NDEAFIHH' })

JSON response, http status code 201 Created

{
  "id": 1,
  "environment_id": 1,
  "bank_customer_id": "11111111",
  "bank_target_id": "11111111A1",
  "bic": "NDEAFIHH",
  "certificate_type": "signing",
  "created_at": "2016-05-23T21:08:16.493Z",
  "updated_at": "2016-05-23T21:08:16.493Z",
  "test": true,
  "not_after": "2017-04-16T09:04:04.000Z",
  "not_before": "2015-04-16T09:04:04.000Z",
  "subject": "C=FI/CN=Nordea Demo Certificate/serialName=5780860238"
}

Upload a .p12 bundle containing the certificate used for signing bank requests.

HTTP request

POST https://api.bankson.fi/certificates/upload

Form parameters

Parameter Description
customer_id The id number given by your bank
target_id [optional] Used by some banks to further identify users
pin Pin code of the .p12 bundle
bic The BIC code of the bank
certificate the actual .p12 file

Request certificate from bank

curl "https://api.bankson.fi/certificates/request" -X POST
  -H "Authorization: Bearer 4fc79757419b539937b94f1bd0f6e315765bbde4"
  -H "Content-Type: application/json"
  -d '{ "customer_id": "11111111", "target_id": "11111111A1", "transfer_key1": "1234567890", "bic": "NDEAFIHH" }'

var Client = require('bankson-js');
var client = new Client({
  bearerToken: '4fc79757419b539937b94f1bd0f6e315765bbde4'
});
client.certificates.request({
  customer_id: '11111111',
  target_id: '11111111A1',
  transfer_key1: '1234567890',
  bic: 'NDEAFIHH'
}).then(function(certificates) {
  // might be multiple certificates
});

from bankson import Bankson, RequestError

with open('/path/to/private_key_file') as privatefile:
  keydata = privatefile.read()
client = Bankson(api_key='<api key uuid>', private_key=keydata)
client.certificates.request({
    'customer_id': '11111111',
    'target_id': '11111111A1',
    'transfer_key1': '1234567890',
    'bic': 'NDEAFIHH'
})

JSON response, http status code 201 Created

[{
  "certificate_type": "signing",
  "environment_id": 1,
  "bank_customer_id": "11111111",
  "bank_target_id": "11111111A1",
  "bic": "NDEAFIHH",
  "test": true,
  "updated_at": "2016-05-24T20:59:32.564Z",
  "created_at": "2016-05-24T20:59:32.564Z",
  "id": 4,
  "not_after": "2012-04-01T07:45:35.000Z",
  "not_before":"2010-04-01T07:45:35.000Z",
  "subject": "C=FI/CN=eid onfile/serialName=2094370004"
}]

Request certificate from bank by using transfer keys provided by the bank

HTTP request

POST https://api.bankson.fi/certificates/request

JSON parameters

Parameter Description
customer_id The id number given by your bank
target_id [optional] Used by some banks to further identify users
transfer_key1 Transfer key (part1) or PIN code
transfer_key2 Trasnfer key (part2), if available
bic The BIC code of the bank

Return value

Returns a list of certificates created by the request

Delete certificate

curl "https:/api.bankson.fi/certificates/2" -X DELETE
  -H "Authorization: Bearer 4fc79757419b539937b94f1bd0f6e315765bbde4"

var Client = require('bankson-js');
var client = new Client({
  bearerToken: '4fc79757419b539937b94f1bd0f6e315765bbde4'
});
client.certificates.remove(2).then(function() {
  // certificate deleted
});

from bankson import Bankson, RequestError

with open('/path/to/private_key_file') as privatefile:
  keydata = privatefile.read()
client = Bankson(api_key='<api key uuid>', private_key=keydata)
client.certificates.remove(2)

Empty response, http status code 204 No content

Delete certificate from Bankson

HTTP request

DELETE https://api.bankson.fi/certificates/:id

Renew certificate

curl "https:/api.bankson.fi/certificates/4/renew" -X POST
  -H "Authorization: Bearer 4fc79757419b539937b94f1bd0f6e315765bbde4"

var Client = require('bankson-js');
var client = new Client({
  bearerToken: '4fc79757419b539937b94f1bd0f6e315765bbde4'
});
client.certificates.renew(4).then(function(certificate) {
  // Certificate renewed
});

// If certificate has already expired, provide new transferkeys as second parameter to renew()

from bankson import Bankson, RequestError

with open('/path/to/private_key_file') as privatefile:
  keydata = privatefile.read()
client = Bankson(api_key='<api key uuid>', private_key=keydata)
client.certificates.renew(4)

JSON response

{
  "certificate_type": "signing",
  "environment_id": 1,
  "bank_customer_id": "11111111",
  "bank_target_id": "11111111A1",
  "bic": "NDEAFIHH",
  "test": true,
  "updated_at": "2016-05-24T20:59:32.564Z",
  "created_at": "2016-05-24T20:59:32.564Z",
  "id": 4,
  "not_after": "2012-04-01T07:45:35.000Z",
  "not_before":"2010-04-01T07:45:35.000Z",
  "subject": "C=FI/CN=eid onfile/serialName=2094370004"
}

Renew certificate already expired or nearing expiration.

If the certificate has not yet expired, this request can be called with an empty body and the certificate will be renewed by using the certificate itself to sign the request.

If the certificate already has expired, you need to obtain new transfer keys from the bank to re-request the certificate.

HTTP request

POST https://api.bankson.fi/certificates/:id/renew

JSON attributes

(Only needed to renew an expired certificate)

Parameter Description
customer_id The id number given by your bank
transfer_key1 Transfer key (part1) or PIN code
transfer_key2 Trasnfer key (part2), if available

Bank accounts

List bank accounts

curl "https://api.bankson.fi/bankaccounts"
  -H "Authorization: Bearer 4fc79757419b539937b94f1bd0f6e315765bbde4"

var Client = require('bankson-js');
var client = new Client({
  bearerToken: '4fc79757419b539937b94f1bd0f6e315765bbde4'
});
client.bankAccounts.fetch().then(function(bankAccounts) {
  // List
});

from bankson import Bankson, RequestError

with open('/path/to/private_key_file') as privatefile:
  keydata = privatefile.read()
client = Bankson(api_key='<api key uuid>', private_key=keydata)
client.bankaccounts.list()

JSON response

[{
  "id": 1,
  "certificate_id": 1,
  "environment_id": 1,
  "iban": "FI4819503000000010",
  "bic": "NDEAFIHH",
  "contract_id": "11111111",
  "created_at": "2016-05-23T21:08:16.503Z",
  "updated_at":"2016-05-23T21:08:16.503Z",
  "balance": null,
  "balance_date": null,
  "test":true
}]

List all bank accounts known to Bankson.

HTTP request

GET https://api.bankson.fi/bankaccounts

Add bank account

curl "https://api.bankson.fi/bankaccounts" -X POST
  -H "Authorization: Bearer 4fc79757419b539937b94f1bd0f6e315765bbde4"
  -H "Content-Type: application/json"
  -d '{ "bic": "NDEAFIHH", "iban": "FI4819503000000010", "certificate_id": 1, "contract_id": "1234" }'

var Client = require('bankson-js');
var client = new Client({
  bearerToken: '4fc79757419b539937b94f1bd0f6e315765bbde4'
});
client.bankAccounts.create({
  bic: 'NDEAFIHH',
  iban: 'FI4819503000000010',
  certificate_id: 1,
  contract_id: '1234'
});

from bankson import Bankson, RequestError

with open('/path/to/private_key_file') as privatefile:
  keydata = privatefile.read()
client = Bankson(api_key='<api key uuid>', private_key=keydata)
client.bankaccounts.create({ 'bic': 'NDEAFIHH', 'iban': 'FI4819503000000010', 'certificate_id': 1, 'contract_id': '1234' })

JSON response

{
  "id": 5,
  "certificate_id": 1,
  "environment_id": 1,
  "iban": "FI4819503000000010",
  "bic": "NDEAFIHH",
  "contract_id": "11111111",
  "created_at": "2016-05-23T21:08:16.503Z",
  "updated_at":"2016-05-23T21:08:16.503Z",
  "balance": null,
  "balance_date": null,
  "test":true
}

Creates a new bank account and associates it with a certificate.

HTTP Request

POST https://api.bankson.fi/bankaccounts

JSON parameters

Parameter Description
bic BIC code of bank
iban IBAN of the account to be added
certificate_id id of the certificate associated by
contract_id The identification given by the bank for services like CAMT

Delete bank account

curl "https://api.bankson.fi/bankaccounts/5" -X DELETE
  -H "Authorization: Bearer 4fc79757419b539937b94f1bd0f6e315765bbde4"

var Client = require('bankson-js');
var client = new Client({
  bearerToken: '4fc79757419b539937b94f1bd0f6e315765bbde4'
});
client.bankAccounts.remove(5).then(function() {
  // Bank accoutn deleted
});

from bankson import Bankson, RequestError

with open('/path/to/private_key_file') as privatefile:
  keydata = privatefile.read()
client = Bankson(api_key='<api key uuid>', private_key=keydata)
client.bankaccounts.remove(5)

Empty response, HTTP Status code 204

Deletes a bank account.

HTTP Request

DELETE https://api.bankson.fi/bankaccounts/:id

Bank account statements

List statements

curl "https://api.bankson.fi/bankaccountstatements"
  -H "Authorization: Bearer 4fc79757419b539937b94f1bd0f6e315765bbde4"

var Client = require('bankson-js');
var client = new Client({
  bearerToken: '4fc79757419b539937b94f1bd0f6e315765bbde4'
});
client.bankAccountStatements.fetch().then(function(statements) {
  // Do something
});

from bankson import Bankson, RequestError

with open('/path/to/private_key_file') as privatefile:
  keydata = privatefile.read()
client = Bankson(api_key='<api key uuid>', private_key=keydata)
client.bankaccountstatements.list()

JSON response

[
  {
    "id":1,
    "environment_id":1,
    "bank_account_id":1,
    "from":"2006-03-02T22:00:00.000Z",
    "to":"2006-03-02T22:00:00.000Z",
    "legal_sequence_number":"043",
    "entries":[
      {
        "entry_reference":1,
        "archive_id":"060303258877C24002",
        "booking_date":"2006-03-03",
        "value_date":"2006-03-06",
        "payment_date":"2006-03-03",
        "booking_information":"710Pano",
        "amount":2205.6,
        "receiver":"RUUVI JA MUTTERI",
        "receiver_account":"",
        "reference_number":"",
        "additional_information":[

        ]
      },
      {
        "entry_reference":1,
        "archive_id":"",
        "booking_date":"2006-03-03",
        "value_date":"0000-00-00",
        "payment_date":"2006-03-03",
        "booking_information":"710Hyvityslasku",
        "amount":-3205.6,
        "receiver":"RUUVI JA MUTTERI",
        "receiver_account":"",
        "reference_number":"",
        "additional_information":[
          "HYVITYSLASKU 2425"
        ]
      },
      {
        "entry_reference":1,
        "archive_id":"",
        "booking_date":"2006-03-03",
        "value_date":"0000-00-00",
        "payment_date":"2006-03-03",
        "booking_information":"710Lasku",
        "amount":3200,
        "receiver":"RUUVI JA MUTTERI",
        "receiver_account":"",
        "reference_number":"800056124147",
        "additional_information":[

        ]
      },
      {
        "entry_reference":1,
        "archive_id":"",
        "booking_date":"2006-03-03",
        "value_date":"0000-00-00",
        "payment_date":"2006-03-03",
        "booking_information":"710Lasku",
        "amount":2211.2,
        "receiver":"RUUVI JA MUTTERI",
        "receiver_account":"",
        "reference_number":"800056124150",
        "additional_information":[

        ]
      },
      {
        "entry_reference":2,
        "archive_id":"060303258877A26324",
        "booking_date":"2006-03-03",
        "value_date":"2006-03-06",
        "payment_date":"2006-03-03",
        "booking_information":"710Pano",
        "amount":3695,
        "receiver":"LUMILINNA KY",
        "receiver_account":"",
        "reference_number":"",
        "additional_information":[

        ]
      },
      {
        "entry_reference":3,
        "archive_id":"060303258877A22357",
        "booking_date":"2006-03-03",
        "value_date":"2006-03-06",
        "payment_date":"2006-03-03",
        "booking_information":"710Pano",
        "amount":2229.3,
        "receiver":"PELTOLA PEKKA OY",
        "receiver_account":"",
        "reference_number":"",
        "additional_information":[
          "LASKUT 3278/3251/4836"
        ]
      },
      {
        "entry_reference":4,
        "archive_id":"0603032584SM020048",
        "booking_date":"2006-03-03",
        "value_date":"2006-03-02",
        "payment_date":"2006-03-03",
        "booking_information":"780Zero Balancing",
        "amount":10364.87,
        "receiver":"ABC-KONSERNI",
        "receiver_account":"",
        "reference_number":"",
        "additional_information":[
          "CMZ/0036540000 /5400"
        ]
      },
      {
        "entry_reference":5,
        "archive_id":"0603032588WWNG0370",
        "booking_date":"2006-03-03",
        "value_date":"2006-03-06",
        "payment_date":"2006-03-03",
        "booking_information":"710Pano",
        "amount":256.75,
        "receiver":"PELTOLA LIISA",
        "receiver_account":"",
        "reference_number":"",
        "additional_information":[
          "LASKU 3265/HYVITYSLASKU 777"
        ]
      },
      {
        "entry_reference":6,
        "archive_id":"0603032584SM010117",
        "booking_date":"2006-03-03",
        "value_date":"2006-03-03",
        "payment_date":"2006-03-03",
        "booking_information":"710Nordea maksu",
        "amount":1130.91,
        "receiver":"US IRON AND STEEL",
        "receiver_account":"",
        "reference_number":"",
        "additional_information":[
          "2584SMM0849971 /RFB/WT0000626289 000049302611118 MAKSAJAN ILMOITTAMA SAAJAN NIMI: NORTH CASTLE'S IRONHOUSE TORPANKATU 1111 PL 999 99999 POHJANLINNA FINLAND",
          "LÄHETTÄJÄN OSOITE: 1239 EAST CIRCLESTREET PO BOX55/5 8877"
        ]
      },
      {
        "entry_reference":7,
        "archive_id":"060303258873A20009",
        "booking_date":"2006-03-03",
        "value_date":"2006-03-06",
        "payment_date":"2006-03-03",
        "booking_information":"704Suoraveloituspalvelu",
        "amount":2120.68,
        "receiver":"",
        "receiver_account":"",
        "reference_number":"",
        "additional_information":[

        ]
      },
      {
        "entry_reference":8,
        "archive_id":"060303258874A35319",
        "booking_date":"2006-03-03",
        "value_date":"2006-03-06",
        "payment_date":"2006-03-03",
        "booking_information":"703Maksupäätepalvelu",
        "amount":5219,
        "receiver":"POHJANLINNAN RAUTATALO",
        "receiver_account":"",
        "reference_number":"",
        "additional_information":[
          "OSTOT    111 KPL            5219,00 OIK.       0 KPL               0,00",
          "TILITYSERÄ 0120070"
        ]
      },
      {
        "entry_reference":9,
        "archive_id":"0603032584LV143623",
        "booking_date":"2006-03-03",
        "value_date":"2006-03-03",
        "payment_date":"2006-03-03",
        "booking_information":"720Tilisiirto",
        "amount":-81.1,
        "receiver":"ABC-KONSERNI",
        "receiver_account":"19503000001414",
        "reference_number":"",
        "additional_information":[
          "00000324510099418709",
          "001311     REC:5",
          "MAKSAJAN ILMOITTAMA SAAJAN NIMI: C/O ABCDEF GROUP OY"
        ]
      }
    ],
    "balances":[
      {
        "booking_date":"2006-03-02",
        "amount":30838.49
      },
      {
        "bookingDate":"2006-03-03",
        "amount":4409.27,
        "availableAmount":0
      }
    ],
    "created_at":"2016-05-24T22:45:48.672Z",
    "updated_at":"2016-05-24T22:45:48.672Z",
    "servicer_name":"Nordea Pankki Suomi Oyj Y-tunn 1680235-8",
    "servicer_bic":"NDEAFIHH",
    "account_owner_name":"POHJANLINNAN RAUTATALO",
    "currency":"EUR",
    "test":true,
    "bank_account":{
      "id":1,
      "certificate_id":1,
      "environment_id":1,
      "iban":"FI4819503000000010",
      "bic":"NDEAFIHH",
      "contract_id":"11111111",
      "created_at":"2016-05-23T21:08:16.503Z",
      "updated_at":"2016-05-23T21:08:16.503Z",
      "balance":null,
      "balance_date":null,
      "test":true
    }
  }
]

Fetches bank account statements from Bankson

HTTP request

GET https://api.bankson.fi/bankaccountstatements

Fetch bank account statements from bank

curl "https://api.bankson.fi/bankaccountstatements" -X POST
  -H "Authorization: Beare 4fc79757419b539937b94f1bd0f6e315765bbde4"
  -H "Content-Type: application/json"
  -d '{ "certificate_id": 1 }'

var Client = require('bankson-js');
var client = new Client({
  bearerToken: '4fc79757419b539937b94f1bd0f6e315765bbde4'
});
var certificateId = 1;
client.bankAccountStatements.refresh(certificateId).then(function(statements) {
  console.log('new statements', statements);
});

from bankson import Bankson, RequestError

with open('/path/to/private_key_file') as privatefile:
  keydata = privatefile.read()
client = Bankson(api_key='<api key uuid>', private_key=keydata)
certificate_id = 1
client.bankaccountstatements.refresh(certificate_id)

JSON response

[
  {
    "id":1,
    "environment_id":1,
    "bank_account_id":1,
    "from":"2006-03-02T22:00:00.000Z",
    "to":"2006-03-02T22:00:00.000Z",
    "legal_sequence_number":"043",
    "entries":[
      {
        "entry_reference":1,
        "archive_id":"060303258877C24002",
        "booking_date":"2006-03-03",
        "value_date":"2006-03-06",
        "payment_date":"2006-03-03",
        "booking_information":"710Pano",
        "amount":2205.6,
        "receiver":"RUUVI JA MUTTERI",
        "receiver_account":"",
        "reference_number":"",
        "additional_information":[

        ]
      },
      {
        "entry_reference":1,
        "archive_id":"",
        "booking_date":"2006-03-03",
        "value_date":"0000-00-00",
        "payment_date":"2006-03-03",
        "booking_information":"710Hyvityslasku",
        "amount":-3205.6,
        "receiver":"RUUVI JA MUTTERI",
        "receiver_account":"",
        "reference_number":"",
        "additional_information":[
          "HYVITYSLASKU 2425"
        ]
      },
      {
        "entry_reference":1,
        "archive_id":"",
        "booking_date":"2006-03-03",
        "value_date":"0000-00-00",
        "payment_date":"2006-03-03",
        "booking_information":"710Lasku",
        "amount":3200,
        "receiver":"RUUVI JA MUTTERI",
        "receiver_account":"",
        "reference_number":"800056124147",
        "additional_information":[

        ]
      },
      {
        "entry_reference":1,
        "archive_id":"",
        "booking_date":"2006-03-03",
        "value_date":"0000-00-00",
        "payment_date":"2006-03-03",
        "booking_information":"710Lasku",
        "amount":2211.2,
        "receiver":"RUUVI JA MUTTERI",
        "receiver_account":"",
        "reference_number":"800056124150",
        "additional_information":[

        ]
      },
      {
        "entry_reference":2,
        "archive_id":"060303258877A26324",
        "booking_date":"2006-03-03",
        "value_date":"2006-03-06",
        "payment_date":"2006-03-03",
        "booking_information":"710Pano",
        "amount":3695,
        "receiver":"LUMILINNA KY",
        "receiver_account":"",
        "reference_number":"",
        "additional_information":[

        ]
      },
      {
        "entry_reference":3,
        "archive_id":"060303258877A22357",
        "booking_date":"2006-03-03",
        "value_date":"2006-03-06",
        "payment_date":"2006-03-03",
        "booking_information":"710Pano",
        "amount":2229.3,
        "receiver":"PELTOLA PEKKA OY",
        "receiver_account":"",
        "reference_number":"",
        "additional_information":[
          "LASKUT 3278/3251/4836"
        ]
      },
      {
        "entry_reference":4,
        "archive_id":"0603032584SM020048",
        "booking_date":"2006-03-03",
        "value_date":"2006-03-02",
        "payment_date":"2006-03-03",
        "booking_information":"780Zero Balancing",
        "amount":10364.87,
        "receiver":"ABC-KONSERNI",
        "receiver_account":"",
        "reference_number":"",
        "additional_information":[
          "CMZ/0036540000 /5400"
        ]
      },
      {
        "entry_reference":5,
        "archive_id":"0603032588WWNG0370",
        "booking_date":"2006-03-03",
        "value_date":"2006-03-06",
        "payment_date":"2006-03-03",
        "booking_information":"710Pano",
        "amount":256.75,
        "receiver":"PELTOLA LIISA",
        "receiver_account":"",
        "reference_number":"",
        "additional_information":[
          "LASKU 3265/HYVITYSLASKU 777"
        ]
      },
      {
        "entry_reference":6,
        "archive_id":"0603032584SM010117",
        "booking_date":"2006-03-03",
        "value_date":"2006-03-03",
        "payment_date":"2006-03-03",
        "booking_information":"710Nordea maksu",
        "amount":1130.91,
        "receiver":"US IRON AND STEEL",
        "receiver_account":"",
        "reference_number":"",
        "additional_information":[
          "2584SMM0849971 /RFB/WT0000626289 000049302611118 MAKSAJAN ILMOITTAMA SAAJAN NIMI: NORTH CASTLE'S IRONHOUSE TORPANKATU 1111 PL 999 99999 POHJANLINNA FINLAND",
          "LÄHETTÄJÄN OSOITE: 1239 EAST CIRCLESTREET PO BOX55/5 8877"
        ]
      },
      {
        "entry_reference":7,
        "archive_id":"060303258873A20009",
        "booking_date":"2006-03-03",
        "value_date":"2006-03-06",
        "payment_date":"2006-03-03",
        "booking_information":"704Suoraveloituspalvelu",
        "amount":2120.68,
        "receiver":"",
        "receiver_account":"",
        "reference_number":"",
        "additional_information":[

        ]
      },
      {
        "entry_reference":8,
        "archive_id":"060303258874A35319",
        "booking_date":"2006-03-03",
        "value_date":"2006-03-06",
        "payment_date":"2006-03-03",
        "booking_information":"703Maksupäätepalvelu",
        "amount":5219,
        "receiver":"POHJANLINNAN RAUTATALO",
        "receiver_account":"",
        "reference_number":"",
        "additional_information":[
          "OSTOT    111 KPL            5219,00 OIK.       0 KPL               0,00",
          "TILITYSERÄ 0120070"
        ]
      },
      {
        "entry_reference":9,
        "archive_id":"0603032584LV143623",
        "booking_date":"2006-03-03",
        "value_date":"2006-03-03",
        "payment_date":"2006-03-03",
        "booking_information":"720Tilisiirto",
        "amount":-81.1,
        "receiver":"ABC-KONSERNI",
        "receiver_account":"19503000001414",
        "reference_number":"",
        "additional_information":[
          "00000324510099418709",
          "001311     REC:5",
          "MAKSAJAN ILMOITTAMA SAAJAN NIMI: C/O ABCDEF GROUP OY"
        ]
      }
    ],
    "balances":[
      {
        "booking_date":"2006-03-02",
        "amount":30838.49
      },
      {
        "bookingDate":"2006-03-03",
        "amount":4409.27,
        "availableAmount":0
      }
    ],
    "created_at":"2016-05-24T22:45:48.672Z",
    "updated_at":"2016-05-24T22:45:48.672Z",
    "servicer_name":"Nordea Pankki Suomi Oyj Y-tunn 1680235-8",
    "servicer_bic":"NDEAFIHH",
    "account_owner_name":"POHJANLINNAN RAUTATALO",
    "currency":"EUR",
    "test":true,
    "bank_account":{
      "id":1,
      "certificate_id":1,
      "environment_id":1,
      "iban":"FI4819503000000010",
      "bic":"NDEAFIHH",
      "contract_id":"11111111",
      "created_at":"2016-05-23T21:08:16.503Z",
      "updated_at":"2016-05-23T21:08:16.503Z",
      "balance":null,
      "balance_date":null,
      "test":true
    }
  }
]

Updates bank account statements from the bank

HTTP request

POST https://api.bankson.fi/bankaccountstatments

JSON params

Parameter Description
certificate_id The certificate to use for bank acount statement refresh

Show single statement

curl "https://api.bankson.fi/bankaccountstatements/12"
  -H "Accept: application/json"

var Client = require('bankson-js');
var client = new Client({
  bearerToken: '4fc79757419b539937b94f1bd0f6e315765bbde4'
});
client.bankAccountStatements.statementXml(12).then(function(xmlBuffer) {
});
// client.bankAccountStatements.statementHtml(12)...
// client.bankAccountStatements.statementText(12)...
// client.bankAccountStatements.statementPdf(12)...

from bankson import Bankson, RequestError

with open('/path/to/private_key_file') as privatefile:
  keydata = privatefile.read()
client = Bankson(api_key='<api key uuid>', private_key=keydata)
client.bankaccountstatments.get(12) # json output
client.bankaccountstatments.get(12, 'xml') # XML (if applicable)
client.bankaccountstatments.get(12, 'html') # HTML output
client.bankaccountstatments.get(12, 'pdf').# PDF output
client.bankaccountstatments.get(12, 'text') # TEXT (if applicable)

JSON response

{
    "id":1,
    "environment_id":1,
    "bank_account_id":1,
    "from":"2006-03-02T22:00:00.000Z",
    "to":"2006-03-02T22:00:00.000Z",
    "legal_sequence_number":"043",
    "entries":[
      {
        "entry_reference":1,
        "archive_id":"060303258877C24002",
        "booking_date":"2006-03-03",
        "value_date":"2006-03-06",
        "payment_date":"2006-03-03",
        "booking_information":"710Pano",
        "amount":2205.6,
        "receiver":"RUUVI JA MUTTERI",
        "receiver_account":"",
        "reference_number":"",
        "additional_information":[

        ]
      },
      {
        "entry_reference":1,
        "archive_id":"",
        "booking_date":"2006-03-03",
        "value_date":"0000-00-00",
        "payment_date":"2006-03-03",
        "booking_information":"710Hyvityslasku",
        "amount":-3205.6,
        "receiver":"RUUVI JA MUTTERI",
        "receiver_account":"",
        "reference_number":"",
        "additional_information":[
          "HYVITYSLASKU 2425"
        ]
      },
      {
        "entry_reference":1,
        "archive_id":"",
        "booking_date":"2006-03-03",
        "value_date":"0000-00-00",
        "payment_date":"2006-03-03",
        "booking_information":"710Lasku",
        "amount":3200,
        "receiver":"RUUVI JA MUTTERI",
        "receiver_account":"",
        "reference_number":"800056124147",
        "additional_information":[

        ]
      },
      {
        "entry_reference":1,
        "archive_id":"",
        "booking_date":"2006-03-03",
        "value_date":"0000-00-00",
        "payment_date":"2006-03-03",
        "booking_information":"710Lasku",
        "amount":2211.2,
        "receiver":"RUUVI JA MUTTERI",
        "receiver_account":"",
        "reference_number":"800056124150",
        "additional_information":[

        ]
      },
      {
        "entry_reference":2,
        "archive_id":"060303258877A26324",
        "booking_date":"2006-03-03",
        "value_date":"2006-03-06",
        "payment_date":"2006-03-03",
        "booking_information":"710Pano",
        "amount":3695,
        "receiver":"LUMILINNA KY",
        "receiver_account":"",
        "reference_number":"",
        "additional_information":[

        ]
      },
      {
        "entry_reference":3,
        "archive_id":"060303258877A22357",
        "booking_date":"2006-03-03",
        "value_date":"2006-03-06",
        "payment_date":"2006-03-03",
        "booking_information":"710Pano",
        "amount":2229.3,
        "receiver":"PELTOLA PEKKA OY",
        "receiver_account":"",
        "reference_number":"",
        "additional_information":[
          "LASKUT 3278/3251/4836"
        ]
      },
      {
        "entry_reference":4,
        "archive_id":"0603032584SM020048",
        "booking_date":"2006-03-03",
        "value_date":"2006-03-02",
        "payment_date":"2006-03-03",
        "booking_information":"780Zero Balancing",
        "amount":10364.87,
        "receiver":"ABC-KONSERNI",
        "receiver_account":"",
        "reference_number":"",
        "additional_information":[
          "CMZ/0036540000 /5400"
        ]
      },
      {
        "entry_reference":5,
        "archive_id":"0603032588WWNG0370",
        "booking_date":"2006-03-03",
        "value_date":"2006-03-06",
        "payment_date":"2006-03-03",
        "booking_information":"710Pano",
        "amount":256.75,
        "receiver":"PELTOLA LIISA",
        "receiver_account":"",
        "reference_number":"",
        "additional_information":[
          "LASKU 3265/HYVITYSLASKU 777"
        ]
      },
      {
        "entry_reference":6,
        "archive_id":"0603032584SM010117",
        "booking_date":"2006-03-03",
        "value_date":"2006-03-03",
        "payment_date":"2006-03-03",
        "booking_information":"710Nordea maksu",
        "amount":1130.91,
        "receiver":"US IRON AND STEEL",
        "receiver_account":"",
        "reference_number":"",
        "additional_information":[
          "2584SMM0849971 /RFB/WT0000626289 000049302611118 MAKSAJAN ILMOITTAMA SAAJAN NIMI: NORTH CASTLE'S IRONHOUSE TORPANKATU 1111 PL 999 99999 POHJANLINNA FINLAND",
          "LÄHETTÄJÄN OSOITE: 1239 EAST CIRCLESTREET PO BOX55/5 8877"
        ]
      },
      {
        "entry_reference":7,
        "archive_id":"060303258873A20009",
        "booking_date":"2006-03-03",
        "value_date":"2006-03-06",
        "payment_date":"2006-03-03",
        "booking_information":"704Suoraveloituspalvelu",
        "amount":2120.68,
        "receiver":"",
        "receiver_account":"",
        "reference_number":"",
        "additional_information":[

        ]
      },
      {
        "entry_reference":8,
        "archive_id":"060303258874A35319",
        "booking_date":"2006-03-03",
        "value_date":"2006-03-06",
        "payment_date":"2006-03-03",
        "booking_information":"703Maksupäätepalvelu",
        "amount":5219,
        "receiver":"POHJANLINNAN RAUTATALO",
        "receiver_account":"",
        "reference_number":"",
        "additional_information":[
          "OSTOT    111 KPL            5219,00 OIK.       0 KPL               0,00",
          "TILITYSERÄ 0120070"
        ]
      },
      {
        "entry_reference":9,
        "archive_id":"0603032584LV143623",
        "booking_date":"2006-03-03",
        "value_date":"2006-03-03",
        "payment_date":"2006-03-03",
        "booking_information":"720Tilisiirto",
        "amount":-81.1,
        "receiver":"ABC-KONSERNI",
        "receiver_account":"19503000001414",
        "reference_number":"",
        "additional_information":[
          "00000324510099418709",
          "001311     REC:5",
          "MAKSAJAN ILMOITTAMA SAAJAN NIMI: C/O ABCDEF GROUP OY"
        ]
      }
    ],
    "balances":[
      {
        "booking_date":"2006-03-02",
        "amount":30838.49
      },
      {
        "bookingDate":"2006-03-03",
        "amount":4409.27,
        "availableAmount":0
      }
    ],
    "created_at":"2016-05-24T22:45:48.672Z",
    "updated_at":"2016-05-24T22:45:48.672Z",
    "servicer_name":"Nordea Pankki Suomi Oyj Y-tunn 1680235-8",
    "servicer_bic":"NDEAFIHH",
    "account_owner_name":"POHJANLINNAN RAUTATALO",
    "currency":"EUR",
    "test":true,
    "bank_account":{
      "id":1,
      "certificate_id":1,
      "environment_id":1,
      "iban":"FI4819503000000010",
      "bic":"NDEAFIHH",
      "contract_id":"11111111",
      "created_at":"2016-05-23T21:08:16.503Z",
      "updated_at":"2016-05-23T21:08:16.503Z",
      "balance":null,
      "balance_date":null,
      "test":true
    }
  }

Shows one statement. You can use the Accept header to control the output format. Valid values are:

HTTP request

GET https://api.bankson.fi/bankaccountstatements/:id

Payments

List payments

curl "https://api.bankson.fi/payments"
  -H "Authorization: Bearer 4fc79757419b539937b94f1bd0f6e315765bbde4"

var Client = require('bankson-js');
var client = new Client({
  bearerToken: '4fc79757419b539937b94f1bd0f6e315765bbde4'
});
client.payments.list().then(function(payments) {
  // Payments
});

from bankson import Bankson, RequestError

with open('/path/to/private_key_file') as privatefile:
  keydata = privatefile.read()
client = Bankson(api_key='<api key uuid>', private_key=keydata)
client.payments.list()

JSON response

[{
  "id": 1,
  "bank_account_id": 5,
  "environment_id": 2,
  "amount": 608.3,
  "recipient_name": "Työeläkeyhtiö Elo",
  "recipient_iban": "FI2721533800005022",
  "recipient_bic": "NDEAFIHH",
  "payment_date": "2014-12-04",
  "reference_number": "13",
  "vendor_reference": "23",
  "end_to_end_id": "1417712682855-G-1-P-1",
  "payment_information_id": "1417712682855-G-1",
  "message_id": "1417712682855",
  "created_at": "2014-12-04T17:04:44.102Z",
  "updated_at": "2014-12-04T17:04:44.102Z",
  "status": null,
  "status_details": null,
  "test": false,
  "bank_account": {
    "id": 5,
    "certificate_id": 14,
    "environment_id": 2,
    "iban": "FI4819503000000010",
    "bic": "NDEAFIHH",
    "contract_id": "111111111",
    "created_at": "2014-12-04T17:04:11.906Z",
    "updated_at": "2014-12-04T17:04:11.906Z",
    "balance": null,
    "balance_date": null,
    "test": false
  }
}]

Lists all payments made through Bankson.

payment.status can be one of values:

HTTP Request

GET https://api.bankson.fi/payments

Add payment

curl "https://api.bankson.fi/payments" -X POST
  -H "Authorization: Bearer 4fc79757419b539937b94f1bd0f6e315765bbde4"
  -H "Content-Type: application/json"
  -d '{"amount":308.3,"recipient_name":"Työeläkeyhtiö Elo","recipient_iban":"FI2721533800005022","recipient_bic":"NDEAFIHH","payment_date":"2014-12-04","reference_number":"13","vendor_reference":"23","from":{"iban":"FI4819503000000010","bic":"NDEAFIHH"}}'

var Client = require('bankson-js');
var client = new Client({
  bearerToken: '4fc79757419b539937b94f1bd0f6e315765bbde4'
});
client.payments.create({
  amount: 308.3,
  recipient_name: 'Työeläkeyhtiö Elo',
  recipient_iban: 'FI2721533800005022',
  recipient_bic: 'NDEAFIHH',
  payment_date: '2014-12-04',
  reference_number: '13',
  vendor_reference: '23' // Free form string, can be used to identify payments with your own system
}, { // From which account payment will be made
  iban: 'FI4819503000000010',
  bic: 'NDEAFIHH'
}).then(function(payment) {
  // Payment created and sent to bank
});

from bankson import Bankson, RequestError

with open('/path/to/private_key_file') as privatefile:
  keydata = privatefile.read()
client = Bankson(api_key='<api key uuid>', private_key=keydata)
client.payments.create({
    'amount': 308.3,
    'recipient_name': 'Työeläkeyhtiö Elo',
    'recipient_iban': 'FI2721533800005022',
    'recipient_bic': 'NDEAFIHH',
    'payment_date': '2014-12-04',
    'reference_number': '13',
    'vendor_reference': '23' # Free form string, can be used to identify payments with your own system
}, { # From which account payment will be made
    'iban': 'FI4819503000000010',
    'bic': 'NDEAFIHH'
})

JSON response (http status code 201 Created)

{
  "id": 1,
  "bank_account_id": 5,
  "environment_id": 2,
  "amount": 608.3,
  "recipient_name": "Työeläkeyhtiö Elo",
  "recipient_iban": "FI2721533800005022",
  "recipient_bic": "NDEAFIHH",
  "payment_date": "2014-12-04",
  "reference_number": "13",
  "vendor_reference": "23",
  "end_to_end_id": "1417712682855-G-1-P-1",
  "payment_information_id": "1417712682855-G-1",
  "message_id": "1417712682855",
  "created_at": "2014-12-04T17:04:44.102Z",
  "updated_at": "2014-12-04T17:04:44.102Z",
  "status": null,
  "status_details": null,
  "test": false,
  "bank_account": {
    "id": 5,
    "certificate_id": 14,
    "environment_id": 2,
    "iban": "FI4819503000000010",
    "bic": "NDEAFIHH",
    "contract_id": "111111111",
    "created_at": "2014-12-04T17:04:11.906Z",
    "updated_at": "2014-12-04T17:04:11.906Z",
    "balance": null,
    "balance_date": null,
    "test": false
  }
}

Sends payment to bank and stores into bankson.

HTTP request

POST https://api.bankson.fi/payments

JSON Schema

Payment

Update payment statuses

curl "https://api.bankson.fi/payments/feedback" -X POST
  -H "Authorization: Bearer 4fc79757419b539937b94f1bd0f6e315765bbde4"

var Client = require('bankson-js');
var client = new Client({
  bearerToken: '4fc79757419b539937b94f1bd0f6e315765bbde4'
});
client.payments.fetchFeedback().then(function() {
  // Payments updated with current status
});

from bankson import Bankson, RequestError

with open('/path/to/private_key_file') as privatefile:
  keydata = privatefile.read()
client = Bankson(api_key='<api key uuid>', private_key=keydata)
client.payments.refresh()

JSON response

{
  "message": "OK"
}

Updates payment status from bank for all pending payments.

Inbound Payments (Reference payments)

List inbound payments

curl "https://api.bankson.fi/inboundpayments"
  -H "Authorization: Bearer 4fc79757419b539937b94f1bd0f6e315765bbde4"

var Client = require('bankson-js');
var client = new Client({
  bearerToken: '4fc79757419b539937b94f1bd0f6e315765bbde4'
});
var opts = { // for filtering results
  //reference_number: '13'
  //since: '2016-05-10'
};
client.inboundPayments.fetch(opts).then(function(payments) {
  // Payments
});

from bankson import Bankson, RequestError

with open('/path/to/private_key_file') as privatefile:
  keydata = privatefile.read()
client = Bankson(api_key='<api key uuid>', private_key=keydata)
# optional filter parameters
# opts = { 'reference_number': '13', 'since': '2016-10-10' }
client.inboundpayments.list(opts)

JSON response

[{
  "id": 266,
  "bank_account_id": 22,
  "environment_id": 2,
  "amount": 64.9,
  "debitor_name": "MYYRY VILJO",
  "payment_date": "2006-03-03",
  "archive_id": "03032950PS120058",
  "booking_date": "2006-03-02T22:00:00.000Z",
  "reference_number": "890948",
  "created_at": "2016-06-02T17:14:20.299Z",
  "updated_at": "2016-06-02T17:14:20.299Z",
  "inbound_payment_batch_id": 19,
  "test": true,
  "bank_account": {
    "id": 22,
    "certificate_id": 26,
    "environment_id": 2,
    "iban": "FI4819503000000010",
    "bic": "NDEAFIHH",
    "contract_id": null,
    "created_at": "2016-05-21T21:50:11.800Z",
    "updated_at": "2016-05-21T21:50:11.800Z",
    "balance": null,
    "balance_date": null,
    "test": true
  }
},{
  "id": 316,
  "bank_account_id": 22,
  "environment_id": 2,
  "amount": 40,
  "debitor_name": "COPPERHOUSE",
  "payment_date": "2006-03-06",
  "archive_id": "0306258877B40058",
  "booking_date": "2006-03-05T22:00:00.000Z",
  "reference_number": "890948",
  "created_at": "2016-06-02T17:14:20.952Z",
  "updated_at": "2016-06-02T17:14:20.952Z",
  "inbound_payment_batch_id": 21,
  "test": true,
  "bank_account": {
    "id": 22,
    "certificate_id": 26,
    "environment_id": 2,
    "iban": "FI4819503000000010",
    "bic": "NDEAFIHH",
    "contract_id": null,
    "created_at": "2016-05-21T21:50:11.800Z",
    "updated_at": "2016-05-21T21:50:11.800Z",
    "balance": null,
    "balance_date": null,
    "test": true
  }
}]

Lists all received reference payments

HTTP Request

GET https://api.bankson.fi/inboundpayments

Query parameters

The result set can be filtered by query parameters

Parameter Description
reference_number Only show payments matching the reference number
since Only show payments newer thant provided timestamp

Refresh payments from bank

curl "https://api.bankson.fi/inboundpayments" -X POST
  -H "Authorization: Beare 4fc79757419b539937b94f1bd0f6e315765bbde4"
  -H "Content-Type: application/json"
  -d '{ "certificate_id": 1 }'

var Client = require('bankson-js');
var client = new Client({
  bearerToken: '4fc79757419b539937b94f1bd0f6e315765bbde4'
});
var certificateId = 1;
client.inboundPayments.refresh(certificateId).then(function(payments) {
  console.log('new payments', payments);
});

from bankson import Bankson, RequestError

with open('/path/to/private_key_file') as privatefile:
  keydata = privatefile.read()
client = Bankson(api_key='<api key uuid>', private_key=keydata)
certificate_id = 1
client.inboundpayments.refresh(certificate_id)

JSON response

[{
  "id": 266,
  "bank_account_id": 22,
  "environment_id": 2,
  "amount": 64.9,
  "debitor_name": "MYYRY VILJO",
  "payment_date": "2006-03-03",
  "archive_id": "03032950PS120058",
  "booking_date": "2006-03-02T22:00:00.000Z",
  "reference_number": "890948",
  "created_at": "2016-06-02T17:14:20.299Z",
  "updated_at": "2016-06-02T17:14:20.299Z",
  "inbound_payment_batch_id": 19,
  "test": true,
  "bank_account": {
    "id": 22,
    "certificate_id": 26,
    "environment_id": 2,
    "iban": "FI4819503000000010",
    "bic": "NDEAFIHH",
    "contract_id": null,
    "created_at": "2016-05-21T21:50:11.800Z",
    "updated_at": "2016-05-21T21:50:11.800Z",
    "balance": null,
    "balance_date": null,
    "test": true
  }
},{
  "id": 316,
  "bank_account_id": 22,
  "environment_id": 2,
  "amount": 40,
  "debitor_name": "COPPERHOUSE",
  "payment_date": "2006-03-06",
  "archive_id": "0306258877B40058",
  "booking_date": "2006-03-05T22:00:00.000Z",
  "reference_number": "890948",
  "created_at": "2016-06-02T17:14:20.952Z",
  "updated_at": "2016-06-02T17:14:20.952Z",
  "inbound_payment_batch_id": 21,
  "test": true,
  "bank_account": {
    "id": 22,
    "certificate_id": 26,
    "environment_id": 2,
    "iban": "FI4819503000000010",
    "bic": "NDEAFIHH",
    "contract_id": null,
    "created_at": "2016-05-21T21:50:11.800Z",
    "updated_at": "2016-05-21T21:50:11.800Z",
    "balance": null,
    "balance_date": null,
    "test": true
  }
}]

Refreshes all inbound payments from bank.

HTTP request

POST https://api.bankson.fi/inboundpayments

JSON params

Parameter Description
certificate_id The certificate to use

Errors

curl "https://api.bankson.fi/payments" -i -X POST
  -H "Authorization: 4fc79757419b539937b94f1bd0f6e315765bbde4"

HTTP/1.1 400 Bad Request
content-type: application/json; charset=utf-8

var Client = require('bankson-js');
var client = new Client({
  bearerToken: '4fc79757419b539937b94f1bd0f6e315765bbde4'
});
client.payments.create({}, {}).then(function() {
  // Never called
}).catch(function(err) {
  // err.status === 400
  // err.body === { error: 'Validation failed', details: [{...}, {...}] }
});

from bankson import Bankson, RequestError

with open('/path/to/private_key_file') as privatefile:
  keydata = privatefile.read()
client = Bankson(api_key='<api key uuid>', private_key=keydata)
try:
    client.payments.create({}, {})
except RequestError as err:
    print 'Request error'
    print err.status
    print err.body # { 'error': u'Validation failed', ... }j

JSON output

{
  "error": "Validation failed",
  "details": [
    {
      "property": "instance.recipient_name",
      "message": "is required",
      "schema": {
        "type": "string",
        "required": true,
        "minLength": 1
      },
      "name": "required",
      "stack": "instance.recipient_name is required"
    },
    {
      "property": "instance.recipient_bic",
      "message": "is required",
      "schema": {
        "type": "string",
        "required": true,
        "minLength": 1
      },
      "name": "required",
      "stack": "instance.recipient_bic is required"
    },
    {
      "property": "instance.recipient_iban",
      "message": "is required",
      "schema": {
        "type": "string",
        "iban": true,
        "required": true,
        "minLength": 1
      },
      "name": "required",
      "stack": "instance.recipient_iban is required"
    },
    {
      "property": "instance.amount",
      "message": "is required",
      "schema": {
        "type": "double",
        "required": true,
        "minLength": 1
      },
      "name": "required",
      "stack": "instance.amount is required"
    },
    {
      "property": "instance.payment_date",
      "message": "is required",
      "schema": {
        "type": "string",
        "format": "date",
        "required": true
      },
      "name": "required",
      "stack": "instance.payment_date is required"
    },
    {
      "property": "instance.reference_number",
      "message": "is required",
      "schema": {
        "type": "string",
        "referenceNumber": true,
        "required": true
      },
      "name": "required",
      "stack": "instance.reference_number is required"
    },
    {
      "property": "instance.from",
      "message": "is required",
      "schema": {
        "required": true,
        "type": "object",
        "description": "From which bank account should the charge be done",
        "properties": {
          "iban": {
            "iban": true,
            "type": "string",
            "required": true,
            "minLength": 1
          },
          "bic": {
            "type": "string",
            "required": true,
            "minLength": 1
          }
        }
      },
      "name": "required",
      "stack": "instance.from is required"
    }
  ]
}

The Bankson API uses the following error codes:

Error Code Meaning
400 Bad Request – Something about the request is malformed or schema validation did not succeed.
401 Unauthorized – The valua provided in Authorization header is invalid
404 Not Found – The specified resource could not be found
406 Not Acceptable – The specified resource cannot be represented in the format specified by Accept request header.
500 Internal Server Error – We had a problem with our server. Try again later.
503 Service Unavailable – We’re temporarially offline for maintanance. Please try again later.

Detailed information can be found in the response body. All error responses contain a message property.

JSON Schemas

Schema: Application

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "id": "/Application",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "required": true,
      "minLength": 1
    },
    "redirect_uri": {
      "format": "uri",
      "type": "string",
      "required": true,
      "minLength": 1
    }
  }
}

Schema: BankAccount

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "id": "/BankAccount",
  "type": "object",
  "properties": {
    "iban": {
      "iban": true,
      "type": "string",
      "required": true,
      "minLength": 1
    },
    "bic": {
      "type": "string",
      "required": true,
      "minLength": 1
    },
    "contract_id": {
      "type": "string"
    },
    "certificate_id": {
      "type": "integer",
      "required": true
    }
  }
}

Schema: BankAccountStatement

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "id": "/BankAccountStatement",
  "type": "object",
  "properties": {
    "account_owner_name": {
      "type": "string"
    },
    "balances": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "amount": {
            "type": "number"
          },
          "booking_date": {
            "type": "string",
            "format": "date"
          },
          "available_amount": {
            "type": "number"
          }
        }
      }
    },
    "bank_account_id": {
      "type": "integer"
    },
    "created_at": {
      "type": "string",
      "format": "datetime"
    },
    "currency": {
      "type": "string"
    },
    "entries": {
      "type": "array",
      "items": {
        "type": "object",
        "description": "The statement rows",
        "properties": {
          "additional_information": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Additional information for one row. Messages etc."
          },
          "amount": {
            "type": "number"
          },
          "archive_id": {
            "type": "string",
            "description": "The archive identifier given by the bank"
          },
          "booking_date": {
            "type": "string",
            "format": "date"
          },
          "booking_information": {
            "type": "string"
          },
          "entry_reference": {
            "type": "integer",
            "description": "The row number in the statement"
          },
          "payment_date": {
            "type": "string",
            "format": "datetime"
          },
          "receiver": {
            "type": "string"
          },
          "receiver_account": {
            "type": "string"
          },
          "reference_number": {
            "type": "string"
          },
          "value_date": {
            "type": "string",
            "format": "date"
          }
        }
      }
    },
    "from": {
      "type": "string",
      "format": "datetime",
      "description": "The start date of the statement period"
    },
    "id": {
      "type": "integer"
    },
    "legal_sequence_number": {
      "type": "string",
      "description": "The sequence number for the statement given by the bank"
    },
    "servicer_bic": {
      "type": "string",
      "description": "BIC of the bank"
    },
    "servicer_name": {
      "type": "string",
      "description": "Name of the bank"
    },
    "to": {
      "type": "string",
      "format": "datetime",
      "description": "The end date of the statement period"
    },
    "updated_at": {
      "type": "string",
      "format": "datetime"
    }
  }
}

Schema: Certificate

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "id": "/Certificate",
  "type": "object",
  "properties": {
    "not_after": {
      "type": "string",
      "readonly": true
    },
    "not_before": {
      "type": "string",
      "readonly": true
    },
    "subject": {
      "type": "string",
      "readonly": true
    },
    "created_at": {
      "type": "string",
      "format": "datetime"
    },
    "updated_at": {
      "type": "string",
      "format": "datetime"
    },
    "customer_id": {
      "type": "string",
      "required": true,
      "minLength": 1
    },
    "bic": {
      "type": "string",
      "required": true,
      "minLength": 1
    },
    "target_id": {
      "type": "string",
      "required": true,
      "minLength": 1
    }
  }
}

Schema: Environment

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "id": "/Environment",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "required": true,
      "minLength": 1
    }
  }
}

Schema: Payment

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "id": "/Payment",
  "type": "object",
  "properties": {
    "recipient_name": {
      "type": "string",
      "required": true,
      "minLength": 1
    },
    "recipient_bic": {
      "type": "string",
      "required": true,
      "minLength": 1
    },
    "recipient_iban": {
      "type": "string",
      "iban": true,
      "required": true,
      "minLength": 1
    },
    "amount": {
      "type": "double",
      "required": true,
      "minLength": 1
    },
    "payment_date": {
      "type": "string",
      "format": "date",
      "required": true
    },
    "reference_number": {
      "type": "string",
      "referenceNumber": true,
      "required": true
    },
    "vendor_reference": {
      "type": "string"
    },
    "from": {
      "required": true,
      "type": "object",
      "description": "From which bank account should the charge be done",
      "properties": {
        "iban": {
          "iban": true,
          "type": "string",
          "required": true,
          "minLength": 1
        },
        "bic": {
          "type": "string",
          "required": true,
          "minLength": 1
        }
      }
    }
  }
}

Schema: User

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "id": "/User",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "required": true,
      "minLength": 1
    },
    "email": {
      "type": "email",
      "required": true,
      "minLength": 1,
      "format": "email"
    }
  }
}
shell javascript python