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

| 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: "[email protected]",
        phone: "+407xxxxxxxx",
        firstName: "First",
        lastName: "Last",
        city: "City",
        country: 642,
        countryName: "Country",
        state: "State",
        postalCode: "Zip",
        details: "",
    },
    shipping: {
        email: "[email protected]",
        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

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

| 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": "[email protected]",
        "phone": "+407xxxxxxxx",
        "firstName": "First",
        "lastName": "Last",
        "city": "City",
        "country": 642,
        "countryName": "Country",
        "state": "State",
        "postalCode": "Zip",
        "details": ""
      },
      "shipping": {
        "email": "[email protected]",
        "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);

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

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

| 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