Go Integration

Install the official Plaidly Go SDK:

Not yet published to the package registry

github.com/plaidly/plaidly-go has no tagged release yet — pin to a branch or commit until a semver tag ships.

go get github.com/plaidly/plaidly-go@main

Once a tagged release ships, the intended install command will be:

go get github.com/plaidly/plaidly-go

Initialize the client

import (
    "os"

    plaidly "github.com/plaidly/plaidly-go"
)

client, err := plaidly.NewClient(os.Getenv("PLAIDLY_API_KEY"))
if err != nil {
    return err
}

Create and poll a payment session

session, err := client.CreatePaymentSession(ctx, plaidly.CreatePaymentSessionRequest{
    Amount:    10.0,
    ExpiresIn: "15m",
    PaymentMethod: plaidly.PaymentMethod{
        MethodID: plaidly.MethodIDCrypto,
        Chain:    "solana",
        Token:    "USDC",
        Network:  "mainnet",
    },
    Metadata: map[string]any{
        "order_id": "ord_123",
    },
})
if err != nil {
    return fmt.Errorf("create session: %w", err)
}

log.Println(session.Address)

latest, err := client.GetPaymentSession(ctx, session.SessionId)
if err != nil {
    return err
}
log.Println(latest.Status)

Sandbox onboarding

demo, err := client.CreateDemoPaymentSession(ctx)
if err != nil {
    return err
}

done, err := client.SimulatePayment(ctx, demo.SessionId)
if err != nil {
    return err
}

receipt, settled, err := plaidly.GetSessionReceiptIfSettled(ctx, client, done.SessionId)
if err != nil {
    return err
}

log.Printf("session=%s receipt-bytes=%d", settled.SessionId, len(receipt))

Verify webhooks

import (
    "io"
    "net/http"

    plaidly "github.com/plaidly/plaidly-go"
)

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

    signature := r.Header.Get(plaidly.SignatureHeader)
    event, err := plaidly.VerifyWebhook(
        rawBody,
        signature,
        os.Getenv("PLAIDLY_WEBHOOK_SECRET"),
        plaidly.DefaultWebhookTolerance,
    )
    if err != nil {
        http.Error(w, "invalid signature", http.StatusBadRequest)
        return
    }

    if event.EventType == plaidly.EventPaymentCompleted {
        if err := fulfillOrder(r.Context(), event.SessionID); err != nil {
            log.Printf("fulfill order: %v", err)
        }
    }

    w.WriteHeader(http.StatusOK)
}

Agent example flows

The Go example in plaidly-go/examples/agent_integration.go covers merchant registration, sandbox simulation, receipt lookup, and webhook verification.

Error handling

import "github.com/plaidly/plaidly-go"

session, err := client.CreatePaymentSession(ctx, req)
if err != nil {
    var apiErr *plaidly.Error
    if errors.As(err, &apiErr) {
        log.Printf("API error %d: %s (code: %s)", apiErr.StatusCode, apiErr.Message, apiErr.Code)
    }
    return err
}

Context and timeouts

All SDK calls accept a context.Context:

ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()

session, err := client.CreatePaymentSession(ctx, req)

Go Integration

On this page