معرفی پکیج نوگت غیر رسمی زرین پال برای دات نت

در این مطلب پکیج نوگت Riviera.ZarinPal را برای دسترسی به درگاه پرداخت زرین پال در دات نت بررسی خواهیم کرد.

نحوه نصب

با استفاده از Package Manager Console در ویژوال استودیو پکیج نوگت Riviera.ZarinPal را نصب کنید.

Install-Package Riviera.ZarinPal -PreRelease

انتخاب نسخه درگاه

در حال حاظر دو نسخه از REST API زرین پال در دسترس است که شما می‌توانید یکی از آن‌ها را انتخاب کنید:

• نسخه 1: این نسخه قدیمی‌تر REST API زرین پال است که امکانات پایه را همراه با پاسخ های ساده‌تر در اختیار شما قرار می‌دهد.
• نسخه 4: این نسخه جدید‌تر REST API زرین پال است که دارای امکانات بیشتری است.

استفاده از نسخه 4

برای استفاده از این نسخه ابتدا لازم است ZarinPalService و تنظیمات آن را ریجستر کنید.

// using Riviera.ZarinPal.V4;

builder.Services.Configure<ZarinPalOptions>(o => builder.Configuration.GetSection("ZarinPal").Bind(o));
builder.Services.AddHttpClient<ZarinPalService>();

سپس تنظیمات زیر را به فایل appsettings.Development.json خود اضافه کنید.

• MerchantId: کد اختصاصی پذیرنده است.
• IsDevelopment: تعیین می‌کند که از سرویس تست پرداخت «سندباکس» استفاده شود یا خیر.

"ZarinPal": {
  "MerchantId": "your-merchant-id",
  "IsDevelopment": true
}

پس از ریجستر کردن سرویس لازم است آن را به کنترلر خود اضافه کنید.

// using Riviera.ZarinPal.V4;

public class HomeController : Controller
{
    private readonly ZarinPalService _zarinpal;

    public HomeController(ZarinPalService zarinpal)
    {
        _zarinpal = zarinpal;
    }
}

درخواست پرداخت جدید

ابتدا یک نمونه از کلاس NewPayment را ایجاد کنید.

• Amount: مبلغ تراکنش است.
• Description: توضیحاتی کوتاه در مورد تراکنش است.
• CallbackUri: آدرسی است که پس از پرداخت، جهت بررسی وضعیت تراکنش به آن ارجاع داده می‌شود.

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

var payment = new NewPayment
{
    Amount = 1000,
    Description = "This is a test payment",
    CallbackUri = new Uri("https://localhost:5001/get"),
};

var result = await _zarinpal.RequestPaymentAsync(payment);

در ادامه وضعیت درخواست را بررسی کرده و در صورت موفقیت آمیز بودن به درگاه پرداخت ری‌دایرکت کنید.

• Code: وضعیت درخواست است.
• PaymentUri: آدرس ارجاع به درگاه پرداخت، برای شروع پرداخت است.

if (result is null)
{
    // Return an error message.
}

if (result.Data?.Code == 100 && result.Data.PaymentUri is not null)
{
    return Redirect(result.Data.PaymentUri.AbsoluteUri);
}

نمونه کد کامل اکشن به شکل زیر خواهد بود:

// using Riviera.ZarinPal.V4.Models;

[Route("send")]
public async Task<IActionResult> Send()
{
    var payment = new NewPayment
    {
        Amount = 1000,
        Description = "This is a test payment",
        CallbackUri = new Uri("https://localhost:5001/get"),
    };

    var result = await _zarinpal.RequestPaymentAsync(payment);

    if (result is null)
    {
        return Content("Failed, Unexpected error.");
    }

    if (result.Data?.Code == 100 && result.Data.PaymentUri is not null)
    {
        return Redirect(result.Data.PaymentUri.AbsoluteUri);
    }

    return Content($"Failed, Error {result.Error?.Code}: {result.Error?.Message}");
}

پیشنهاد می‌شود قبل از ریدایرکت به درگاه پرداخت، مقدار Authority را در دیتابیس ذخیره کنید.

اعتبار سنجی تراکنش

پس از پرداخت، درگاه پرداخت به CallbackUri معرفی شده در «درخواست پرداخت» ری‌دایرکت کرده و مقادیر Status و Authority را به صورت Query String برگشت خواهد داد.

• Status: وضعیت تراکنش است.
• Authority: کد یکتای تراکنش است.

برای شروع، در اکشن مورد نظر مقادیر Status و Authority را دریافت کنید.

var status = Request.Query["Status"].ToString();
var authority = Request.Query["Authority"].ToString();

if (string.IsNullOrEmpty(status) || string.IsNullOrEmpty(authority))
{
    // Return an error message.
}

سپس مقدار Status را بررسی کنید.

زرین پال مقادیر OK و NOK را برای Status برگشت خواهد داد که برای بررسی آن می‌توانید از متد کمکی IsStatusValid استفاده کنید.

if (!_zarinpal.IsStatusValid(status))
{
    // Return an error message.
}

در صورت صحیح بودن وضعیت، یک نمونه از کلاس NewVerify را ایجاد کنید.

• Amount: مبلغ تراکنش است که باید آن را از دیتابیس خوانده و سپس تنظیم کنید.
• Authority: همان کد یکتای تراکنش است که زرین پال پس از بازگشت از درگاه پرداخت برگشت داده است.

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

var verify = new NewVerify
{
    Amount = 1000,
    Authority = authority,
};

var result = await _zarinpal.VerifyPaymentAsync(verify);

در ادامه وضعیت اعتبار سنجی را بررسی کرده و در صورت موفقیت آمیز بودن اقدامات لازم را انجام دهید.

• Code: وضعیت درخواست اعتبار سنجی است.
• RefId: کد پیگیری پرداخت است.

if (result is null)
{
    // Return an error message.
}

if (result.Data?.Code == 100 || result.Data?.Code == 101)
{
    return Content($"Success, RefId: {result.Data.RefId}");
}

نمونه کد کامل اکشن به شکل زیر خواهد بود:

// using Riviera.ZarinPal.V4.Models;

[Route("get")]
public async Task<IActionResult> Get()
{
    // Get the query strings.
    var status = Request.Query["Status"].ToString();
    var authority = Request.Query["Authority"].ToString();

    if (string.IsNullOrEmpty(status) || string.IsNullOrEmpty(authority))
    {
        return Content("Bad request.");
    }

    // Check if status query string is valid.
    if (!_zarinpal.IsStatusValid(status))
    {
        return Content("Failed, payment request has been cancelled.");
    }

    var verify = new NewVerify
    {
        Amount = 1000,
        Authority = authority,
    };

    var result = await _zarinpal.VerifyPaymentAsync(verify);

    if (result is null)
    {
        return Content("Failed, Unexpected error.");
    }

    // Check the transaction status.
    if (result.Data?.Code == 100 || result.Data?.Code == 101)
    {
        return Content($"Success, RefId: {result.Data.RefId}");
    }

    return Content($"Failed, Error {result.Error?.Code}: {result.Error?.Message}");
}

تراکنش های معوق

شما می‌توانید لیست تراکنش های اعتبارسنجی نشده را با استفاده از متد GetPendingPaymentsAsync دریافت کنید.

var result = await _zarinpal.GetPendingPaymentsAsync();

وضعیت تراکنش

شما می‌توانید با استفاده از متد GetPaymentStatusAsync وضعیت یک تراکنش را بررسی کنید.

// using Riviera.ZarinPal.V4.Models;

var status = new NewPaymentStatus
{
    Authority = "authority",
};

var result = await _zarinpal.GetPaymentStatusAsync(status);

لغو تراکنش

شما می‌توانید با استفاده از متد RefundAsync یک تراکنش موفق را بازگشت دهید.

به گفته زرین پال شما می‌توانید تراکنش های موفق که کمتر 30 دقیقه از آن‌ها گذشته باشد را به حساب خریدار بازگردانید.

// using Riviera.ZarinPal.V4.Models;

var refund = new NewRefund
{
    Authority = "authority",
};

var result = await _zarinpal.RefundAsync(refund);

استفاده از نسخه 1

برای استفاده از این نسخه ابتدا لازم است ZarinPalService و تنظیمات آن را ریجستر کنید.

// using Riviera.ZarinPal.V1;

builder.Services.Configure<ZarinPalOptions>(o => builder.Configuration.GetSection("ZarinPal").Bind(o));
builder.Services.AddHttpClient<ZarinPalService>();

سپس تنظیمات زیر را به فایل appsettings.Development.json خود اضافه کنید.

• MerchantId: کد اختصاصی پذیرنده است.
• IsDevelopment: تعیین می‌کند که از سرویس تست پرداخت «سندباکس» استفاده شود یا خیر.

"ZarinPal": {
  "MerchantId": "your-merchant-id",
  "IsDevelopment": true
}

پس از ریجستر کردن سرویس لازم است آن را به کنترلر خود اضافه کنید.

// using Riviera.ZarinPal.V1;

public class HomeController : Controller
{
    private readonly ZarinPalService _zarinpal;

    public HomeController(ZarinPalService zarinpal)
    {
        _zarinpal = zarinpal;
    }
}

درخواست پرداخت جدید

ابتدا با استفاده از متد RequestPaymentAsync درخواست پرداخت جدید را ارسال کنید.

• Amount: مبلغ تراکنش است.
• Description: توضیحاتی کوتاه در مورد تراکنش است.
• CallbackUri: آدرسی است که پس از پرداخت، جهت بررسی وضعیت تراکنش به آن ارجاع داده می‌شود.

long amount = 1000;
string description = "This is a test payment";
string callbackUrl = "https://localhost:5001/get";

var request = await _zarinpal.RequestPaymentAsync(amount, description, new Uri(callbackUrl));

در ادامه وضعیت درخواست را بررسی کرده و در صورت موفقیت آمیز بودن به درگاه پرداخت ری‌دایرکت کنید.

• Status: وضعیت درخواست است.
• PaymentUri: آدرس ارجاع به درگاه پرداخت، برای شروع پرداخت است.

if (result is null)
{
    // Return an error message.
}

if (result.Status == 100 && result.PaymentUri is not null)
{
    return Redirect(result.PaymentUri.AbsoluteUri);
}

نمونه کد کامل اکشن به شکل زیر خواهد بود:

[Route("send")]
public async Task<IActionResult> Send()
{
    long amount = 1000;
    string description = "This is a test payment";
    string callbackUrl = "https://localhost:5001/get";

    var result = await _zarinpal.RequestPaymentAsync(amount, description, new Uri(callbackUrl));

    if (result is null)
    {
        return Content("Failed, Unexpected error.");
    }

    if (result.Status == 100 && result.PaymentUri is not null)
    {
        return Redirect(result.PaymentUri.AbsoluteUri);
    }

    return Content($"Failed, Error code: {result.Status}");
}

پیشنهاد می‌شود قبل از ریدایرکت به درگاه پرداخت، مقدار Authority را در دیتابیس ذخیره کنید.

اعتبار سنجی تراکنش

پس از پرداخت، درگاه پرداخت به CallbackUri معرفی شده در «درخواست پرداخت» ری‌دایرکت کرده و مقادیر Status و Authority را به صورت Query String برگشت خواهد داد.

• Status: وضعیت تراکنش است.
• Authority: کد یکتای تراکنش است.

برای شروع، در اکشن مورد نظر مقادیر Status و Authority را از درخواست دریافت کنید.

var status = Request.Query["Status"].ToString();
var authority = Request.Query["Authority"].ToString();

if (string.IsNullOrEmpty(status) || string.IsNullOrEmpty(authority))
{
    // Return an error message.
}

سپس وضعیت Status را بررسی کنید.

زرین پال مقادیر OK و NOK را برای Status برگشت خواهد داد که برای بررسی آن می‌توانید از متد کمکی IsStatusValid استفاده کنید.

if (!_zarinpal.IsStatusValid(status))
{
    // Return an error message.
}

در صورت صحیح بودن وضعیت، با استفاده از متد VerifyPaymentAsync درخواست اعتبار سنجی را ارسال کنید.

• Amount: مبلغ تراکنش است که باید آن را از دیتابیس خوانده و سپس تنظیم کنید.
• Authority: همان کد یکتای تراکنش است که زرین پال پس از بازگشت از درگاه پرداخت برگشت داده است.

long amount = 1000;
var response = await _zarinpal.VerifyPaymentAsync(amount, authority);

در ادامه وضعیت اعتبار سنجی را بررسی کرده و در صورت موفقیت آمیز بودن اقدامات لازم را انجام دهید.

• Status: وضعیت درخواست اعتبار سنجی است.
• RefId: کد پیگیری پرداخت است.

if (result is null)
{
    // Return an error message.
}

if (result.Status == 100 || result.Status == 101)
{
    return Content($"Success, RefId: {result.RefId}");
}

نمونه کد کامل اکشن به شکل زیر خواهد بود:

[Route("get")]
public async Task<IActionResult> Get()
{
    // Get the query strings.
    var status = Request.Query["Status"].ToString();
    var authority = Request.Query["Authority"].ToString();

    if (string.IsNullOrEmpty(status) || string.IsNullOrEmpty(authority))
    {
        return Content("Bad request.");
    }

    // Check if status query string is valid.
    if (!_zarinpal.IsStatusValid(status))
    {
        return Content("Failed, payment request has been cancelled.");
    }

    long amount = 1000;
    var result = await _zarinpal.VerifyPaymentAsync(amount, authority);

    if (result is null)
    {
        return Content("Failed, Unexpected error.");
    }

    // Check the transaction status.
    if (result.Status == 100 || result.Status == 101)
    {
        return Content($"Success, RefId: {result.RefId}");
    }

    return Content($"Failed, Error code: {result.Status}");
}

اطلاعات بیشتر

• سورس کامل این کتابخانه در صفحه گیت هاب قابل دسترسی است.
• مستندات درگاه پرداخت زرین پال نسخه 1 را می‌توانید در این لینک مشاهده کنید.
• مستندات درگاه پرداخت زرین پال نسخه 4 را می‌توانید در وب سایت زرین پال مشاهده کنید.