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
Getting started
Installation
Usage
API
Test cards
Built with
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

vladutilie/euplatesc

EuPlătesc Node.js API Library

Table of Contents

Getting started ⤴

Installation ⤴

Usage ⤴

API ⤴

Constructor ⤴

paymentUrl ⤴

checkResponse ⤴

getStatus ⤴

capture ⤴

reversal ⤴

partialCapture ⤴

refund ⤴

cancelRecurring ⤴

updateInvoiceId ⤴

getInvoiceList ⤴

getInvoiceTransactions ⤴

getCapturedTotal ⤴

getCardArt ⤴

getSavedCards ⤴

removeCard ⤴

checkMid ⤴

Test cards ⤴

Built with ⤴

License ⤴