add support for /v1/Pos endpoints

README.md

@@ -24,6 +24,8 @@ Helps manage e-payment transactions through the [Barion Smart Gateway](https://w
     - [Get existing accounts of the user](#get-existing-accounts-of-the-user---bariongetaccountsoptions-callback)
     - [Send money to a Barion user or email address](#send-e-money-to-an-email-address---barionemailtransferoptions-callback)
     - [Download statement files](#download-statement-files---bariondownloadstatementoptions-callback)
+    - [Get POS details](#get-pos-details---bariongetposdetailsoptions-callback)
+    - [Create a new POS](#create-a-new-pos---barioncreateposoptions-callback)
     - [Get transaction history](#get-transaction-history---bariongethistoryoptions-callback)
     - [Handling errors](#handling-errors)
     - [Secure vs. insecure mode](#secure-vs-insecure-mode)
@@ -85,6 +87,8 @@ barion.getPaymentState({
 - get existing accounts of the user
 - send money to existing Barion account or email address
 - download monthly or daily statements of your account
+- get details of a specific POS (shop)
+- create a new POS (shop) in Barion
 - get transaction history for wallet accounts.
 
 > **IMPORTANT**: ``node-barion`` is completely consistent with [Barion Docs](https://docs.barion.com/Main_Page), so you can use exactly the same field names, that are specified in it. **Reading the official Barion documentation is highly recommended** before starting to use ``node-barion`` module.<br>
@@ -678,6 +682,205 @@ barion.downloadStatement({
 });
 ```
 
+### Get POS details - barion.getPosDetails(options, \[callback\])
+To retrieve details and the current state of a specific POS (shop), call the ``getPosDetails`` function. [[Barion Docs](https://docs.barion.com/Pos-Get-v1)]
+
+**Authentication**: This endpoint requires Api Key authentication.
+
+**Parameters**:
+  - ``ApiKey``: Api Key for authentication (string). (required)
+
+  - ``PublicKey``: The public key (identifier) of the POS to retrieve details for (string, GUID format). (required)
+
+**Output**: [Read at Barion Docs](https://docs.barion.com/Pos-Get-v1#Output_properties)
+
+#### Usage example
+##### With callback
+```js
+barion.getPosDetails({
+    ApiKey: 'your-api-key-here',
+    PublicKey: '12345678-1234-1234-1234-123456789012'
+}, function (err, data) {
+    //handle error / process data
+});
+```
+##### With promise
+```js
+barion.getPosDetails({
+    ApiKey: 'your-api-key-here',
+    PublicKey: '12345678-1234-1234-1234-123456789012'
+}).then(data => {
+    //process data
+}).catch(err => {
+    //handle error
+});
+```
+
+### Create a new POS - barion.createPos(options, \[callback\])
+To create a new POS (shop) in the Barion system, call the ``createPos`` function. [[Barion Docs](https://docs.barion.com/Pos-Create-v1)]
+
+**Authentication**: This endpoint requires Api Key authentication.
+
+**Parameters**:
+  - ``ApiKey``: Api Key for authentication (string). (required)
+
+  - ``Name``: The name of the shop (string, max 200 characters). (required)
+
+  - ``Url``: The URL of the shop (string, max 2000 characters, must be HTTPS). (required)
+
+  - ``Description``: Description of the shop (string, min 20, max 200 characters). (required)
+
+  - ``Logo``: Base64 encoded logo image of the shop (string). (required)
+
+  - ``Category``: Array of shop categories (string[]). (required)<br>
+    Allowed values are:
+    - ``'Agriculture'``
+    - ``'BookNewsPaper'``
+    - ``'Ad'``
+    - ``'BonusCoupon'``
+    - ``'Dating'``
+    - ``'Electronics'``
+    - ``'FashionClothes'``
+    - ``'FoodDrink'``
+    - ``'FurnitureAntiquity'``
+    - ``'GiftToyFlower'``
+    - ``'BeautyHealth'``
+    - ``'HomeDesignGarden'``
+    - ``'JobEducation'``
+    - ``'BuildingMaterialMachine'``
+    - ``'Baby'``
+    - ``'FilmMusic'``
+    - ``'Other'``
+    - ``'Pet'``
+    - ``'Property'``
+    - ``'Service'``
+    - ``'SportLeisureTravel'``
+    - ``'BettingGambling'``
+    - ``'Tobacco'``
+    - ``'Vehicle'``
+    - ``'WatchJewelry'``
+
+  - ``BusinessContact``: Contact information for business matters (object). (required)
+    - ``Name``: Contact person name (string). (required)
+    - ``PhoneNumber``: Contact phone number (string, max 30 characters). (required)
+    - ``Email``: Contact email address (string, valid email format). (required)
+
+  - ``TechnicalContact``: Contact information for technical matters (object). (required)
+    - ``Name``: Contact person name (string). (required)
+    - ``PhoneNumber``: Contact phone number (string, max 30 characters). (required)
+    - ``Email``: Contact email address (string, valid email format). (required)
+
+  - ``CustomerServiceContact``: Contact information for customer service (object). (required)
+    - ``Name``: Contact person name (string). (required)
+    - ``PhoneNumber``: Contact phone number (string, max 30 characters). (required)
+    - ``Email``: Contact email address (string, valid email format). (required)
+
+  - ``PrimaryCurrency``: The primary currency of the shop (string). (required)<br>
+    Allowed values are:
+    - ``'HUF'`` (Hungarian forint)
+    - ``'CZK'`` (Czech crown)
+    - ``'EUR'`` (Euro)
+    - ``'USD'`` (U.S. dollar)
+
+  - ``ExpectedTurnover``: The expected turnover tier for the shop (number, integer, 1-6). (required)<br>
+    The value represents predefined turnover ranges based on PrimaryCurrency:
+    - For HUF: 1 (1-100K), 2 (100K-1M), 3 (1M-10M), 4 (10M-29M), 5 (29M-99M), 6 (99M+)
+    - For EUR: 1 (1-300), 2 (301-3K), 3 (3K-30K), 4 (30K-90K), 5 (90K-300K), 6 (300K+)
+    - For CZK: 1 (1-8K), 2 (8K-80K), 3 (80K-800K), 4 (800K-2.2M), 5 (2.2M-7.7M), 6 (7.7M+)
+    - For USD: 1 (1-350), 2 (351-3.5K), 3 (3.5K-35K), 4 (35K-100K), 5 (100K-345K), 6 (345K+)
+
+  - ``FullPixelImplemented``: Indicates if full pixel tracking is implemented (boolean). (required)
+
+  - ``UseForEInvoicing``: Indicates if the shop will be used for e-invoicing (boolean). (required)
+
+  - ``AverageBasketValue``: Average basket value in the shop (number, integer, greater than 0). (optional)
+
+  - ``PercentageOfB2BCustomers``: Percentage of B2B customers (number, 0-100). (optional)
+
+  - ``PercentageOfNonEuCards``: Percentage of non-EU cards (number, 0-100). (optional)
+
+  - ``CallBackUrl``: Callback URL for the shop (string, max 2000 characters, valid URI). (required)
+
+  - ``ReferenceId``: Reference identifier for the shop (string). (optional)
+
+  - ``NoteForApproval``: Note for the approval process (string). (optional)
+
+  - ``CustomTemplate``: Custom template for the shop (string). (optional)
+
+  - ``CustomCss``: Custom CSS for the shop (string). (optional)
+
+**Output**: [Read at Barion Docs](https://docs.barion.com/Pos-Create-v1#Output_properties)
+
+#### Usage example
+##### With callback
+```js
+barion.createPos({
+    ApiKey: 'your-api-key-here',
+    Name: 'My Awesome Shop',
+    Url: 'https://example.com',
+    Description: 'This is a shop that sells awesome products and provides great service.',
+    Logo: 'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==',
+    Category: [ 'Electronics' ],
+    BusinessContact: {
+        Name: 'John Doe',
+        PhoneNumber: '36301234567',
+        Email: 'business@example.com'
+    },
+    TechnicalContact: {
+        Name: 'Jane Smith',
+        PhoneNumber: '36301234568',
+        Email: 'tech@example.com'
+    },
+    CustomerServiceContact: {
+        Name: 'Support Team',
+        PhoneNumber: '36301234569',
+        Email: 'support@example.com'
+    },
+    PrimaryCurrency: 'HUF',
+    ExpectedTurnover: 3,
+    FullPixelImplemented: false,
+    UseForEInvoicing: false,
+    CallBackUrl: 'https://example.com/callback'
+}, function (err, data) {
+    //handle error / process data
+});
+```
+##### With promise
+```js
+barion.createPos({
+    ApiKey: 'your-api-key-here',
+    Name: 'My Awesome Shop',
+    Url: 'https://example.com',
+    Description: 'This is a shop that sells awesome products and provides great service.',
+    Logo: 'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==',
+    Category: [ 'Electronics' ],
+    BusinessContact: {
+        Name: 'John Doe',
+        PhoneNumber: '36301234567',
+        Email: 'business@example.com'
+    },
+    TechnicalContact: {
+        Name: 'Jane Smith',
+        PhoneNumber: '36301234568',
+        Email: 'tech@example.com'
+    },
+    CustomerServiceContact: {
+        Name: 'Support Team',
+        PhoneNumber: '36301234569',
+        Email: 'support@example.com'
+    },
+    PrimaryCurrency: 'HUF',
+    ExpectedTurnover: 3,
+    FullPixelImplemented: false,
+    UseForEInvoicing: false,
+    CallBackUrl: 'https://example.com/callback'
+}).then(data => {
+    //process data
+}).catch(err => {
+    //handle error
+});
+```
+
 ### Get transaction history - barion.getHistory(options, \[callback\])
 To query the transaction history of a wallet account, call the ``getHistory`` function. [[Barion Docs](https://docs.barion.com/UserHistory-GetHistory-v3)]
 

lib/barion.js

@@ -14,6 +14,8 @@ const {
     StartPaymentWithGoogleToken,
     StartPaymentWithAppleToken,
     ValidateApplePaySession,
+    GetPosDetails,
+    CreatePos,
     GetHistory
 } = require('./domain');
 const { buildRequest, buildRequestWithoutValidation } = require('./build');
@@ -259,8 +261,9 @@ Barion.prototype.downloadStatement = function (options, callback) {
 /**
  * Starts a new payment in Barion using Google Pay token.
  * @param {Object} options - Options that are required to start payment with Google Pay.
- * @param {Function} [callback] - Callback that handles the response. If not passed, the function returns a *Promise*.
- * @see {@link https://docs.barion.com/Payment-StartPaymentWithGoogleToken-v3|Barion API: Start payment with Google Pay?}
+ * @param {Function} [callback] - Callback that handles the response.
+ * If not passed, the function returns a *Promise*.
+ * @see {@link https://docs.barion.com/Payment-StartPaymentWithGoogleToken-v3}
 */
 Barion.prototype.startPaymentWithGoogleToken = function (options, callback) {
     return doRequestAndReturn({
@@ -301,6 +304,36 @@ Barion.prototype.validateApplePaySession = function (options, callback) {
     }, callback);
 };
 
+/**
+ * Gets the details of a specific POS.
+ * @param {Object} options - Options that are required to get POS details.
+ * @param {Function} [callback] - Callback that handles the response. If not passed, the function returns a *Promise*.
+ * @see {@link https://docs.barion.com/Pos-Get-v1|Barion API Documentation}
+ */
+Barion.prototype.getPosDetails = function (options, callback) {
+    return doRequestAndReturn({
+        defaults: this.defaults,
+        customs: options,
+        schema: GetPosDetails,
+        service: services.getPosDetails
+    }, callback);
+};
+
+/**
+ * Creates a new POS (shop) in Barion.
+ * @param {Object} options - Options that are required to create a POS.
+ * @param {Function} [callback] - Callback that handles the response. If not passed, the function returns a *Promise*.
+ * @see {@link https://docs.barion.com/Pos-Create-v1|Barion API Documentation}
+ */
+Barion.prototype.createPos = function (options, callback) {
+    return doRequestAndReturn({
+        defaults: this.defaults,
+        customs: options,
+        schema: CreatePos,
+        service: services.createPos
+    }, callback);
+};
+
 /**
  * Gets the transaction history of a wallet account.
  * @param {Object} options - Options that are required to get history.

lib/constants.js

@@ -13,6 +13,8 @@ const {
     StartPaymentWithAppleToken,
     ValidateApplePaySession,
     StartPaymentWithGoogleToken,
+    GetPosDetails,
+    CreatePos,
     GetHistory
 } = require('./domain');
 
@@ -97,6 +99,16 @@ module.exports = {
             path: '/v2/ApplePay/ValidateSession',
             model: ValidateApplePaySession
         },
+        getPosDetails: {
+            method: 'GET',
+            path: '/v1/Pos/{PublicKey}',
+            model: GetPosDetails
+        },
+        createPos: {
+            method: 'POST',
+            path: '/v1/Pos',
+            model: CreatePos
+        },
         getHistory: {
             method: 'GET',
             path: '/v3/UserHistory/GetHistory',

lib/domain/CreatePos.js

@@ -0,0 +1,58 @@
+const Joi = require('joi');
+const { CaseInsensitiveSchema } = require('../schema');
+const { ShopCategory } = require('./_constraints');
+const { NamedContactSchema } = require('./pos/BaseContact');
+
+/**
+ * Used to create a shop (POS) in Barion.
+ *
+ * Note: Uses API key authentication (wallet endpoint).
+ *
+ * @see {@link https://docs.barion.com/Pos-Create-v1|Barion API: Create a POS in Barion}
+ */
+const schema = Joi.object({
+    ApiKey: Joi.string().required()
+        .pattern(/^[0-9a-fA-F]{32}$/),
+    Name: Joi.string().required()
+        .max(200),
+    Url: Joi.string().required()
+        .max(2000)
+        .uri({ scheme: [ 'https' ] }),
+    Description: Joi.string().required()
+        .min(20)
+        .max(200),
+    Logo: Joi.string().required()
+        .base64(),
+    Category: Joi.array().required()
+        .items(Joi.string().valid(...ShopCategory))
+        .min(1),
+    BusinessContact: NamedContactSchema.required(),
+    TechnicalContact: NamedContactSchema.required(),
+    CustomerServiceContact: NamedContactSchema.required(),
+    PrimaryCurrency: Joi.string().required()
+        .valid('HUF', 'CZK', 'EUR', 'USD'),
+    ExpectedTurnover: Joi.number().required()
+        .integer()
+        .min(1)
+        .max(6),
+    AverageBasketValue: Joi.number().optional()
+        .integer()
+        .greater(0),
+    PercentageOfB2BCustomers: Joi.number().optional()
+        .min(0)
+        .max(100),
+    PercentageOfNonEuCards: Joi.number().optional()
+        .min(0)
+        .max(100),
+    FullPixelImplemented: Joi.boolean().required(),
+    UseForEInvoicing: Joi.boolean().required(),
+    CallBackUrl: Joi.string().required()
+        .max(2000)
+        .uri(),
+    ReferenceId: Joi.string().optional(),
+    NoteForApproval: Joi.string().optional(),
+    CustomTemplate: Joi.string().optional(),
+    CustomCss: Joi.string().optional()
+});
+
+module.exports = new CaseInsensitiveSchema(schema);

lib/domain/GetPosDetails.js

@@ -0,0 +1,18 @@
+const Joi = require('joi');
+const { CaseInsensitiveSchema } = require('../schema');
+
+/**
+ * Used to retrieve all details and the current state of a point of sale (POS).
+ *
+ * Note: Uses API key authentication (wallet endpoint).
+ *
+ * @see {@link https://docs.barion.com/Pos-Get-v1|Barion API: Request all details of a POS}
+ */
+const schema = Joi.object({
+    ApiKey: Joi.string().required()
+        .pattern(/^[0-9a-fA-F]{32}$/),
+    PublicKey: Joi.string().required()
+        .guid()
+});
+
+module.exports = new CaseInsensitiveSchema(schema);