npm package: @kevin.eu/kevin-platform-client
Description: Node JS library implementing kevin. platform API.
Author: kevin.
Latest version: 2.2.5

# 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
```javascript
{
  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
```javascript
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](https://api-reference.kevin.eu/public/platform/v0.3#tag/General-Service)
#### [Supported countries](https://api-reference.kevin.eu/public/platform/v0.3#tag/General-Service/operation/getCountries)
Get list of countries that are supported by kevin.
```javascript
  const response = await client.general.getCountries();

  const countries = response.data;
```

#### [Bank](https://api-reference.kevin.eu/public/platform/v0.3#tag/General-Service/operation/getBank)
Get single bank data from the bank list
```javascript
  const bankId = 'SEB_LT_TEST';

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

#### [Supported banks](https://api-reference.kevin.eu/public/platform/v0.3#tag/General-Service/operation/getBanks)
Get all the supported banks for country or project

❗️If no country code is provided, all banks available to the project are returned
```javascript
  const countryCode = 'LT';

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

  const banks = response.data;
```

#### [Savings banks](https://api-reference.kevin.eu/public/platform/v0.3#tag/General-Service/operation/getSavingsBanks)
Get savings bank list for given bank

❗️Not all banks have savings banks
```javascript
  const bankId = 'SEB_LT_TEST';

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

  const banks = response.data;
```

#### [Supported payment methods](https://api-reference.kevin.eu/public/platform/v0.3#tag/General-Service/operation/getPaymentMethods)
Get list of supported payment methods for given project
```javascript
  const response = await client.general.getPaymentMethods();

  const paymentMethods = response.data;
```

#### [Project settings](https://api-reference.kevin.eu/public/platform/v0.3#tag/General-Service/operation/getProjectSettings)
Get all project settings
```javascript
  const projectSettings = await client.general.getProjectSettings();
```

### [Payment Initiation Service](https://api-reference.kevin.eu/public/platform/v0.3#tag/Payment-Initiation-Service)
#### [Bank payment](https://api-reference.kevin.eu/public/platform/v0.3#tag/Payment-Initiation-Service/operation/initiatePayment)
Initiate bank payment
```javascript
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](https://api-reference.kevin.eu/public/platform/v0.3#tag/Payment-Initiation-Service/operation/initiatePayment)
Initiate a card payment

❗️All card payments are required to contain bank payment data
```javascript
  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](https://api-reference.kevin.eu/public/platform/v0.3#tag/Payment-Initiation-Service/operation/getPayment)
Returns information for given payment
```javascript
const options = { paymentId: 'my-payment-id' };

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

#### [Payment status](https://api-reference.kevin.eu/public/platform/v0.3#tag/Payment-Initiation-Service/operation/getPaymentStatus)
Returns current status for given payment
```javascript
const options = { paymentId: 'my-payment-id' };

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

#### [Payment refund](https://api-reference.kevin.eu/public/platform/v0.3#tag/Payment-Initiation-Service/operation/initiatePaymentRefund)
Initiate payment refund

❗️You can initiate one or more partial refunds for one payment
```javascript
const options = { 
  paymentId: 'my-payment-id',
  amount: '1.23',
};

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

#### [Get refunds](https://api-reference.kevin.eu/public/platform/v0.3#tag/Payment-Initiation-Service/operation/getPaymentRefunds)
Returns all refunds for given payment
```javascript
const paymentId = 'my-payment-id';

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

const paymentRefunds = response.data;
```

### [Authentication Service](https://api-reference.kevin.eu/public/platform/v0.3#tag/Authentication-Service)
#### [Start authentication](https://api-reference.kevin.eu/public/platform/v0.3#tag/Authentication-Service/operation/startAuth)
Returns auth key which can be exchanged to token
```javascript
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](https://api-reference.kevin.eu/public/platform/v0.3#tag/Authentication-Service/operation/receiveToken)
Exchange auth key to a bearer token and refresh token pair
```javascript
const authKey = 'my-auth-key';

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

#### [Refresh token](https://api-reference.kevin.eu/public/platform/v0.3#tag/Authentication-Service/operation/receiveToken)
Exchange refresh token to a new bearer token
```javascript
const refreshToken = 'my-refresh-token';

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

#### [Get token content](https://api-reference.kevin.eu/public/platform/v0.3#tag/Authentication-Service/operation/receiveTokenContent)
Receive information about a bearer token
```javascript
const token = 'my-bearer-token';

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

### [Account Information Service](https://api-reference.kevin.eu/public/platform/v0.3#tag/Account-Information-Service)
#### [Get accounts list](https://api-reference.kevin.eu/public/platform/v0.3#tag/Account-Information-Service/operation/getAccounts)
Get user accounts information
```javascript
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](https://api-reference.kevin.eu/public/platform/v0.3#tag/Account-Information-Service/operation/getAccount)
Receive user account information
```javascript
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](https://api-reference.kevin.eu/public/platform/v0.3#tag/Account-Information-Service/operation/getAccountTransactions)
Get user account transaction history
```javascript
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](https://api-reference.kevin.eu/public/platform/v0.3#tag/Account-Information-Service/operation/getAccountBalance)
Get user account balance
```javascript
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](https://developer.kevin.eu/platform/payments/payment-verification#computing-signature-hash)
Make sure that received webhook is authentic
```javascript
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); 
```