Tapsilat.Net 2025.8.18.4

Tapsilat.Net

Enterprise-grade TypeScript SDK for Tapsilat Payment Processing Platform

About Tapsilat

Tapsilat is Turkey's leading fintech platform providing comprehensive payment processing solutions for businesses of all sizes. Our cutting-edge technology enables secure, fast, and reliable payment transactions with support for multiple payment methods, currencies, and advanced fraud protection.

Features

• Complete Payment Operations - Create, manage, and track payments
• Advanced Refund Management - Full and partial refund capabilities
• Order Management - List, cancel, and query order status
• Payment Terms System - Installment and term-based payments
• Transaction History - Detailed payment transaction logs
• Submerchant Management - Multi-vendor payment processing
• Webhook Security - HMAC-SHA256 signature verification
• Health Monitoring - API status checking
• Async/Await Support - Modern C# patterns
• Multi-Framework - .NET 6, 8, 9 support
• Dependency Injection - ASP.NET Core ready
• Comprehensive Validation - Built-in parameter validation
• Custom Exception Handling - Detailed error information

Installation

dotnet add package Tapsilat.Net

Quick Start

Initialize the SDK

using Tapsilat.Net;
using Tapsilat.Net.Configuration;

// Basic initialization
var client = new TapsilatClient("your-api-key");

// Advanced configuration
var client = new TapsilatClient(new TapsilatOptions
{
    ApiKey = "your-api-key",
    Environment = TapsilatEnvironment.Production,
    BaseUrl = "https://acquiring.tapsilat.dev/api/v1",
    Timeout = TimeSpan.FromSeconds(30)
});

Create an Order

var orderRequest = new CreateOrderRequest
{
    Amount = 150.75m,
    Currency = "TRY",
    Locale = "tr",
    Buyer = new BuyerInfo
    {
        Name = "John",
        Surname = "Doe",
        Email = "john.doe@example.com",
        Phone = "+9099999999",
        BuyerAddress = new AddressInfo
        {
            Country = "Turkey",
            City = "Istanbul",
            ContactName = "John Doe"
        }
    },
    Description = "Premium subscription - Monthly plan",
    ConversationId = Guid.NewGuid().ToString(),
    CallbackUrl = "https://mystore.com/callback"
};

var order = await client.Payment.CreateOrderAsync(orderRequest);
Console.WriteLine($"Checkout URL: {order.CheckoutUrl}");

Check Order Status

var status = await client.Payment.GetOrderStatusAsync(order.ReferenceId);
Console.WriteLine($"Order status: {status.Status}");

API Methods & Examples

Order Management

Create Order

var order = await client.Payment.CreateOrderAsync(new CreateOrderRequest
{
    Amount = 299.99m,
    Currency = "TRY",
    Locale = "tr",
    Buyer = new BuyerInfo
    {
        Name = "John",
        Surname = "Doe",
        Email = "john.doe@example.com",
        Phone = "+9099999999"
    },
    Description = "Product purchase",
    CallbackUrl = "https://mystore.com/success"
});

Get Order Details

var order = await client.Payment.GetOrderAsync("order-reference-id");
Console.WriteLine($"Order amount: {order.Amount} {order.Currency}");
Console.WriteLine($"Order status: {order.Status}");

Check Order Status

var status = await client.Payment.GetOrderStatusAsync("order-reference-id");
if (status.Status == "completed")
{
    Console.WriteLine("Payment successful!");
}

List Orders with Pagination

var orders = await client.Payment.GetOrdersAsync(page: 1, perPage: 10);
orders.Data.ForEach(order =>
{
    Console.WriteLine($"Order {order.ReferenceId}: {order.Amount} {order.Currency}");
});

Cancel Order

try
{
    var result = await client.Payment.CancelOrderAsync("order-reference-id");
    Console.WriteLine("Order cancelled successfully");
}
catch (TapsilatValidationException ex)
{
    Console.Error.WriteLine($"Cannot cancel order: {ex.Message}");
}

Payment Operations

Get Payment Details

var paymentDetails = await client.Payment.GetOrderPaymentDetailsAsync("order-reference-id");
Console.WriteLine($"Payment: {paymentDetails.Amount} {paymentDetails.Currency}");

// Get by conversation ID
var detailsByConversation = await client.Payment.GetOrderPaymentDetailsByConversationIdAsync("conversation-id");

Get Transaction History

var transactions = await client.Payment.GetOrderTransactionsAsync("order-reference-id");
transactions.Transactions.ForEach(tx =>
{
    Console.WriteLine($"{tx.Type}: {tx.Amount} on {tx.CreatedAt}");
});

Get Checkout URL

var checkoutUrl = await client.Payment.GetCheckoutUrlAsync("order-reference-id");
// Redirect customer to checkout
Response.Redirect(checkoutUrl);

Refund Operations

Process Partial Refund

var refund = await client.Payment.RefundOrderAsync(new RefundOrderRequest
{
    ReferenceId = "order-reference-id",
    Amount = 50.00m,
    Reason = "Customer request"
});
Console.WriteLine($"Refund ID: {refund.RefundId}");

Process Full Refund

var fullRefund = await client.Payment.RefundAllOrderAsync("order-reference-id");
Console.WriteLine($"Full refund processed: {fullRefund.Amount}");

Payment Terms Management

Get Order Terms

var terms = await client.Payment.GetOrderTermsAsync("order-id");
terms.Terms.ForEach(term =>
{
    Console.WriteLine($"Term {term.TermId}: {term.Amount} due on {term.DueDate}");
});

Create Payment Term

var termRequest = new CreateOrderTermRequest
{
    OrderId = "order-123",
    Amount = 100.00m,
    DueDate = "2025-12-31",
    Description = "First installment"
};

var term = await client.Payment.CreateOrderTermAsync(termRequest);
Console.WriteLine($"Created term: {term.TermId}");

Update Payment Term

var updateRequest = new UpdateOrderTermRequest
{
    TermReferenceId = "term-ref-123",
    DueDate = "2025-12-31",
    Amount = 150.00m
};

await client.Payment.UpdateOrderTermAsync("term-id", updateRequest);

Delete Payment Term

await client.Payment.DeleteOrderTermAsync("term-id");

Refund Payment Term

var refundRequest = new RefundOrderTermRequest
{
    Amount = 50.00m,
    Reason = "Customer request"
};

var refund = await client.Payment.RefundOrderTermAsync("term-id", refundRequest);

Terminate Order and All Terms

var termination = await client.Payment.TerminateOrderAsync("order-id");
Console.WriteLine($"Order terminated: {termination.Success}");

Submerchant Management

List Order Submerchants

var submerchants = await client.Payment.GetOrderSubmerchantsAsync(page: 1, perPage: 20);
submerchants.Data.ForEach(sub =>
{
    Console.WriteLine($"Submerchant: {sub.Name} - {sub.SubMerchantKey}");
});

Webhook Handling

Verify Webhook Signature

using Microsoft.AspNetCore.Mvc;

[ApiController]
[Route("api/[controller]")]
public class WebhookController : ControllerBase
{
    [HttpPost("tapsilat")]
    public async Task<IActionResult> HandleWebhook()
    {
        var payload = await new StreamReader(Request.Body).ReadToEndAsync();
        var signature = Request.Headers["X-Tapsilat-Signature"].FirstOrDefault();
        var secret = Environment.GetEnvironmentVariable("WEBHOOK_SECRET");

        var isValid = TapsilatClient.VerifyWebhook(payload, signature, secret);

        if (!isValid)
        {
            return Unauthorized(new { error = "Invalid signature" });
        }

        var webhookEvent = JsonSerializer.Deserialize<WebhookEvent>(payload);

        switch (webhookEvent.Type)
        {
            case "order.completed":
                Console.WriteLine($"Order completed: {webhookEvent.Data.ReferenceId}");
                // Process successful payment
                break;
            case "order.failed":
                Console.WriteLine($"Order failed: {webhookEvent.Data.ReferenceId}");
                // Handle failed payment
                break;
        }

        return Ok(new { received = true });
    }
}

Alternative Webhook Verification (with prefix)

// Handles signatures with 'sha256=' prefix
var isValid = WebhookService.VerifyWebhookSignatureWithPrefix(payload, signature, secret);

Utility Operations

Manual Callback

var callbackRequest = new ManualCallbackRequest
{
    OrderId = "order-123",
    CallbackUrl = "https://mystore.com/callback"
};

var response = await client.Payment.SendManualCallbackAsync(callbackRequest);

Update Order Reference

var updateRequest = new OrderRelatedUpdateRequest
{
    ReferenceId = "new-reference-id"
};

var result = await client.Payment.UpdateOrderRelatedReferenceAsync("order-id", updateRequest);

Health Check

var health = await client.Payment.HealthCheckAsync();
Console.WriteLine($"API Status: {health.Status}");
Console.WriteLine($"Timestamp: {health.Timestamp}");

� API Reference

Core Operations

Payment Terms

Type System

All C# types are strongly typed with comprehensive validation. Key models include:

• CreateOrderRequest - Order creation parameters
• BuyerInfo - Customer information
• RefundOrderRequest - Refund parameters
• WebhookEvent - Webhook payload structure

Testing

dotnet test

41 comprehensive tests covering payment operations, validation, and webhook verification.

License

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

Resources

• Website: https://tapsilat.dev
• Documentation: API Documentation
• Issues: GitHub Issues
• Examples: See examples folder for complete implementations
• NuGet Package: Tapsilat.Net

Support

For technical support or questions:

• Create an issue on GitHub
• Contact our development team at support@tapsilat.dev
• Visit our documentation for detailed guides

<div align="center">

</div>