Dzeta.Bicycle.Client 1.0.1

Bicycle Payment Processor Client

This package provides a .NET client for the Bicycle payment processor API.

Features

• Generate new deposit addresses
• Retrieve deposit history
• Send withdrawal requests
• Full async/await support
• Comprehensive error handling with custom exceptions
• Structured logging
• Easy dependency injection integration

Quick Start

1. Configuration

Add the payment processor configuration to your appsettings.json:

{
  "BicyclePaymentProcessor": {
    "ApiUrl": "https://api.Bicycle-payment.com",
    "Passkey": "your-api-passkey",
    "RequestTimeout": "00:00:30"
  }
}

2. Service Registration

In your Program.cs or Startup.cs:

using RPS.Common.Services.PaymentProcessor;

// Option 1: From configuration
services.AddBicyclePaymentClient(configuration);

// Option 2: Direct configuration
services.AddBicyclePaymentClient(config =>
{
    config.ApiUrl = "https://api.Bicycle-payment.com";
    config.Passkey = "your-api-passkey";
    config.RequestTimeout = TimeSpan.FromSeconds(30);
});

// Option 3: With custom configuration object
var config = new PaymentProcessorConfig
{
    ApiUrl = "https://api.Bicycle-payment.com",
    Passkey = "your-api-passkey"
};
services.AddBicyclePaymentClient(config);

3. Usage

Inject IBicyclePaymentClient into your services:

public class PaymentService
{
    private readonly IBicyclePaymentClient _paymentClient;

    public PaymentService(IBicyclePaymentClient paymentClient)
    {
        _paymentClient = paymentClient;
    }

    public async Task<string> GenerateDepositAddressAsync(string userId, string currency)
    {
        var response = await _paymentClient.GenerateNewAddressAsync(userId, currency);
        return response.Address;
    }

    public async Task<List<DepositIncome>> GetDepositsAsync(string userId, string currency)
    {
        var query = new DepositHistoryQuery
        {
            UserId = userId,
            Currency = currency,
            Limit = 50,
            SortOrder = "desc"
        };

        var response = await _paymentClient.GetDepositHistoryAsync(query);
        return response.Incomes;
    }

    public async Task<int> SendWithdrawalAsync(string userId, string currency, 
        string amount, string destination, string? comment = null)
    {
        var request = new WithdrawalRequest
        {
            UserId = userId,
            QueryId = Guid.NewGuid().ToString(),
            Currency = currency,
            Amount = amount,
            Destination = destination,
            Comment = comment
        };

        var response = await _paymentClient.SendWithdrawalAsync(request);
        return response.Id;
    }
}

API Reference

Generate New Address

Creates a new deposit address for a user and currency:

var response = await client.GenerateNewAddressAsync("user123", "TON");
// response.Address = "0QB7BSerVyP9xAKnxp3QpqR8JO2HKwZhl10zsfwg7aJ281ZR"

Get Deposit History

Retrieves deposit history with optional filtering:

var query = new DepositHistoryQuery
{
    UserId = "user123",
    Currency = "TON",
    Limit = 10,
    Offset = 0,
    SortOrder = "desc"
};

var response = await client.GetDepositHistoryAsync(query);
foreach (var deposit in response.Incomes)
{
    Console.WriteLine($"Amount: {deposit.Amount}, Time: {deposit.GetDateTime()}");
}

Send Withdrawal

Sends a withdrawal request:

var request = new WithdrawalRequest
{
    UserId = "user123",
    QueryId = Guid.NewGuid().ToString(), // Unique request ID
    Currency = "TON",
    Amount = "1000000", // Amount in base units (NanoTONs for TON)
    Destination = "0QCdyiS-fIV9UVfI9Phswo4l2MA-hm8YseHynZ_YiH9Y1oSe",
    Comment = "Withdrawal to user wallet"
};

var response = await client.SendWithdrawalAsync(request);
// response.Id = withdrawal ID for tracking

Error Handling

The client throws specific exceptions for different error conditions:

try
{
    var response = await client.GenerateNewAddressAsync("user123", "TON");
}
catch (PaymentProcessorAuthenticationException)
{
    // Handle authentication errors (401)
}
catch (PaymentProcessorBadRequestException ex)
{
    // Handle validation errors (400)
    Console.WriteLine($"Bad request: {ex.ErrorResponse}");
}
catch (PaymentProcessorServerException ex)
{
    // Handle server errors (500)
    Console.WriteLine($"Server error: {ex.ErrorResponse}");
}
catch (PaymentProcessorException ex)
{
    // Handle other payment processor errors
    Console.WriteLine($"Payment error: {ex.Message}");
}

Models

DepositIncome

Represents a deposit transaction:

public class DepositIncome
{
    public string DepositAddress { get; set; }    // Receiving address
    public long Time { get; set; }                // Unix timestamp
    public string SourceAddress { get; set; }     // Sender address
    public string Amount { get; set; }            // Amount in base units
    public string Comment { get; set; }           // Transaction comment
    public string TxHash { get; set; }            // Transaction hash
    
    public DateTime GetDateTime() => ...          // Converts Time to DateTime
}

Important Notes

• Amounts: All amounts are in base units (e.g., NanoTONs for TON currency)
• Authentication: Uses Bearer token authentication with the provided passkey
• Currency: Supported currencies depend on the payment processor configuration
• Query IDs: Should be unique for each withdrawal request to prevent duplicates

Logging

The client uses structured logging. Configure your logging system to capture:

• Request/response details (Debug level)
• Error information (Error level)
• Client initialization (Information level)

Example log output:

[INF] Bicycle payment client initialized with base URL: https://api.Bicycle-payment.com
[DBG] Generating new address for user user123 and currency TON
[ERR] Payment processor API error: 400 - Invalid currency code