Go SDK for KYC, AML and Transactions

The official Didit module for Go. It needs Go 1.22 or later and uses only the standard library. See the server SDKs overview for what every SDK shares.

Install

go get github.com/didit-protocol/sdk-go

The module is github.com/didit-protocol/sdk-go on pkg.go.dev. Its source and changelog are in didit-protocol/sdk-go on GitHub. The package is named didit. Webhooks live in github.com/didit-protocol/sdk-go/webhook, Authentication in .../authentication and client options in .../option. The sample on each API reference page is the body of a function: it uses context, fmt and log from the standard library and this module.

Configure the client

didit.NewClient() reads DIDIT_API_KEY from the environment. Pass options to override it, or to set the organization and application ids that application-scoped calls (cases, networks, regulatory reports) need. Any option also works on a single call.

package main

import (
	"context"
	"fmt"
	"log"
	"os"
	"time"

	"github.com/didit-protocol/sdk-go"
	"github.com/didit-protocol/sdk-go/option"
)

func main() {
	client := didit.NewClient(
		option.WithAPIKey(os.Getenv("DIDIT_API_KEY")),
		option.WithOrganizationID(os.Getenv("DIDIT_ORGANIZATION_ID")),
		option.WithApplicationID(os.Getenv("DIDIT_APPLICATION_ID")),
		option.WithTimeout(30*time.Second),
		option.WithMaxRetries(2),
	)

	// Options for a single call.
	decision, err := client.Sessions.RetrieveDecision(context.Background(), "11111111-2222-3333-4444-555555555555",
		didit.SessionsRetrieveDecisionParams{}, option.WithTimeout(5*time.Second))
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(decision.Status)
}

Optional request fields are didit.Opt values: set them with didit.String, didit.Int, didit.Bool, didit.Float or didit.Some, and leave them out to send nothing.

Create a session

Create a verification session for a workflow and send your user to its URL.

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/didit-protocol/sdk-go"
)

func main() {
	client := didit.NewClient()

	session, err := client.Sessions.Create(context.Background(), didit.SessionsCreateParams{
		WorkflowID: "11111111-2222-3333-4444-555555555555",
		VendorData: didit.String("user-123"),
		Callback:   didit.String("https://example.com/verification/done"),
	})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(session.URL)
}

Read the decision

When the user finishes (or when the webhook arrives), read the decision. Every feature result is a slice with one entry per workflow node.

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/didit-protocol/sdk-go"
)

func main() {
	client := didit.NewClient()

	decision, err := client.Sessions.RetrieveDecision(context.Background(), "11111111-2222-3333-4444-555555555555",
		didit.SessionsRetrieveDecisionParams{})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(decision.Status)
	for _, verification := range decision.IDVerifications {
		fmt.Println(verification.Status)
	}
}

Verify a webhook

Pass the raw body bytes and the request headers. webhook.Verify returns a *didit.WebhookVerificationError for anything that is not a valid, fresh delivery, and a typed event otherwise.

package main

import (
	"errors"
	"fmt"
	"io"
	"log"
	"net/http"
	"os"

	"github.com/didit-protocol/sdk-go"
	"github.com/didit-protocol/sdk-go/webhook"
)

func main() {
	secret := os.Getenv("DIDIT_WEBHOOK_SECRET")
	http.HandleFunc("POST /webhooks/didit", func(w http.ResponseWriter, r *http.Request) {
		body, err := io.ReadAll(http.MaxBytesReader(w, r.Body, 1<<20))
		if err != nil {
			http.Error(w, "bad body", http.StatusBadRequest)
			return
		}
		event, err := webhook.Verify(body, r.Header, secret)
		var invalid *didit.WebhookVerificationError
		if errors.As(err, &invalid) {
			http.Error(w, string(invalid.Reason), http.StatusBadRequest)
			return
		} else if err != nil {
			http.Error(w, "error", http.StatusInternalServerError)
			return
		}
		if e, ok := event.(*webhook.StatusUpdatedEvent); ok {
			fmt.Println(e.SessionID, e.Status)
		}
		w.WriteHeader(http.StatusOK)
	})
	log.Fatal(http.ListenAndServe(":8080", nil))
}

While you rotate the secret, add the old one with webhook.WithSecrets. See Webhooks for the events and the signature scheme.

Screen a transaction

Submit a payment, withdrawal or crypto transfer to transaction monitoring; the response carries its status and risk score.

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/didit-protocol/sdk-go"
)

func main() {
	client := didit.NewClient()

	transaction, err := client.Transactions.Create(context.Background(), didit.TransactionsCreateParams{
		TransactionID:       "txn-1001",
		TransactionCategory: "finance",
		TransactionDetails: didit.TransactionsCreateParamsTransactionDetails{
			Direction: "outbound",
			Amount:    1500,
			Currency:  "EUR",
		},
		Subject: didit.TransactionsCreateParamsSubject{
			EntityType: didit.String("individual"),
			VendorData: "user-123",
			FullName:   "Maria Garcia",
		},
	})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(transaction.Status, transaction.Score)
}

Verify Authentication tokens

The authentication package checks the access tokens your Authentication issuer signs, in your backend, without calling Didit for each request. It also exchanges codes, refreshes tokens, checks and revokes sessions, and runs step-ups.

Token verification makes the checks in Verify a token on your server, against your application’s issuer and signing keys.

package main

import (
	"context"
	"errors"
	"fmt"
	"log"

	"github.com/didit-protocol/sdk-go"
	"github.com/didit-protocol/sdk-go/authentication"
)

func main() {
	// The publishable key (pk_live_... or pk_test_...) carries your issuer URL.
	auth, err := authentication.NewFromPublishableKey("pk_live_...", authentication.WithClientID("your-application-id"))
	if err != nil {
		log.Fatal(err)
	}

	claims, err := auth.VerifyAccessToken(context.Background(), "the bearer token")
	var invalid *didit.TokenVerificationError
	if errors.As(err, &invalid) {
		fmt.Println("rejected:", invalid.Reason)
		return
	} else if err != nil {
		log.Fatal(err)
	}
	fmt.Println(claims.Subject)
}

Errors

package main

import (
	"context"
	"errors"
	"fmt"

	"github.com/didit-protocol/sdk-go"
)

func main() {
	client := didit.NewClient()

	_, err := client.Sessions.RetrieveDecision(context.Background(), "11111111-2222-3333-4444-555555555555",
		didit.SessionsRetrieveDecisionParams{})
	var notFound *didit.NotFoundError
	var status *didit.APIStatusError
	switch {
	case errors.As(err, &notFound):
		fmt.Println("no such session")
	case errors.As(err, &status):
		fmt.Println(status.StatusCode, status.RequestID, status.Body)
	case err != nil:
		fmt.Println("no response:", err)
	}
}

Lists and files

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/didit-protocol/sdk-go"
)

func main() {
	ctx := context.Background()
	client := didit.NewClient()

	// Lists page through every result.
	iter := client.Sessions.ListAutoPaging(ctx, didit.SessionsListParams{Status: didit.String("Approved")})
	for iter.Next() {
		fmt.Println(iter.Current().SessionID)
	}
	if err := iter.Err(); err != nil {
		log.Fatal(err)
	}

	// Uploads take didit.FileFromPath, FileFromBytes or FileFromReader.
	result, err := client.IDVerification.Verify(ctx, didit.IDVerificationVerifyParams{
		FrontImage: didit.FileFromPath("id-front.jpg"),
		BackImage:  didit.Some(didit.FileFromPath("id-back.jpg")),
	})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(result.IDVerification.Status)
}

Endpoints not in the Go SDK yet

Go 1.0.1 was generated before these endpoints were added to the API, so it has no method for them and their pages have no Go sample:

Validate an address
Batch delete transactions
Travel Rule networks: get the networks, request access to a network, and get, save or submit the network questionnaire
Travel Rule wallet proofs: list the screenshot wallet proofs and approve or reject one
Google Wallet, which no 1.0.1 release has yet: start a Google Wallet verification and submit a wallet response

It also cannot send these newer request fields:

biometric_consent, tags and user_state when it creates a session
biometric_consent_mode when it updates the webhook configuration
beneficiary_vasp when it updates a Travel Rule transfer
confirm_delete, which deleting a finalized report needs
the 16 newer Database Validation fields that no 1.0.1 release has

Until a later Go release adds them, call these over HTTP as each page’s cURL request shows. Every other server endpoint page of the API reference has a Go sample for its operation.

Guides

Authentication

Model Context Protocol (MCP)

Web SDKs

Native SDKs

Server SDKs

Integrations

Go SDK for KYC, AML and Transactions

Install

Configure the client

Create a session

Read the decision

Verify a webhook

Screen a transaction

Verify Authentication tokens

Errors

Lists and files

Endpoints not in the Go SDK yet

​Install

​Configure the client

​Create a session

​Read the decision

​Verify a webhook

​Screen a transaction

​Verify Authentication tokens

​Errors

​Lists and files

​Endpoints not in the Go SDK yet

Install

Configure the client

Create a session

Read the decision

Verify a webhook

Screen a transaction

Verify Authentication tokens

Errors

Lists and files

Endpoints not in the Go SDK yet