euplatesc

v1.0.5

Published

a year ago

The payment gateway for EuPlatesc.ro

Downloads

375

0High
0Medium
0Low

vladilie

euplatesc payment gateway eu platesc

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.

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.

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

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

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

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

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

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

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: "[email protected]", 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));

| Field | Type | Description | | ----- | ------ | -------------------------- | | epId | string | The ID of the transaction. |

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

| Field | Type | Description | | ----- | ------ | -------------------------- | | epId | string | The ID of the transaction. |

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

| Field | Type | Description | | ------ | ------ | -------------------------- | | epId | string | The ID of the transaction. | | amount | number | Partially captured amount. |

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

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

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

| Field | Type | Description | | ------ | ------ | ------------------------------------------------------------------ | | epId | string | The ID of the transaction. | | reason | string | Optional. The reason, the recurring transaction is to be canceled. |

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

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

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

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

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

| Field | Type | Description | | ------- | ------ | -------------------------- | | invoice | string | Settlement invoice number. |

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

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

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

| Field | Type | Description | | ----- | ------ | ---------------------------- | | epId | string | The EPID of the transaction. |

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

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

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

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

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 }

| Field | Type | Description | | ----- | ------ | ------------------------------------------------------------------------------------------- | | mid | string | Optional. Merchant ID. If empty, it will se tup the merchant ID from client initialization. |

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

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

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 ⤴