@aspianet/idpay - npm explorer

Created by ASPIANET - Omid Rouhani

تولید شده توسط آسپیانت - امید روحانی

# درباره پرداخت‌یار آیدی‌پی

آیدی پی یک سیستم درگاه پرداخت شخصی است که بهترین و راحت ترین راه جهت دریافت پول میباشد.
شما با ایجاد یک حساب کاربری در آیدی پی ، دارای یک صفحه پرداخت شخصی با آدرس منحصر به فرد خواهید شد، که با دادن آدرس آن میتوانید از هر شخصی به صورت الکترونیک پول دریافت نمایید.
همچنین شما میتوانید برای وب سایت یا اپلیکیشن خود جهت اتصال به درگاه بانکی از خدمات وب سرویس آیدی پی استفاده کنید.

بسته توسعه موجود بر روی API رسمی آيدی‌پی تولید شده است.

## روش نصب

sh
npm install @aspianet/idpay

## کاربرد قبل از هر چیز شما نیازمند دریافت کلید API از پنل کاربری خود در آیدی پی هستید تا بتوانید به واسطه آن، SDK موجود را مقداردهی اولیه و راه اندازی کنید. برای مثال، شما می توانید کد زیر را در فایل اصلی اپلیکیشن اکسپرس خود (مانند app.js) ایجاد و با کلید API مقداردهی نمایید تا بتوانید در هر فایل دیگر اپلیکیشن خود بدون استفاده مکرر از این کلید از سایر امکانات SDK استفاده نمایید:

ts
import { idPay } from '@aspianet/idpay';

idPay.init( "کلید-API" );`


  
  در صورتی که تمایل دارید در محیط توسعه برنامه خود را با اتصال به پرداخت‌یار آیدی‌پی به صورت آزمایشی تست کنید و نمی خواهید پرداخت واقعی صورت گیرد می توانید پارامتر دوم متود init را با مقدار true مقداردهی نمایید تا حالت آزمایشی فعال گردد.
  
  ## ایجاد تراکنش
  
  با استفاده از آدرس زیر می‌توانید یک تراکنش جدید ایجاد کنید.

ts
import { idPay } from '@aspianet/idpay';

const transaction = await idPay.createTransaction( { order_id: '101', amount: 10000, name: 'امید روحانی', phone: '09380001234', mail: 'my@site.com', desc: 'توضیحات پرداخت کننده', callback: 'https://example.com/callback', } );`


  
  درصورتیکه درخواست موفق باشد، وضعیت پاسخ 201 Created اعلام خواهد شد. 
  
  توجه: در پاسخ، مقادیر id و link باز میگردد که بهتر است آنها را در دیتابیس خود ذخیره کنید. بعد از ذخیره اطلاعات دریافتی، پرداخت کننده باید به لینک دریافت شده منتقل شود.
  
   توجه: درصورتیکه هر یک از مقادیر name یا phone یا mail معتبر نباشند، خطایی باز نمی‌گردد و هیچ مقداری برای آن ذخیره نمی‌شود.
  
   توجه: دامنه آدرس بازگشت به سایت پذیرنده یا callback باید مطابق با آدرسی باشد که در وب سرویس‌های من تعریف شده است.
  
  
  ## بازگشت به سایت پذیرنده
  
  بعد از اتمام عملیات پرداخت، درصورتیکه پرداخت با موفقیت انجام شده باشد، پرداخت کننده به آدرسی که پذیرنده در callback مشخص کرده بود منتقل می‌شود.
همچنین پارامترهای زیر به آدرس callback تعریف شده در مرحله ایجاد تراکنش با توجه به تنظیمات وب سرویس در داشبورد آیدی پی تحت عنوان روش بازگشت پس از پرداخت به دو روش POST (Post form) یا GET (Query String) ارسال می شوند. برای کسب اطلاعات بیشتر اینجا کلیک نمایید.
  
  ## تایید تراکنش
  
  بعد از دریافت اطلاعات به سایت پذیرنده و اعتبار سنجی اطلاعات توسط پذیرنده، پذیرنده باید تراکنش را تایید کند تا پرداخت بصورت سیستمی تکمیل شود و از بازگشت پول به پرداخت کننده جلوگیری شود. به این منظور از متود زیر می توانید استفاده نمایید:

ts
import { idPay } from '@aspianet/idpay';

const verifiedTransaction = await idPay.verifyTransaction( { id: 'd2e353189823079e1e4181772cff5292', order_id: '101', } );`


  
  توجه: بعد از پرداخت تراکنش توسط پرداخت کننده، تراکنش باید ظرف مدت حداکثر 10 دقیقه تایید شود. در غیر اینصورت مبلغ به کارت پرداخت کننده برگردانده خواهد شد.
  
  توجه: جهت جلوگیری از دوبار مصرف شدن یک پرداخت (Double Spending)، پذیرنده موظف است کلیدهای منحصر بفردی که از طریق API آیدی پی دریافت می‌کند را (مثل id و track_id) در دیتابیس خود ذخیره کند و از یکتا بودن آنها اطمینان حاصل فرماید.
توجه داشته باشید که ممکن است یک مشتری رسید پرداخت آیدی پی را ذخیره کند و برای یک خرید دیگر از آن استفاده کند.
مسئولیت بررسی و شناسایی Double Spending کاملا به عهده پذیرنده می‌باشد.
  
  ## استعلام وضعیت تراکنش
  با استفاده از متود زیر می‌توانید آخرین وضعیت یک تراکنش را دریافت نمایید.

ts
import { idPay } from '@aspianet/idpay';

const info = await idPay.inquireTransaction( { id: 'd2e353189823079e1e4181772cff5292', order_id: '101', } );`


  
  ## لیست تراکنش ها
  با استفاده از متود زیر می توانید لیست تراکنش های خود را دریافت کنید.

ts
import { idPay } from '@aspianet/idpay';

const result = await idPay.listTransactions( { page: 0, page_size: 25, id: "e22952579725883bbad9f8fa429134bf", order_id: 101, amount: 10000, status: ["100"], track_id: "27384837", payment_card_no: "6362145409", payment_hashed_card_no: "B913D97F01CE42601181135DF3D0F81DA9E98E61BE3E3AB4436E6345D6AB0AEA", payment_date: {min: 1600005000, max: 1600006000}, settlement_date: {min: 1600005746, max: 1600006000} } );`


  
  
  ## وضعیت تراکنش
  برای دریافت پیام فارسی وضعیت تراکنش با استفاده از کد دریافتی آن در پاسخ های دریافتی و ... می توانید از متود زیر استفاده نمایید:

ts
import { idPay } from '@aspianet/idpay';

const message = idPay.getStatusMsgByCode( 2 );``