kevin. platform client

kevin. API implementation for node.js

Example

kevin. platform client response

Success

On success, an exact response documented in https://api-reference.kevin.eu is returned.

Example below displays possible response from /auth/countries endpoint

{
  data: [
    'AT', 'BE', 'BG', 'CZ', 'DE',
    'DK', 'EE', 'ES', 'FI', 'FR',
    'GB', 'GR', 'HR', 'HU', 'IE',
    'IS', 'IT', 'LT', 'LU', 'LV',
    'NL', 'NO', 'PL', 'PT', 'RO',
    'SE', 'SI', 'SK'
  ]
}

Failure

On failure, an error inheriting KevinError class is thrown. Possible errors are:

• KevinBadRequestError
• KevinUnauthorizedError

Each error contains useful information such as httpCode, errorName, errorCode etc.

Initialize client

const kevin = require('@kevin.eu/kevin-platform-client');

const clientId = 'my-client-id';
const clientSecret = 'my-client-secret';

const client = new kevin.Client(clientId, clientSecret);

General Service

Supported countries

Get list of countries that are supported by kevin.

  const response = await client.general.getCountries();

  const countries = response.data;

Bank

Get single bank data from the bank list

  const bankId = 'SEB_LT_TEST';

  const bank = await client.general.getBank(bankId);

Supported banks

Get all the supported banks for country or project

❗️If no country code is provided, all banks available to the project are returned

  const countryCode = 'LT';

  const response = await client.general.getBanks(countryCode);

  const banks = response.data;

Savings banks

Get savings bank list for given bank

❗️Not all banks have savings banks

  const bankId = 'SEB_LT_TEST';

  const response = await client.general.getBanks(countryCode);

  const banks = response.data;

Supported payment methods

Get list of supported payment methods for given project

  const response = await client.general.getPaymentMethods();

  const paymentMethods = response.data;

Project settings

Get all project settings

  const projectSettings = await client.general.getProjectSettings();

Payment Initiation Service

Bank payment

Initiate bank payment

const options = {
  headers: {
    'Redirect-URL': 'https://redirect.kevin.eu/payment.html',
  },
  query: {
    redirectPreferred: true
  },
  body: {
    amount: '1.23',
    currencyCode: 'EUR',
    description: 'Lorem Ipsum',
    bankPaymentMethod: {
      creditorName: 'John Doe',
      endToEndId: '123',
      creditorAccount: {
        iban: 'LT000000000000000000',
      }
    }
  },
}

const payment = await client.payment.initiatePayment(options);

Card (hybrid) payment

Initiate a card payment

❗️All card payments are required to contain bank payment data

  const options = {
  headers: {
    'Redirect-URL': 'https://redirect.kevin.eu/payment.html',
  },
  query: {
    redirectPreferred: true
  },
  body: {
    amount: '1.23',
    currencyCode: 'EUR',
    description: 'Lorem Ipsum',
    bankPaymentMethod: {
      creditorName: 'John Doe',
      endToEndId: '123',
      creditorAccount: {
        iban: 'LT000000000000000000',
      }
    },
    cardPaymentMethod: {}
  },
}

const payment = await client.payment.initiatePayment(options);

Get payment

Returns information for given payment

const options = { paymentId: 'my-payment-id' };

const payment = await client.payment.getPayment(options);

Payment status

Returns current status for given payment

const options = { paymentId: 'my-payment-id' };

const paymentStatus = await client.payment.getPaymentStatus(options);

Payment refund

Initiate payment refund

❗️You can initiate one or more partial refunds for one payment

const options = { 
  paymentId: 'my-payment-id',
  amount: '1.23',
};

const refund = await client.payment.initiatePaymentRefund(options);

Get refunds

Returns all refunds for given payment

const paymentId = 'my-payment-id';

const response = await client.payment.getPaymentRefunds(paymentId);

const paymentRefunds = response.data;

Authentication Service

Start authentication

Returns auth key which can be exchanged to token

const options = {
  headers: {
    'Request-Id': '123',
    'Redirect-URL': 'https://redirect.kevin.eu/authorization.html'
  },
  query: {
    scopes: ['payments', 'accounts_basic'],
  },
};

const authenticationData = await client.auth.authenticate(options);

Receive token

Exchange auth key to a bearer token and refresh token pair

const authKey = 'my-auth-key';

const tokenData = await client.auth.receiveToken(authKey);

Refresh token

Exchange refresh token to a new bearer token

const refreshToken = 'my-refresh-token';

const tokenData = await client.auth.refreshToken(refreshToken);

Get token content

Receive information about a bearer token

const token = 'my-bearer-token';

const tokenContentData = await client.auth.receiveTokenContent(token);

Account Information Service

Get accounts list

Get user accounts information

const options = {
  token: 'my-bearer-token',
  headers: {
    'PSU-IP-Address': 'my-ip-address',
    'PSU-User-Agent': 'my-user-agent',
    'PSU-IP-Port': 'my-port',
    'PSU-Http-Method': 'GET',
    'PSU-Device-ID': 'my-device-id',
  },
};

const accountList = await client.account.getAccounts(options);

Get account details

Receive user account information

const options = {
  token: 'my-bearer-token',
  accountId: 'my-account-id',
  headers: {
    'PSU-IP-Address': 'my-ip-address',
    'PSU-User-Agent': 'my-user-agent',
    'PSU-IP-Port': 'my-port',
    'PSU-Http-Method': 'GET',
    'PSU-Device-ID': 'my-device-id',
  },
};

const accountData = await client.account.getAccount(options);

Get account transactions

Get user account transaction history

const options = {
  token: 'my-bearer-token',
  accountId: 'my-account-id',
  dateFrom: '1970-01-01',
  dateTo: '1970-01-01',
  headers: {
    'PSU-IP-Address': 'my-ip-address',
    'PSU-User-Agent': 'my-user-agent',
    'PSU-IP-Port': 'my-port',
    'PSU-Http-Method': 'GET',
    'PSU-Device-ID': 'my-device-id',
  },
};

const accountTransactions = await client.account.getAccountTransactions(options);

Get account balance

Get user account balance

const options = {
  token: 'my-bearer-token',
  accountId: 'my-account-id',
  headers: {
    'PSU-IP-Address': 'my-ip-address',
    'PSU-User-Agent': 'my-user-agent',
    'PSU-IP-Port': 'my-port',
    'PSU-Http-Method': 'GET',
    'PSU-Device-ID': 'my-device-id',
  },
};

const response = await client.account.getAccountBalance(options);

const accountTransactions = response.data;

Security manager

Verify webhook signature

Make sure that received webhook is authentic

const endpointSecret = 'my-endpoint-secret';

const securityManager = new kevin.SecurityManager(endpointSecret);

// webhook request headers object
const headers = req.headers;

// webhook request body object
const body = req.body;

// URL to which webhook was requested
const webhookUrl = 'https://example.com/notify?orderId=123';

// Timestamp timeout in milliseconds
const timestampTimeout = '300000';

const isWebhookSignatureValid = securityManager.verifySignature(body, headers, webhookUrl, timestampTimeout);