Kintsugi Java Transaction Creation Demo

A practical demonstration of creating tax transactions using the Kintsugi Tax Platform Java SDK. This project shows how to integrate with Kintsugi's API to programmatically create sales transactions with proper tax calculations.

Overview

This application demonstrates the complete workflow for creating a transaction through the Kintsugi Tax Platform. It handles authentication, transaction data construction, API communication, and response processing. The implementation follows the official SDK documentation and includes all necessary fields for accurate tax calculation.

Features

• Complete transaction creation workflow
• Proper authentication with Kintsugi's security model
• Comprehensive transaction data mapping
• Address and customer information handling
• Tax calculation field management
• Error handling and response parsing
• Production-ready code patterns

Prerequisites

• Java 17 or higher
• Gradle (wrapper included)
• Kintsugi Tax Platform account with API access
• Valid API key and organization ID

Project Structure

kintsugi-java-creation-demo/
├── app/
│   ├── build.gradle.kts          # Build configuration
│   └── src/
│       ├── main/kotlin/
│       │   └── com/kintsugi/demo/
│       │       └── App.kt         # Main application
│       └── test/kotlin/
│           └── com/kintsugi/demo/
│               └── AppTest.kt     # Basic tests
├── gradle/                       # Gradle wrapper files
└── README.md                     # This file

Setup

1. Clone the repository

   git clone <repository-url>
   cd kintsugi-java-creation-demo

2. Configure your credentials

   Open app/src/main/kotlin/com/kintsugi/demo/App.kt and replace the placeholder values:

   .apiKeyHeader("your-api-key-here")
   .customHeader("your-organization-id-here")

   Also update the organization ID references in the transaction data:

   .organizationId("your-organization-id-here")

3. Build the project

   ./gradlew build

Usage

Run the application to create a sample transaction:

./gradlew run

The application will:

1. Initialize the Kintsugi SDK with your credentials
2. Construct a transaction with sample data
3. Send the request to Kintsugi's API
4. Display the results

Sample Output

Starting Kintsugi Transaction Creation Demo...
Creating transaction with external ID: REV-DEMO-001
Transaction created successfully!
   Transaction ID: txn_abc123xyz789
   External ID: REV-DEMO-001
   Status: COMMITTED
   Total Amount: $99.0
Demo completed!

Configuration

Transaction Data

The demo creates a transaction with the following sample data:

• Product: Formal Dress ($99.00)
• Customer: Demo Customer
• Address: 333 N Main St, Cedar City, UT 84721
• Tax Amount: $6.75
• Transaction Type: Sale
• Status: Committed

Modifying the Transaction

To customize the transaction data, edit the transaction builder in App.kt:

val transactionRequest = TransactionPublicRequest.builder()
    .externalId("your-external-id")
    .totalAmount(yourAmount)
    .addresses(java.util.List.of(
        TransactionAddressPublic.builder()
            .street1("your address")
            .city("your city")
            // ... other fields
    ))
    // ... other transaction details

Important Implementation Notes

Numeric Field Requirements

This implementation explicitly sets numeric values for all tax-related fields to avoid serialization issues with the Speakeasy-generated SDK:

.totalAmount(99.0)
.totalTaxAmountImported(6.75)
.totalTaxAmountCalculated(6.75)
.taxRateImported(0.0681)
.taxRateCalculated(0.0681)

Authentication

The SDK uses two authentication headers:

• x-api-key: Your Kintsugi API key
• x-organization-id: Your organization identifier

Both are configured through the Security builder pattern.

Dependencies

• Kotlin: JVM-based implementation
• Kintsugi Tax Platform Java SDK: Version 0.10.0
• Java: Version 17 toolchain
• Gradle: Build automation

Error Handling

The application includes comprehensive error handling for:

• Authentication failures
• Network connectivity issues
• Invalid transaction data
• API response errors
• Serialization problems

Development

Running Tests

./gradlew test

Building for Production

./gradlew build

The compiled application will be available in app/build/.

API Reference

This implementation follows the official Kintsugi Java SDK documentation. For detailed API information, refer to:

• Kintsugi Java SDK Documentation
• Transaction Creation Guide

Troubleshooting

Common Issues

Authentication Errors

• Verify your API key is correct and has proper permissions
• Ensure your organization ID matches your account

Serialization Errors

• Make sure all numeric fields are set with explicit Double values
• Check that date formats include proper timezone information

Network Issues

• Confirm network connectivity to Kintsugi's API endpoints
• Check for firewall or proxy restrictions

License

This demo project is provided as-is for educational and integration purposes. Please refer to Kintsugi's terms of service for API usage guidelines.

Support

For issues related to:

• This demo: Create an issue in this repository
• Kintsugi SDK: Refer to the official SDK repository
• Kintsugi API: Contact Kintsugi support through their official channels