SDK Go da Didit para KYC, AML e transações

A versão oficial do Didit para Go. Requer Go 1.22 ou superior e usa apenas a biblioteca padrão. Consulte a visão geral dos SDKs para 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 é o github.com/didit-protocol/sdk-go no pkg.go.dev. O código-fonte e o registo de alterações estão em didit-protocol/sdk-go no GitHub. O pacote chama-se didit. Os webhooks estão em github.com/didit-protocol/sdk-go/webhook, o pacote Authentication em .../authentication e as opções do cliente em .../option. O exemplo de cada página da referência da API é o corpo de uma função: usa context, fmt e log da biblioteca padrão e este módulo.

Configurar o cliente

didit.NewClient() lê DIDIT_API_KEY a partir do ambiente. Passe opções para a substituir, ou para definir os identificadores da organização e da aplicação de que precisam as chamadas com âmbito de aplicação (casos, redes, relatórios regulamentares). Qualquer opção também funciona numa ú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 do pedido são valores didit.Opt: defina-os com didit.String, didit.Int, didit.Bool, didit.Float ou didit.Some, ou deixe-os de fora para não enviar nada.

Criar uma sessão

Crie uma sessão de verificação para um fluxo e envie o seu utilizador para o respetivo 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)
}

Ler a decisão

Quando o utilizador terminar (ou quando o webhook chegar), leia a decisão. Cada resultado de funcionalidade é 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 do corpo bruto e os cabeçalhos do pedido. webhook.Verify devolve um *didit.WebhookVerificationError para qualquer entrega que não seja válida e recente, e um evento tipificado nos restantes casos.

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 substitui o segredo, adicione o antigo com webhook.WithSecrets. Consulte Webhooks para ver os eventos e o esquema de assinatura.

Triar uma transação

Envie um pagamento, um levantamento ou uma transferência de criptoativos para a monitorização de transações; a resposta inclui o respetivo estado 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, no seu backend, os tokens de acesso que o emissor da sua Authentication assina, sem chamar a Didit em cada pedido. Também troca códigos, atualiza tokens, verifica e revoga sessões e executa step-ups.

A verificação de tokens faz as validações 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 ficheiros

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 de Go

A versão 1.0.1 do SDK de Go foi gerada antes de estes endpoints serem adicionados à API, por isso não tem método para eles e as respetivas páginas não têm exemplo em Go:

Validar um endereço
Eliminar transações em lote
Redes Travel Rule: obter as redes, pedir acesso a uma rede e obter, guardar ou submeter o questionário da rede
Comprovativos de carteira Travel Rule: listar os comprovativos de carteira por captura de ecrã e aprovar ou rejeitar um
Google Wallet, que ainda não existe em nenhuma versão 1.0.1: iniciar uma verificação Google Wallet e submeter uma resposta de carteira

Também não consegue enviar estes campos de pedido mais recentes:

biometric_consent, tags e user_state ao criar uma sessão
biometric_consent_mode ao atualizar a configuração do webhook
beneficiary_vasp ao atualizar uma transferência Travel Rule
confirm_delete, necessário para eliminar um relatório finalizado
os 16 campos mais recentes da Validação de base de dados, que nenhuma versão 1.0.1 inclui

Até que uma versão posterior do SDK de Go os adicione, chame estes endpoints por HTTP, tal como mostra o pedido cURL de cada página. Todas as outras páginas de endpoints do servidor na referência da API têm um exemplo em Go para a respetiva operação.

Guias

Autenticação

Model Context Protocol (MCP)

SDKs web

SDKs nativos

SDKs de servidor

Integrações

SDK Go da Didit para KYC, AML e transações

Instalação

Configurar o cliente

Criar uma sessão

Ler a decisão

Verificar um webhook

Triar uma transação

Verificar tokens de Authentication

Erros

Listas e ficheiros

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

​Instalação

​Configurar o cliente

​Criar uma sessão

​Ler a decisão

​Verificar um webhook

​Triar uma transação

​Verificar tokens de Authentication

​Erros

​Listas e ficheiros

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

Instalação

Configurar o cliente

Criar uma sessão

Ler a decisão

Verificar um webhook

Triar uma transação

Verificar tokens de Authentication

Erros

Listas e ficheiros

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