Zarinpal SDK Node.js

https://www.zarinpal.com/docs/sdk/nodejs/
Admin
Zarinpal SDK for Node.js enables developers to integrate Zarinpal payment gateway into their Node.js...
Tokens:10,424
Snippets:37
Trust Score:10
Update:11 months ago
Show doc for...
Tokens:
Raw
### Inquire Transaction using Node.js

Source: https://www.zarinpal.com/docs/sdk/nodejs/method/inquiry

This snippet shows how to call the ZarinPal SDK's inquiry method to retrieve the status of a transaction. It requires the merchant ID and the authority code, and returns an object containing code, message, and status. The example uses async/await and handles errors via try/catch.

```JavaScript
import { ZarinPal } from 'zarinpal-node-sdk';

const zarinpal = new ZarinPal({
    merchantId: 'your-merchant-id',
    sandbox: true,
});

async function inquireTransaction() {
  try {
    const inquiryResult = await zarinpal.inquiries.inquire({
      authority: 'A000000000000000000000000000000000',
    });

    console.log('Inquiry Result:', inquiryResult);
  } catch (error) {
    console.error('Error during inquiry:', error);
  }
}

inquireTransaction();
```

--------------------------------

### Reverse Transaction using ZarinPal Node.js SDK

Source: https://www.zarinpal.com/docs/sdk/nodejs/method/reverse

This function reverses a successful transaction within 30 minutes using the ZarinPal Node.js SDK. It requires initialization with merchant ID and sandbox mode, and takes the authority as input. Outputs the API response on success or logs errors; limited to 30 minutes post-transaction and requires server IP setup to avoid error 62.

```javascript
import { ZarinPal } from 'zarinpal-node-sdk';

const zarinpal = new ZarinPal({
  merchantId: 'your-merchant-id',
  sandbox: true,
});

async function reverseTransaction() {
  try {
    const response = await zarinpal.reversals.reverse({
      authority: 'A000000000000000000000000000000000',
    });
    console.log('Transaction Reversed:', response);
  } catch (error) {
    console.error('Error reversing transaction:', error);
  }
}

reverseTransaction();
```

--------------------------------

### Calculate Transaction Fee using ZarinPal Node.js SDK

Source: https://www.zarinpal.com/docs/sdk/nodejs/method/feeCalculation

This Node.js code snippet demonstrates how to use the `feeCalculation` method from the `zarinpal-node-sdk` to get the estimated transaction fee. It requires your merchant ID and the transaction amount. The output includes the fee, fee type, and other relevant details. Ensure you have the SDK installed and your merchant ID configured.

```javascript
const { ZarinPal } = require('zarinpal-node-sdk');

const zarinpal = new ZarinPal({
  merchant_id: 'Your merchant code',
});

async function calculateFee() {
  try {
    const response = await zarinpal.payments.feeCalculation({
      merchant_id: 'Your merchant code',
      amount: 100000, // ۱۰۰,۰۰۰ ریال
      currency: 'IRR', // اختیاری
    });
    console.log('نتیجه محاسبه کارمزد:');
    console.log('کد:', response.data.code);
    console.log('پیام:', response.data.message);
    console.log('مبلغ:', response.data.amount, 'ریال');
    console.log('کارمزد:', response.data.fee, 'ریال');
    console.log('نوع کارمزد:', response.data.fee_type);
  } catch (error) {
    console.error('خطا در محاسبه کارمزد:', error.message);
  }
}

calculateFee();

```

--------------------------------

### GET /api/transactions

Source: https://www.zarinpal.com/docs/sdk/nodejs/method/transaction

Retrieves a list of transactions for a given terminal, with optional filtering and pagination.

```APIDOC
## GET /api/transactions

### Description
Retrieves a list of transactions associated with a specific terminal. This endpoint can be used to view transaction statuses and filter them.

### Method
GET

### Endpoint
/api/transactions

### Parameters
#### Path Parameters
- **terminal_id** (String) - Required - Identifier of the ZarinPal terminal.

#### Query Parameters
- **filter** (String) - Optional - Filter transactions by status (PAID, VERIFIED, TRASH, ACTIVE, REFUNDED).
- **offset** (Integer) - Optional - Starting row for returned results.
- **limit** (Integer) - Optional - Number of rows to return.

#### Request Body
N/A

### Request Example
N/A

### Response
#### Success Response (200)
- **id** (String) - Transaction identifier.
- **status** (String) - Transaction status (e.g., PAID, FAILED).
- **amount** (Integer) - Transaction amount in Iranian Rial (IRR).
- **description** (String) - Transaction description.
- **created_at** (String) - Transaction creation date and time.

#### Response Example
{
  "id": "transaction_id",
  "status": "PAID",
  "amount": 100000, 
  "description": "Payment for product",
  "created_at": "2024-01-27T10:00:00Z"
}
```

--------------------------------

### Initialize ZarinPal Node.js SDK with merchantId and accessToken

Source: https://www.zarinpal.com/docs/sdk/nodejs/configuration

Configures the ZarinPal SDK with merchant credentials and sandbox mode. Required for payment requests and verification. Access token needed for refund/transaction methods.

```JavaScript
import { ZarinPal } from 'zarinpal-node-sdk';

const zarinpal = new ZarinPal({
  merchantId: 'your-merchant-id',
  sandbox: true,
  accessToken: 'your-access-token',
});
```

--------------------------------

### Process Refund Using ZarinPal Node.js SDK

Source: https://www.zarinpal.com/docs/sdk/nodejs/method/refund

This code demonstrates creating a refund, retrieving refund details, and listing refunds using the ZarinPal Node.js SDK. It requires the 'zarinpal-node-sdk' package with an access token and sandbox mode. Inputs include session ID, amount (min 20000 IRR), description, method (CARD or PAYA), and reason; outputs include refund ID, details, and list with limitations on minimum amount and API response times.

```JavaScript
import { ZarinPal } from 'zarinpal-node-sdk';


const zarinpal = new ZarinPal({
  accessToken: 'your-access-token',
  sandbox: true,
});

async function processRefund() {
  try {
    const refundResponse = await zarinpal.refunds.create({
      sessionId: 'session-id-to-refund',
      amount: 5000,
      description: 'Refund for order #1234',
      method: 'CARD',
      reason: 'CUSTOMER_REQUEST',
    });
    console.log('Refund Created:', refundResponse);

    const refundDetails = await zarinpal.refunds.retrieve(refundResponse.id);
    console.log('Refund Details:', refundDetails);

    const refundsList = await zarinpal.refunds.list({
      terminalId: 'your-terminal-id',
      limit: 10,
      offset: 0,
    });
    console.log('Refunds List:', refundsList);
  } catch (error) {
    console.error('Error processing refund:', error);
  }
}

processRefund();

```

--------------------------------

### Initiate Payment Request with ZarinPal Node.js SDK

Source: https://www.zarinpal.com/docs/sdk/nodejs/method/request

This code snippet demonstrates how to initiate a payment request using the ZarinPal Node.js SDK. It includes setting up the SDK with merchant ID and sandbox mode, defining payment details like amount, description, and callback URL, and optionally providing user information. The `create` method sends the payment request, and the response (including the authority) is logged. Error handling is included.

```javascript
import { ZarinPal } from 'zarinpal-node-sdk';


const zarinpal = new ZarinPal({
  merchantId: 'your-merchant-id',
  sandbox: true,
});

async function initiatePayment() {
  try {
    const response = await zarinpal.payments.create({
      amount: 10000,
      callback_url: 'https://yourwebsite.com/callback',
      description: 'Payment for order #1234',
      mobile: '09123456789',
      email: 'customer@example.com',
      cardPan: ['6219861034529007', '5022291073776543'],
      referrer_id: 'affiliate123',
    });
    console.log(response);
  } catch (error) {
    console.error(error);
  }
}

initiatePayment();

```

--------------------------------

### استعلام تراکنش‌های تأیید نشده در Node.js

Source: https://www.zarinpal.com/docs/sdk/nodejs/method/unVerified

این کد نمونه نحوه استفاده از متد unverified.list() را در Node.js برای دریافت لیست تراکنش‌های تأیید نشده از درگاه زرین‌پال نشان می‌دهد. این تابع به merchantId و تنظیمات sandbox نیاز دارد و لیست تراکنش‌ها یا خطا را در کنسول چاپ می‌کند.

```javascript
import { ZarinPal } from 'zarinpal-node-sdk';

const zarinpal = new ZarinPal({
  merchantId: 'your-merchant-id',
  sandbox: true,
});

async function getUnverifiedPayments() {
  try {
    const unverifiedPayments = await zarinpal.unverified.list();
    console.log('Unverified Payments:', unverifiedPayments);
  } catch (error) {
    console.error('Error fetching unverified payments:', error);
  }
}

getUnverifiedPayments();

```

--------------------------------

### تأیید پرداخت زرین‌پال با Node.js

Source: https://www.zarinpal.com/docs/sdk/nodejs/method/verify

این نمونه کد نحوه تأیید پرداخت را با استفاده از `zarinpal-node-sdk` نشان می‌دهد. پس از دریافت کد `authority` و مبلغ تراکنش از دیتابیس، متد `verify` برای بررسی وضعیت پرداخت فراخوانی می‌شود. پاسخ شامل اطلاعاتی مانند `ref_id`, `card_pan` و `fee` در صورت موفقیت‌آمیز بودن است.

```javascript
import { ZarinPal } from 'zarinpal-node-sdk';

const zarinpal = new ZarinPal({
  merchantId: 'your-merchant-id',
  sandbox: true,
});

async function verifyPayment(authority, status) {
  if (status === 'OK') {
    const amount = await getAmountFromDatabase(authority); // Implement this function

    if (amount) {
      try {
        const response = await zarinpal.verifications.verify({
          amount: amount,
          authority: authority,
        });

        if (response.data.code === 100) {
          console.log('Payment Verified:');
          console.log('Reference ID:', response.data.ref_id);
          console.log('Card PAN:', response.data.card_pan);
          console.log('Fee:', response.data.fee);
        } else if (response.data.code === 101) {
          console.log('Payment already verified.');
        } else {
          console.log('Transaction failed with code:', response.data.code);
        }
      } catch (error) {
        console.error('Payment Verification Failed:', error);
      }
    } else {
      console.log('No Matching Transaction Found For This Authority Code.');
    }
  } else {
    console.log('Transaction was cancelled or failed.');
  }
}

// Example usage:
const authority = 'A000000000000000000000000000000000';
const status = 'OK';

verifyPayment(authority, status);

```

--------------------------------

### POST /payments/create

Source: https://www.zarinpal.com/docs/sdk/nodejs/method/request

Initiates a new payment request to the ZarinPal gateway. This method is used to send payment information and receive an 'authority' to redirect the user to the payment page.

```APIDOC
## POST /payments/create

### Description
Initiates a new payment request to the ZarinPal gateway. This method is used to send payment information and receive an 'authority' to redirect the user to the payment page.

### Method
POST

### Endpoint
/payments/create

### Parameters
#### Query Parameters
- **merchantId** (string) - Required - Your ZarinPal merchant ID.
- **sandbox** (boolean) - Optional - Set to true for testing in sandbox mode.

#### Request Body
- **amount** (integer) - Required - The payment amount in Rials. Minimum amount is 10000 Rials.
- **description** (string) - Required - A description of the transaction, such as an order number or product name.
- **callback_url** (string) - Required - The return URL after successful or failed payment.
- **mobile** (string) - Optional - The user's mobile number.
- **email** (string) - Optional - The user's email address.
- **referrer_id** (string) - Optional - Referrer ID.
- **currency** (string) - Optional - The currency unit for the transaction. Default is 'IRR' (Rial), other option is 'IRT' (Toman).
- **cardPan** (string) - Optional - The bank card number the user will pay with.
- **wages** (Array) - Optional - An array containing profit-sharing information. Each element includes 'iban' (IBAN), 'amount' (amount), and 'description' (description).

### Request Example
```javascript
import { ZarinPal } from 'zarinpal-node-sdk';

const zarinpal = new ZarinPal({
  merchantId: 'your-merchant-id',
  sandbox: true,
});

async function initiatePayment() {
  try {
    const response = await zarinpal.payments.create({
      amount: 10000,
      callback_url: 'https://yourwebsite.com/callback',
      description: 'Payment for order #1234',
      mobile: '09123456789',
      email: 'customer@example.com',
      cardPan: ['6219861034529007', '5022291073776543'],
      referrer_id: 'affiliate123',
    });
    console.log(response);
  } catch (error) {
    console.error(error);
  }
}

initiatePayment();
```

### Response
#### Success Response (200)
- **authority** (string) - The unique authority token for the payment transaction.
- **message** (string) - A message indicating the success of the request.
- **errors** (Array) - An array of error objects if any occurred during the request.

#### Response Example
```json
{
  "authority": "a1b2c3d4e5f67890",
  "message": "Payment request created successfully.",
  "errors": []
}
```
```

--------------------------------

### دریافت لیست تراکنش‌ها در Node.js

Source: https://www.zarinpal.com/docs/sdk/nodejs/method/transaction

این متد با استفاده از SDK رسمی زرین‌پال، لیست تراکنش‌های یک ترمینال خاص را با امکان فیلترکردن براساس وضعیت تراکنش و محدودیت تعداد نتایج برمی‌گرداند. ورودی‌های اختیاری شامل offset، limit و filter هستند. خروجی شامل شناسه، وضعیت، مبلغ، توضیحات و تاریخ ایجاد تراکنش است.

```javascript
import { ZarinPal } from 'zarinpal-node-sdk';

const zarinpal = new ZarinPal({
  accessToken: 'your-access-token'
});

async function getTransactions() {
  try {
    const transactions = await zarinpal.transactions.list({
      terminalId: 'your-terminal-id',
      filter: 'PAID',
      limit: 10,
      offset: 0,
    });
    console.log('Transactions List:', transactions);
  } catch (error) {
    console.error('Error fetching transactions:', error);
  }
}

getTransactions();
```

--------------------------------

### Refund API

Source: https://www.zarinpal.com/docs/sdk/nodejs/method/refund

The Refund API allows you to refund full or partial amounts of a payment to a customer's account, either instantly or through PAYA cycles. This is useful for canceled orders, incorrect payments, or other scenarios requiring a refund.

```APIDOC
## POST /refunds

### Description
Initiates a refund for a given transaction. This can be a full or partial refund.

### Method
POST

### Endpoint
/refunds

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **session_id** (String) - Required - The transaction ID to be refunded.
- **amount** (Integer) - Required - The amount in Rials to be refunded. Minimum refund amount is 20,000 Rials.
- **description** (String) - Required - A description explaining the reason for the refund.
- **method** (String) - Required - The refund method. Accepted values are 'CARD' or 'PAYA'.
- **reason** (String) - Required - The reason for the refund. e.g., 'CUSTOMER_REQUEST'.

### Request Example
```json
{
  "session_id": "session-id-to-refund",
  "amount": 5000,
  "description": "Refund for order #1234",
  "method": "CARD",
  "reason": "CUSTOMER_REQUEST"
}
```

### Response
#### Success Response (200)
- **id** (String) - The transaction ID of the refund.
- **terminal_id** (String) - The gateway terminal ID.
- **amount** (Integer) - The refunded amount in Rials.
- **timeline** (Object) - Transaction history.
- **refund_amount** (Integer) - The total amount refunded.
- **refund_time** (String) - The timestamp when the refund was processed.
- **refund_status** (String) - The status of the refund.

#### Response Example
```json
{
  "id": "refund-transaction-id",
  "terminal_id": "your-terminal-id",
  "amount": 5000,
  "timeline": {},
  "refund_amount": 5000,
  "refund_time": "2023-10-27T10:00:00Z",
  "refund_status": "SUCCESS"
}
```

## GET /refunds/{id}

### Description
Retrieves the details of a specific refund by its ID.

### Method
GET

### Endpoint
/refunds/{id}

### Parameters
#### Path Parameters
- **id** (String) - Required - The ID of the refund to retrieve.

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **id** (String) - The transaction ID of the refund.
- **terminal_id** (String) - The gateway terminal ID.
- **amount** (Integer) - The refunded amount in Rials.
- **timeline** (Object) - Transaction history.
- **refund_amount** (Integer) - The total amount refunded.
- **refund_time** (String) - The timestamp when the refund was processed.
- **refund_status** (String) - The status of the refund.

#### Response Example
```json
{
  "id": "refund-transaction-id",
  "terminal_id": "your-terminal-id",
  "amount": 5000,
  "timeline": {},
  "refund_amount": 5000,
  "refund_time": "2023-10-27T10:00:00Z",
  "refund_status": "SUCCESS"
}
```

## GET /refunds

### Description
Retrieves a list of all refunds associated with your terminal.

### Method
GET

### Endpoint
/refunds

### Parameters
#### Path Parameters
None

#### Query Parameters
- **terminalId** (String) - Optional - Filter refunds by terminal ID.
- **limit** (Integer) - Optional - The maximum number of refunds to return.
- **offset** (Integer) - Optional - The number of refunds to skip before starting to collect.

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- A list of refund objects, each containing:
  - **id** (String) - The transaction ID of the refund.
  - **terminal_id** (String) - The gateway terminal ID.
  - **amount** (Integer) - The refunded amount in Rials.
  - **timeline** (Object) - Transaction history.
  - **refund_amount** (Integer) - The total amount refunded.
  - **refund_time** (String) - The timestamp when the refund was processed.
  - **refund_status** (String) - The status of the refund.

#### Response Example
```json
[
  {
    "id": "refund-transaction-id-1",
    "terminal_id": "your-terminal-id",
    "amount": 5000,
    "timeline": {},
    "refund_amount": 5000,
    "refund_time": "2023-10-27T10:00:00Z",
    "refund_status": "SUCCESS"
  },
  {
    "id": "refund-transaction-id-2",
    "terminal_id": "your-terminal-id",
    "amount": 10000,
    "timeline": {},
    "refund_amount": 10000,
    "refund_time": "2023-10-26T15:30:00Z",
    "refund_status": "SUCCESS"
  }
]
```
```

--------------------------------

### POST /verifications/verify

Source: https://www.zarinpal.com/docs/sdk/nodejs/method/verify

Verifies a payment using the authority and amount. Typically called after the user returns to callback_url. Returns verification status and transaction details.

```APIDOC
## POST /verifications/verify

### Description
Verifies a payment transaction with ZarinPal using the authority code and amount. Should be called after the user returns to callback_url from the payment gateway.

### Method
POST

### Endpoint
/verifications/verify

### Parameters
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- **authority** (String) - Required - The authority code returned by the gateway and appended to callback_url as a query parameter.
- **amount** (Integer) - Required - The order amount to verify. Must match the original transaction amount (in the smallest currency unit).

### Request Example
{
  "authority": "A000000000000000000000000000000000",
  "amount": 10000
}

### Response
#### Success Response (200)
- **code** (Integer) - Verification status code (e.g., 100 for success).
- **ref_id** (String) - Unique reference ID of the verified transaction.
- **card_pan** (String) - Masked card number used in the transaction.
- **fee** (Integer) - Transaction fee.

#### Response Example
{
  "code": 100,
  "ref_id": "1234567890",
  "card_pan": "1234-****-****-5678",
  "fee": 90
}

#### Duplicate Verification (101)
Indicates the transaction has already been verified.

### Error Handling
- If amount does not match the original transaction amount, verification fails.
- If the authority is invalid or the transaction is canceled, verification fails.
```

--------------------------------

### Transaction Inquiry API

Source: https://www.zarinpal.com/docs/sdk/nodejs/method/inquiry

The `inquiry` method allows you to check and inquire about the status of a transaction. This method is used when you want to obtain more detailed information about the transaction's status after initiating a payment request or confirming a payment.

```APIDOC
## POST /zarinpal/inquiry

### Description
This endpoint allows you to check the status of a previously initiated ZarinPal transaction using its unique authority code.

### Method
POST

### Endpoint
/zarinpal/inquiry

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **merchant_id** (String) - Required - Your ZarinPal merchant ID.
- **authority** (String) - Required - The unique payment request ID obtained after initiating a payment.

### Request Example
```json
{
  "merchant_id": "your-merchant-id",
  "authority": "A000000000000000000000000000000000"
}
```

### Response
#### Success Response (200)
- **code** (Integer) - Transaction status code. `100` indicates a successful transaction.
- **message** (String) - A message describing the transaction status (e.g., success or failure).
- **status** (String) - The final status of the transaction, indicating whether it was successful or canceled.

#### Response Example
```json
{
  "code": 100,
  "message": "Transaction Successful",
  "status": "success"
}
```
```

--------------------------------

### POST /unverified

Source: https://www.zarinpal.com/docs/sdk/nodejs/method/unVerified

Retrieves a list of unverified transactions from the payment gateway. This endpoint allows merchants to check transactions with undetermined status for further processing or verification.

```APIDOC
## POST /unverified

### Description
The unverified transactions inquiry method allows you to receive a list of unverified transactions from the payment gateway. This method can be used to check transactions whose status has not yet been determined.

### Method
POST

### Endpoint
/unverified

### Parameters
#### Request Body
- **merchant_id** (String) - Required - The unique 36-character merchant identification code

### Request Example
```json
{
  "merchant_id": "your-merchant-id"
}
```

### Response
#### Success Response (200)
- **code** (Integer) - A numeric code indicating the success or failure of the operation
- **authorities** (Array) - Contains additional transaction information including gateway type and payment time as JSON encoded data

#### Response Example
```json
{
  "code": 100,
  "authorities": []
}
```

### Node.js SDK Example
```javascript
import { ZarinPal } from 'zarinpal-node-sdk';

const zarinpal = new ZarinPal({
  merchantId: 'your-merchant-id',
  sandbox: true,
});

async function getUnverifiedPayments() {
  try {
    const unverifiedPayments = await zarinpal.unverified.list();
    console.log('Unverified Payments:', unverifiedPayments);
  } catch (error) {
    console.error('Error fetching unverified payments:', error);
  }
}

getUnverifiedPayments();
```
```

--------------------------------

### POST /api/feeCalculation

Source: https://www.zarinpal.com/docs/sdk/nodejs/method/feeCalculation

Calculates the transaction fee before creating a payment request. This is useful for displaying the fee to the user or incorporating it into calculations.

```APIDOC
## POST /api/feeCalculation

### Description
Calculates the fee for a transaction before creating a payment request.

### Method
POST

### Endpoint
/api/feeCalculation

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- `merchant_id` (String) - Required - Your ZarinPal Merchant ID.
- `amount` (Number) - Required - The transaction amount in IRR (must be greater than 1000).
- `currency` (String) - Optional - The currency of the transaction (default: IRR). Allowed values: IRR, IRT

### Request Example
{
  "merchant_id": "Your merchant code",
  "amount": 100000, // 100,000 IRR
  "currency": "IRR"
}

### Response
#### Success Response (200)
- `code` (Number) - Request status code: 100 for successful request.
- `message` (String) - Request status message, e.g., "Successful fee calculation".
- `amount` (Number) - The original transaction amount in IRR.
- `fee` (Number) - The calculated fee in IRR.
- `fee_type` (String) - The fee payer type: Merchant or Payer.
- `suggested_amount` (String) - The suggested amount for settlement.

#### Response Example
{
  "code": 100,
  "message": "Successful fee calculation",
  "amount": 100000,
  "fee": 1000,
  "fee_type": "Merchant",
  "suggested_amount": "101000"
}
```
Tokens:
Raw