Tapsilat Rust SDK

Enterprise-grade Rust 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.

Quick Start

Initialize the SDK

use tapsilat::{Config, TapsilatClient};

let client = TapsilatClient::from_api_key("your-bearer-token")?;

// Or with advanced configuration
let config = Config::new("your-bearer-token")
    .with_base_url("https://panel.tapsilat.dev/api/v1")
    .with_timeout(30);
let client = TapsilatClient::new(config)?;

Create an Order

use tapsilat::{CreateOrderRequest, CreateBuyerRequest, Currency};

let order_request = CreateOrderRequest {
    amount: 150.75,
    currency: Currency::TRY,
    locale: Some("tr".to_string()),
    conversation_id: Some("order-12345".to_string()),
    description: Some("Premium subscription - Monthly plan".to_string()),
    buyer: Some(CreateBuyerRequest {
        name: "John".to_string(),
        surname: "Doe".to_string(),
        email: "john.doe@example.com".to_string(),
        phone: Some("5551234567".to_string()),
        identity_number: None,
        shipping_address: None,
        billing_address: None,
    }),
    items: vec![],
    callback_url: None,
    metadata: None,
};

let order = client.create_order(order_request)?;
println!("Order ID: {}", order.order_id);

Check Order Status

let status = client.get_order_status(&order.order_id)?;
println!("Order status: {}", status);

Features

Core Payment Operations

• Secure authentication with bearer tokens
• Complete payment lifecycle management
• Multi-currency support (TRY, USD, EUR, GBP)
• Advanced filtering and pagination

Payment Term Management

• Create and manage installment plans
• Update payment terms (amount, dates, status)
• Delete payment terms
• Term-specific refunds and termination
• Complete order termination

Validation & Utilities

• Turkish GSM number validation and formatting
• Installment validation with flexible input formats
• Input validation for all request parameters
• Webhook signature verification

Technical Features

• Full Rust type safety
• Zero-copy deserialization with serde
• Async/await support
• Configuration management
• Request/response validation
• Comprehensive error handling

SDK Compatibility

This Rust SDK provides full feature parity with Tapsilat's JavaScript and Python SDKs:

API Methods & Examples

Order Management

Create Order

use tapsilat::CreateOrderItemRequest;

let order_request = CreateOrderRequest {
    amount: 299.99,
    currency: Currency::TRY,
    locale: Some("tr".to_string()),
    conversation_id: Some("order-12345".to_string()),
    description: Some("Product purchase".to_string()),
    buyer: Some(CreateBuyerRequest {
        name: "John".to_string(),
        surname: "Doe".to_string(),
        email: "john.doe@example.com".to_string(),
        phone: Some("5551234567".to_string()),
        identity_number: None,
        shipping_address: None,
        billing_address: None,
    }),
    items: vec![CreateOrderItemRequest {
        name: "Premium Product".to_string(),
        price: 299.99,
        quantity: 1,
        description: Some("High quality product".to_string()),
    }],
    callback_url: Some("https://mystore.com/success".to_string()),
    metadata: None,
};

let order = client.create_order(order_request)?;

Get Order Details

let order = client.get_order("order-id")?;
println!("Order amount: {}", order.order.amount);
println!("Order status: {:?}", order.order.status);

Check Order Status

let status = client.get_order_status("order-id")?;
println!("Payment status: {}", status);

List Orders

let orders = client.get_order_list(Some(1), Some(10))?;
println!("Found {} orders", orders.total);

Cancel Order

match client.cancel_order("order-id") {
    Ok(_) => println!("Order cancelled successfully"),
    Err(e) => eprintln!("Cannot cancel order: {}", e),
}

Payment Operations

Get Payment Details

let payment_details = client.get_order_payment_details("order-id")?;
println!("Payment details: {:?}", payment_details);

Get Transaction History

let transactions = client.get_order_transactions("order-id")?;
println!("Transaction history: {:?}", transactions);

Get Checkout URL

let checkout_url = client.get_checkout_url("order-id")?;
println!("Redirect customer to: {:?}", checkout_url);

Refund Operations

Process Partial Refund

let refund_result = client.refund_order("order-id", Some(50.0))?;
println!("Refund processed: {:?}", refund_result);

Process Full Refund

let full_refund = client.refund_all_order("order-id")?;
println!("Full refund processed: {:?}", full_refund);

Webhook Handling

Verify Webhook Signature

use tapsilat::WebhookModule;

// In your webhook handler
fn handle_webhook(payload: &str, signature: &str, secret: &str) -> Result<(), Box<dyn std::error::Error>> {
    let is_valid = WebhookModule::verify_webhook(payload, signature, secret)?;
    
    if !is_valid {
        return Err("Invalid webhook signature".into());
    }
    
    let webhook_event = WebhookModule::parse_webhook(payload)?;
    
    match webhook_event.event_type {
        tapsilat::WebhookEventType::OrderCompleted => {
            println!("Order completed: {:?}", webhook_event.data.order_id);
            // Process successful payment
        }
        tapsilat::WebhookEventType::OrderFailed => {
            println!("Order failed: {:?}", webhook_event.data.order_id);
            // Handle failed payment
        }
        _ => {}
    }
    
    Ok(())
}

Payment Term Management

Create Installment Plan

use tapsilat::CreateInstallmentPlanRequest;

let installment_request = CreateInstallmentPlanRequest {
    order_id: "order-id".to_string(),
    installment_count: 6,
    first_installment_date: "2024-12-31".to_string(),
};

let plan = client.installments().create_plan(installment_request)?;
println!("Installment plan created: {:?}", plan);

Validation Utilities

GSM Number Validation

use tapsilat::Validators;

// Validate and normalize Turkish GSM numbers
let gsm_result = Validators::validate_gsm("0555 123 45 67")?;
println!("Normalized GSM: {}", gsm_result); // "905551234567"

// Supports multiple formats
let formats = vec![
    "0555 123 45 67",  // National format
    "555 123 45 67",   // Local format  
    "5551234567",      // No formatting
    "+905551234567",   // International format
];

for gsm in formats {
    match Validators::validate_gsm(gsm) {
        Ok(normalized) => println!("{} -> {}", gsm, normalized),
        Err(e) => eprintln!("Invalid GSM {}: {}", gsm, e),
    }
}

Installments Validation

// Validate installment counts
let valid_installments = vec![1, 3, 6, 12];
for count in valid_installments {
    match Validators::validate_installments(count) {
        Ok(_) => println!("{} installments: Valid", count),
        Err(e) => eprintln!("{} installments: {}", count, e),
    }
}

Email and Amount Validation

// Email validation
Validators::validate_email("user@example.com")?;

// Amount validation (currency precision)
Validators::validate_amount(99.99)?;

// Turkish identity number validation
Validators::validate_identity_number("12345678901")?;

Advanced Configuration

The SDK can be customized with various configuration options:

use tapsilat::Config;

let config = Config::new("your-bearer-token")
    .with_base_url("https://panel.tapsilat.dev/api/v1")
    .with_timeout(30); // 30 seconds

let client = TapsilatClient::new(config)?;

Authentication

Use Bearer Token authentication:

// Simple initialization
let client = TapsilatClient::from_api_key("your-bearer-token")?;

// Or via environment variable
use std::env;
let api_key = env::var("TAPSILAT_BEARER_TOKEN")?;
let client = TapsilatClient::from_api_key(api_key)?;

Get your API token from the Tapsilat Dashboard → Settings → API Keys

License

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

Resources

• Website: https://tapsilat.dev
• Issues: GitHub Issues
• Examples: See examples/advanced_usage.rs for a complete implementation

Type System

All Rust types are organized in src/types/ with comprehensive documentation including:

• Strong compile-time type safety
• Zero-cost abstractions
• Memory safety guarantees
• Comprehensive error handling with Result types