Go SDK

Official Go SDK for the Islamic Open Finance™ API.

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"),
        "whsec_...",
    )
    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