Go SDK

Go SDK

Official Go SDK for the Islamic Open Finance™ API.

::: caution Preview Release The Go SDK is in preview and under active development. The API may change before the stable 1.0 release. Subscribe to our GitHub Discussions for release announcements. :::

Installation

go get github.com/Islamic-Open-Finance/iof-go

Quick Start

package main

import (
    "context"
    "fmt"
    "github.com/Islamic-Open-Finance/iof-go"
)

func main() {
    client := iof.NewClient("iof_sk_live_...")

    contract, err := client.Contracts.Create(context.Background(), &iof.ContractCreateParams{
        Type: iof.String("MURABAHA"),
        Counterparty: &iof.CounterpartyParams{
            ID: iof.String("cpty_123"),
        },
        Terms: &iof.TermsParams{
            Amount: iof.Int64(50000),
            Currency: iof.String("USD"),
        },
    })

    if err != nil {
        panic(err)
    }

    fmt.Printf("Created contract: %s\n", contract.ID)
}

Configuration

client := iof.NewClient(
    "iof_sk_live_...",
    iof.WithBaseURL("https://api.islamicopenfinance.com"),
    iof.WithTimeout(30 * time.Second),
)

Working with Contracts

Create

contract, err := client.Contracts.Create(ctx, &iof.ContractCreateParams{
    Type: iof.String("MURABAHA"),
    // ...
})

Retrieve

contract, err := client.Contracts.Get(ctx, "contract_123")

List

iter := client.Contracts.List(&iof.ContractListParams{
    Status: iof.String("active"),
    Limit:  iof.Int64(20),
})

for iter.Next() {
    contract := iter.Contract()
    fmt.Println(contract.ID)
}

if err := iter.Err(); err != nil {
    panic(err)
}

Error Handling

contract, err := client.Contracts.Create(ctx, params)
if err != nil {
    if iofErr, ok := err.(*iof.Error); ok {
        fmt.Printf("IOF error: %s (code: %s)\n", iofErr.Message, iofErr.Code)

        if iofErr.Code == "VALIDATION_ERROR" {
            for _, detail := range iofErr.Details {
                fmt.Printf("  %s: %s\n", detail.Field, detail.Message)
            }
        }
    }
    return
}

Webhooks

import "github.com/Islamic-Open-Finance/iof-go/webhook"

func webhookHandler(w http.ResponseWriter, r *http.Request) {
    payload, err := io.ReadAll(r.Body)
    if err != nil {
        http.Error(w, err.Error(), http.StatusBadRequest)
        return
    }

    event, err := webhook.ConstructEvent(
        payload,
        r.Header.Get("X-IOF-Signature"),
        os.Getenv("WEBHOOK_SECRET"),
    )
    if err != nil {
        http.Error(w, "Invalid signature", http.StatusUnauthorized)
        return
    }

    switch event.Type {
    case "contract.created":
        var contract iof.Contract
        json.Unmarshal(event.Data.Raw, &contract)
        // Handle contract created
    }

    w.WriteHeader(http.StatusOK)
}

Requirements

• Go 1.21+

Next Steps

• Error Handling - Error patterns
• Pagination - List operations
• API Reference - All endpoints