node-barion
Node API library for Barion Smart Gateway electronic payment system.
Last updated 2 months ago by aron123 .
MIT · Repository · Bugs · Original npm · Tarball · package.json
$ cnpm install node-barion 
SYNC missed versions from official npm registry.

node-barion

Build Status Coverage Status npm version MIT license

Helps you to manage e-payment transactions through the Barion Smart Gateway.

Table of contents

Install

To add node-barion to your project, run this command inside your workspace directory:

npm install node-barion --save

Usage

This simple example code shows, how to use node-barion:

// 1) Import the 'node-barion' module
const Barion = require('node-barion');

// 2) Instantiate a Barion object
let barion = new Barion({
    POSKey: '21ec20203aea4069a2dd08002b30',
    Environment: 'test'
});

// 3) Query the Barion API

// 3.a) using callback
barion.getPaymentState({ 
    PaymentId: '046a46b98838473684da452da7' 
}, function (err, data) {
    //handle the result
});

// 3.b) or using promise
barion.getPaymentState({
    PaymentId: '046a46b98838473684da452da7'
}).then(data => {
    //handle data
}).catch(err => {
    //handle error
});

If you are not familiar with Promise and other ES6 stuff, get closer to it.

Documentation

Node-barion provides all the functionality of Barion API:

  • start new reservation or immediate payment,
  • get the state of an already started payment,
  • finish a pending reservation,
  • refund a completed payment,
  • send money out of Barion via international bank transfer,
  • send money to existing Barion account or email address

IMPORTANT: Node-barion is fully consistent with Barion Docs, so you can use exactly the same field names, that are specified in it. It is highly recommended, to read the official Barion documentation before start to use the node-barion module.
IMPORTANT: Barion uses PascalCased field naming, but node-barion is case insensitive (this means that if Barion Docs mentions a field name PaymentId, you can either use PaymentId, paymentId, paymentid or paymentID notation in your application).

The signature for every instance method is (options, [callback]), where options is an object, which contains the input parameters, and callback is a function, which processes the response.
If no callback is defined, the methods return a Promise, which resolves with data or rejects with error.

Instantiate new Barion object - Barion(options)

A Barion instance represents a merchant, that accepts e-payment through Barion.

In the constructor, you can define default values, that can be overridden later in certain queries (except POSKey and Environment):

  • POSKey: POSKey of the merchant (string). (required)

  • Environment: Environment to use, 'test' or 'prod' (string). (optional, default: 'test')

    IMPORTANT: To use the production environment, you have to explicitly assign 'prod' to this field. Otherwise, the environment is set to 'test' by default.

  • FundingSources: The allowed funding sources, [ 'All' ] or [ 'Balance' ] (string[]). (optional, default: [ 'All' ])

  • GuestCheckOut: Indicates if guest checkout is enabled (boolean). (optional, default: true)

  • Locale: Localization of Barion GUI (string). (optional, default: 'hu-HU')
    Allowed values are:

    • 'cs-CZ' (Czech)
    • 'de-DE' (German)
    • 'en-US' (English)
    • 'es-ES' (Spanish)
    • 'fr-FR' (French)
    • 'hu-HU' (Hungarian)
    • 'sk-SK' (Slovakian)
    • 'sl-SI' (Slovenian)
  • Currency: The default currency to use (string). (optional, default: 'HUF')
    Allowed values are:

    • 'CZK' (Czech crown)
    • 'EUR' (Euro)
    • 'HUF' (Hungarian forint)
    • 'USD' (U.S. dollar)

Usage example

const Barion = require('node-barion');

let barion = new Barion({
    POSKey: '21ec20203aea4069a2dd08002b30',
    Environment: 'test',
    FundingSources: [ 'Balance' ],
    Locale: 'en-US'
});

Start new payment - barion.startPayment(options, [callback])

To create a new payment, call the startPayment function. [Barion Docs]

Parameters:

  • PaymentType: Type of the payment, 'Immediate' (classic) or 'Reservation' (read more) (string). (required)
  • ReservationPeriod: Time window that allows the shop to finalize the payment (string in 'd:hh:mm:ss' format). (required, if the payment type is reservation)
  • PaymentWindow: Time window that allows the user to complete the payment (string in 'd:hh:mm:ss' format). (optional, default: 30 minutes)
  • GuestCheckOut: Indicates if guest checkout is enabled (boolean). (optional, because it is assigned in the constructor)
  • InitiateRecurrence: Indicates that the shop would like to initialize a token payment (e.g. for subscription) (boolean). (optional)
  • RecurrenceId: A string used to identify a given authorized payment (read more) (string). (optional)
  • FundingSources: Array, that contains the allowed funding sources (string[]). (optional, because it is assigned in the constructor)
  • PaymentRequestId: The unique identifier for the payment generated by the shop (string). (required)
  • PayerHint: Email address of the customer. Barion use this to fill e-mail field automatically (string). (optional)
  • RedirectUrl: URL to redirect the user after the payment is completed (string). (optional)
  • CallbackUrl: URL that Barion should call, when the payment state changes (string). (optional)
  • Transactions: Array of transactions contained by the payment (PaymentTransaction[]). (required)
  • OrderNumber: Order number generated by the shop (string). (optional)
  • ShippingAddress: Address of the user (ShippingAddress[]). (optional)
  • Locale: Localization of Barion GUI (string). (optional, because it is assigned in the constructor)
  • Currency: The currency to use (string). (optional, because it is assigned in the constructor)

Output: Read at Barion Docs

Usage example

Example order data:

let orderPayment = {
    OrderNumber: 'O-2019-0001',
    PaymentRequestId: 'O-2019-0001-1',
    PaymentType: 'Immediate',
    Transactions: [
        {
            POSTransactionId: 'O-2019-0001',
            Payee: 'info@example.com',
            Total: 210,
            Items: [
                {
                    Name: 'Egg',
                    Description: 'Child of chicken',
                    Quantity: 3,
                    Unit: 'pcs',
                    UnitPrice: 70,
                    ItemTotal: 210
                }    
            ]
        }
    ],
    ShippingAddress: {
        FullName: 'Andrew Jones',
        Zip: '1000',
        City: 'Budapest',
        Street: 'Kossuth Street 2.'
    },
    Currency: 'HUF'
};
With callback

Use the object, initialized above:

barion.startPayment(orderPayment, function (err, data) {
    //handle error / process data
});
With promise

Use the object, initialized above:

barion.startPayment(orderPayment).then(data => {
    //process data
}).catch(err => {
    //handle error
});

Get payment state - barion.getPaymentState(options, [callback])

To get the state of a payment, use getPaymentState function. [Barion Docs]

Parameter:

  • PaymentId: ID of the payment in the Barion system (string). (required)

Output: Read at Barion Docs

Usage example

With callback
barion.getPaymentState({
    PaymentId: '15c1071df3ea4289996ead6ae17'
}, function (err, data) {
    //handle error / process data
});
With promise
barion.getPaymentState({
    PaymentId: '15c1071df3ea4289996ead6ae17'
}).then(data => {
    //process data
}).catch(err => {
    //handle error
});

Finish pending reservation - barion.finishReservation(options, [callback])

To finish a pending reservation, use the finishReservation function. [Barion Docs]

Parameters:

  • PaymentId: ID of the payment in Barion system (string). (required)
  • Transactions: Payment transactions to finish (TransactionToFinish[]). The array should only contain the initial payment transactions. (required)

Output: Read at Barion Docs

Usage example

With callback
barion.finishReservation({
    PaymentId: '15c1071df3ea4289996ead6ae17'
    Transactions: [
        {
            TransactionId: 'c9daac12c9154ce3a0c6a1a3',
            Total: 50
        }
    ]
}, function (err, data) {
    //handle error / process data
});
With promise
barion.finishReservation({
    PaymentId: '15c1071df3ea4289996ead6ae17'
    Transactions: [
        {
            TransactionId: 'c9daac12c9154ce3a0c6a1a3',
            Total: 50
        }
    ]
}).then(data => {
    //process data
}).catch(err => {
    //handle error
});

Refund payment partially or completely - barion.refundPayment(options, [callback])

To refund a completed payment, use the refundPayment function. [Barion Docs]

Parameters:

  • PaymentId: ID of the payment in Barion system (string). (required)
  • Transactions: Payment transactions to refund (TransactionToRefund[]). (required)

Output: Read at Barion Docs

Usage example

With callback
barion.refundPayment({
    PaymentId: '15c1071df3ea4289996ead6ae17',
    TransactionsToRefund: [
        {
            POSTransactionId: 'O-2019-0001',
            TransactionId: 'c9daac12c9154ce3a0c6a1a3',
            AmountToRefund: 50,
            Comment: 'Keep the change you filthy animal!'
        }
    ]
}, function (err, data) {
    //handle error / process data
});
With promise
barion.refundPayment({
    PaymentId: '15c1071df3ea4289996ead6ae17',
    TransactionsToRefund: [
        {
            POSTransactionId: 'O-2019-0001',
            TransactionId: 'c9daac12c9154ce3a0c6a1a3',
            AmountToRefund: 50,
            Comment: 'Sorry for the inconvenience.'
        }
    ]
}).then(data => {
    //process data
}).catch(err => {
    //handle error
});

Send money to bank account - barion.bankTransfer(options, [callback])

To send money to a bank account internationally, call the bankTransfer function. [Barion Docs]

Parameters:

  • UserName: Email address of the shop in the Barion system (string). (required)

  • Password: Password of the shop in the Barion system (string). (required)

  • Currency: The currency to use (string). (optional, because it is assigned in the constructor)
    Allowed values are:

    • 'CZK' (Czech crown)
    • 'EUR' (Euro)
    • 'HUF' (Hungarian forint)
    • 'USD' (U.S. dollar)
  • Amount: Amount of the money to send (number). (required)

  • RecipientName: Full name of the recipient (string). (required)

  • BankAccount: The recipient's bank account (BankAccount). (required)

  • Comment: Comment of the transfer (string). (optional)

Output: Read at Barion Docs

Usage example

With callback
barion.bankTransfer({
    UserName: 'info@example.com',
    Password: 'someRlyStrongP4ss#!',
    Currency: 'HUF',
    Amount: 1,
    RecipientName: 'Example Company',
    BankAccount: {
        Country: 'HUN',
        Format: 'Giro',
        AccountNumber: '10032000-01076019'
    },
    Comment: 'Keep the change you filthy animal!'
}, function (err, data) {
    //handle error / process data
});
With promise
barion.bankTransfer({
    UserName: 'info@example.com',
    Password: 'someRlyStrongP4ss#!',
    Currency: 'HUF',
    Amount: 1,
    RecipientName: 'Example Company',
    BankAccount: {
        Country: 'HUN',
        Format: 'Giro',
        AccountNumber: '10032000-01076019'
    },
    Comment: 'Keep the change you filthy animal!'
}).then(data => {
    //process data
}).catch(err => {
    //handle error
});

Send money to Barion user or email address - barion.barionTransfer(options, [callback])

To send money to a Barion user or to an email address, call the barionTransfer function. [Barion Docs]

Parameters:

  • UserName: Email address of the shop in the Barion system (string). (required)

  • Password: Password of the shop in the Barion system (string). (required)

  • Currency: The currency to use (string). (optional, because it is assigned in the constructor)
    Allowed values are:

    • 'CZK' (Czech crown)
    • 'EUR' (Euro)
    • 'HUF' (Hungarian forint)
    • 'USD' (U.S. dollar)
  • Amount: Amount of the money to send (number). (required)

  • Recipient: Email address of the recipient (string). (required)

  • Comment: Comment of the transfer (string). (optional)

Output: Read at Barion Docs

Usage example

With callback
barion.barionTransfer({
    UserName: 'info@example.com',
    Password: 'someRlyStrongP4ss#!',
    Currency: 'HUF',
    Amount: 1,
    Recipient: 'info@example.com',
    Comment: 'Have a nice party'
}, function (err, data) {
    //handle error / process data
});
With promise
barion.barionTransfer({
    UserName: 'info@example.com',
    Password: 'someRlyStrongP4ss#!',
    Currency: 'HUF',
    Amount: 1,
    Recipient: 'info@example.com',
    Comment: 'Have a nice party'
}).then(data => {
    //process data
}).catch(err => {
    //handle error
});

Handle errors

There are 2 main types of errors can thrown, when you use the node-barion module:

  • BarionError: Thrown, when the Barion system responds with errors.

    This error has a name field, set to 'BarionError'.

    This error has an errors array, which contains the returned errors. Every error has the following fields: Title, Description, ErrorCode, HappenedAt, AuthData, EndPoint (read more).

    NOTE: The errors array is set to [] (empty array), when the Barion API responds with:

    • generic error (such as {'Message': 'An error has occurred.'}),
    • invalid JSON (such as an HTML maintenance page)
  • Other errors: Common Javascript errors, such as Error or TypeError (thrown e.g. when network error occured).

Usage example

With callback
barion.startPayment(someObj, function (err, data) {
    if (err) {
        if (err.name == 'BarionError') {
            //Barion API responded with error
            return console.log(err.errors);
        } else {
            //other error occured
            return console.log(err);
        }
    }

    // if no error occured, process data
});
With promise
barion.startPayment(someObj)
    .then(data => {
        //process data
    })
    .catch(err => {
        if (err.name == 'BarionError') {
            //Barion API responded with error
            console.log(err.errors);
        } else {
            //other error occured
            console.log(err);
        }
    });

Future improvements

  • Do more validation before send the request to Barion, including:

    • checking if required values are not null or undefined,
    • validation of the given values' format (e.g. ensure that Guid, TimeSpan and DateTime values are given in the appropriate format),
    • restriction of possible values in certain fields (e.g. Currency field's value MUST BE one of the following: 'CZK', 'EUR', 'HUF', 'USD')
  • Define more error types (e.g. for network error, invalid JSON response, generic error response).

  • Make available to set optional fields as defaults (e.g. callbackUrl): if defined, send it, else, do not send. Currently, the library sends the field with undefined value. It does not affect proper functioning, but can be improved to reduce data traffic.

  • Support for automatic reservation finalization / payment refund (fill the Transactions field via getPaymentState)

Contributions

Contributions are welcome.

If you report a bug/issue, please provide as detailed code to reproduce as possible (of course, without any confidential data), and describe the environment, where you run node-barion.

I do not merge PRs, that break the build success, to test your changes, before send a PR, you have to:

  1. Make sure, that you have a test Barion account, with at least 500 HUF balance.
  2. Add your credentials to Barion in test/integration/credentials.json (there is an EXAMPLE in the directory, with the required format).
  3. Run the tests:
    npm run test
    
  4. To check coverage, run:
    npm run coverage
    

License

Copyright (c) 2019-present, Kiss Aron <aron123dev@gmail.com>

Unless otherwise stated in sources, the terms specified in LICENSE file is applicable.

Current Tags

  • 1.0.3                                ...           latest (2 months ago)

3 Versions

  • 1.0.3                                ...           2 months ago
  • 1.0.2                                ...           5 months ago
  • 1.0.1                                ...           7 months ago
Maintainers (1)
Downloads
Today 0
This Week 0
This Month 3
Last Day 0
Last Week 3
Last Month 1
Dependencies (1)
Dev Dependencies (7)
Dependents (0)
None

Copyright 2014 - 2016 © taobao.org |