Go SDK

Our Go SDK offers a lightweight, concurrent implementation with strong typing and comprehensive error handling. Built with idiomatic Go practices in mind, it provides a clean API for interacting with Cari Finance services.

Installation

Install the SDK using Go modules:

go get github.com/carihq/cari-finance-go

Basic usage

package main

import (
    "fmt"
    "log"

    cari "github.com/carihq/cari-finance-go"
)

func main() {
    // Initialize with your API key
    client := cari.New("sk_test_51NzaWTBOIWoX8E7wnMd1...")

    // The SDK will automatically detect if you're using a test or live key
}

Creating charges

You can create a new charge for a single payment:

// Create charge parameters
params := &cari.ChargeParams{
    Amount:      2000, // Amount in cents (e.g., $20.00)
    Currency:    "usd",
    Provider:    "card",
    Card: &cari.CardParams{
        Token: "tok_visa", // Token obtained from the client-side SDK
    },
    Description: "Payment for order #123",
    Customer: &cari.CustomerParams{
        Name:  "John Doe",
        Email: "john.doe@example.com",
    },
}

// Create a charge
charge, err := client.Charges.Create(params)
if err != nil {
    log.Fatalf("Error creating charge: %v", err)
}

// Check if charge was successful
if charge.Status == "succeeded" {
    // Payment was successful
    fmt.Printf("Payment successful! Charge ID: %s\n", charge.ID)
} else {
    // Payment failed
    fmt.Printf("Payment failed: %s\n", charge.FailureMessage)
}

Working with customers

You can create and manage customers:

// Create a new customer
customerParams := &cari.CustomerParams{
    Name:  "Jane Smith",
    Email: "jane.smith@example.com",
    Phone: "+18765551234",
    Address: &cari.AddressParams{
        Line1:   "123 Main St",
        City:    "Roseau",
        Country: "DM",
    },
}

customer, err := client.Customers.Create(customerParams)
if err != nil {
    log.Fatalf("Error creating customer: %v", err)
}

// Retrieve a customer
customer, err = client.Customers.Get("cus_12345")
if err != nil {
    log.Fatalf("Error retrieving customer: %v", err)
}

// Update a customer
updateParams := &cari.CustomerParams{
    Phone: "+18765559876",
}
customer, err = client.Customers.Update("cus_12345", updateParams)
if err != nil {
    log.Fatalf("Error updating customer: %v", err)
}

// Delete a customer
err = client.Customers.Delete("cus_12345")
if err != nil {
    log.Fatalf("Error deleting customer: %v", err)
}

// List customers
listParams := &cari.CustomerListParams{
    Limit: 10,
    Email: "jane.smith@example.com",
}
customers, err := client.Customers.List(listParams)
if err != nil {
    log.Fatalf("Error listing customers: %v", err)
}

// Iterate through customers
for _, c := range customers.Data {
    fmt.Printf("Customer: %s, Email: %s\n", c.Name, c.Email)
}

Concurrency

The Go SDK is designed to handle concurrent requests efficiently, making it ideal for high-throughput applications:

package main

import (
    "fmt"
    "sync"

    cari "github.com/carihq/cari-finance-go"
)

func main() {
    client := cari.New("sk_test_51NzaWTBOIWoX8E7wnMd1...")

    // Process multiple charges concurrently
    var wg sync.WaitGroup

    // Create a channel to collect results
    results := make(chan *cari.Charge, 10)
    errors := make(chan error, 10)

    // Process 10 charges concurrently
    for i := 0; i < 10; i++ {
        wg.Add(1)
        go func(orderID int) {
            defer wg.Done()

            params := &cari.ChargeParams{
                Amount:      1000 + uint64(orderID*100),
                Currency:    "usd",
                Provider:    "card",
                Card: &cari.CardParams{
                    Token: "tok_visa",
                },
                Description: fmt.Sprintf("Payment for order #%d", orderID),
            }

            charge, err := client.Charges.Create(params)
            if err != nil {
                errors <- err
                return
            }

            results <- charge
        }(i)
    }

    // Wait for all goroutines to complete
    go func() {
        wg.Wait()
        close(results)
        close(errors)
    }()

    // Collect and process results
    for charge := range results {
        fmt.Printf("Processed charge: %s, Amount: %d\n", charge.ID, charge.Amount)
    }

    // Handle any errors
    for err := range errors {
        fmt.Printf("Error processing charge: %v\n", err)
    }
}

Error handling

The SDK provides specific error types to handle different error scenarios:

package main

import (
    "fmt"
    "log"

    cari "github.com/carihq/cari-finance-go"
)

func main() {
    client := cari.New("sk_test_51NzaWTBOIWoX8E7wnMd1...")

    params := &cari.ChargeParams{
        Amount:   2000,
        Currency: "usd",
        // Missing required fields...
    }

    charge, err := client.Charges.Create(params)
    if err != nil {
        switch e := err.(type) {
        case *cari.CardError:
            // Card-related errors (e.g., declined card)
            fmt.Printf("Card error: %s (Code: %s)\n", e.Message, e.Code)

        case *cari.ValidationError:
            // Validation errors (e.g., missing required fields)
            fmt.Printf("Validation error: %s\n", e.Message)

        case *cari.AuthenticationError:
            // Authentication errors (e.g., invalid API key)
            fmt.Printf("Authentication error: %s\n", e.Message)

        case *cari.APIError:
            // API errors (e.g., server errors)
            fmt.Printf("API error: %s\n", e.Message)

        case *cari.RateLimitError:
            // Rate limit errors
            fmt.Printf("Rate limit error: %s\n", e.Message)

        default:
            // Other errors
            fmt.Printf("Unknown error: %v\n", err)
        }

        return
    }

    fmt.Printf("Charge created: %s\n", charge.ID)
}

Additional resources

For more detailed information about the Go SDK, refer to these resources:

Official libraries

PHP

Our PHP SDK provides a fluent interface to the Cari Finance API, with support for Laravel and other PHP frameworks.

Documentation

Ruby

The Ruby SDK includes built-in support for Rails applications and comes with comprehensive documentation and examples.

Documentation

Node.js

Our Node.js SDK provides Promise-based methods for all API endpoints and TypeScript definitions for better development experience.

Documentation

Python

The Python SDK supports both synchronous and asynchronous operations, with Django integration and comprehensive test coverage.

Documentation

Go

Our Go SDK offers a lightweight, concurrent implementation with strong typing and comprehensive error handling.

Documentation