euplatesc

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
   • Constructor
   • paymentUrl
   • paymentParams
   • checkResponse
   • getStatus
   • printTransaction
   • capture
   • reversal
   • partialCapture
   • refund
   • cancelRecurring
   • updateInvoiceId
   • getInvoiceList
   • getInvoiceTransactions
   • getCapturedTotal
   • getTransactionList
   • getCardArt
   • getSavedCards
   • removeCard
   • checkMid
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, and it has no runtime dependencies - it builds on the fetch and FormData globals, so it requires Node 18 or newer.

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.

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

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

{
  paymentUrl: string;
}

paymentParams

Build the full field set posted to the gateway, without wrapping it into a URL.

Use it when you need to POST the fields yourself. That is the only supported way to run a subsequent recurring transaction, since that call is made server to server, without the customer being present.

import epClient from './lib/epClient';

const fields = epClient.paymentParams({
  amount: 12.34,
  currency: 'RON',
  invoiceId: 'invoice id',
  orderDescription: 'Recurent payment',
  baseEpId: '15F124618DA2E299CBEFA787A09464352946F422' // implies recurrentType: 'Recurent'
});

await fetch('https://secure.euplatesc.ro/tdsprocess/tranzactd.php', {
  method: 'POST',
  body: new URLSearchParams(fields)
});

It takes the same parameters as paymentUrl and returns a Record<string, string>.

Recurring payments come in two parts. The initial (enrolling) transaction carries frequency and is sent as recurent=Base; the merchant redirects the customer to it like any other payment. Subsequent transactions carry baseEpId and are sent as recurent=Recurent (or Recurent2CIT for a 3-D Secure one). Depending on how your merchant account is configured, EuPlătesc may initiate the subsequent transactions on its own cron jobs, in which case you never have to send them.

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

Reply to the EuPlătesc server with the plain text OK, otherwise the request may be retried.

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

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

{
  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: "" }]`;
}

{ success: string | TransactionStatus[] } | { error: string; ecode?: string }

printTransaction

Get the transaction receipt as a base64 encoded PDF.

import epClient from './lib/epClient';

const epId = '15F124618DA2E299CBEFA787A09464352946F422';
const result = await epClient.printTransaction(epId);

if ('success' in result) {
  await fs.writeFile('receipt.pdf', Buffer.from(result.file, 'base64'));
}

{
  success: '1',
  file: 'JVBERi0xLjQK...' // base64 encoded PDF
}

{ success: string; file: 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));

{
  success: '1';
}

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

{
  success: '1';
}

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

{
  success: '1';
}

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

{
  success: '1';
}

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

{
  success: '<base EPID>';
}

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

{
  success: '1';
}

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

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

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

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

type InvoiceTransaction = {
  mid: string;
  invoice_id: string;
  epid: string;
  rrn: string;
  amount: string;
  currency: 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));

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

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

getTransactionList

Get the transaction list.

import epClient from './lib/epClient';

const params = {
  from: new Date('2021-01-01'),
  to: new Date('2021-06-01'),
  status: 'success',
  limit: 100
};

console.log(await epClient.getTransactionList(params));

{ success: string | TransactionStatus[] } | { error: string; ecode?: 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));

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

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

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

{
  success: '1';
}

{ 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 }

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

These work only while the account is in test state. Test accounts also accept real cards in the test environment, so that you can exercise the processing terminal; for PSP customers the amount is capped at 1. Contact the EuPlătesc team if you need live card acceptance disabled in the test environment.

Built with

Nothing - the package has no runtime dependencies. It uses the fetch and FormData globals built into Node, so it needs Node 18 or newer.

License

MIT License