Bugeto.Payments.ZarinPal 1.0.0

Bugeto.Payments.ZarinPal

کتابخانه‌ای برای برقراری ارتباط تمیز و قابل تست با درگاه پرداخت زرین‌پال، همراه با نمونه‌ی آماده در قالب برنامه‌ی ASP.NET Core MVC.

امکانات

• ثبت درخواست پرداخت با پشتیبانی از متادیتا و جزئیات سبد خرید
• تولید آدرس هدایت کاربر به صفحه‌ی پرداخت بر اساس محیط (Production یا Sandbox)
• وریفای تراکنش پس از بازگشت کاربر و دریافت اطلاعات کامل کارت و کد پیگیری
• استعلام وضعیت تراکنش از متد inquiry و بازیابی تراکنش‌های تاییدنشده
• ثبت راحت سرویس‌ها در DI با استفاده از متدهای اکستنشن
• تست‌های واحد برای اطمینان از نگاشت صحیح پاسخ‌های زرین پال
• نمونه‌ی MVC جهت اجرای سناریوی کامل پرداخت در محیط سندباکس

نحوه استفاده

ثبت سرویس‌ها و پیکربندی

using Bugeto.Payments.ZarinPal.Abstractions;
using Bugeto.Payments.ZarinPal.Configuration;
using Bugeto.Payments.ZarinPal.Extensions;
using Bugeto.Payments.ZarinPal.Contracts.Requests;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddZarinPalGateway(options =>
{
    options.MerchantId = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx";
    options.Environment = ZarinPalEnvironment.Sandbox;
});

var app = builder.Build();

app.MapPost("/payments/start", async (IZarinPalGateway gateway) =>
{
    var request = new PaymentRequest
    {
        Amount = 50000,
        Description = "تمدید اشتراک کاربر",
        CallbackUrl = new Uri("https://example.com/payments/verify")
    };

    var response = await gateway.RequestPaymentAsync(request);
    return response.IsSuccess ? Results.Redirect(response.Data!.PaymentUri!.ToString()) : Results.BadRequest(response.Errors);
});

ارسال درخواست حداقلی

var minimalRequest = new PaymentRequest
{
    Amount = 10000,
    Description = "خرید اعتبار",
    CallbackUrl = new Uri("https://example.com/payments/verify")
};

var minimalResponse = await gateway.RequestPaymentAsync(minimalRequest);

ارسال درخواست کامل همراه همه پارامترها

var fullRequest = new PaymentRequest
{
    Amount = 250000,
    Description = "سبد خرید فروشگاه",
    CallbackUrl = new Uri("https://example.com/payments/verify"),
    Currency = "IRT",
    Metadata = new PaymentMetadata
    {
        Mobile = "09120000000",
        Email = "buyer@example.com",
        OrderId = Guid.NewGuid().ToString("N")
    },
    Cart = new PaymentCartData
    {
        Items = new[]
        {
            new PaymentCartItem
            {
                Name = "دوره آموزش پیشرفته",
                Amount = "150000",
                Count = "1",
                TotalAmount = "150000"
            },
            new PaymentCartItem
            {
                Name = "پکیج فایل‌های دانلودی",
                Amount = "50000",
                Count = "2",
                TotalAmount = "100000"
            }
        },
        AddedCosts = new PaymentCartAddedCosts
        {
            Tax = "5000",
            Payment = "2000",
            Transport = "8000"
        },
        Deductions = new PaymentCartDeductions
        {
            Discount = "7000"
        }
    }
};

var fullResponse = await gateway.RequestPaymentAsync(fullRequest);

وریفای و استعلام وضعیت

if (minimalResponse.IsSuccess && minimalResponse.Data?.Authority is { } authority)
{
    var verifyResult = await gateway.VerifyPaymentAsync(new PaymentVerificationRequest
    {
        Authority = authority,
        Amount = minimalRequest.Amount
    });

    var inquiryResult = await gateway.InquiryPaymentAsync(new PaymentInquiryRequest
    {
        Authority = authority
    });
}

var unverified = await gateway.GetUnverifiedPaymentsAsync();

اجرای نمونه MVC

cd Bugeto.Payments.ZarinPal.Sample.Mvc
ASPNETCORE_URLS=http://0.0.0.0:5000 dotnet run

مقادیر MerchantId در فایل appsettings.json به صورت پیش‌فرض برای محیط سندباکس تنظیم شده است. پس از اجرای برنامه، با مراجعه به آدرس /Payments می‌توانید یک پرداخت آزمایشی انجام دهید و صفحه‌ی «تراکنش‌های تایید نشده» نیز برای مشاهده خروجی متد unVerified در دسترس است.