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:
- application/json
- text/xml (CAMT format)
- text/plain (TITO format)
- application/pdf
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:
null
- no payment status available, use thePOST /payments/feedback
endpoint to refreshACTC
- the payment request is accepted by the bank with a technical checkACCP
- the payment has been checked for formal validityACSP
- the payment has been processedPNDG
- the payment is pending for processingRJCT
- the bank has rejected the payment, more information can be found from thepayment.status_details
field
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
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"
}
}
}