@bogdan-nita/netopia-card

Netopia Card

Lightweight NodeJS library to integrate Netopia mobilPay payment gateway in your projects.

• builds Netopia mobilPay request from the input data
• adds split payments field to the request to send part of the payment to another account
• validates Netopia mobilPay response based on the private key associated with the account

Installation

npm i netopia-card
#or
yarn add netopia-card

Useful links

• request structure for card payments
• demo cards used for sandbox

Usage

The first step for using this library is to set yor unique environment variables from an approved Netopia sales point.

You can find these keys in the Netopia admin dashboard > Puncte de vanzare > Vezi lista > Setari tehnice

Your .env file should look like this:

NETOPIA_SIGNATURE="XXXX-XXXX-XXXX-XXXX-XXXX"
NETOPIA_PRIVATE_KEY_B64="-----BEGIN PRIVATE KEY-----
XXXX...XXXX
-----END PRIVATE KEY-----"
NETOPIA_PUBLIC_KEY_B64="-----BEGIN CERTIFICATE-----
XXXX...XXXX
-----END CERTIFICATE-----"
NETOPIA_CONFIRM_URL="http://api.example.com"
NETOPIA_RETURN_URL="http://example.com"

Import the library

const Netopia = require('netopia-card'); // ES5
import Netopia from 'netopia-card'; // ES6

constructor params	Type	Description
signature	string	Signature provided by Mobilpay
publicKey	string	Public key provided by Mobilpay
privateKey	string	Private key provided by Mobilpay
confirmUrl	string	The url which the Netopia API should call for confirmation
returnUrl	string	The url which the Netopia API should return after confirmation
sandbox	Boolean	Use for sandbox

If you saved the signature, the public key, and the private key in the .env file, you do not have to provide the constructor with parameters. These will be taken from the environment variables if they exist.

const netopia = new Netopia();

or

const netopia = new Netopia({
  signature, // Netopia mobilPay signature
  publicKey, // Netopia mobilPay public key
  privateKey, // Netopia mobilPay private key
});

After initialization, you need to initialize and set the client and payment details.

setClientBillingData params	Type	Description
firstName	string	The client's first name
lastName	string	The client's last name
country	string	The client's country
county	string	The client's county
city	string	The client's city
zipCode	string	The client's zip code
address	string	The client's address
email	string	The client's email
phone	string	The client's phone number
bank	string	The client's bank
iban	string	The client's iban

netopia.setClientBillingData({
  firstName: 'John',
  lastName: 'Doe',
  country: 'Romania',
  county: 'Bucharest',
  city: 'Bucharest',
  zipCode: '123456',
  address: '123 Main St',
  email: '[e-mail]',
  phone: '1234567890',
  bank: 'Bank',
  iban: 'RO00BANK0000000000000000',
});

setParams params	Type	Description
params	{ [key: string]: any }	The params for the payment

netopia.setParams({ param1: 'string', param2: 1 });

setPaymentData params	Type	Description
orderId	string	The unique identifier for the payment
amount	number	The amount to be paid
currency	string	The currency in which the payment will take place
details	string	The details of the payment

netopia.setPaymentData({
  orderId: Date.now().toString(),
  amount: 1,
  currency: 'RON',
  details: 'No details',
});

You can also set a different shipping address by using netopia.setClientShippingData({...}) which has the same parameters as netopia.setClientBillingData({...}) presented above.

For setting up split payments you can use the setSplitPayment function:

setSplitPayment params	Type	Description
firstDestinationId	string	The sac id (signature) of the first recipient
firstDestinationAmount	number	The amount for the first recipient
secondDestinationId	string	The sac id (signature) of the second recipient
secondDestinationAmount	number	The amount for the second recipient

netopia.setSplitPayment('<first_recipient_sac_id>', 1, '<second_recipient_sac_id>', 2);

To build the request

const request = netopia.buildRequest();

The request that will be constructed will look like:

{
  "url": "http://sandboxsecure.mobilpay.ro",
  "env_key": "OQR4VUMOHY1W+jMcE8NCc7Es2mf37+lqECwygW8rS1O55E2kkwwZqY9oyG4WuXeyN7rjIiC3YvmvJ1od8+5f2p1ygxe4H1gp0naxfEi52W/PAuoChgqkVKswvI67kzKg3yc7JGpbPcOp+hTgnTAzegWGb69WTpLxWf+HGHs0A/o=",
  "data": "OImfydaqxpWVm0ygudhUNaV0vlBkpHSEcs+gqX5z8vr1rt5KXCLtODtTsXo2/B4D7sYpIj21sm4hr4M/80/DuaH/46tw2v602PUs3MdVqY7/KWiDUw3EywwB5Vjvwqd4DfIUtOBYTvbTPvnj2Ly5MdUWxtJpOFkE3UbmmbJqDYIqQDus/G8EisHeJI73pWumoSOZjYpukV6wj4uh9Pbp/GlnaFPIvKWECF0lBx8yr6kYbLGcDYqB6ly8yAtr1BOcCmcfV2J5BGbnPnF3RbAdGYvwd5Vt2MvzdETeoYrtb+hTjw1c2HSo/P/NhbKzk9IOA6ZkMcDE4Lti82c4QkwfwSTtyYlrkszk1CmU+m3r6if0qPqvTd5KTn7Zi/YcRNvwYmu05MKgth8MuAl/guqx37H9o6dSBDpBmCi+fRQ09J/BvzjIihAVpqypayByRu/jB6KJ4PZrBMHdsTdkbjDosuWfJPeEl+HwkWXnTsTdemGjsxpIE80Cat8c2ma/LHMvcRkpowOwX6YAhKBifI+s7zKbbA9L351YqgUSwKLXT2IuWiaPWIF+0ppSMI3Kc3Eqd6GdnFLy1Ku+IX3wpY4rOetbdYdotdLSfTceThx1raQfA6UMqbW7JdRgo++SfLXXO+p9QatWps+ZvLjhFCqufF5l0SeNFyXvmVkk1Qvu0uBxLy+V1t6qoX3SiVho/tEIFf6EcZ3Rp8pHUo+YTQmME+kXP0lexp6Ur3BNYiCqmi6Vobg23IguNzjZV0PIIH0etbq186Rqcz9otmPekO6/z1cZKTVtgoO2t+5PNWQ4ivjvSizUlV2Ltv3D7YqC1bOMJR4rrKarMLUnczAoWplT9OIK7eSnwo3kF7/vceKZJt4J+CbRBWHGATV/c7ktgkJXoOyPyjq8NqRnkX2ECnRVwegOa/ZIoIldPUuQoEqi1Ie5m4IerUDULBVoOGzbzEeq+3H2oGTPyoyCdmK1nz6DiDTMrnRb7C++hPz2+MN6DxYYFAIkXmh6NzfLTK8x/vVeSHkCea1drjSIUTscx9U+uYtcgUpl81IIhGGbvoCaqScf7Pedrj8pZujyX34DBqJ0wdHtFwu3jDL5znRiCIqlmJCYErweJoUCcTphDvpUwY6vWOise+5n33gCf1/FrUrXRApcU9N3/HokiT90cIfyK95TGunU5Q=="
}

To send a request to Mobilpay, you need to setup a form with method="POST", and action=request.url. As inputs for the form, you need to send the request.env_key and request.data.

After being processed and the payment has been made, the Mobilpay API will make an API call to the confirmUrl set above. The confirmUrl should be an endpoint on the API you are building, because it needs to verify the response from Mobilpay.

To verify, you need the validatePayment method which take the env_key and data from the Mobilpay request body, and also set the private key (from file or string).

validatePayment params	Type	Description
env_key	string	The env_key from the Mobilpay request body
data	string	The data from the Mobilpay request body

const { data, env_key } = req.body;
const netopia = new Netopia();
const response = await netopia.validatePayment(env_key, data);

if (response.error) {
  /*
   * Code in case of error
   */
  res.set(response.res.set.key, response.res.set.value);
  res.status(200).send(response.res.send);
}

/*
 * Code in case of success
 */
switch (response.action) {
  case 'confirmed':
    // do something
    break;
  case 'paid':
    // do something
    break;
  case 'paid_pending':
    // do something
    break;
  case 'confirmed_pending':
    // do something
    break;
}

res.set(response.res.set.key, response.res.set.value);
res.status(200).send(response.res.send);

A successful response from the validation looks like this:

{
    "action": mobilpayAction,
    "errorMessage": null,
    "error": null,
    $: {...},
    "orderInvoice": {...},
    "res": {
        "set": {
            "key": "Content-Type",
            "value": "application/xml"
        },
        "send": `<?xml version="1.0" encoding="utf-8" ?><crc>errorMessage</crc>`
    }
}

Implementation details

Confirm URL vs return URL

• confirm URL - a URL in your API that will be called whenever the status of a payment changes
• return URL - a URL in your web application where the client will be redirected to once the payment is complete.

The returnUrl should not be confused with a success or cancel URL, the information displayed here is dynamic, based on the information previously sent to the confirmUrl.

The returnUrl should be a static page to indicate the end-user that the payment has been made.

Debugging

This module uses debugging features for important operations. To activate debugging set the SHOW_NETOPIA_DEBUG="yes" environment variable.