Razorpay Node SDK (razorpay/razorpay-node)

Razorpay Node SDK

https://github.com/razorpay/razorpay-node
Admin
Razorpay Node SDK is the official Node.js library for integrating Razorpay's payment API to accept...

Tokens:230,571
Snippets:623
Trust Score:9.3
Update:1 week ago
Show doc for...
Context Summary (auto-generated)
Raw
# Razorpay Node SDK

Razorpay Node SDK is the official Node.js library for integrating with the Razorpay payment gateway API. It provides a comprehensive set of methods to accept payments, manage orders, customers, refunds, subscriptions, invoices, payment links, transfers, and various other payment-related operations. The SDK supports both API key-based authentication and OAuth token-based authentication for platform partners.

The SDK follows a promise-based architecture with support for callbacks, enabling seamless integration into modern Node.js applications. It offers entities for handling payments across multiple methods including cards, UPI, netbanking, wallets, and EMI, along with specialized features like QR codes, virtual accounts (Smart Collect), and subscription billing.

## Installation

```bash
npm install razorpay
```

## Initialization

### Initialize with API Keys

```javascript
const Razorpay = require('razorpay');

const instance = new Razorpay({
  key_id: 'YOUR_KEY_ID',
  key_secret: 'YOUR_KEY_SECRET'
});
```

### Initialize with OAuth Token (Platform Partners)

```javascript
const Razorpay = require('razorpay');

const instance = new Razorpay({
  oauthToken: 'ACCESS_TOKEN'
});
```

## Orders

Orders represent a payment request to the customer. An order must be created before accepting payments.

### Create an Order

```javascript
instance.orders.create({
  amount: 50000, // Amount in paise (500.00 INR)
  currency: 'INR',
  receipt: 'receipt#1',
  partial_payment: false,
  notes: {
    key1: 'value3',
    key2: 'value2'
  }
}).then(order => {
  console.log(order);
  // Response:
  // {
  //   "id": "order_EKwxwAgItmmXdp",
  //   "entity": "order",
  //   "amount": 50000,
  //   "amount_paid": 0,
  //   "amount_due": 50000,
  //   "currency": "INR",
  //   "receipt": "receipt#1",
  //   "status": "created",
  //   "created_at": 1582628071
  // }
}).catch(error => console.error(error));
```

### Fetch All Orders

```javascript
instance.orders.all({
  from: 1580000000,
  to: 1590000000,
  count: 10,
  skip: 0,
  authorized: true
}).then(orders => console.log(orders));
```

### Fetch Order by ID

```javascript
instance.orders.fetch('order_EKwxwAgItmmXdp')
  .then(order => console.log(order));
```

### Fetch Payments for an Order

```javascript
instance.orders.fetchPayments('order_EKwxwAgItmmXdp')
  .then(payments => console.log(payments));
```

## Payments

Payments represent actual transactions made by customers against orders.

### Capture a Payment

```javascript
instance.payments.capture('pay_G8VQzjPLoAvm6D', 1000, 'INR')
  .then(payment => {
    console.log(payment);
    // Response:
    // {
    //   "id": "pay_G8VQzjPLoAvm6D",
    //   "entity": "payment",
    //   "amount": 1000,
    //   "currency": "INR",
    //   "status": "captured",
    //   "method": "upi",
    //   "captured": true
    // }
  });
```

### Fetch All Payments

```javascript
instance.payments.all({
  from: '2016-08-01',
  to: '2016-08-20',
  count: 10,
  skip: 0,
  'expand[]': 'card'
}).then(payments => console.log(payments));
```

### Fetch a Payment

```javascript
instance.payments.fetch('pay_G8VQzjPLoAvm6D')
  .then(payment => console.log(payment));
```

### Update Payment Notes

```javascript
instance.payments.edit('pay_CBYy6tLmJTzn3Q', {
  notes: {
    key1: 'value1',
    key2: 'value2'
  }
}).then(payment => console.log(payment));
```

### Fetch Card Details for Payment

```javascript
instance.payments.fetchCardDetails('pay_MLzFlOC98cJmHQ')
  .then(card => console.log(card));
```

### Create Payment (S2S JSON)

```javascript
instance.payments.createPaymentJson({
  amount: 100,
  currency: 'INR',
  contact: '9000090000',
  email: 'gaurav.kumar@example.com',
  order_id: 'order_DPzFe1Q1dEOKed',
  method: 'card',
  card: {
    number: '4386289407660153',
    name: 'Gaurav',
    expiry_month: 11,
    expiry_year: 30,
    cvv: 100
  },
  authentication: {
    authentication_channel: 'browser'
  },
  browser: {
    java_enabled: false,
    javascript_enabled: false,
    timezone_offset: 11,
    color_depth: 23,
    screen_width: 23,
    screen_height: 100
  }
}).then(response => console.log(response));
```

### Create UPI Payment

```javascript
instance.payments.createUpi({
  amount: 200,
  currency: 'INR',
  order_id: 'order_GAWRjlWkVcRh0V',
  email: 'gaurav.kumar@example.com',
  contact: '9123456789',
  method: 'upi',
  customer_id: 'cust_EIW4T2etiweBmG',
  save: true,
  ip: '192.168.0.103',
  referer: 'http',
  user_agent: 'Mozilla/5.0',
  description: 'Test flow',
  notes: { note_key: 'value1' },
  upi: {
    flow: 'collect',
    vpa: 'gauravkumar@exampleupi',
    expiry_time: 5
  }
}).then(response => console.log(response));
```

### Validate VPA

```javascript
instance.payments.validateVpa({
  vpa: 'gauravkumar@exampleupi'
}).then(result => {
  console.log(result);
  // { "vpa": "gauravkumar@exampleupi", "success": true, "customer_name": "Gaurav Kumar" }
});
```

## Refunds

Refunds allow you to return money to customers for captured payments.

### Create Normal Refund

```javascript
instance.payments.refund('pay_FCXKPFtYfPXJPy', {
  amount: 100,
  speed: 'normal',
  notes: {
    notes_key_1: 'Beam me up Scotty.',
    notes_key_2: 'Engage'
  },
  receipt: 'Receipt No. 31'
}).then(refund => console.log(refund));
```

### Create Instant Refund

```javascript
instance.payments.refund('pay_FCXKPFtYfPXJPy', {
  amount: 100,
  speed: 'optimum',
  receipt: 'Receipt No. 31'
}).then(refund => console.log(refund));
```

### Fetch All Refunds

```javascript
instance.refunds.all({
  from: 1580000000,
  to: 1590000000,
  count: 10,
  skip: 0
}).then(refunds => console.log(refunds));
```

### Fetch Specific Refund

```javascript
instance.refunds.fetch('rfnd_EqWThTE7dd7utf')
  .then(refund => console.log(refund));
```

### Fetch Refunds for a Payment

```javascript
instance.payments.fetchMultipleRefund('pay_FIKOnlyii5QGNx', {
  count: 10,
  skip: 0
}).then(refunds => console.log(refunds));
```

## Customers

Customers store information about your users for recurring payments and saved cards.

### Create Customer

```javascript
instance.customers.create({
  name: 'Gaurav Kumar',
  contact: 9123456780,
  email: 'gaurav.kumar@example.com',
  fail_existing: '1',
  gstin: '29XAbbA4369J1PA',
  notes: {
    notes_key_1: 'Tea, Earl Grey, Hot',
    notes_key_2: 'Tea, Earl Grey, decaf.'
  }
}).then(customer => console.log(customer));
```

### Fetch Customer

```javascript
instance.customers.fetch('cust_JcXKNTu2YDcbVh')
  .then(customer => console.log(customer));
```

### Fetch All Customers

```javascript
instance.customers.all({ count: 10, skip: 0 })
  .then(customers => console.log(customers));
```

### Update Customer

```javascript
instance.customers.edit('cust_1Aa00000000003', {
  name: 'Gaurav Kumar',
  email: 'Gaurav.Kumar@example.com',
  contact: 9000000000
}).then(customer => console.log(customer));
```

### Add Bank Account to Customer

```javascript
instance.customers.addBankAccount('cust_N5mywh91sXB69O', {
  ifsc_code: 'UTIB0000194',
  account_number: '916010082985661',
  beneficiary_name: 'Pratheek',
  beneficiary_address1: 'address 1',
  beneficiary_email: 'random@email.com',
  beneficiary_mobile: '8762489310',
  beneficiary_city: 'Bangalore',
  beneficiary_state: 'KA',
  beneficiary_country: 'IN'
}).then(result => console.log(result));
```

## Subscriptions

Subscriptions enable recurring billing for customers based on predefined plans.

### Create Plan

```javascript
instance.plans.create({
  period: 'weekly',
  interval: 1,
  item: {
    name: 'Test plan - Weekly',
    amount: 69900,
    currency: 'INR',
    description: 'Description for the test plan'
  },
  notes: {
    notes_key_1: 'Tea, Earl Grey, Hot'
  }
}).then(plan => console.log(plan));
```

### Fetch Plan

```javascript
instance.plans.fetch('plan_00000000000001')
  .then(plan => console.log(plan));
```

### Create Subscription

```javascript
instance.subscriptions.create({
  plan_id: 'plan_00000000000001',
  total_count: 6,
  quantity: 1,
  customer_notify: true,
  start_at: 1580453311,
  expire_by: 1580626111,
  addons: [
    {
      item: {
        name: 'Delivery charges',
        amount: 30000,
        currency: 'INR'
      }
    }
  ],
  notes: {
    notes_key_1: 'Tea, Earl Grey, Hot'
  }
}).then(subscription => console.log(subscription));
```

### Fetch Subscription

```javascript
instance.subscriptions.fetch('sub_00000000000001')
  .then(subscription => console.log(subscription));
```

### Cancel Subscription

```javascript
instance.subscriptions.cancel('sub_00000000000001', {
  cancel_at_cycle_end: true
}).then(subscription => console.log(subscription));
```

### Pause Subscription

```javascript
instance.subscriptions.pause('sub_00000000000001', {
  pause_at: 'now'
}).then(subscription => console.log(subscription));
```

### Resume Subscription

```javascript
instance.subscriptions.resume('sub_00000000000001', {
  resume_at: 'now'
}).then(subscription => console.log(subscription));
```

## Payment Links

Payment Links allow you to collect payments without website integration.

### Create Payment Link

```javascript
instance.paymentLink.create({
  amount: 500,
  currency: 'INR',
  accept_partial: true,
  first_min_partial_amount: 100,
  expire_by: 1691097057,
  reference_id: 'TS1989',
  description: 'For XYZ purpose',
  customer: {
    name: 'Gaurav Kumar',
    email: 'gaurav.kumar@example.com',
    contact: '+919999999999'
  },
  notify: {
    sms: true,
    email: true
  },
  reminder_enable: true,
  notes: {
    policy_name: 'Jeevan Bima'
  },
  callback_url: 'https://example-callback-url.com/',
  callback_method: 'get'
}).then(paymentLink => console.log(paymentLink));
```

### Create UPI Payment Link

```javascript
instance.paymentLink.create({
  upi_link: true,
  amount: 500,
  currency: 'INR',
  description: 'For XYZ purpose',
  customer: {
    name: 'Gaurav Kumar',
    email: 'gaurav.kumar@example.com',
    contact: '+919999999999'
  },
  notify: { sms: true, email: true },
  reminder_enable: true
}).then(paymentLink => console.log(paymentLink));
```

### Fetch Payment Link

```javascript
instance.paymentLink.fetch('plink_FL3Oncr7XxXFf6')
  .then(paymentLink => console.log(paymentLink));
```

### Cancel Payment Link

```javascript
instance.paymentLink.cancel('plink_FL3Oncr7XxXFf6')
  .then(result => console.log(result));
```

## Invoices

Invoices enable billing customers with detailed line items.

### Create Invoice

```javascript
instance.invoices.create({
  type: 'invoice',
  description: 'Invoice for the month of January 2020',
  partial_payment: true,
  customer: {
    name: 'Gaurav Kumar',
    contact: 9999999999,
    email: 'gaurav.kumar@example.com',
    billing_address: {
      line1: 'Ground & 1st Floor, SJR Cyber Laskar',
      line2: 'Hosur Road',
      zipcode: 560068,
      city: 'Bengaluru',
      state: 'Karnataka',
      country: 'in'
    }
  },
  line_items: [
    {
      name: 'Master Cloud Computing in 30 Days',
      description: 'Book by Ravena Ravenclaw',
      amount: 399,
      currency: 'USD',
      quantity: 1
    }
  ],
  sms_notify: true,
  email_notify: true,
  currency: 'USD',
  expire_by: 1589765167
}).then(invoice => console.log(invoice));
```

### Fetch Invoice

```javascript
instance.invoices.fetch('inv_JZz7g9hSZS9IsG')
  .then(invoice => console.log(invoice));
```

### Issue Invoice

```javascript
instance.invoices.issue('inv_DAweOiQ7amIUVd')
  .then(invoice => console.log(invoice));
```

### Cancel Invoice

```javascript
instance.invoices.cancel('inv_JZz7g9hSZS9IsG')
  .then(invoice => console.log(invoice));
```

## Transfers (Route)

Transfers enable splitting payments to multiple linked accounts.

### Create Transfer from Payment

```javascript
instance.payments.transfer('pay_I7watngocuEY4P', {
  transfers: [
    {
      account: 'acc_HgzcrXeSLfNP9U',
      amount: 100,
      currency: 'INR',
      notes: {
        name: 'Gaurav Kumar',
        roll_no: 'IEC2011025'
      },
      linked_account_notes: ['branch'],
      on_hold: 1,
      on_hold_until: 1671222870
    }
  ]
}).then(transfer => console.log(transfer));
```

### Create Order with Transfers

```javascript
instance.orders.create({
  amount: 2000,
  currency: 'INR',
  transfers: [
    {
      account: 'acc_CPRsN1LkFccllA',
      amount: 1000,
      currency: 'INR',
      notes: {
        branch: 'Acme Corp Bangalore North',
        name: 'Gaurav Kumar'
      },
      linked_account_notes: ['branch'],
      on_hold: true,
      on_hold_until: 1671222870
    }
  ]
}).then(order => console.log(order));
```

### Direct Transfer

```javascript
instance.transfers.create({
  account: 'acc_HjVXbtpSCIxENR',
  amount: 500,
  currency: 'INR'
}).then(transfer => console.log(transfer));
```

### Reverse Transfer

```javascript
instance.transfers.reverse('trf_IJOI2DHWQYwqU3', {
  amount: 100
}).then(reversal => console.log(reversal));
```

## QR Codes

QR Codes enable UPI payments through scannable codes.

### Create QR Code

```javascript
instance.qrCode.create({
  type: 'upi_qr',
  name: 'Store_1',
  usage: 'single_use',
  fixed_amount: true,
  payment_amount: 300,
  description: 'For Store 1',
  customer_id: 'cust_HKsR5se84c5LTO',
  close_by: 1681615838,
  notes: {
    purpose: 'Test UPI QR code notes'
  }
}).then(qrCode => console.log(qrCode));
```

### Fetch QR Code

```javascript
instance.qrCode.fetch('qr_HO2e0813YlchUn')
  .then(qrCode => console.log(qrCode));
```

### Close QR Code

```javascript
instance.qrCode.close('qr_HMsVL8HOpbMcjU')
  .then(qrCode => console.log(qrCode));
```

### Fetch Payments for QR Code

```javascript
instance.qrCode.fetchAllPayments('qr_HMsqRoeVwKbwAF', {
  count: 10,
  skip: 0
}).then(payments => console.log(payments));
```

## Virtual Accounts (Smart Collect)

Virtual Accounts enable bank transfer payments with unique account numbers.

### Create Virtual Account

```javascript
instance.virtualAccounts.create({
  receivers: {
    types: ['bank_account']
  },
  description: 'Virtual Account created for Raftar Soft',
  customer_id: 'cust_CaVDm8eDRSXYME',
  close_by: 1681615838,
  notes: {
    project_name: 'Banking Software'
  }
}).then(virtualAccount => console.log(virtualAccount));
```

### Fetch Virtual Account

```javascript
instance.virtualAccounts.fetch('va_JccTXwXA6UG4Gi')
  .then(virtualAccount => console.log(virtualAccount));
```

### Fetch Payments for Virtual Account

```javascript
instance.virtualAccounts.fetchPayments('va_Di5gbNptcWV8fQ', {
  count: 10
}).then(payments => console.log(payments));
```

### Close Virtual Account

```javascript
instance.virtualAccounts.close('va_Di5gbNptcWV8fQ')
  .then(virtualAccount => console.log(virtualAccount));
```

## Webhooks

Webhooks enable real-time notifications for payment events.

### Create Webhook

```javascript
instance.webhooks.create({
  url: 'https://example.com/webhook',
  alert_email: 'gaurav.kumar@example.com',
  secret: '12345',
  events: [
    'payment.authorized',
    'payment.failed',
    'payment.captured',
    'payment.dispute.created',
    'refund.failed',
    'refund.created'
  ]
}, 'acc_GP4lfNA0iIMn5B').then(webhook => console.log(webhook));
```

### Fetch Webhook

```javascript
instance.webhooks.fetch('HK890egfiItP3H', 'acc_GP4lfNA0iIMn5B')
  .then(webhook => console.log(webhook));
```

## Payment Verification

Utility functions to verify payment signatures and webhook authenticity.

### Verify Payment Signature

```javascript
const { validatePaymentVerification } = require('razorpay/dist/utils/razorpay-utils');

const isValid = validatePaymentVerification(
  {
    order_id: 'order_IluGWxBm9U8zJ8',
    payment_id: 'pay_JHAe1Zat55GbZB'
  },
  'signature_from_checkout',
  'YOUR_KEY_SECRET'
);
console.log('Payment verified:', isValid);
```

### Verify Subscription Payment

```javascript
const { validatePaymentVerification } = require('razorpay/dist/utils/razorpay-utils');

const isValid = validatePaymentVerification(
  {
    subscription_id: 'sub_ID6MOhgkcoHj9I',
    payment_id: 'pay_IDZNwZZFtnjyym'
  },
  '601f383334975c714c91a7d97dd723eb56520318355863dcf3821c0d07a17693',
  'YOUR_KEY_SECRET'
);
```

### Verify Webhook Signature

```javascript
const { validateWebhookSignature } = require('razorpay/dist/utils/razorpay-utils');

const payload = JSON.stringify({
  entity: 'event',
  account_id: 'acc_Hn1ukn2d32Fqww',
  event: 'payment.captured',
  payload: {
    payment: {
      entity: {
        id: 'pay_JRP3Y66cNcf2qF',
        amount: 2244,
        status: 'captured'
      }
    }
  }
});

const xRazorpaySignature = '55d3c166391ec51285b388f1bb9f0ba9b13dde1bece4484aaac6edd34a01459a';
const webhookSecret = '123456';

const isValid = validateWebhookSignature(payload, xRazorpaySignature, webhookSecret);
console.log('Webhook verified:', isValid);
```

## IIN (Card Information)

Fetch card information using IIN (Issuer Identification Number).

### Fetch Token IIN

```javascript
instance.iins.fetch('412345')
  .then(iin => {
    console.log(iin);
    // {
    //   "iin": "412345",
    //   "network": "Visa",
    //   "type": "credit",
    //   "issuer_code": "HDFC",
    //   "issuer_name": "HDFC Bank Ltd"
    // }
  });
```

## Summary

The Razorpay Node SDK provides a complete solution for integrating payment functionality into Node.js applications. Key use cases include e-commerce checkout flows using Orders and Payments, recurring billing through Subscriptions, marketplace payment splitting via Transfers, and invoice-based billing. The SDK supports multiple payment methods including cards, UPI, netbanking, and wallets, with built-in support for payment verification and webhook handling.

Integration patterns typically involve creating an order on the server, processing payment through Razorpay Checkout on the client, and verifying the payment signature on the server before fulfilling the order. For marketplaces, Route transfers can be configured at order creation time. For subscription businesses, plans and subscriptions can be managed programmatically, with automatic recurring billing handled by Razorpay. The promise-based API makes it easy to integrate with async/await patterns in modern Node.js applications.