1.2.1 • Public • Published

Zarinpal payement and gateway API

Read more about Zarinpal API at

How to download

npm i zarinpal-nodejs

How to use

const Zarinpal = require("zarinpal-nodejs")

async function createTransaction(){

  const merchantID = "XXXX-XX-XXXX-XXXXX-XXXX"
  const zarinpal = new Zarinpal(merchantID)

    // currency by default is Toman
    const paymentResponse = await zarinpal.paymentRequest({
      amount: 1000,
      callback_url: "http://localhost:3000/api/payment",
      description: "a simple test",

    // if creating payement transaction was not successfull the redirect url
    // will be an empty string
    const redirectURL = zarinpal.getRedirectURL(paymentResponse)

    return redirectURL
    console.log("Error happend while trying to create a new transaction", e)
    return ""

Translate response error to Farsi

Note: if the error code couldnt not be found in the list of predefined errors it will return an empty string

For a list of predefined errors please check

const farsiError = zarinpal.translateError(paymentResponse)

Check to see if the payment was successfull

  // here payment was successfull

An example:

if (zarinpal.wasSuccessfull(paymentResponse)) {
  const redirectURL = zarinpal.getRedirectURL(paymentResponse)
} else {
  const farsiError =  zarinpal.translateError(paymentResponse)

You can get the authority if the payment was successfull

and save it in db for later use and checks

Note: if creating payement transaction was not successfull it will return undefined

const authority = zarinpal.getAuthority(paymentResponse)

Now Zarinpal gateway redirects the user to this callbakc_url

  • After user payed then zarinpal will redirect the user to the callback_url
  • In there you can find out the if the payment was successfull
// here is in your callback_url api
const query =  req.query // for example in the express like apis where you have res,req objects
  // successfull payment

Get the authority

Note: this will return undefined if user didnt pay successfull

const authority = zarinpal.getAuthorityAfterSuccessfullPayment(query)

Make sure to verify

if the payment was successfull in your callbakc_url api otherwise after sometime the zarinpal will reject the amount back to the owner

const verificationResponse = await zarinpal.verifyPayment({
  amount: 1000,

Utils for checking verification response

  • To check if verify was successfull
const ok = zarinpal.wasVerifySuccessfull(verificationResponse)

  // everyting is fine and verified
  • For getting masked card number
const maskedCardNumber = zarinpal.getMaskedCardPan(verificationResponse)
  • For getting the ref id the code that user can use to track the transaction
const refID = zarinpal.getRefID(verificationResponse)
  • For getting the fee that this amount should pay to zarinpal

Note: As of now zarinpal takes 1% to the amount of 3000 toman from each successfull transaction

const fee = zarinpal.getFee(verificationResponse)

Get all the unverified paymenets

const unverifiedRequests = await getAllUnverifiedRequests()

Refund the amount to the owner

NOTE: for using refund you should first request an access token from zarinpal website

const refundResponse = await refund({

  // refund was successfull

Package Sidebar


npm i zarinpal-nodejs

Weekly Downloads






Unpacked Size

19 kB

Total Files


Last publish


  • sc0d3r