@getkevin.eu/kevin-platform-client

kevin. platform client

kevin. API implementation for node.js

Example

kevin. platform client response

Success

Example below displays possible response from /auth/countries endpoint

{
  code: 200, // http code
  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'
  ] // response data
}

Failure

Example below displays possible response from /auth/banks endpoint

{
  code: 400, // http code
  error: {
    code: 10015, // kevin. error code
    name: 'InvalidCountryCode', // error name
    description: 'Invalid country code.' // error message
  },
  data: {} // response data
}

Initialize client

const kevin = require('@getkevin.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 response = await client.general.getBank();

  const bank = response.data;

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 response = await client.general.getProjectSettings();

  const projectSettings = response.data;

Payment Service

Bank payment

Initiate bank payment

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

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

const payment = response.data;

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',
    'Webhook-URL': 'https://example.com/notify?orderId=123',
  },
  body: {
    amount: '1.23',
    currencyCode: 'EUR',
    description: 'Lorem Ipsum',
    bankPaymentMethod: {
      creditorName: 'John Doe',
      endToEndId: '123',
      creditorAccount: {
        iban: 'LT000000000000000000',
      }
    },
    cardPaymentMethod: [],
  },
}

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

const payment = response.data;

Get payment

Returns information for given payment

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

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

const payment = response.data;

Payment status

Returns current status for given payment

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

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

const paymentStatus = response.data;

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 response = await client.payment.initiatePaymentRefund(options);

const refund = response.data;

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

Authenticate

Returns auth key which can be exchanged to token

const options = {
  'headers': {
    'Request-Id': '123',
    'Redirect-URL': 'https://example.com/authenticate'
  },
  'query': {
    scopes: ['payments', 'accounts_basic'],
  },
};

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

const authenticationData = response.data;

Get token

Exchange auth key to a bearer token and refresh token pair

const authKey = 'my-auth-key';

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

const tokenData = response.data;

Refresh token

Exchange refresh token to a new bearer token

const refreshToken = 'my-refresh-token';

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

const tokenData = response.data;

Get token content

Receive information about a bearer token

const token = 'my-bearer-token';

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

const tokenContentData = response.data;

Account information service

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-ip-port',
    'PSU-Http-Method': 'GET',
    'PSU-Device-ID': 'my-device-id',
  },
};

const response = client.account.getAccounts(options);

const accountList = response.data;

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-ip-port',
    'PSU-Http-Method': 'GET',
    'PSU-Device-ID': 'my-device-id',
  },
};

const response = client.account.getAccount(options);

const accountData = response.data;

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-ip-port',
    'PSU-Http-Method': 'GET',
    'PSU-Device-ID': 'my-device-id',
  },
};

const response = client.account.getAccountTransactions(options);

const accountTransactions = response.data;

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-ip-port',
    'PSU-Http-Method': 'GET',
    'PSU-Device-ID': 'my-device-id',
  },
};

const response = client.account.getAccountTransactions(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);