node-barion
Node API library for Barion Smart Gateway electronic payment system.
Last updated 3 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 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 payment, reservation or delayed capture
  • get the state of an already started payment
  • finish a pending reservation
  • capture or cancel a previously authorized payment
  • 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 completely 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, node-barion converts these to the standard PaymentId name).

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 transactions 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.

  • ValidateModels: Indicates if node-barion have to validate options object of method calls before sending the request to the Barion API, when it is set to true, the module is prevalidates the request (boolean). (optional, default: true)

  • FundingSources: Array with 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)
    • 'el-GR' (Greek)
  • 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');

const 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:

- Properties marked with this badge must be provided to comply with 3D Secure authentication. Provide as much attributes as you can to avoid 3DS challenge flow for your customers. If the merchant does not provide 3DS-related properties, it doesn't mean that the payment will fail. It means that the payer will have a higher chance of getting a challenge during payment.

  • PaymentType: Type of the payment, 'Immediate' (classic), 'Reservation' or DelayedCapture (read more) (string). (required)

  • ReservationPeriod: Time window allowed by the shop to finalize the payment (string in 'd:hh:mm:ss' format). (required, if the payment type is reservation)

  • DelayedCapturePeriod: Time window allowed by the shop to capture or cancel the payment (string in 'd:hh:mm:ss' format). (required, if the payment type is delayed capture)

  • PaymentWindow: Time window allowed for the customer 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 email field automatically in login form (string). (optional)

  • CardHolderNameHint: Full name of the customer. Barion use this to prefill the payment form (string). (optional)

  • RecurrenceType: Indiates the nature of the recurrence (RecurrenceType string). (optional, can be defined only when RecurrenceId is specified)

  • 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)

  • PayerPhoneNumber: The mobile phone number of the payer (string in '36301234567' format, where 36 is the country code). (optional)

  • PayerWorkPhoneNumber: The work phone number of the payer (string in '36301234567' format, where 36 is the country code). (optional)

  • PayerHomeNumber: The home number of the payer (string in '36301234567' format, where 36 is the country code). (optional)

  • BillingAddress: The billing address associated with the payment, if applicable (BillingAddress). (optional)

  • PayerAccount: Information about the account of the payer (PayerAccountInformation). (optional)

  • PurchaseInformation: Information about the purchase (PurchaseInformation). (optional)

  • ChallengePreference: The merchant's preference about the 3DS challenge (ChallengePreference string). (optional)

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
});

Capture a previously authorized payment - barion.captureAuthorizedPayment(options, [callback])

To capture (finish) a previously authorized payment, use the captureAuthorizedPayment function. [Barion Docs]

Parameters:

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

Output: Read at Barion Docs

Usage example

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

Cancel a previously authorized payment - barion.cancelAuthorizedPayment(options, [callback])

To cancel a previously authorized payment, use the cancelAuthorizedPayment function. [Barion Docs]

Parameters:

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

Output: Read at Barion Docs

Usage example

With callback
barion.cancelAuthorizedPayment({
    PaymentId: '15c1071df3ea4289996ead6ae17'
}, function (err, data) {
    //handle error / process data
});
With promise
barion.cancelAuthorizedPayment({
    PaymentId: '15c1071df3ea4289996ead6ae17'
}).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 3 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)
  • BarionModelError: Thrown, when the prevalidation of the request is failed. node-barion can throw this type of error only if ValidateModels option is set to true on instantiation.

    NOTE: ValidateModels option is set to true by default.

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

    This error has an errors array, which contains the returned errors as strings.

  • Other errors: Common Javascript errors, such as Error or TypeError (thrown e.g. when network error occured).

Usage example

You can distinguish types of errors based on their names, but it is not a must. Instead, you can simply log them to somewhere without any condition checking.

With callback
barion.startPayment(someObj, function (err, data) {
    if (err) {
        if (err.name === 'BarionModelError') {
            //prevalidation of request object found errors
            return console.log(err.errors);
        } else 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 === 'BarionModelError') {
            //prevalidation of request object found errors
            console.log(err.errors);
        } else if (err.name === 'BarionError') {
            //Barion API responded with error
            console.log(err.errors);
        } else {
            //other error occured
            console.log(err);
        }
    });

Future improvements

  • Make available to set optional fields as defaults (e.g. callbackUrl).
  • Support automatic reservation finalization / payment refund (fill the Transactions field via getPaymentState)

Contributions

Contributions are welcome.

If you report a bug/issue, please provide the simplest example code where the error is reproducible (of course, without any confidential data) and describe the environment, where you run node-barion.

If you found a security issue, please contact me in email, and I will get back to you as soon as possible.

I do not merge any PRs that break the build success. To test your changes, before send a PR, you should follow the instructions below:

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

License

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

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

Current Tags

  • 2.0.1                                ...           latest (3 months ago)

5 Versions

  • 2.0.1                                ...           3 months ago
  • 2.0.0                                ...           3 months ago
  • 1.0.3                                ...           6 months ago
  • 1.0.2                                ...           9 months ago
  • 1.0.1                                ...           10 months ago
Maintainers (1)
Downloads
Today 0
This Week 0
This Month 0
Last Day 0
Last Week 0
Last Month 1
Dependencies (2)
Dev Dependencies (11)
Dependents (0)
None

Copyright 2014 - 2016 © taobao.org |