SDK Go para KYC, AML e Transações

O módulo oficial da Didit para Go. Ele exige Go 1.22 ou superior e usa apenas a biblioteca padrão. Consulte a visão geral dos SDKs de servidor para ver o que todos os SDKs têm em comum.

Instalação

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

O módulo é github.com/didit-protocol/sdk-go no pkg.go.dev. O código-fonte e o changelog estão em didit-protocol/sdk-go no GitHub. O pacote se chama didit. Os webhooks ficam em github.com/didit-protocol/sdk-go/webhook, a autenticação em .../authentication e as opções do cliente em .../option. O exemplo em cada página da referência da API é o corpo de uma função: ele usa context, fmt e log da biblioteca padrão e este módulo.

Configurar o cliente

didit.NewClient() lê DIDIT_API_KEY do ambiente. Passe opções para substituí-la ou para definir os IDs da organização e da aplicação de que as chamadas no escopo da aplicação precisam (casos, redes, relatórios regulatórios). Qualquer opção também funciona em uma única chamada.

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)
}

Os campos opcionais da requisição são valores didit.Opt: defina-os com didit.String, didit.Int, didit.Bool, didit.Float ou didit.Some e omita-os para não enviar nada.

Criar uma sessão

Crie uma sessão de verificação para um workflow e envie seu usuário para a URL dela.

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)
}

Ler a decisão

Quando o usuário terminar (ou quando o webhook chegar), leia a decisão. O resultado de cada recurso é um slice com uma entrada por nó do fluxo.

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)
	}
}

Verificar um webhook

Passe os bytes brutos do corpo e os cabeçalhos da requisição. webhook.Verify retorna um *didit.WebhookVerificationError para tudo o que não for uma entrega válida e recente e, caso contrário, um evento tipado.

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))
}

Enquanto você faz a rotação do segredo, adicione o antigo com webhook.WithSecrets. Consulte Webhooks para ver os eventos e o esquema de assinatura.

Analisar uma transação

Envie um pagamento, um saque ou uma transferência de criptoativos para o monitoramento de transações; a resposta traz o status e a pontuação de risco.

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)
}

Verificar tokens de Authentication

O pacote authentication verifica os tokens de acesso que o seu emissor de Authentication assina, no seu backend, sem chamar a Didit a cada requisição. Ele também troca códigos, renova tokens, verifica e revoga sessões e executa step-ups.

A verificação de tokens faz as checagens descritas em Verificar um token no seu servidor, com base no emissor e nas chaves de assinatura da sua aplicação.

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)
}

Erros

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)
	}
}

Listas e arquivos

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 que ainda não estão no SDK para Go

O SDK Go 1.0.1 foi gerado antes de estes endpoints serem adicionados à API, então ele não tem método para eles e as páginas deles não têm exemplo em Go:

Validar um endereço
Excluir transações em lote
Redes de Travel Rule: obter as redes, solicitar acesso a uma rede e obter, salvar ou enviar o questionário da rede
Comprovações de carteira da Travel Rule: listar as comprovações de carteira por captura de tela e aprovar ou rejeitar uma delas
Google Wallet, que ainda não está disponível em nenhuma versão 1.0.1: iniciar uma verificação com Google Wallet e enviar uma resposta da carteira

Ele também não consegue enviar estes campos de requisição mais recentes:

biometric_consent, tags e user_state quando cria uma sessão
biometric_consent_mode quando atualiza a configuração de webhook
beneficiary_vasp quando atualiza uma transferência de Travel Rule
confirm_delete, necessário para excluir um relatório finalizado
os 16 campos mais recentes de Validação de banco de dados que nenhuma versão 1.0.1 tem

Até que uma versão posterior para Go os adicione, chame esses endpoints via HTTP como mostra a requisição cURL de cada página. Todas as outras páginas de endpoints de servidor da referência da API têm um exemplo em Go para a operação correspondente.

Guias

Autenticação

Model Context Protocol (MCP)

SDKs web

SDKs nativos

SDKs de servidor

Integrações

SDK Go para KYC, AML e Transações

Instalação

Configurar o cliente

Criar uma sessão

Ler a decisão

Verificar um webhook

Analisar uma transação

Verificar tokens de Authentication

Erros

Listas e arquivos

Endpoints que ainda não estão no SDK para Go

​Instalação

​Configurar o cliente

​Criar uma sessão

​Ler a decisão

​Verificar um webhook

​Analisar uma transação

​Verificar tokens de Authentication

​Erros

​Listas e arquivos

​Endpoints que ainda não estão no SDK para Go

Instalação

Configurar o cliente

Criar uma sessão

Ler a decisão

Verificar um webhook

Analisar uma transação

Verificar tokens de Authentication

Erros

Listas e arquivos

Endpoints que ainda não estão no SDK para Go