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: '[email protected]',
  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.