❤
npm
Sign UpSign In

expresscheckout-nodejs
TypeScript icon, indicating that this package has built-in type declarations

1.0.0 • Public • Published

MIT License v1.0.0

Juspay's Expresscheckout NodeJs SDK

Please go through the documentation for Juspay API here

Contents

Installation

Installation using npm

npm i expresscheckout-nodejs

Getting Started

To access the apis you will need merchantId and authentication methods, juspay supports Basic authentication with apikey for most of the routes. This SDK also supports JWT authentication for routes that currently support it. It'll be prioritized over Basic authentication in case of multiple authentication options.

Identify Endpoints

Rest endpoints for Juspay

Environment Endpoint
Sandbox https://sandbox.juspay.in
Production https://api.juspay.in

Rest endpoints for HDFC tenant

Environment Endpoint
Sandbox https://smartgatewayuat.hdfcbank.com
Production https://smartgateway.hdfcbank.com

Default endpoint is https://sandbox.juspay.in

Authentication and Access

Current version of expresscheckout-nodejs supports JWE+JWS and Basic authentication method using apiKey. Basic info on each methods

Make sure to pass merchantId in Juspay initialization

Basic Authentication method

To use this method use apiKey generated from your dashboard under sidebar Payments > Settings > Security > API Keys

const juspay = new Juspay({
  apiKey: "your apiKey",
  merchantId: "your merchantId"
})

JWE+JWS encryption

This method is more secure authentication method that encrypts the signed payload using AES-256-GCM algorithm, payload is signed using RSA-SHA256 algorithm of actual data. Hence, we'll use 2 pairs for keys, one for JWE and one for JWS.

JWT and JWE+JWS will be used interchangeably here.

const juspay = new Juspay.Juspay({
  merchantId: "your merchantId",
  jweAuth: {
    keyId: "your keyId",
    privateKey: "your privateKey",
    publicKey: "your publicKey",
  },
})

To get the keys go to sidebar then Payments > Settings > Security > JWT Keys > Upload New JWT > (I don't have the JWT Keys, I want to auto generate the keys I have the JWT Keys already, I want to manually upload the Public Key). Keys will be downloaded as per your selection.

Keys should not be hard coded and should be saved securely either on server file system, env or KMS services.

JWE components (as json)

Component Function
encryptedKey A random key created during runtime and shared after encrypting (alg RSA-OAEP-256) it using publicKey
encryptedPayload Actual cipher text is encrypted using AES-GCM-256 data, for JWE+JWS use case it will be JWS see below in JWS components section
iv It adds randomness to encryption, ensuring varied ciphertext for the same plaintext
tag It ensures the integrity and authenticity of the ciphertext, detecting any unauthorized modifications
header metadata information containing keyId(for rotation mainly), alg, enc, cty

JWS components (as stringified json)

Component Function
payload request data
header Contains algorithm to sign, key-id (for rotation mainly)
signature The generated signature which will be verified on Juspay’s end

You don't have to worry about encrypting and decrypting the data as it'll be handled by sdk itself. If JWE configuration is present and api supports it, it'll prioritize that over apiKey. For cases where api only supports basic auth and apikey is not given, it'll throw appropriate errors.

Importing SDKs

CommonJS

const { Juspay, APIError } = require('expresscheckout-nodejs')

OR

const expresscheckout = require('expresscheckout-nodejs')
// usage expresscheckout.Juspay, expresscheckout.APIError

Using Typescript/ES Module

import Juspay, { APIError } from 'expresscheckout-nodejs'

OR

import * as expresscheckout from 'expresscheckout-nodejs'
// usage expresscheckout. Juspay, expresscheckout.APIError, expresscheckout.CreateCustomerRequest

SDK Resources

Now that we have setup authentication and have access to call juspay apis we'll see an example of orderSession api using promise and try/catch blocks whichever suits your programming style.

Using try/catch blocks

try {
  const juspay = new Juspay.Juspay({
    merchantId: 'merchantId',
    apiKey: 'apiKey',
  })
  const orderSessionResponse = await juspay.orderSession.create({
    amount: 1,
    order_id: 'order_' + Date.now(),
    payment_page_client_id: 'your payment page client id',
  })
  console.log(orderSessionResponse)
} catch (error) {
  console.log(error)
}

Using Promises

const juspay = new Juspay({
  merchantId: 'merchantId',
  apiKey: 'apiKey',
})
const orderId = 'ORD_' + Date.now()
juspay.order
  .create({
    amount: 100,
    order_id: orderId,
    // optional fields below
    currency: 'INR',
    customer_id: 'juspay_test_1',
    customer_email: 'test@juspay.in',
    customer_phone: '9988776655',
    product_id: '123456',
    return_url: 'https://abc.xyz.com/123456',
    description: 'Sample Description',
    billing_address_first_name: 'Juspay',
    billing_address_last_name: 'Technologies',
    billing_address_line1: 'Girija Building',
    billing_address_line2: 'Ganapati Temple Road',
    billing_address_line3: '8th Block, Koramangala',
    billing_address_city: 'Bengaluru',
    billing_address_state: 'Karnataka',
    billing_address_country: 'India',
    billing_address_postal_code: '560095',
    billing_address_phone: '9988776655',
    billing_address_country_code_iso: 'IND',
    shipping_address_first_name: 'Juspay',
    shipping_address_last_name: 'Technologies',
    shipping_address_line1: 'Girija Building',
    shipping_address_line2: 'Ganapathi Temple Road',
    shipping_address_line3: '8th Block, Koramangala',
    shipping_address_city: 'Bengaluru',
    shipping_address_state: 'Karnataka',
    shipping_address_country: 'India',
    shipping_address_postal_code: '560095',
    shipping_address_phone: '9988776655',
    shipping_address_country_code_iso: 'IND',
    'options.get_client_auth_token': true,
    basket:
      '[{"id":"PID1","quantity":1,"unitPrice":25123.25}, {"id":"PID2","quantity":1,"unitPrice":25123.25}]',
  })
  .then((res) => console.log(res))
  .catch((err) => console.error(res))

Override default configs for single resource

Let's say you want to increase a timeout for payments api other than default 80,000ms. Do Not modify juspay instance directly, as it's shared and can cause troubles with other apis. Use optional juspayConfig params inside resource function calls to override configs.

try {
  const juspay = new Juspay({
    jweAuth: {
      keyId: process.env.KEY_ID,
      privateKey: prepareKey(process.env.PRIVATE_KEY),
      publicKey: prepareKey(process.env.PUBLIC_KEY),
    },
    merchantId: 'merchantId',
  })
  // uses default timeout
  const order = await juspay.order.create({
    amount: 100,
    order_id: 'ORD_' + Date.now(),
  })
  const paymentResponse = await juspay.payments.create(
    {
      order_id: order.order_id,
      payment_method_type: 'CARD',
      redirect_after_payment: true,
      payment_method: 'MASTERCARD',
      card_exp_month: '04',
      card_exp_year: '24',
      card_security_code: '424',
      save_to_locker: false,
      card_number: '4242424242424242',
    },
    // resource specific timeout
    {
      timeout: 100000,
    }
  )
  console.log(paymentResponse)
} catch (error) {
  throw error
}

you can override all the juspay environment specific config using resource function parameter as shown below

PCI compliant merchants can use order+txns call inside payments resource itself, read more here.

In some cases you will need to pass customer id to use juspay's active-active features. Here's how you can add resources specific headers.

const orderStatus = await juspay.order.status(
  order.order_id,
  {
    'options.add_full_gateway_response': true,
  },
  {
    timeout: 10000,
    version: '2024-01-03'
    headers: {
      'x-customerid': customerId,
    },
  }
)

Response http object

SDK attaches http key in response object for the user if it's of any use.

Error Handling And Examples

SDK errors are categorized in three parts APIError, JuspayError and Error. APIError is api errors coming from servers like AuthenticationError, InvalidRequestError, InternalServerError. Here JuspayError is thrown by sdk for cases like IllegalPrivateKey, IllegalPublicKey, DecryptionFailed, SignatureValidationFailed etc. Error is usually user error for setting up authentication configurations or some unkown cases. Also APIError extends JuspayError.

APIError to refund unknown order id

// unknown order id
const orderId = 'order_' + Date.now()
juspay.order
  .refund(orderId, {
    unique_request_id: 'refund_test_' + Date.now(),
    order_id: orderId,
    amount: 1,
  })
  .catch((res) => {
    // prints true
    console.log(err instanceof APIError)
    // prints true
    console.log(err instanceof JuspayError)
    console.error(res)
  })

JuspayError in case of failed signature verification

const order_id = 'ORD_' + Date.now()
juspay.order
  .status('order_id', {
    order_id,
    'options.add_full_gateway_response': true,
  })
  .then((res) => {
    console.log(res)
  })
  .catch((err) => {
    // prints true
    console.log(err instanceof JuspayError)
    console.error(err)
  })

APIError will be false in this case as decryption and verification is done by sdk and error is raised by sdk. If you want to raise flags in your system for such tampering cases please use error names such as SignatureValidationFailed or DecryptionFailed.

Logging

Logging sdk events like request, response and resource url becomes important for debugging in large and complicated systems. Hence, sdk comes with winston logger and has minimal logging configuration with it. It is enabled by default.

If you want to customize logging in accordance with your project, please go through this section. Because nodejs does not have standardized logging framework support like Java SDK has exposed a basic logging interface to customize it for your own system.

Juspay.customLogger of type (resource: string) => IJuspayLogger takes a function with one string parameter i.e. resource (which is the name of the class from which it's printed, used for debugging purposes) and returns the instance of the class which implements IJuspayLogger interface. interface definition below

Disable Logs

import Juspay from 'expresscheckout-nodejs'

Juspay.customLogger = (resource) => Juspay.silentLogger

Custom winston logger

import Juspay from 'expresscheckout-nodejs'
import winston from 'winston'

Juspay.customLogger = (resource) => winston.createLogger({
    transports: new winston.transports.Console(),
})

Custom pino or buyan logger

import Juspay from 'expresscheckout-nodejs'
import pino from 'pino'
import bunyan from 'bunyan'

// pino
Juspay.customLogger = (resource) => new pino()

// buyan
Juspay.customLogger = (resource) => bunyan.createLogger({name: 'expresscheckout-nodejs-sampleProject'})

Custom logging framework

If you have your custom logging framework, the instance should look like IJuspayLogger interface, it's a basic interface as shown below.

interface IJuspayLogger {
  info: (message: any) => IJuspayLogger | unknown
  error: (message: any) => IJuspayLogger | unknown
}
// making a custom logger, it has to implement IJuspayLogger interface
class CustomLogger {
  constructor(defaultJuspayLogs) {}

  info(message) {
    console.log(message)
    return this
  }

  error(message) {
    console.log(message)
    return this
  }
}
Juspay.customLogger = (resource) => new CustomLogger(resource)

because of a common interface of logger and SDK's logging usage is not chained we can do something like

import Juspay from 'expresscheckout-nodejs'

Juspay.customLogger = (resource) => console

to print it directly on the console for quick tests. But as it's printing to console it will not print nested deep objects.

Resources List

Here's the list of supported apis in this sdk under current version

Resource Endpoint Authentication Methods Documentation
customers.create POST: /customers Basic here
customers.get GET: /customers/:customer_id Basic here
customers.update POST: /customers/:customer_id Basic here
payments.create POST: /txns Basic, JWE+JWS here
order.create POST: /orders Basic here
order.status GET: /orders/:order_id Basic, JWE+JWS here
order.update POST: /orders/:order_id Basic here
order.refund POST: /orders/:order_id/refunds Basic, JWE+JWS here
orderSession.create POST: /session Basic, JWE+JWS here

Please note that JWE+JWS or JWT if supported has different route than normal, general nomenclature has /v4/ prefixed, with few exceptions with order.status has /v4/order-status and refund has /v4/orders/${order_id}/refunds

Questions?

Still have any questions? Feel free to mail us here - support@juspay.in.

Readme

Keywords

Package Sidebar

Install

npm i expresscheckout-nodejs

Repository

bitbucket.juspay.net/projects/CL/repos/expresscheckout-nodejs-sdk/browse

Homepage

docs.juspay.in/api-reference/docs/express-checkout/introduction

Weekly Downloads

33

Version

1.0.0

License

MIT

Unpacked Size

306 kB

Total Files

137

Last publish

Collaborators

  • krupal.panchasara.juspay
Try on RunKit
Report malware