netopia-payment2

NETOPIA Payments Package

The NETOPIA Payments package provides access to the NETOPIA Payments API V2 from applications written in server-side JavaScript.

Table of Contents

• Installation
• Usage
• API Reference
  • Netopia Constructor
    • Netopia Methods
      • createOrder
      • getStatus
      • verifyAuth
  • IPN Constructor
    • Ipn Methods
      • verify
• Error Handling
• Useful Links

Installation ⤴

Install the package with:

npm i netopia-payment2

or

yarn add netopia-payment2

Usage ⤴

The package needs to be configured with your account's API key and signature key, which are available in the NETOPIA Payments admin.

API Reference ⤴

Netopia Constructor ⤴

const { Netopia } = require("netopia-payment2");

const netopia = new Netopia({ apiKey, posSignature, isLive });

Creates a new instance of the Netopia class.

Note
API Key: NETOPIA Payments admin > Profile > Security
POS Signature: NETOPIA Payments admin > Point of sale > Technical settings

Parameter list

constructor params	Type	Default	Description	Required
apiKey	string	null	API key provided by NETOPIA	Yes
posSignature	string	null	Signature provided by NETOPIA	Yes
isLive	Boolean	false	Use for sandbox	No

Netopia Methods ⤴

createOrder ⤴

Creates a new order for payment.

const response = await netopia.createOrder(configData, paymentData, orderData);

Example:

const configData = {
  emailTemplate: "Email template",
  emailSubject: "Email subject",
  notifyUrl: "https://www.my.domain/my_notify_url",
  redirectUrl: "https://www.my.domain/my_redirect_url",
  cancelUrl: "https://www.my.domain/my_cancel_url",
  language: "ro",
};
const paymentData = {
    options: {
        "installments": 0,
        "bonus": 0,
        "split": [
            {
                posID: 0,
                amount: 0
            }
        ]
    },
    instrument: {
        "type": "card",
        "account": "9900004810225098",
        "expMonth": 12,
        "expYear": 2022,
        "secretCode": "111",
        "token": "",
        "clientID": ""
    },
    data: {
        "property1": "string",
        "property2": "string"
    }
};
const orderData = {
    ntpID: '',
    orderID: "XXXXXXX",
    description: "Some order description",
    amount: 0.1,
    currency: "RON",
    dateTime: "2023-09-27T15:48:17",
    products: {
        name: 'Product name'
        code: 'xxx',
        category: 'Category name',
        price: 10,
        vat: 19,
    },
    billing: {
        email: "[e-mail]",
        phone: "+407xxxxxxxx",
        firstName: "First",
        lastName: "Last",
        city: "City",
        country: 642,
        countryName: "Country",
        state: "State",
        postalCode: "Zip",
        details: "",
    },
    shipping: {
        email: "[e-mail]",
        phone: "+407xxxxxxxx",
        firstName: "First",
        lastName: "Last",
        city: "City",
        country: 642,
        countryName: "Country",
        state: "State",
        postalCode: "Zip",
        details: "",
    },
    installments: {
        selected: 0,
        available: [ 0 ];
    }
    data: {
        "property1": "string",
        "property2": "string"
    }
}

Note
The shippingData is optional

Parameter list

Fields for configData

Field	Type	Description	Required
emailTemplate	string	Required only for custom notification emails; shared by NETOPIA	No
emailSubject	string	Notification e-mail subject; mandatory if emailTemplate is present	Yes
cancelUrl	string	URL where NETOPIA will send payment result notifications	Yes
notifyUrl	string	URL on the merchant side where NETOPIA will send payment results	Yes
redirectUrl	string	URL on the merchant side where 3-D Secure authentication response sent	Yes
language	string	Language for notifications; use ISO 639-1 codes	Yes

Fields for paymentData

Field	Type	Description
options	object	Payment options information
installments	integer	Set the installments number for the client to pay in
bonus	integer	Set the loyalty points number for the client to use
split	array[object]	Split payments (will be available in future versions)
posID	integer	Destination POS
amount	number	Amount to be disbursed; should always be smaller than order amount
		- Must be greater than or equal to 0
instrument	object	Payment instrument information
type	string	Mandatory for all payment methods except token
account	string	Mandatory for all payment methods except token
		- If type is card, this is the card number
expMonth	integer	Expiration month (mandatory if type is card)
expYear	integer	Expiration year (mandatory if type is card)
secretCode	string	Card security code (CVV/CVC) for card payments
		- Must be less than or equal to 4 characters
token	string	If present, token overrides all other data
clientID	string	If present, binding, etc.
data	Atributes	Payment-specific information (customer browser and device data)

Fields for orderData

Field	Type	Description	Required
ntpID	string	NETOPIA internal id	No
posSignature	string	Merchant POS identifier, available in your NETOPIA account	Yes
		- Must have between 0 and 64 characters
dateTime	string	Order registration date	Yes
description	string	Order description	Yes
orderID	string	Merchant internal order id	Yes
amount	number	Amount to be paid (set to 0 for account verification)	Yes
		- Must be greater than or equal to 0
		- Must be less than or equal to 100000
currency	string	Currency using ISO 4217 alpha codes	Yes
		- Must have between 3 characters and 3 characters
billing	object	Customer billing information	Yes
email	string	Customer email address	Yes
phone	string	Customer phone number	Yes
firstName	string	Customer first name	Yes
lastName	string	Customer last name	Yes
city	string	Customer city	Yes
country	integer	Customer country using ISO 3166-1 numeric codes	Yes
countryName	string	Customer country name	Yes
state	string	Customer state	Yes
postalCode	string	Customer postal code	Yes
details	string	Customer address details, interphone	Yes
shipping	object	Customer shipping information	No
products	array[object]	Array of product objects	No
installments	object		No
selected	integer	Available	No
available	array[integer]	Array of integers	No
data	Atributes	Custom merchant parameters related to the order	No

Response

Example:

{
    code: 200,
    message: 'You send your request successfully',
    data: {
        customerAction: {},
        error: { code: '101', message: 'Redirect user to payment page' },
        payment: {
            amount: 0.1,
            currency: 'RON',
            ntpID: '1234567',
            operationDate: '0001-01-01T00:00:00',
            paymentURL: 'https://secure-sandbox.netopia-payments.com/ui/card?p=XXXXX-XXXX-XXXX',
            status: 1
        }
    }
}

getStatus ⤴

Get status of an order.

const response = await netopia.getStatus(ntpID);

Parameter list

Field	Type	Description	Required
ntpID	string	NETOPIA internal id you received in your start response	Yes

Response

Example:

{
  "code": 200,
  "message": "Successfully get payment status",
  "data": {
    "bnpl": {
      "oney": {}
    },
    "config": {
      "emailTemplate": "Comanda platita",
      "language": "ro",
      "notifyUrl": "https://www.my.domain/my_notify_url",
      "redirectUrl": "https://www.my.domain/my_redirect_url",
      "cancelUrl": "https://www.my.domain/my_cancel_url"
    },
    "customerAction": {},
    "error": {
      "code": "00",
      "message": "Approved"
    },
    "merchant": {
      "merchantName": "Test test",
      "posID": 00000,
      "posName": "NETOPIA Test",
      "posType": 0,
      "posUrl": "https://www.my.domain/",
      "qrType": 1,
      "showCancel": false
    },
    "order": {
      "amount": 0.1,
      "billing": {
        "email": "[e-mail]",
        "phone": "+407xxxxxxxx",
        "firstName": "First",
        "lastName": "Last",
        "city": "City",
        "country": 642,
        "countryName": "Country",
        "state": "State",
        "postalCode": "Zip",
        "details": ""
      },
      "shipping": {
        "email": "[e-mail]",
        "phone": "+407xxxxxxxx",
        "firstName": "First",
        "lastName": "Last",
        "city": "City",
        "country": 642,
        "countryName": "Country",
        "state": "State",
        "postalCode": "Zip",
        "details": ""
      },
      "currency": "RON",
      "dateTime": "2023-09-27T15:48:17",
      "description": "produse diverse",
      "installments": {
        "selected": 0
      },
      "ntpID": "XXXXX",
      "orderID": "000000",
      "posSignature": "XXXX-XXXX-XXXX-XXXX-XXXX"
    },
    "payment": {
      "allowedMethods": [
        "card"
      ],
      "amount": 0.1,
      "binding": {
        "expireMonth": 0,
        "expireYear": 0
      },
      "currency": "RON",
      "instrument": {
        "country": 0
      },
      "ntpID": "2010313",
      "operationDate": "2024-11-06T10:38:44",
      "options": {
        "bonus": 0,
        "installments": 1
      },
      "rrn": "XXXxxxxx",
      "status": 3
    }
  }
}

verifyAuth ⤴

Verify-auth use is only for the transactions with 3DS cards and after you have authorize end-point response.

const response = await netopia.verifyAuth(authenticationToken, ntpID, formData);

Parameter list

Field	Type	Description	Required
authenticationToken	string	The authentication token you received in your start response	Yes
ntpID	string	NETOPIA internal id you received in your start response	Yes
formData	object	3-D Secure authentication response; all data received in your redirectUrl is mandatory and should not be altered	Yes

Response

Example:

{
    "status": 1,
    "code": 200,
    "message": "Successfully verify authentication ",
    "data": {
        "error": {
        "code": "00",
        "message": "Approved"
        },
        "payment": {
        "amount": 10,
        "currency": "RON",
        "data": {
            "AuthCode": "1XXX",
            "BIN": "990000",
            "ISSUER": "Netopia",
            "ISSUER_COUNTRY": "642",
            "RRN": "XXXxxxx"
        },
        "ntpID": "1234567",
        "status": 3,
        "token": "NTY1Mzq4mwb4nynMLEfcwrA0MnEUJ/19Pk9doJWe5PWxoLhQC++W/Eqh6h/wB1KCDVSiBCkaWYtFzWyFoP6YbS"
        }
    }
}

IPN Constructor ⤴

const { Ipn } = require("netopia-payment2"); // ES5

const netopiaIpn = new Ipn({
  posSignature,
  posSignatureSet,
  hashMethod,
  alg,
  publicKeyStr,
});

Creates a new instance of the Ipn class.

Parameter list

constructor params	Type	Default	Description	Required
posSignature	string	null	Signature provided by NETOPIA	Yes
posSignatureSet	array	null	All POS Signatures provided by NETOPIA	Yes
hashMethod	string	'sha512'	Hash method used	No
alg	string	'RS512'	Algorithm	No
publicKey	string	null	Public Key provided by NETOPIA	Yes

Ipn Methods ⤴

verify ⤴

const response = await netopiaIpn.verify(verificationToken, rawData);

Parameter list

Field	Type	Default	Description	Required
verificationToken	string	null	Verification token provided by NETOPIA	Yes
rawData	string	null	Data provided by NETOPIA in the IPN	Yes

Response

Example:

   {
    errorType: 2,
    errorCode: 1234,
    errorMessage: 'Payment was confirmed; deliver goods',
    message: null,
    status: null
  }

Error Handling ⤴

Error codes

• 0 : Card has no 3DS
• 16 : Declined. Card has a risk
• 17 : Invalid card number
• 18 : Closed card
• 19 : Expired card
• 20 : Insufficient funds
• 21 : Invalid CVV
• 22 : Issuer error
• 23 : Order is expired
• 26 : Card limit exceeded
• 34 : Transaction not allowed
• 35 : Transaction declined (no reason specified)
• 36 : Transaction declined by antifraud system
• 39 : 3DSecure authentication failed
• 56 : duplicated Order ID
• 99 : General error
• 100 : Requires 3-D Secure authentication
• 101 : Redirect user to payment URL
• 102 : Payment locked, 3DSecure authentication pending

Status codes

• 3 : is paid
• 5 : is confirmed
• 12 : rejected
• 15 : need authorize

Useful links ⤴

• demo cards used for sandbox

• NETOPIA Payments Documentation

• API Reference

License

This project is licensed under the MIT License. See the LICENSE file for details.