payOS .NET Library

The payOS .NET library provides convenient access to the payOS Merchant API from applications written in C#.

To learn how to use payOS Merchant API, checkout our API Reference and Documentation. We also have some examples in the Examples directory.

Requirements

This library currently support .NET Standard 2.0+, .NET Core 5+.

Installation

Install the package via NuGet Package Manager:

dotnet add package payOS

Or via Package Manager Console:

Install-Package payOS

Usage

Basic usage

First you need to initialize the client to interact with payOS Merchant API.

using PayOS;

// Initialize the client
var client = new PayOSClient("your-client-id", "your-api-key", "your-checksum-key");

// Or initialize with options
var client = new PayOSClient(new PayOSOptions
{
    ClientId = "your-client-id",
    ApiKey = "your-api-key",
    ChecksumKey = "your-checksum-key"
});

// Or use default value in environment variables (recommended)
// Set PAYOS_CLIENT_ID, PAYOS_API_KEY, PAYOS_CHECKSUM_KEY, PAYOS_PARTNER_CODE
var client = new PayOSClient();

Then you can interact with payOS Merchant API, for example create a payment link using PaymentRequests.CreateAsync().

using PayOS.Models;

var paymentRequest = new CreatePaymentLinkRequest
{
    OrderCode = 123,
    Amount = 2000,
    Description = "payment",
    ReturnUrl = "https://your-url.com",
    CancelUrl = "https://your-url.com"
};

var paymentLink = await client.PaymentRequests.CreateAsync(paymentRequest);

Webhook verification

You can register an endpoint to receive the payment webhook.

var confirmResult = await client.Webhooks.ConfirmAsync("https://your-url.com/payos-webhook");

Then use Webhooks.VerifyAsync() to verify and receive webhook data.

var webhookData = await client.Webhooks.VerifyAsync(new Webhook
{
    Code = "00",
    Description = "success",
    Success = true,
    Data = new WebhookData
    {
        OrderCode = 123,
        Amount = 3000,
        Description = "VQRIO123",
        AccountNumber = "12345678",
        Reference = "TF230204212323",
        TransactionDateTime = "2023-02-04 18:25:00",
        Currency = "VND",
        PaymentLinkId = "124c33293c43417ab7879e14c8d9eb18",
        Code = "00",
        Description2 = "Thành công",
        CounterAccountBankId = "",
        CounterAccountBankName = "",
        CounterAccountName = "",
        CounterAccountNumber = "",
        VirtualAccountName = "",
        VirtualAccountNumber = ""
    },
    Signature = "8d8640d802576397a1ce45ebda7f835055768ac7ad2e0bfb77f9b8f12cca4c7f"
});

For more information about webhooks, see the API doc.

Handling errors

The library throws custom exceptions for different error scenarios:

try
{
    var paymentLink = await client.PaymentRequests.CreateAsync(paymentData);
}
catch (ApiException ex)
{
    Console.WriteLine($"API Error: {ex.Message}");
    Console.WriteLine($"Status Code: {ex.StatusCode}");
    Console.WriteLine($"Error Code: {ex.ErrorCode}");
}
catch (PayOSException ex)
{
    Console.WriteLine($"PayOS Error: {ex.Message}");
}

Auto pagination

For endpoints that support pagination, you can use the built-in pagination:

var payouts = await client.Payouts.ListAsync(limit: 20, offset: 0);

Advanced usage

Custom configuration

You can customize the PayOS client with various options:

var client = new PayOSClient(new PayOSOptions
{
    ClientId = "your-client-id",
    ApiKey = "your-api-key",
    ChecksumKey = "your-checksum-key",
    PartnerCode = "your-partner-code", // Optional partner code
    BaseUrl = "https://api-merchant.client.vn", // Custom base URL
    TimeoutMs = 30000, // Request timeout in milliseconds (default: 60000)
    MaxRetries = 3, // Maximum retry attempts (default: 2)
    LogLevel = LogLevel.Information, // Log level
    Logger = logger, // Custom logger implementation
    HttpClient = httpClient, // Custom HttpClient instance
    DefaultHeaders = new Dictionary<string, string>
    {
        { "Custom-Header", "value" }
    }
});

Custom HttpClient

You can provide a custom HttpClient instance:

var httpClient = new HttpClient();
// Configure your HttpClient as needed

var client = new PayOSClient(new PayOSOptions
{
    ClientId = "your-client-id",
    ApiKey = "your-api-key",
    ChecksumKey = "your-checksum-key",
    HttpClient = httpClient
});

Request-level options

You can override client-level settings for individual requests using CancellationToken:

var cts = new CancellationTokenSource(TimeSpan.FromSeconds(10));

var paymentLink = await client.PaymentRequests.CreateAsync(
    paymentData,
    cts.Token // Custom timeout for this request
);

Logging and debugging

The SDK supports logging through Microsoft.Extensions.Logging:

var logger = LoggerFactory.Create(builder => builder.AddConsole()).CreateLogger<PayOS>();

var client = new PayOSClient(new PayOSOptions
{
    ClientId = "your-client-id",
    ApiKey = "your-api-key",
    ChecksumKey = "your-checksum-key",
    LogLevel = LogLevel.Debug, // Enable debug logging
    Logger = logger
});

Direct API access

For advanced use cases, you can make direct API calls:

// GET request
var response = await client.GetAsync<List<PaymentLink>>("/v2/payment-requests");

// POST request
var response = await client.PostAsync<CreatePaymentLinkResponse>("/v2/payment-requests", new
{
    orderCode = 123,
    amount = 2000,
    description = "payment",
    returnUrl = "https://your-url.com",
    cancelUrl = "https://your-url.com"
});

Signature

The signature can be manually created by PayOS.Crypto:

// for create-payment-link signature
var signature = await client.Crypto.CreateSignatureOfPaymentRequestAsync(data, client.ChecksumKey);

// for payment-requests and webhook signature
var signature = await client.Crypto.CreateSignatureFromObjectAsync(data, client.ChecksumKey);

// for payouts signature
var signature = await client.Crypto.CreateSignatureAsync(client.ChecksumKey, data);

Contributing

Please see our Contributing Guidelines for details.