Paymentus.Core 1.0.1

Paymentus Server .NET SDK

What is the Paymentus Server SDK?

The Paymentus Server SDK is a comprehensive .NET-based toolkit that simplifies integration with the Paymentus Server-side APIs. Designed for backend services, it enables secure, streamlined access to Paymentus' powerful XOTP platform—including payments, user management, autopay, account inquiries, and more. The SDK abstracts authentication flows, allowing developers to focus on building functionality without managing token lifecycles manually.

Features

• Modular Architecture: Use individual packages or the unified SDK
• Type Safety: Full type information with strongly typed models
• Automatic Token Management: Seamless JWT token handling (via Paymentus.Auth)
• Error Handling: Comprehensive error types and messages
• Configuration Validation: Runtime validation of configuration options
• Granular Scope Support: Targeted API access via granular access scopes
• Pixel Integration: Automatic scope mapping for Paymentus pixels
• XOTP Integration: Full support for payment API functionality

Installation

dotnet add package Paymentus.Core

Basic Usage

Using the Core SDK

using Paymentus.Auth.Models;
using Paymentus.Auth.Types;
using Paymentus.Core;
using Paymentus.Core.Models;

// Configure the Auth component
var authConfig = AuthConfig.CreateBuilder()
    .WithBaseUrl("https://<environment>.paymentus.com")
    .WithPreSharedKey("shared-256-bit-secret")
    .WithTla("ABC")
    .WithScope(new List<string> { Scopes.Xotp })
    .Build();

// Create SDK configuration with authConfig
var config = CoreConfig.CreateBuilder()
    .WithAuthConfig(authConfig)
    .Build();

// Initialize SDK
var sdk = CoreSdk.CreateSdk(config);

// Fetch token
var token = sdk.Auth().FetchTokenAsync().Result;
var isTokenExpired = sdk.Auth().IsTokenExpired();
var currentToken = sdk.Auth().GetCurrentToken();

Payment Examples

// Example 1: Make Payment
using Paymentus.Auth.Models;
using Paymentus.Auth.Types;
using Paymentus.Core;
using Paymentus.Core.Models;
using Paymentus.Xotp.Model;
using Paymentus.Xotp.Types;

// Configure the SDK
var authConfig = AuthConfig.CreateBuilder()
    .WithBaseUrl("https://<environment>.paymentus.com")
    .WithPreSharedKey("shared-256-bit-secret")
    .WithTla("ABC")
    .WithScope(new List<string> { Scopes.XotpPayment })
    .Build();

var config = CoreConfig.CreateBuilder()
    .WithAuthConfig(authConfig)
    .WithLogLevel(LogLevel.Normal)
    .WithMaskingLevel(MaskingLevel.AllPii)
    .Build();

var sdk = CoreSdk.CreateSdk(config);

// Create payment headers
var header1 = new PaymentHeader(
    accountNumber: "6759370",
    paymentAmount: 13.21,
    paymentTypeCode: "UTILITY"
);

var header2 = new PaymentHeader(
    accountNumber: "6759375",
    paymentAmount: 13.21,
    paymentTypeCode: "WATER"
);

// Create payment method (credit card)
var paymentMethod = new PaymentMethod(
    type: PaymentMethodTypeEnum.VISA,
    accountNumber: "4111111111111111",
    cardHolderName: "John Doe",
    creditCardExpiryDate: new CreditCardExpiryDate(
        month: MonthEnum.January, 
        year: 2035
    )
);

// Create address for customer
var address = new Address(
    line1: "10 Fifth Ave.",
    state: "NY",
    zipCode: "12345",
    city: "New York",
    country: "US"
);

// Create customer information
var customer = new Customer(
    firstName: "John",
    lastName: "Doe",
    email: "customer@example.com",
    dayPhoneNr: "9051112233",
    address: address
);

// Create payment item combining all details
var paymentItem = new MakePaymentItem(
    header: new List<PaymentHeader> { header1, header2 },
    paymentMethod: paymentMethod,
    customer: customer
);

// Create the payment payload
var paymentPayload = new MakePaymentRequest(
    payment: paymentItem
);

// Make the payment
PaymentResponse result = sdk.Xotp().MakePayment(paymentPayload);

// Example 2: Refund Payment
using Paymentus.Auth.Models;
using Paymentus.Auth.Types;
using Paymentus.Core;
using Paymentus.Core.Models;
using Paymentus.Xotp.Model;
using Paymentus.Xotp.Types;

// Configure the SDK
var authConfig = AuthConfig.CreateBuilder()
    .WithBaseUrl("https://<environment>.paymentus.com")
    .WithPreSharedKey("shared-256-bit-secret")
    .WithTla("ABC")
    .WithScope(new List<string> { Scopes.Xotp })
    .Build();

var config = CoreConfig.CreateBuilder()
    .WithAuthConfig(authConfig)
    .WithLogLevel(LogLevel.Verbose)
    .WithMaskingLevel(MaskingLevel.AllPii)
    .Build();

var sdk = CoreSdk.CreateSdk(config);

// Create payment header
var header = new PaymentHeader(
    accountNumber: "6759370",
    paymentAmount: 11.22,
    paymentTypeCode: "UTILITY"
);

// Create payment method for refund
var expiryDate = new CreditCardExpiryDate(
    month: MonthEnum.December,
    year: 2035
);

var paymentMethod = new PaymentMethod(
    type: PaymentMethodTypeEnum.VISAIREFUND,
    accountNumber: "4111111111111111",
    cardHolderName: "John Doe",
    creditCardExpiryDate: expiryDate
);

// Create address
var address = new Address(
    line1: "10 Fifth Ave.",
    state: "NY",
    zipCode: "12345",
    city: "New York",
    country: "US"
);

// Create customer
var customer = new Customer(
    firstName: "John",
    lastName: "Doe",
    email: "john@example.com",
    dayPhoneNr: "9051112233",
    address: address
);

// Create payment item
var payment = new Payment(
    header: header,
    paymentMethod: paymentMethod,
    customer: customer
);

// Create refund payment request
var refundPayload = new PaymentRequest(
    payment: payment
);

// Process refund
PaymentResponse result = sdk.Xotp().RefundPayment(refundPayload);

// Example 3: Payment History
using Paymentus.Auth.Models;
using Paymentus.Auth.Types;
using Paymentus.Core;
using Paymentus.Core.Models;
using Paymentus.Xotp.Model;
using Paymentus.Xotp.Types;

// Configure the SDK
var authConfig = AuthConfig.CreateBuilder()
    .WithBaseUrl("https://<environment>.paymentus.com")
    .WithPreSharedKey("shared-256-bit-secret")
    .WithTla("ABC")
    .WithScope(new List<string> { Scopes.Xotp })
    .Build();

var config = CoreConfig.CreateBuilder()
    .WithAuthConfig(authConfig)
    .WithLogLevel(LogLevel.Verbose)
    .WithMaskingLevel(MaskingLevel.AllPii)
    .Build();

var sdk = CoreSdk.CreateSdk(config);

// Create payment search request with date range
var searchPayload = new PaymentSearchRequest(
    accountNumber: "6759370"
)
{
    DateFrom = DateTime.Parse("2025-06-18"),
    DateTo = DateTime.Parse("2025-09-19")
};

// Get payment history
PaymentHistoryResponse result = sdk.Xotp().GetPaymentHistory(searchPayload);

// Example 4: Fetch Last Payment
using Paymentus.Auth.Models;
using Paymentus.Auth.Types;
using Paymentus.Core;
using Paymentus.Core.Models;
using Paymentus.Xotp.Model;
using Paymentus.Xotp.Types;

// Configure the SDK
var authConfig = AuthConfig.CreateBuilder()
    .WithBaseUrl("https://<environment>.paymentus.com")
    .WithPreSharedKey("shared-256-bit-secret")
    .WithTla("ABC")
    .WithScope(new List<string> { Scopes.Xotp })
    .Build();

var config = CoreConfig.CreateBuilder()
    .WithAuthConfig(authConfig)
    .WithLogLevel(LogLevel.Verbose)
    .WithMaskingLevel(MaskingLevel.AllPii)
    .Build();

var sdk = CoreSdk.CreateSdk(config);

// Create payment search request
var paymentSearchRequest = new PaymentSearchRequest(
    accountNumber: "6759370"
);

// Fetch the last payment
PaymentSearchResponse result = sdk.Xotp().FetchLastPayment(paymentSearchRequest);

// Example 5: Conv Fee Calculation
using Paymentus.Auth.Models;
using Paymentus.Auth.Types;
using Paymentus.Core;
using Paymentus.Core.Models;
using Paymentus.Xotp.Model;
using Paymentus.Xotp.Types;

// Configure the SDK
var authConfig = AuthConfig.CreateBuilder()
    .WithBaseUrl("https://<environment>.paymentus.com")
    .WithPreSharedKey("shared-256-bit-secret")
    .WithTla("ABC")
    .WithScope(new List<string> { Scopes.XotpPayment })
    .Build();

var config = CoreConfig.CreateBuilder()
    .WithAuthConfig(authConfig)
    .WithLogLevel(LogLevel.Minimal)
    .Build();

var sdk = CoreSdk.CreateSdk(config);

// Create payment header with convenience fee information
var header = new PaymentHeader(
    paymentAmount: 22.00,
    convenienceFeeState: "NY",
    convenienceFeeCountry: ConvenienceFeeCountryEnum.US
);

// Create payment method
var method = new PaymentMethod(
    type: PaymentMethodTypeEnum.MC
);

// Create payment object
var payment = new Payment(
    header: header,
    paymentMethod: method,
    paymentMethodCategory: PaymentMethodCategoryEnum.CC
);
    
// Create convenience fee calculation request
var feePayload = new PaymentRequest(
    payment: payment
);

// Calculate convenience fee
PaymentResponse result = sdk.Xotp().CnvCalculation(feePayload);

// Example 6: Stage Payment
using Paymentus.Auth.Models;
using Paymentus.Auth.Types;
using Paymentus.Core;
using Paymentus.Core.Models;
using Paymentus.Xotp.Model;

// Configure the SDK
var authConfig = AuthConfig.CreateBuilder()
    .WithBaseUrl("https://<environment>.paymentus.com")
    .WithPreSharedKey("shared-256-bit-secret")
    .WithTla("ABC")
    .WithScope(new List<string> { Scopes.Xotp })
    .Build();

var config = CoreConfig.CreateBuilder()
    .WithAuthConfig(authConfig)
    .Build();

var sdk = CoreSdk.CreateSdk(config);

// Create payment header
var header = new PaymentHeader(
    accountNumber: "6759370",
    paymentAmount: 13.21,
    paymentTypeCode: "UTILITY",
    authToken1: "12345"
);

// Create customer
var customer = new Customer(
    firstName: "John",
    lastName: "Doe",
    email: "john@example.com",
    dayPhoneNr: "9051112233"
);

// Create payment item
var payment = new Payment(
    header: header,
    customer: customer
);

// Create stage payment request
var stagePaymentPayload = new PaymentRequest(
    payment: payment
);

// Stage the payment
StagePaymentResponse result = sdk.Xotp().StagePayment(stagePaymentPayload);

Autopay Examples

// Example 1: Create Autopay
using Paymentus.Auth.Models;
using Paymentus.Auth.Types;
using Paymentus.Core;
using Paymentus.Core.Models;
using Paymentus.Xotp.Model;
using Paymentus.Xotp.Types;

// Configure the SDK
var authConfig = AuthConfig.CreateBuilder()
    .WithBaseUrl("https://<environment>.paymentus.com")
    .WithPreSharedKey("shared-256-bit-secret")
    .WithTla("ABC")
    .WithScope(new List<string> { Scopes.XotpAutopay })
    .Build();

var config = CoreConfig.CreateBuilder()
    .WithAuthConfig(authConfig)
    .WithLogLevel(LogLevel.Normal)
    .Build();

var sdk = CoreSdk.CreateSdk(config);

// Create payment header with schedule information
var header = new PaymentHeader(
    accountNumber: "6759371",
    paymentAmount: 21.01,
    paymentTypeCode: "UTILITY",
    scheduleTypeCode: ScheduleTypeCodeEnum.MONTHLY,
    scheduleDay: 2
);

// Create payment method with token
var paymentMethod = new PaymentMethod(
    token: "17BA0791499DB908433B80F37C5FBC89B870084B"
);

// Create customer information
var customer = new Customer(
    firstName: "John",
    lastName: "Doe",
    email: "john@example.com",
    dayPhoneNr: "9051112233"
);

// Create payment schedule combining all details
var paymentSchedule = new Payment(
    header: header,
    paymentMethod: paymentMethod,
    customer: customer
);

// Create the autopay request
var autopayPayload = new AutopayRequest(
    paymentSchedule: paymentSchedule
);

// Create autopay schedule
AutopayResponse result = sdk.Xotp().CreateAutopay(autopayPayload);

// Example 2: Update Autopay
using Paymentus.Auth.Models;
using Paymentus.Auth.Types;
using Paymentus.Core;
using Paymentus.Core.Models;
using Paymentus.Xotp.Model;
using Paymentus.Xotp.Types;

// Configure the SDK
var authConfig = AuthConfig.CreateBuilder()
    .WithBaseUrl("https://<environment>.paymentus.com")
    .WithPreSharedKey("shared-256-bit-secret")
    .WithTla("ABC")
    .WithScope(new List<string> { Scopes.XotpAutopay })
    .Build();

var config = CoreConfig.CreateBuilder()
    .WithAuthConfig(authConfig)
    .WithLogLevel(LogLevel.Normal)
    .Build();

var sdk = CoreSdk.CreateSdk(config);

// Create payment header with updated values
var header = new PaymentHeader(
    scheduleTypeCode: ScheduleTypeCodeEnum.MONTHLY,
    scheduleDay: 13,
    paymentAmount: 11.09
);

// Create payment schedule
var paymentSchedule = new Payment(
    header: header
);

// Create autopay request
var autopayPayload = new AutopayRequest(
    paymentSchedule: paymentSchedule
);

// Reference number of the autopay schedule to update
string referenceNumber = "3454";

// Update autopay schedule
AutopayResponse result = sdk.Xotp().UpdateAutopay(referenceNumber, autopayPayload);

// Example 3: Get Autopay By Reference Number
using Paymentus.Auth.Models;
using Paymentus.Auth.Types;
using Paymentus.Core;
using Paymentus.Core.Models;
using Paymentus.Xotp.Model;
using Paymentus.Xotp.Types;

// Configure the SDK
var authConfig = AuthConfig.CreateBuilder()
    .WithBaseUrl("https://<environment>.paymentus.com")
    .WithPreSharedKey("shared-256-bit-secret")
    .WithTla("ABC")
    .WithScope(new List<string> { Scopes.XotpAutopay })
    .Build();

var config = CoreConfig.CreateBuilder()
    .WithAuthConfig(authConfig)
    .WithLogLevel(LogLevel.Normal)
    .Build();

var sdk = CoreSdk.CreateSdk(config);

// Reference number of the autopay schedule to retrieve
string referenceNumber = "3454";

// Fetch autopay details
AutopayFindResponse result = sdk.Xotp().GetAutopay(referenceNumber);

// Example 4: List Autopay
using Paymentus.Auth.Models;
using Paymentus.Auth.Types;
using Paymentus.Core;
using Paymentus.Core.Models;
using Paymentus.Xotp.Model;
using Paymentus.Xotp.Types;

// Configure the SDK
var authConfig = AuthConfig.CreateBuilder()
    .WithBaseUrl("https://<environment>.paymentus.com")
    .WithPreSharedKey("shared-256-bit-secret")
    .WithTla("ABC")
    .WithScope(new List<string> { Scopes.XotpAutopay })
    .Build();

var config = CoreConfig.CreateBuilder()
    .WithAuthConfig(authConfig)
    .WithLogLevel(LogLevel.Normal)
    .Build();

var sdk = CoreSdk.CreateSdk(config);

// Create autopay search request
var searchPayload = new AutopaySearchRequest(
    accountNumber: "6759371"
);

// List autopay schedules
AutopayListResponse result = sdk.Xotp().ListAutoPay(searchPayload);

// Example 5: Stage Autopay
using Paymentus.Auth.Models;
using Paymentus.Auth.Types;
using Paymentus.Core;
using Paymentus.Core.Models;
using Paymentus.Xotp.Model;
using Paymentus.Xotp.Types;

// Configure the SDK
var authConfig = AuthConfig.CreateBuilder()
    .WithBaseUrl("https://<environment>.paymentus.com")
    .WithPreSharedKey("shared-256-bit-secret")
    .WithTla("ABC")
    .WithScope(new List<string> { Scopes.Xotp })
    .Build();

var config = CoreConfig.CreateBuilder()
    .WithAuthConfig(authConfig)
    .WithLogLevel(LogLevel.Normal)
    .Build();

var sdk = CoreSdk.CreateSdk(config);

// Create payment header with schedule information
var header = new PaymentHeader(
    accountNumber: "6759372",
    paymentAmount: 13.21,
    paymentTypeCode: "UTILITY",
    scheduleTypeCode: ScheduleTypeCodeEnum.MONTHLY,
    scheduleStartDate: "20250909",
    scheduleDay: 11,
    authToken1: "12345"
);

// Create customer information
var customer = new Customer(
    firstName: "John",
    lastName: "Doe",
    email: "john@example.com",
    dayPhoneNr: "9051112233"
);

// Create payment schedule
var payment = new Payment(
    header: header,
    customer: customer
);

// Create stage autopay request
var stageAutopayPayload = new PaymentRequest(
    payment: payment
);

// Stage the autopay
StagePaymentResponse result = sdk.Xotp().StageAutopay(stageAutopayPayload);

// Example 6: Delete Autopay
using Paymentus.Auth.Models;
using Paymentus.Auth.Types;
using Paymentus.Core;
using Paymentus.Core.Models;
using Paymentus.Xotp.Model;
using Paymentus.Xotp.Types;

// Configure the SDK
var authConfig = AuthConfig.CreateBuilder()
    .WithBaseUrl("https://<environment>.paymentus.com")
    .WithPreSharedKey("shared-256-bit-secret")
    .WithTla("ABC")
    .WithScope(new List<string> { Scopes.Xotp })
    .Build();

var config = CoreConfig.CreateBuilder()
    .WithAuthConfig(authConfig)
    .WithLogLevel(LogLevel.Normal)
    .Build();

var sdk = CoreSdk.CreateSdk(config);

// Reference number of the autopay schedule to delete
string referenceNumber = "3449";

// Delete the autopay schedule
AutopayResponse result = sdk.Xotp().DeleteAutopay(referenceNumber);

Account Examples

// Example 1: Account Inquiry
using Paymentus.Auth.Models;
using Paymentus.Auth.Types;
using Paymentus.Core;
using Paymentus.Core.Models;
using Paymentus.Xotp.Model;
using Paymentus.Xotp.Types;

// Configure the SDK
var authConfig = AuthConfig.CreateBuilder()
    .WithBaseUrl("https://<environment>.paymentus.com")
    .WithPreSharedKey("shared-256-bit-secret")
    .WithTla("ABC")
    .WithScope(new List<string> { Scopes.Xotp })
    .Build();

var config = CoreConfig.CreateBuilder()
    .WithAuthConfig(authConfig)
    .WithLogLevel(LogLevel.Verbose)
    .WithMaskingLevel(MaskingLevel.None)
    .Build();

var sdk = CoreSdk.CreateSdk(config);

var payload = new AccountInquiryRequest(
    accountNumber: "6759370",
    paymentTypeCode: "UTILITY",
    authToken1: "12345",
    includeSchedules: true,
    includeLastUsedPm: true,
    detailedInfo: true
);

AccountInquiryResponse result = sdk.Xotp().AccountInquiry(payload);

// Example 2: Account Info by Account Number
using Paymentus.Auth.Models;
using Paymentus.Auth.Types;
using Paymentus.Core;
using Paymentus.Core.Models;
using Paymentus.Xotp.Model;

// Configure the SDK
var authConfig = AuthConfig.CreateBuilder()
    .WithBaseUrl("https://<environment>.paymentus.com")
    .WithPreSharedKey("shared-256-bit-secret")
    .WithTla("ABC")
    .WithScope(new List<string> { Scopes.Xotp })
    .Build();

var config = CoreConfig.CreateBuilder()
    .WithAuthConfig(authConfig)
    .Build();

var sdk = CoreSdk.CreateSdk(config);

string accountNumber = "6759370";

ListAccountInfoResponse result = sdk.Xotp().GetAccountInfoByAccountNumber(accountNumber);

// Example 3: Account Info by Email
using Paymentus.Auth.Models;
using Paymentus.Auth.Types;
using Paymentus.Core;
using Paymentus.Core.Models;
using Paymentus.Xotp.Model;
using Paymentus.Xotp.Types;

// Configure the SDK
var authConfig = AuthConfig.CreateBuilder()
    .WithBaseUrl("https://<environment>.paymentus.com")
    .WithPreSharedKey("shared-256-bit-secret")
    .WithTla("ABC")
    .WithScope(new List<string> { Scopes.Xotp })
    .Build();

var config = CoreConfig.CreateBuilder()
    .WithAuthConfig(authConfig)
    .WithLogLevel(LogLevel.Normal)
    .WithMaskingLevel(MaskingLevel.AllPii)
    .Build();

var sdk = CoreSdk.CreateSdk(config);

string email = "user@example.com";

ListAccountInfoResponse result = sdk.Xotp().GetAccountInfoByEmail(email);

User Examples

// Example 1: Create User
using Paymentus.Auth.Models;
using Paymentus.Auth.Types;
using Paymentus.Core;
using Paymentus.Core.Models;
using Paymentus.Xotp.Model;

// Configure the SDK
var authConfig = AuthConfig.CreateBuilder()
    .WithBaseUrl("https://<environment>.paymentus.com")
    .WithPreSharedKey("shared-256-bit-secret")
    .WithTla("ABC")
    .WithScope(new List<string> { Scopes.Xotp })
    .Build();

var config = CoreConfig.CreateBuilder()
    .WithAuthConfig(authConfig)
    .WithLogLevel(LogLevel.Normal)
    .WithMaskingLevel(MaskingLevel.AllPii)
    .Build();

var sdk = CoreSdk.CreateSdk(config);

// Create user profile info
var profile = new UserProfileInfo(
    firstName: "John",
    lastName: "Doe",
    email: "john@example.com"
);

// Create user info
var userInfo = new UserInfo(
    loginId: "john@example.com",
    password: "SecretPassword123",
    forcePasswordChange: true,
    profile: profile
);

// Create client account
var clientAccount = new ClientAccountItem(
    accountNumber: "6759374",
    paymentTypeCode: "UTILITY",
    authToken1: "12345"
);

// Create user profile
var userProfile = new UserRequestItem(
    userInfo: userInfo,
    clientAccount: new List<ClientAccountItem> { clientAccount }
);

// Create the request
var createUser = new UserRequest(userProfile: userProfile);

// Create the user
UserResponse result = sdk.Xotp().CreateUser(createUser);

// Example 2: Update User
using Paymentus.Auth.Models;
using Paymentus.Auth.Types;
using Paymentus.Core;
using Paymentus.Core.Models;
using Paymentus.Xotp.Model;

// Configure the SDK
var authConfig = AuthConfig.CreateBuilder()
    .WithBaseUrl("https://<environment>.paymentus.com")
    .WithPreSharedKey("shared-256-bit-secret")
    .WithTla("ABC")
    .WithScope(new List<string> { Scopes.Xotp })
    .Build();

var config = CoreConfig.CreateBuilder()
    .WithAuthConfig(authConfig)
    .WithLogLevel(LogLevel.Normal)
    .WithMaskingLevel(MaskingLevel.AllPii)
    .Build();

var sdk = CoreSdk.CreateSdk(config);

// Create profile info with updated details
var profile = new UserProfileInfo(
    dayPhoneNr: "5559098888",
    zipCode: "28202"
);

// Create user info for user to be updated
var userInfo = new UserInfo(
    loginId: "john@example.com",
    profile: profile
);

// Create user with permission
var userWithPermission = new UserLoginId(
    loginId: "admin@example.com"
);

// Create user update request item
var userProfile = new UserUpdateRequestItem(
    userInfo: userInfo,
    user: userWithPermission
);

// Create update request
var updateUser = new UserUpdateRequest(
    userProfile: userProfile
);

// Update the user
UserResponse result = sdk.Xotp().UpdateUser(updateUser);

// Example 3: Get User
using Paymentus.Auth.Models;
using Paymentus.Auth.Types;
using Paymentus.Core;
using Paymentus.Core.Models;
using Paymentus.Xotp.Model;

// Configure the SDK
var authConfig = AuthConfig.CreateBuilder()
    .WithBaseUrl("https://<environment>.paymentus.com")
    .WithPreSharedKey("shared-256-bit-secret")
    .WithTla("ABC")
    .WithScope(new List<string> { Scopes.Xotp })
    .Build();

var config = CoreConfig.CreateBuilder()
    .WithAuthConfig(authConfig)
    .WithLogLevel(LogLevel.Normal)
    .WithMaskingLevel(MaskingLevel.AllPii)
    .Build();

var sdk = CoreSdk.CreateSdk(config);

bool includeContactInfo = true;
var result = sdk.Xotp().GetUser("john@example.com", includeContactInfo);

// Example 4: Delete User
using Paymentus.Auth.Models;
using Paymentus.Auth.Types;
using Paymentus.Core;
using Paymentus.Core.Models;
using Paymentus.Xotp.Model;
using Paymentus.Xotp.Types;

// Configure the SDK
var authConfig = AuthConfig.CreateBuilder()
    .WithBaseUrl("https://<environment>.paymentus.com")
    .WithPreSharedKey("shared-256-bit-secret")
    .WithTla("ABC")
    .WithScope(new List<string> { Scopes.Xotp })
    .Build();

var config = CoreConfig.CreateBuilder()
    .WithAuthConfig(authConfig)
    .WithLogLevel(LogLevel.Verbose)
    .WithMaskingLevel(MaskingLevel.AllPii)
    .Build();

var sdk = CoreSdk.CreateSdk(config);

// Create user to delete
var userToDelete = new UserLoginId(
    loginId: "john@example.com"
);

// Create user with permission
var userWithPermission = new UserLoginId(
    loginId: "admin@example.com"
);

// Create user delete request
var user = new UserDeleteRequestItem(
    userInfo: userToDelete,
    user: userWithPermission
);

// Create the delete request
var deleteUser = new UserDeleteRequest(
    userProfile: user
);

// Delete the user
UserResponse result = sdk.Xotp().DeleteUser(deleteUser);

Profile Examples

// Example 1: Create Profile
using Paymentus.Auth.Models;
using Paymentus.Auth.Types;
using Paymentus.Core;
using Paymentus.Core.Models;
using Paymentus.Xotp.Model;
using Paymentus.Xotp.Types;

// Configure the SDK
var authConfig = AuthConfig.CreateBuilder()
    .WithBaseUrl("https://<environment>.paymentus.com")
    .WithPreSharedKey("shared-256-bit-secret")
    .WithTla("ABC")
    .WithScope(new List<string> { Scopes.XotpProfileCreate })
    .Build();

var config = CoreConfig.CreateBuilder()
    .WithAuthConfig(authConfig)
    .WithLogLevel(LogLevel.Normal)
    .WithMaskingLevel(MaskingLevel.AllPii)
    .Build();

var sdk = CoreSdk.CreateSdk(config);

var paymentMethod = new PaymentMethod(
    type: PaymentMethodTypeEnum.VISA,
    accountNumber: "4444444444444448",
    creditCardExpiryDate: new CreditCardExpiryDate(
        month: MonthEnum.October,
        year: 2035
    ),
    cardHolderName: "John Doe"
);

var userInfo = new ProfileUserInfo(
    loginId: "john@example.com"
);

var customer = new ProfileCustomer(
    firstName: "John", 
    lastName: "Doe"
);

var profileItem = new ProfileRequestItem(
    paymentMethod: paymentMethod, 
    customer: customer,
    userInfo: userInfo
);

var payload = new ProfileRequest(profile: profileItem);

var result = sdk.Xotp().CreateProfile(payload);

// Example 2: Update Profile
using Paymentus.Auth.Models;
using Paymentus.Auth.Types;
using Paymentus.Core;
using Paymentus.Core.Models;
using Paymentus.Xotp.Model;
using Paymentus.Xotp.Types;

// Configure the SDK
var authConfig = AuthConfig.CreateBuilder()
    .WithBaseUrl("https://<environment>.paymentus.com")
    .WithPreSharedKey("shared-256-bit-secret")
    .WithTla("ABC")
    .WithScope(new List<string> { Scopes.XotpProfile })
    .Build();

var config = CoreConfig.CreateBuilder()
    .WithAuthConfig(authConfig)
    .WithLogLevel(LogLevel.Normal)
    .WithMaskingLevel(MaskingLevel.AllPii)
    .Build();

var sdk = CoreSdk.CreateSdk(config);

var profileItem = new ProfileUpdateItem(
    profileDescription: "Main Payment Profile",
    defaultFlag: true
);

var payload = new ProfileUpdateRequest(profile: profileItem);

string profileToken = "some-token";

var result = sdk.Xotp().UpdateProfile(profileToken, payload);

// Example 3: Get Profile
using Paymentus.Auth.Models;
using Paymentus.Auth.Types;
using Paymentus.Core;
using Paymentus.Core.Models;
using Paymentus.Xotp.Model;
using Paymentus.Xotp.Types;

// Configure the SDK
var authConfig = AuthConfig.CreateBuilder()
    .WithBaseUrl("https://<environment>.paymentus.com")
    .WithPreSharedKey("shared-256-bit-secret")
    .WithTla("ABC")
    .WithScope(new List<string> { Scopes.XotpProfile })
    .Build();

var config = CoreConfig.CreateBuilder()
    .WithAuthConfig(authConfig)
    .WithLogLevel(LogLevel.Normal)
    .WithMaskingLevel(MaskingLevel.AllPii)
    .Build();

var sdk = CoreSdk.CreateSdk(config);

string profileToken = "some-token";

var result = sdk.Xotp().GetProfile(profileToken);

// Example 4: List Profiles
using Paymentus.Auth.Models;
using Paymentus.Auth.Types;
using Paymentus.Core;
using Paymentus.Core.Models;
using Paymentus.Xotp.Model;
using Paymentus.Xotp.Types;

// Configure the SDK
var authConfig = AuthConfig.CreateBuilder()
    .WithBaseUrl("https://<environment>.paymentus.com")
    .WithPreSharedKey("shared-256-bit-secret")
    .WithTla("ABC")
    .WithScope(new List<string> { Scopes.XotpListProfiles })
    .Build();

var config = CoreConfig.CreateBuilder()
    .WithAuthConfig(authConfig)
    .WithLogLevel(LogLevel.Normal)
    .WithMaskingLevel(MaskingLevel.AllPii)
    .Build();

var sdk = CoreSdk.CreateSdk(config);

string loginId = "john@example.com";

// Use null for paymentMethodTypes to get all profiles
var result = sdk.Xotp().GetProfiles(loginId);

// Example 5: Delete Profile
using Paymentus.Auth.Models;
using Paymentus.Auth.Types;
using Paymentus.Core;
using Paymentus.Core.Models;
using Paymentus.Xotp.Model;
using Paymentus.Xotp.Types;

// Configure the SDK
var authConfig = AuthConfig.CreateBuilder()
    .WithBaseUrl("https://<environment>.paymentus.com")
    .WithPreSharedKey("shared-256-bit-secret")
    .WithTla("ABC")
    .WithScope(new List<string> { Scopes.XotpProfile, Scopes.XotpProfileDelete })
    .Build();

var config = CoreConfig.CreateBuilder()
    .WithAuthConfig(authConfig)
    .WithLogLevel(LogLevel.Normal)
    .WithMaskingLevel(MaskingLevel.AllPii)
    .Build();

var sdk = CoreSdk.CreateSdk(config);

string profileToken = "some-token";

var result = sdk.Xotp().DeleteProfile(profileToken);

Other Examples

// Example 1: Get Bank Info
using Paymentus.Auth.Models;
using Paymentus.Auth.Types;
using Paymentus.Core;
using Paymentus.Core.Models;
using Paymentus.Xotp.Model;

// Configure the SDK
var authConfig = AuthConfig.CreateBuilder()
    .WithBaseUrl("https://<environment>.paymentus.com")
    .WithPreSharedKey("shared-256-bit-secret")
    .WithTla("ABC")
    .WithScope(new List<string> { Scopes.Xotp })
    .Build();

var config = CoreConfig.CreateBuilder()
    .WithAuthConfig(authConfig)
    .Build();

var sdk = CoreSdk.CreateSdk(config);

string routingNumber = "021000128";

var result = sdk.Xotp().GetBankInfo(routingNumber);

// Example 2: Resend Email Confirmation
using Paymentus.Auth.Models;
using Paymentus.Auth.Types;
using Paymentus.Core;
using Paymentus.Core.Models;
using Paymentus.Xotp.Model;

// Configure the SDK
var authConfig = AuthConfig.CreateBuilder()
    .WithBaseUrl("https://<environment>.paymentus.com")
    .WithPreSharedKey("shared-256-bit-secret")
    .WithTla("ABC")
    .WithScope(new List<string> { Scopes.Xotp })
    .Build();

var config = CoreConfig.CreateBuilder()
    .WithAuthConfig(authConfig)
    .Build();

var sdk = CoreSdk.CreateSdk(config);

var header = new ResendEmailRequestHeader(
    accountNumber: "6759370",
    referenceNumber: "731358"
);

var payment = new ResendEmailRequestItem(
    header: header
);

var resendRequest = new ResendEmailRequest(
    payment: payment
);

var result = sdk.Xotp().ResendEmailConfirmation(resendRequest);

Custom Logging

You can implement custom logging middleware by creating a class that implements the ILogger interface:

using Paymentus.Auth.Models;
using Paymentus.Auth.Types;
using Paymentus.Core;
using Paymentus.Core.Models;
using Paymentus.Xotp.Util;
using Paymentus.Xotp.Types;

// Custom logger implementation 
public class MyCustomLogger : ILogger
{
    public void Info(string message, params object[] args)
    {
        Console.WriteLine("[[INFO]] -- " + FormatMessage(message, args));
    }

    public void Error(string message, params object[] args)
    {
        Console.WriteLine("[[ERROR]] -- " + FormatMessage(message, args));
    }

    public void Warn(string message, params object[] args)
    {
        Console.WriteLine("[[WARN]] -- " + FormatMessage(message, args));
    }

    public void Debug(string message, params object[] args)
    {
        Console.WriteLine("[[DEBUG]] -- " + FormatMessage(message, args));
    }

    private static string FormatMessage(string message, object[] args)
    {
        if (args == null || args.Length == 0)
        {
            return message;
        }
        
        return string.Format(message, args);
    }
}

var authConfig = AuthConfig.CreateBuilder()
    .WithBaseUrl("https://<environment>.paymentus.com")
    .WithPreSharedKey("shared-256-bit-secret")
    .WithTla("ABC")
    .WithScope(new List<string> { Scopes.Xotp })
    .Build();

var config = CoreConfig.CreateBuilder()
    .WithAuthConfig(authConfig)
    .WithLogger(new MyCustomLogger()) // Provide custom logger
    .Build();

Available Log Levels

The SDK supports the following log levels to control the verbosity of logging output:

SILENT

Suppresses all logging output. Use this in production environments where you want to minimize overhead and don't need operational visibility.

var config = CoreConfig.CreateBuilder()
    // ... other config options
    .WithLogLevel(LogLevel.Silent)  // For No logging
    .Build();

MINIMAL

Logs only essential information such as request initiation and completion status with response codes. Use this for basic operational monitoring with minimal verbosity.

var config = CoreConfig.CreateBuilder()
    // ... other config options
    .WithLogLevel(LogLevel.Minimal)  // For Minimal logging
    .Build();

NORMAL

The default log level. Logs request/response information including basic request bodies and error details. Suitable for most development and staging environments.

var config = CoreConfig.CreateBuilder()
    // ... other config options
    .WithLogLevel(LogLevel.Normal)  // Default logging mode
    .Build();

VERBOSE

Maximum logging level that includes all request/response details, headers, and timing information. Ideal for debugging integration issues in development environments.

var config = CoreConfig.CreateBuilder()
    // ... other config options
    .WithLogLevel(LogLevel.Verbose)  // For Maximum logging
    .Build();

Available Masking Levels

The SDK also supports data masking to protect sensitive information in logs:

• NONE: No data masking is applied. Only use in secure environments where logs are properly protected.

var config = CoreConfig.CreateBuilder()
    // ... other config options
    .WithMaskingLevel(MaskingLevel.None)  // No masking in logs
    .Build();

• PCI_ONLY: Masks payment card information (account numbers, CVV) while preserving other data for debugging.

var config = CoreConfig.CreateBuilder()
    // ... other config options
    .WithMaskingLevel(MaskingLevel.PciOnly)  // Default Mode
    .Build();

• ALL_PII: Maximum protection that masks all personally identifiable information including names, addresses, and payment data.

var config = CoreConfig.CreateBuilder()
    // ... other config options
    .WithMaskingLevel(MaskingLevel.AllPii)  // Maximum masking while logging
    .Build();

Error Handling

The SDK provides comprehensive error handling:

using Paymentus.Auth.Errors;
using Paymentus.Xotp.Client;

try
{
    var result = sdk.Xotp().MakePayment(paymentPayload);
}
catch (TokenException ex)
{
    // Handle token-related issues
    Console.WriteLine($"Token Error: {ex.Message}");
}
catch (NetworkException ex)
{
    // Handle network connectivity issues
    Console.WriteLine($"Network Error: {ex.Message}");
}
catch (ConfigurationException ex)
{
    // Handle misconfiguration issues
    Console.WriteLine($"Configuration Error: {ex.Message}");
}
catch (ApiException ex)
{
    // Handle API errors
    Console.WriteLine($"API Error: {ex.ErrorCode} - {ex.Message}");
}

Available Scopes

The SDK supports the following scopes:

• xotp - Basic XOTP functionality
• xotp:profile - Profile management
• xotp:profile:read - Read profile data
• xotp:profile:create - Create profiles
• xotp:profile:update - Update profiles
• xotp:profile:delete - Delete profiles
• xotp:listProfiles - List profiles
• xotp:payment - Payment processing
• xotp:payment:history - Payment history
• xotp:payment:void - Void or cancel payments
• xotp:autopay - Autopay functionality
• xotp:autopay:delete - Delete autopay settings
• xotp:account - Link account to user
• xotp:accounts - Account management
• xotp:listAccounts - List accounts
• paybotus - Paybotus functionality

Pixel Integration

The SDK provides automatic scope mapping for Paymentus pixels. Specify pixels in AuthConfig and the SDK adds required scopes and validates required claims.

Basic example

using System.Collections.Generic;
using System.Threading.Tasks;
using Paymentus.Auth.Models;
using Paymentus.Auth.Types;
using Paymentus.Core;
using Paymentus.Core.Models;

var authConfig = AuthConfig.CreateBuilder()
    .WithBaseUrl("https://<environment>.paymentus.com")
    .WithPreSharedKey("your-pre-shared-key")
    .WithTla("ABC")
    .WithPixels(new List<PixelType> { PixelType.UserCheckout })
    .WithUserLogin("user@example.com")
    .WithPaymentsData(new List<PaymentData>
    {
        new PaymentData
        {
            AccountNumber = "123456",
            ConvFeeState = "NY",
            ConvFeeCountry = "US"
        }
    })
    .Build();

var sdk = CoreSdk.CreateSdk(CoreConfig.CreateBuilder()
    .WithAuthConfig(authConfig)
    .Build());

var token = await sdk.Auth().FetchTokenAsync();

Pixel reference

• tokenization-pixel

  • Scopes: xotp:profile
  • Claims: none required

• list-wallets-pixel

  • Scopes: xotp:profile, xotp:listProfiles, xotp:profile:delete
  • Claims: userLogin required

• user-checkout-pixel

  • Scopes: xotp:profile, xotp:payment, xotp:listProfiles, xotp:listAccounts, xotp:profile:delete
  • Claims: userLogin and paymentsData required; pmToken optional
  • Optional scopes:
    • xotp:autopay — autopay enrollment during checkout
    • xotp:account — link account to user (single account only)

var authConfig = AuthConfig.CreateBuilder()
    .WithBaseUrl("https://<environment>.paymentus.com")
    .WithPreSharedKey("your-pre-shared-key")
    .WithTla("ABC")
    .WithPixels(new List<PixelType> { PixelType.UserCheckout })
    .WithScope(new List<string> { Scopes.XotpAutopay, Scopes.XotpAccount })
    .WithUserLogin("user@example.com")
    .WithPaymentsData(new List<PaymentData>
    {
        new PaymentData { AccountNumber = "123456" }
    })
    .Build();

var sdk = CoreSdk.CreateSdk(CoreConfig.CreateBuilder()
    .WithAuthConfig(authConfig)
    .Build());

• guest-checkout-pixel
  • Scopes: xotp:payment, xotp:listAccounts, xotp:profile
  • Claims: paymentsData required
  • Automatically sets pmToken: ['anonymousPMOnly'] in the JWT

var authConfig = AuthConfig.CreateBuilder()
    .WithBaseUrl("https://<environment>.paymentus.com")
    .WithPreSharedKey("your-pre-shared-key")
    .WithTla("ABC")
    .WithPixels(new List<PixelType> { PixelType.GuestCheckout })
    .WithPaymentsData(new List<PaymentData>
    {
        new PaymentData { AccountNumber = "123456" }
    })
    .Build();

var sdk = CoreSdk.CreateSdk(CoreConfig.CreateBuilder()
    .WithAuthConfig(authConfig)
    .Build());

• user-autopay-pixel
  • Scopes: xotp:profile, xotp:autopay, xotp:payment, xotp:listProfiles, xotp:listAccounts, xotp:profile:delete
  • Claims: userLogin and paymentsData required; pmToken optional
  • Optional scope: xotp:account — link schedule account to user (single account only)

var authConfig = AuthConfig.CreateBuilder()
    .WithBaseUrl("https://<environment>.paymentus.com")
    .WithPreSharedKey("your-pre-shared-key")
    .WithTla("ABC")
    .WithPixels(new List<PixelType> { PixelType.UserAutopay })
    .WithScope(new List<string> { Scopes.XotpAccount })
    .WithUserLogin("user@example.com")
    .WithPaymentsData(new List<PaymentData>
    {
        new PaymentData { AccountNumber = "123456" }
    })
    .Build();

var sdk = CoreSdk.CreateSdk(CoreConfig.CreateBuilder()
    .WithAuthConfig(authConfig)
    .Build());

• list-autopay-pixel

  • Scopes: xotp:profile, xotp:autopay, xotp:payment, xotp:listProfiles, xotp:listAccounts, xotp:profile:delete, xotp:autopay:delete
  • Claims: userLogin and paymentsData required

• payment-history-pixel

  • Scopes: xotp:payment:history, xotp:payment, xotp:listProfiles
  • Claims: userLogin and paymentsData required
  • Optional scope: xotp:payment:void — cancel scheduled payments

var authConfig = AuthConfig.CreateBuilder()
    .WithBaseUrl("https://<environment>.paymentus.com")
    .WithPreSharedKey("your-pre-shared-key")
    .WithTla("ABC")
    .WithPixels(new List<PixelType> { PixelType.PaymentHistory })
    .WithScope(new List<string> { Scopes.XotpPaymentVoid })
    .WithUserLogin("user@example.com")
    .WithPaymentsData(new List<PaymentData>
    {
        new PaymentData { AccountNumber = "123456" }
    })
    .Build();

var sdk = CoreSdk.CreateSdk(CoreConfig.CreateBuilder()
    .WithAuthConfig(authConfig)
    .Build());

• manage-payment-pixel
  • Scopes: xotp:payment, xotp:profile, xotp:listProfiles, xotp:payment:void
  • Claims: userLogin and paymentsData required
  • paymentsData must include the reference or account number the user is allowed to manage

var authConfig = AuthConfig.CreateBuilder()
    .WithBaseUrl("https://<environment>.paymentus.com")
    .WithPreSharedKey("your-pre-shared-key")
    .WithTla("ABC")
    .WithPixels(new List<PixelType> { PixelType.ManagePayment })
    .WithUserLogin("user@example.com")
    .WithPaymentsData(new List<PaymentData>
    {
        new PaymentData { ReferenceNumber = "736165" }
    })
    .Build();

var sdk = CoreSdk.CreateSdk(CoreConfig.CreateBuilder()
    .WithAuthConfig(authConfig)
    .Build());

paymentsData entries support accountNumber, referenceNumber, and optional convenience fee fields (convFeeState, convFeeCountry).

API Reference

SDK Class

Constructor

SDK(CoreConfig config)

Creates a new SDK instance with the provided configuration.

Disclaimer

These SDKs are intended for use with the URLs and keys that are provided to you for your company by Paymentus. If you do not have this information, please reach out to your implementation or account manager. If you are interested in learning more about the solutions that Paymentus provides, you can visit our website at paymentus.com. You can request access to our complete documentation at developer.paymentus.io. If you are currently not a customer or partner and would like to learn more about the solution and how you can get started with Paymentus, please contact us at https://www.paymentus.com/lets-talk/.

Contact us

If you have any questions or need assistance, please contact us at sdksupport@paymentus.com.

License

MIT