Etpay-sdk NPM | npm.io

ETpay Node.js SDK

Official ETpay SDK for Node.js

Installation

Using npm

npm install etpay-sdk

Using yarn

yarn add etpay-sdk

Documentation

Download source code, then install proyect dependencies and execute the docs command:

npm install
npm run docs

For yarn use the next commands

yarn install
yarn docs

A folder named docs will be created on proyect root.

Test

Run local test.

npm install # install proyect dependencies
npm run test

How to use

Configure ETpay module:

Example code

// Import ETpay module
import { ETpay } from "etpay-sdk";

// Declare global vars

// Commerce identifier provided by ETpay.
const MERCHANT_CODE = "valid_code";
// Secret token used to authenticate against the API provided by ETpay.
const MERCHANT_API_TOKEN = "valid_api_key";
// Api url provided by ETpay.
const API_URL = "valid_api_url";

// Configure module
ETpay.configure(
  MERCHANT_CODE,
  MERCHANT_API_TOKEN,
  API_URL
);

Create transaction process:

Method: ETpay.Transaction.create(args: _CreateTransactionArgs)

Interface: _CreateTransactionArgs

Property	Type	Required	Description
merchant_order_id	string	true	Id used by the merchant to identify the transaction.
order_amount	string	true	Transaction amount.
customer_email	string	false	Customer email.
payment_completed_url	string	true	URL to which the API will redirect in the event of a successful payment.
payment_cancellation_url	string	true	URL to which the API will redirect in the event that the payer explicitly cancels the payment, or an unforeseen error occurs.
user_bank_code	string	false	If this field is sent, the session starts with the bank already selected. - See below available options
user_rut	string	false	If this field is sent, the session starts with the client's RUT already entered in the respective field.
is_rut_block	string	false	If this field is sent, the session starts with the client's RUT field already blocked. Important to consider sending `user_rut` together wit this attribute.
concat	string	false	When merchants have URLs that vary based on different inputs, this value is what ETpay uses to recognize the character/symbol that concatenates those inputs.
metadata	Array\<Metadata>	false	Data showing on transaction process - See below `Metadata` definition

Example code

// Import ETpay module
import { ETpay } from "etpay-sdk";

// Configure ETpay module following named step "Configure ETpay module"
...

// Create Transaction Object
const tx = new ETpay.Transaction(ETpay.options);

// Create Transaction process
const response = await tx.create({
  merchant_order_id: "oc123456",
  order_amount: 1000,
  customer_email: "mail@example.com",
  payment_completed_url: "<valid-completed-url>",
  payment_cancellation_url: "<valid-cancellation-url>",
  metadata: [
    {
      name: "Cuenta",
      value: "1111",
      show: true,
    },
  ],
});

Response Object

{
  "token": "LnA0o[...]UaDgTa",
  "signature_token": "J1Bdd[...]jzsLD5",
  // terms_url can be null when module is configured with ETpay MX api
  "terms_url": "https://<etpay-terms-url>"
}

Validate a transaction result:

Method: ETpay.Transaction.verify(token: string, signature_token: string)

Params:

Param	Type	Required	Description
jwt	string	true	Received jwt on transaction result
signature_token	string	true	Signature Received when transaction was created

Example code

// Import ETpay module
import { ETpay } from "etpay-sdk";

// Configure ETpay module following named step "Configure ETpay module"
...

const result = await new ETpay.Transaction(ETpay.options).verify(
  "eyJhbGc[...]l_TU2Y", // Received jwt on transaction result
  "J1Bdd[...]jzsLD5" // Signature Received when transaction was created
);

Response Object

{
  "session_token": "wWkob[...]wC0L5",
  "merchant_account_bank": "cl_estado",
  "merchant_account_type": "cuenta_vista",
  "merchant_account": "19687526",
  "merchant_name": "Sandbox Developer Merchant",
  "merchant_currency": "CLP",
  "merchant_order_id": "oc1234566",
  "merchant_amount": 1,
  "user_bank": "Banco de prueba",
  "user_rut": "111111111",
  "user_account": "Cuenta Corriente 12345678",
  "payment_token": "prNZK[...]yuPfd",
  "payment_status": true,
  "payment_process": "auto",
  "iat": 1643663332
}

A TypeError will be throw if signature_token is incorrect for given token.

Retrieve transaction status:

Method: ETpay.Transaction.status(args: _TransactionStatusArgs)

Interface: _TransactionStatusArgs

Property	Type	Required	Description
session_token	string	false	Received when transaction was created
merchant_order_id	string	false	Internal merchant order identifier
payment_token	string	false	Received when transaction was created

Example code

// Import ETpay module
import { ETpay } from "etpay-sdk";

// Configure ETpay module following named step "Configure ETpay module"
...

const result = await new ETpay.Transaction(ETpay.options).status({
  merchant_order_id: 'oc1234566'
});

Response Object

[
  {
    "session_token": "wWkob[...]wC0L5",
    "merchant_account_bank": "cl_estado",
    "merchant_account_type": "cuenta_vista",
    "merchant_account": "19687526",
    "merchant_name": "Sandbox Developer Merchant",
    "merchant_currency": "CLP",
    "merchant_order_id": "oc1234566",
    "merchant_amount": 1,
    "user_bank": "Banco de prueba",
    "user_rut": "111111111",
    "user_account": "Cuenta Corriente 12345678",
    "payment_token": "prNZK[...]yuPfd",
    "payment_status": true,
    "payment_process": "auto",
    "iat": 1643663332
  }
]

!!!warning If response is an empty array then a string message will be returned from status method.

Error Handler

SDK common errors `[POST] /transactions/verify`

Error	Common Cause
TokenVerificationError: invalid Signature	signature_token is incorrect for given token

SDK common errors `[POST] /transactions/status`

Error	Common Cause
"No data found"	Response with empty array in Method Status
ValueError: The function requires at least one argument	No argument was send in this method. Is required at least one