ZibalClient 1.0.0

Zibal .NET Client Library

A modern .NET client library for integrating with the Zibal payment gateway. This library provides a simple and type-safe way to interact with Zibal's payment services, supporting both standard and advanced payment workflows.

Features

• Full support for standard and advanced payment operations
• Strongly-typed request/response models
• Async/await pattern support
• Built-in validation for payment parameters
• Support for multiplexing payments (split payments between multiple beneficiaries)
• Lazy payment request handling
• transaction status inquiry

Installation

dotnet add package ZibalClient  

Quick Start

Non-DI Projects:

// Create an instance of ZibalClient
using var httpClient = new HttpClient();
var ZibalClient = new ZibalClient(httpClient);

// Create a basic payment request
CreateTransactionRequest request = new()
{
    Merchant = "YOUR_MERCHANT_INFO",
    Amount = 10000,  // Amount to pay in Rials
    CallbackURL = "https://your-website.com/payment/callback", // Where Zibal Will Send Transaction Information.
    IsTest = true, // supported... will set merchant as Zibal as per document.
    Description = "Payment for Order #1984",
    Mobile = "09xxxxxxxxx"
};

// Request a new transaction from Zibal.
var response = await ZibalClient.RequestTransactionAsync(request);

// Get the payment URL
var paymentUrl = $"https://gateway.zibal.ir/start/{response.TrackID}"; 

Dependancy Injection:

in program.cs:

builder.services.AddHttpClient<ZibalClient>();

Or if you want to specify object lifetime:

services.AddHttpClient<ZibalClient>().AddScoped<ZibalClient>();

In your service (e.g PaymentService):

private readonly ZibalClient _zibalClient;

public PaymentService(ZibalClient zibalClient)
{
    _zibalClient = zibalClient;
}

Usage Examples

Basic Payment Flow

1. Request a Transaction

var request = new CreateTransactionRequest
{
    Merchant = "YOUR_MERCHANT_INFO",
    Amount = 10000,  // Amount to pay in Rials
    CallbackURL = "https://your-website.com/payment/callback", // Where Zibal Will Send Transaction Information.
    IsTest = true, // supported... will set merchant as Zibal as per document.
    Description = "Payment for Order #1984",
    Mobile = "09xxxxxxxxx"
};

var response = await ZibalClient.RequestTransactionAsync(request);

2. Verify the Transaction

var verifyRequest = new VerifyTransactionRequest
{
    Merchant = "YOUR_MERCHANT_INFO",
    TrackID = response.TrackID
};

var verificationResponse = await ZibalClient.VerifyTransactionAsync(verifyRequest);

Advanced Payment (Multiplexing)

var advancedRequest = new CreateAdvancedTransactionRequest
{
    Merchant = "YOUR_MERCHANT_INFO",
    Amount = 10000,
    CallbackURL = "https://your-website.com/payment/callback",
    PercentMode = 0,  // 0 for fixed amounts, 1 for percentages
    FeeMode = 0,      // 0: from transaction, 1: from wallet, 2: paid by client
    MultiplexingInfos = new List<MultiplexingInformation>
    {
        new()
        {
            SubMerchantID = "MERCHANT1",
            Amount = 7000,
            WagePayer = true
        },
        new()
        {
            BankAccount = "SHABA Number",
            Amount = 3000
        }
    }
};

var response = await ZibalClient.RequestTransactionAsync(advancedRequest, isAdvanced: true);

Transaction Status Inquiry

var inquiryRequest = new InquiryTransactionRequest
{
    Merchant = "YOUR_MERCHANT_INFO",
    TrackID = trackId
};

var status = await ZibalClient.GetTransactionStatusAsync(inquiryRequest);

Card Number Restrictions

var request = new CreateTransactionRequest
{
    // ... other properties ...
    AllowedCards = new List<string> { "6219861012345678", "6274121234567890" }
};

National Code Validation

var request = new CreateTransactionRequest
{
    // ... other properties ...
    NationalCode = "1234567890",
    CheckMobileWithCard = true  // Validates mobile number matches card owner
};

Important Lazy Mode Note:

Since Zibal uses Post requests and Json to inform you about the transaction in Lazy Mode, I have also written a class to deserialize that information called LazyCallbackResponse.

using System.Text.Json;

var transactionInfo = await JsonSerializer.DeserializeAsync<LazyCallbackResponse>(await response.Content.ReadAsStreamAsync());

Error Handling

The library provides detailed error information through response codes and messages. Check the Result and Message properties in response objects for error details.

Testing

Set IsTest = true in your requests to use Zibal's test environment:

var request = new CreateTransactionRequest
{
    IsTest = true,
    // ... other properties ...
};

Response Status Codes

For a complete list of status codes and their meanings, refer to Zibal's API documentation.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Zibal API Documentation
• Contributors if there will be any!

Support

For support with this library, please open an issue on GitHub. For Zibal-specific questions, please contact Zibal support directly.