/euplatesc

The Node.js library for EuPlătesc Payment Gateway

Primary LanguageTypeScriptMIT LicenseMIT

EuPlătesc Node.js API Library

The EuPlătesc Node Library provides access to the entire EuPlătesc API from applications written in server-side JavaScript.

IMPORTANT: To use this package, you need to ask and apply for an account on the EuPlătesc website. After signing a contract with EuPlătesc, you will receive credentials for accessing the API.

Table of Contents

  1. Table of contents
  2. Getting started
  3. Installation
  4. Usage
  5. API
  6. Test cards
  7. Built with
  8. License

Getting started

This package is the result of my passion and openness to open-source software. I had to implement this service many times in my projects, and almost every time, I had to deal with a headache due to the poor documentation and the non-standard "REST API" provided by EuPlătesc.

This package covers all the actions provided in the EuPlătesc documentation. It can be used either as a CommonJS or ES module.

Installation

Using npm:

$ npm install euplatesc

Using yarn:

$ yarn add euplatesc

Usage

Create a client file and instantiate the EuPlătesc class:

// ./src/lib/epClient.js
import { EuPlatesc } from 'euplatesc';

export default epClient = new EuPlatesc({
  merchantId: process.env.EUPLATESC_MERCHANT_ID,
  secretKey: process.env.EUPLATESC_SECRET_KEY
});

Import the client and call the methods you need:

// ./src/index.js
import epClient from './lib/epClient';

epClient.checkMid().then((midInfo) => console.log(midInfo));

// Also it can be used with async-await:
// await epClient.checkMid()

API

Constructor

import { EuPlatesc } from 'euplatesc';

const epClient = new EuPlatesc({
  merchantId: process.env.EUPLATESC_MERCHANT_ID,
  secretKey: process.env.EUPLATESC_SECRET_KEY,
  testMode: 'true' === process.env.EUPLATESC_TEST_MODE,
  userKey: process.env.EUPLATESC_USER_KEY,
  userApi: process.env.EUPLATESC_USER_API
});

The merchant ID (MID) and the secret key (KEY) can be found at EuPlătesc Panel > Integrations parameters.

The user key (UKEY) and the user API (UAPI) are optional for some methods, but required for others - these methods are indicated with a notice. These credentials can be found at EuPlătesc Panel > Settings > User settings > Account permissions.

Parameter list
Field Type Description
merchantId * string The merchant ID.
secretKey * string The secret key.
testMode boolean Optional. Whether the module is in test mode or not. Default: false.
userKey string Optional. The user key
userApi string Optional. The user API.

* Required field.

paymentUrl

Generate EuPlătesc payment URL.

import epClient from './lib/epClient';

const data = {
  amount: 12.34,
  currency: 'USD',
  invoiceId: 'invoice id',
  orderDescription: 'The description of the order'
};

console.log(epClient.paymentUrl(data));
Parameter list
Field Type Description
amount * number
currency * 'RON' | 'EUR' | 'USD' | 'HUF' | 'MDL' | 'BGN' | 'GBP' | 'PLN'
invoiceId * string
orderDescription * string
frequency { days: number; expiresAt: Date }
billingFirstName string
billingLastName string
billingCompany string Billing company name.
billingAddress string Billing (company) address.
billingCity string Billing (company) city.
billingState string Billing (company) county.
billingZip string Billing (company) ZIP code.
billingCountry string Billing (company) country.
billingPhone string Billing (company) phone number.
billingEmail string Billing (company) email address.
shippingFirstName string
shippingLastName string
shippingCompany string Company data.
shippingAddress string
shippingCity string
shippingState string
shippingZip string
shippingCountry string
shippingPhone string
shippingEmail string
Extra string Additional information sent by the merchant to the gateway. This data is echoed back to the merchant in the reply request.
silentUrl string Callback URL
successUrl string URL to redirect the client in case of a successful transaction.
failedUrl string URL to redirect the client in case of a failed transaction.
epTarget string "self" for the case of using iframe.
epMethod string "post" or "get" for succes/fail redirect.
backToSite string URL to redirect the client when clicking back to the site button or after 60 seconds on the result page.
backToSiteMethod string "post" or "get" for the back-to-site button.
expireUrl string If a timer is set on the payment page, you can change the URL to which the client will be redirected when the timer reaches 0.
rate string Installments number. Format: [bank_code]-[installments_no].
filterRate string Installments number. Format: [bank_code1]-[i_no1]-...-[i_noN],[bank_code2]-[i_no1]-...-[i_no2]. Ex: apb-3-4,btrl-5-6
channel string Filter the available payment channels. Any combinations of the values CC, OP, C2P, and MASTERPASS concatenated with a comma.
generateEpid string If specified and have value 1, instead of redirecting the client will return a JSON containing the URL of the payment page.
valability Date Payment link available until the specified timestamp (Romania timezone).
c2pId string Unique ID of the client used for C2P wallet, blank values disable the wallet.
c2pCid string Unique ID of the enrolled card used for C2P wallet.
lang 'ro' | 'en' | 'fr' | 'de' | 'it' | 'es' | 'hu' Preselect the language of the payment page. If not sent, the language will be chosen based on the client's IP.

* required fields

Return

Example:

{
  paymentUrl: 'https://secure.euplatesc.ro/tdsprocess/tranzactd.php?amount=...';
}

The returned URL will redirect the user to a secure EuPlătesc payment page.

Type:

{
  paymentUrl: string;
}

checkResponse

Check the backward response received by the EuPlătesc POST request.

This logic should be used as a callback in an API endpoint that processes a POST request from the EuPlătesc server.

import epClient from './lib/epClient';

// The data below should be passed from a POST request from EuPlătesc server after a payment is made.
const params = {
  amount: '',
  currency: '',
  invoiceId: '',
  epId: '',
  merchantId: '',
  action: '',
  message: '',
  approval: '',
  timestamp: '',
  nonce: '',
  fpHash: ''
};

console.log(epClient.checkResponse(params));
Parameter list
Field Type Description
amount string The made transaction's amount.
currency 'RON' | 'EUR' | 'USD' | 'HUF' | 'MDL' | 'BGN' | 'GBP' | 'PLN' The made transaction's currency.
invoiceId string The made transaction's invoice ID.
epId string The made transaction's ep ID.
merchantId string The made transaction's merchant ID.
action string The made transaction's action.
message string The made transaction's message.
approval string The made transaction's approval value.
timestamp string The made transaction's timestamp.
nonce string The made transaction's nonce.
fpHash string The made transaction's hash.
Return

Example:

// ResponseResult
{ success: true, response: 'complete' }

Type:

type ResponseResult = {
  success: boolean;
  response: 'complete' | 'failed' | 'invalid';
};

getStatus

Get the status of a transaction.

import epClient from './lib/epClient';

const params = {
  epId: '15F124618DA2E299CBEFA787A09464352946F422'
  // invoiceId: 'FPS12145601'
};

console.log(await epClient.getStatus(params));
Parameter list
Field Type Description
epId string The ID of the transaction.
invoiceId string The ID of the transaction's invoice.

You have to pass either epId or invoiceId as a param object to get the status. If both are passed, the epId field has priority.

Return

Example:

{
  success: `[{merch_id: "4484xxxxxxxxx", invoice_id: "00000", ep_id:"0000000000000000000000000000000000000000", action: "0", message: "Approved", captured: "0", refunded: "0", masked_card: "444444xxxxxx4444", card_expire: "mm-yy", name_on_card: "Test", email: "test@test.com", timestamp: "2014-11-26 10:11:48", tran_type: "Normal", recurent_exp: "", recurent_cancel_date: "" }]`;
}

Type:

{ success: string } | { error: string, ecode: string }

capture

Capture a transaction.

IMPORTANT: For using this method, in addition to merchant ID and secret key in the EuPlătesc client instantiation you should pass both userKey and userApi, too.

import epClient from './lib/epClient';

const epId = '15F124618DA2E299CBEFA787A09464352946F422';
console.log(await epClient.capture(epId));
Parameter list
Field Type Description
epId string The ID of the transaction.
Return

Example:

{
  success: '1';
}

Type:

{ success: string } | { error: string; ecode: string }

reversal

Reversal of a transaction.

IMPORTANT: For using this method, in addition to merchant ID and secret key in the EuPlătesc client instantiation you should pass both userKey and userApi, too.

import epClient from './lib/epClient';

const epId = '15F124618DA2E299CBEFA787A09464352946F422';
console.log(await epClient.reversal(epId));
Parameter list
Field Type Description
epId string The ID of the transaction.
Return

Example:

{
  success: '1';
}

Type:

{ success: string } | { error: string; ecode: string }

partialCapture

Partial capture of a transaction.

IMPORTANT: For using this method, in addition to merchant ID and secret key in the EuPlătesc client instantiation you should pass both userKey and userApi, too.

import epClient from './lib/epClient';

const epId = '15F124618DA2E299CBEFA787A09464352946F422';
const amount = 123.78;

console.log(await epClient.partialCapture(epId, amount));
Parameter list
Field Type Description
epId string The ID of the transaction.
amount number Partially captured amount.
Return

Example:

{
  success: '1';
}

Type:

{ success: string } | { error?: string; message?: string; ecode: string }

refund

(Partial) Refund a transaction.

IMPORTANT: For using this method, in addition to merchant ID and secret key in the EuPlătesc client instantiation you should pass both userKey and userApi, too.

import epClient from './lib/epClient';

const epId = '15F124618DA2E299CBEFA787A09464352946F422';
const amount = 123.78;
const reason = 'Refund reason.';

console.log(await epClient.refund(epId, amount, reason));
Parameter list
Field Type Description
epId string The ID of the transaction.
amount number The refunded amount. It can be smaller than the total amount of the transaction.
reason string Optional. The reason, the transaction is to be refunded.
Return

Example:

{
  success: '1';
}

Type:

{ success: string } | { error?: string; message?: string; ecode: string }

cancelRecurring

Cancel a recurring transaction.

IMPORTANT: For using this method, in addition to merchant ID and secret key in the EuPlătesc client instantiation you should pass both userKey and userApi, too.

import epClient from './lib/epClient';

const epId = '15F124618DA2E299CBEFA787A09464352946F422';
const reason = 'The user asked to cancel this recurrent transaction.';

console.log(await epClient.cancelRecurring(epId, reason));
Parameter list
Field Type Description
epId string The ID of the transaction.
reason string Optional. The reason, the recurring transaction is to be canceled.
Return

Example:

{
  success: '<base EPID>';
}

Type:

{ success: string } | { error?: string; message?: string; ecode: string }

updateInvoiceId

Update the invoice ID of a transaction.

IMPORTANT: For using this method, in addition to merchant ID and secret key in the EuPlătesc client instantiation you should pass both userKey and userApi, too.

import epClient from './lib/epClient';

const epId = '15F124618DA2E299CBEFA787A09464352946F422';
const newInvoiceId = 'INV-0075';

console.log(await epClient.updateInvoiceId(epId, newInvoiceId));
Parameter list
Field Type Description
epId string The ID of transaction invoice ID is to be updated.
newInvoiceId string The new invoice ID is to be updated.
Return

Example:

{
  success: '1';
}

Type:

{ success: string } | { error: string }

getInvoiceList

Get invoice list.

IMPORTANT: For using this method, in addition to merchant ID and secret key in the EuPlătesc client instantiation you should pass both userKey and userApi, too.

import epClient from './lib/epClient';

const from = new Date('2022-08-24');
const to = new Date('2022-09-14');

console.log(await epClient.getInvoiceList({ from, to }));
Parameter list
Field Type Description
from Date Optional. The date from which the filter starts to search invoices.
to Date Optional. The date to which the filter ends to search invoices.

If from and to are sent empty, it will look for invoices from the last three months. It returns max 100 records.

Return

Example:

// { success: Invoice[] } | { error: string }
{
  success: [
    {
      invoice_number: '',
      invoice_date: '',
      invoice_amount_novat: '',
      invoice_amount_vat: '',
      invoice_currency: '',
      transactions_number: '',
      transactions_amount: '',
      transferred_amount: ''
    }
  ];
}

Type:

type Invoice = {
  invoice_number: string;
  invoice_date: string;
  invoice_amount_novat: string;
  invoice_amount_vat: string;
  invoice_currency: 'RON' | 'EUR' | 'USD';
  transactions_number: string;
  transactions_amount: string;
  transferred_amount: string;
};

getInvoiceTransactions

Get invoice transaction list.

IMPORTANT: For using this method, in addition to merchant ID and secret key in the EuPlătesc client instantiation you should pass both userKey and userApi, too.

import epClient from './lib/epClient';

const invoice = 'FPSxxxxxxxx';

console.log(await epClient.getInvoiceTransactions(invoice));
Parameter list
Field Type Description
invoice string Settlement invoice number.
Return

Example:

// { success: InvoiceTransaction[] } | { error: string }
{
  success: [{
    mid: string;
    invoice_id: string;
    epid: string;
    rrn: string;
    amount: string;
    commission: string;
    installments: string;
    type: 'capture' | 'refund' | 'chargeback';
  }]
}

Type:

type InvoiceTransaction = {
  mid: string;
  invoice_id: string;
  epid: string;
  rrn: string;
  amount: string;
  commission: string;
  installments: string;
  type: 'capture' | 'refund' | 'chargeback';
};

getCapturedTotal

Get captured total.

IMPORTANT: For using this method, in addition to merchant ID and secret key in the EuPlătesc client instantiation you should pass both userKey and userApi, too.

import epClient from './lib/epClient';

const params = {
  mids: '4484xxxxxxxxx,4484xxxxxxxxx', // or just "4484xxxxxxxxx"
  from: new Date('2022-02-13'),
  to: new Date('2022-03-22')
};

console.log(await epClient.getCapturedTotal(params));
Parameter list
Field Type Description
mids string Optional. Separated merchant IDs by commas. If empty, it will set up the merchant ID from client initialization.
from Date Optional. The date from which the filter starts to search totals.
to Date Optional. The date to which the filter ends to search totals.

If from and to are empty, it will look for the total in the last month.

Return

Example:

// { success: CapturedTotal } | { error: string }
{
  success: {
    EUR: "xxx",
    GBP: "xxx",
    RON: "xxx",
    USD: "xxx"
  }
}

Type:

type CapturedTotal = {
  EUR?: string;
  GBP?: string;
  RON?: string;
  USD?: string;
};

getCardArt

Get card art data.

IMPORTANT: For using this method, in addition to merchant ID and secret key in the EuPlătesc client instantiation you should pass both userKey and userApi, too.

import epClient from './lib/epClient';

const epId = '15F124618DA2E299CBEFA787A09464352946F422';

console.log(await epClient.getCardArt(epId));
Parameter list
Field Type Description
epId string The EPID of the transaction.
Return

Example:

// { success: CardArt } | { error: string; ecode: string }
{
  success: {
    bin: "4xxxxx",
    last4: "xxxx",
    exp: "yymm",
    cardart: "*BASE64 ENCODED IMAGE*"
  }
}

Type:

type CardArt = {
  bin: string;
  last4: string;
  exp: string;
  cardart: string;
};

getSavedCards

Get saved cards of a customer.

import epClient from './lib/epClient';

const clientId = '1';
const mid = '4484xxxxxxxxx';

console.log(await epClient.getSavedCards(clientId, mid));
Parameter list
Field Type Description
clientId string The ID of the client.
mid string Optional. Merchant ID. If empty, it will set up the merchant ID from client initialization.
Return

Example:

// { cards: SavedCard[] } | { error: string; ecode: string }
{
  cards: [
    {
      id: 'xxxxxx',
      bin: '479032',
      last4: '4512',
      mask: '479032xxxxxx4512',
      exp: '23-10',
      cardart:
        'https://secure.euplatesc.ro/tdsprocess/images/ca8_small/1698962c052c3c6e40468363636304b23070222638c5f7071d415372b5119ba6.jpg'
    }
  ];
}

Type:

type SavedCard = {
  id: string;
  bin: string;
  last4: string;
  mask: string;
  exp: string;
  cardart: string;
};

removeCard

Remove a saved card of a customer.

import epClient from './lib/epClient';

const clientId = '1';
const cardId = '234';
const mid = '4484xxxxxxxxx';

console.log(await epClient.removeCard(clientId, cardId, mid));
Parameter list
Field Type Description
clientId string The ID of the client.
cardId string The ID of the card.
mid string Optional. Merchant ID. If empty, it will set up the merchant ID from client initialization.
Return

Example:

{
  success: '1';
}

Type:

{ success: string } | { error: string; ecode: string }

checkMid

Check a merchant ID.

import epClient from './lib/epClient';

const mid = '4484xxxxxxxxx';

console.log(await epClient.checkMid(mid));

// { success: "1" } or { error, ecode }
Parameter list
Field Type Description
mid string Optional. Merchant ID. If empty, it will se tup the merchant ID from client initialization.
Return

Example:

// Merchant | { error: string }
{
  name: "...",
  url: "...",
  cui: "...",
  j: "...",
  status: "test/live",
  recuring: "N/Y/YA",
  tpl: "tpl-v15/tpl-v17/tpl-v21",
  rate_mode: "C/EP",
  rate_apb: "6;12",
  rate_btrl: "2;3;4;5;6",
  rate_brdf: "3;6",
  rate_fbr: "2;3;4",
  rate_gbr: "",
  rate_rzb: "2;3;4;5;6;7;8;9;10;11;12;15;18;20;24"
}

Type:

type Merchant = {
  name: string;
  url: string;
  cui: string;
  j: string;
  status: string;
  recuring: string;
  tpl: string;
  rate_mode: string;
  rate_apb: string;
  rate_btrl: string;
  rate_brdf: string;
  rate_fbr: string;
  rate_gbr: string;
  rate_rzb: string;
};

Test cards

Card number Expire date CVC Name Result
4111111111111111 24/01 123 Test Authentication failed
4444333322221111 24/01 123 Test Not sufficient funds
4000020000000000 24/01 123 Test Transaction declined
4400000000000008 24/01 123 Test Expired card
4607000000000009 24/01 123 Test Invalid response
4000640000000005 24/01 123 Test Approved
5454545454545454 24/01 123 Test Authentication failed
5555555555554444 24/01 123 Test Not sufficient funds
2222400010000008 24/01 123 Test Transaction declined
2222400030000004 24/01 123 Test Expired card
5100060000000002 24/01 123 Test Invalid response
5500000000000004 24/01 123 Test Approved

Built with

License

MIT License