moov

README

moov-go

A complete, production-grade Go client for the Moov API, structured with Domain-Driven Design — each API resource group is its own package with explicit types and a Service struct, with only moov.go in the root acting as the façade entry point.

Zero external runtime dependencies. Go 1.25.

---

Project structure

moov-go/
├── moov.go                    ← only .go file in root: Client, New(), all option funcs
│
├── types/                     ← shared primitives (Amount, Address, TransferSource…)
├── errors/                    ← public APIError type + IsNotFound/IsTransient helpers
├── webhook/                   ← HMAC-SHA512 signature verification + event parsing
│
├── internal/
│   └── httpclient/            ← HTTP engine (not part of public API)
│       ├── client.go          ← Do / DoRaw / UploadFile + auth + retry
│       ├── options.go         ← Option / RequestOption functional options
│       ├── retry.go           ← exponential backoff with full jitter
│       ├── idempotency.go     ← UUID v4 via crypto/rand
│       └── query.go           ← reflect-based URL query encoder
│
├── accounts/                  ← bounded context: Moov accounts
├── capabilities/
├── representatives/
├── underwriting/
├── billing/
├── files/
├── onboarding/
├── resolution/
├── partner/
├── bankaccounts/              ← bounded context: sources
├── cards/
├── applepay/
├── googlepay/
├── paymentmethods/
├── terminal/
├── wallets/
├── transfers/                 ← bounded context: money movement
├── sweeps/
├── refunds/
├── disputes/
├── issuing/
├── invoices/
├── paymentlinks/
├── receipts/
├── schedules/
├── images/                    ← bounded context: account tools
├── products/
├── support/
├── branding/                  ← bounded context: enrichment
├── enrichment/
├── institutions/
├── auth/                      ← bounded context: authentication
├── e2ee/
└── ping/

Installation

go get github.com/fintech-sdk/moov-go

Quick start

import (
    "github.com/fintech-sdk/moov-go"
    "github.com/fintech-sdk/moov-go/accounts"
    "github.com/fintech-sdk/moov-go/transfers"
    "github.com/fintech-sdk/moov-go/types"
)

// Build a client (only needs to happen once)
client := moov.NewClientWithBasicAuth(
    os.Getenv("MOOV_PUBLIC_KEY"),
    os.Getenv("MOOV_PRIVATE_KEY"),
    moov.WithAPIVersion("v2026.04.00"),
)

// Use the all-in-one façade
m := moov.New(client)

// Create an account
account, err := m.Accounts.Create(ctx, accounts.CreateRequest{
    AccountType: accounts.AccountTypeBusiness,
    Profile: accounts.Profile{
        Business: &accounts.BusinessProfile{
            LegalBusinessName: "Whole Body Fitness LLC",
        },
    },
})

// Create a transfer
transfer, err := m.Transfers.Create(ctx, account.AccountID, transfers.CreateRequest{
    Source:      types.TransferSource{PaymentMethodID: srcPMID},
    Destination: types.TransferDestination{PaymentMethodID: dstPMID},
    Amount:      types.Amount{Currency: "USD", Value: 2500},
})

Or use domain services directly without the façade:

import "github.com/fintech-sdk/moov-go/accounts"

svc := accounts.NewService(client)
account, err := svc.Create(ctx, accounts.CreateRequest{...})

Error handling

import mooverr "github.com/fintech-sdk/moov-go/errors"

account, err := m.Accounts.Get(ctx, accountID)
if mooverr.IsNotFound(err) {
    return nil, nil          // 404 — account doesn't exist
}
var e *mooverr.APIError
if errors.As(err, &e) {
    log.Printf("status=%d type=%s requestID=%s", e.StatusCode, e.Type, e.RequestID)
}

Idempotency

Transfers.Create auto-generates a UUID v4 key reused across every retry. Pin your own for cross-restart safety:

m.Transfers.Create(ctx, accountID, req,
    moov.WithIdempotencyKey("order-"+order.ID),
)

Synchronous transfers

transfer, err := m.Transfers.Create(ctx, accountID, req,
    moov.WithWaitFor("rail-response"),
)
// transfer.Status, transfer.Source.ACHDetails, etc. are now populated

Webhook verification

import "github.com/fintech-sdk/moov-go/webhook"

event, err := webhook.ParseEvent(r.Header, body, webhookSecret)
if errors.Is(err, webhook.ErrInvalidSignature) {
    http.Error(w, "bad signature", 400)
    return
}
switch event.Type {
case "transfer.updated":
    var payload MyTransferPayload
    json.Unmarshal(event.Data, &payload)
}

Testing

srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
    json.NewEncoder(w).Encode(accounts.Account{AccountID: "acct_test"})
}))
defer srv.Close()

client := moov.NewClientWithBasicAuth("pub", "priv",
    moov.WithBaseURL(srv.URL),
    moov.WithMaxRetries(0),
)
svc := accounts.NewService(client)

License

MIT — not officially affiliated with or endorsed by Moov Financial, Inc.

Documentation

Overview

Package moov is the root package of the moov-go SDK.

Create a client, then either use the Moov facade (which holds every service) or construct individual domain services directly:

// Using the facade
client := moov.NewClientWithBasicAuth(pubKey, privKey,
    moov.WithAPIVersion("v2026.04.00"),
)
m := moov.New(client)
account, err := m.Accounts.Create(ctx, accounts.CreateRequest{...})
transfer, err := m.Transfers.Create(ctx, accountID, transfers.CreateRequest{...})

// Using domain services directly
acctSvc  := accounts.NewService(client)
xferSvc  := transfers.NewService(client)

Error handling

Every method returns (*T, error). On API errors the error wraps an *errors.APIError accessible via errors.As:

import mooverr "github.com/fintech-sdk/moov-go/errors"

acct, err := m.Accounts.Get(ctx, accountID)
if mooverr.IsNotFound(err) { return nil }

var e *mooverr.APIError
if stdErrors.As(err, &e) {
    log.Printf("status=%d requestID=%s", e.StatusCode, e.RequestID)
}

Idempotency

[Transfers.Create] automatically generates a UUID v4 idempotency key and reuses it across every retry attempt. Pin your own key to stay deduplicated across process restarts:

m.Transfers.Create(ctx, accountID, req,
    moov.WithIdempotencyKey("order-"+order.ID),
)

Webhook verification

Use the [webhook] sub-package:

import "github.com/fintech-sdk/moov-go/webhook"

event, err := webhook.ParseEvent(r.Header, body, secret)

Domain packages

Each Moov API resource group is a distinct package:

github.com/fintech-sdk/moov-go/accounts
github.com/fintech-sdk/moov-go/capabilities
github.com/fintech-sdk/moov-go/representatives
github.com/fintech-sdk/moov-go/underwriting
github.com/fintech-sdk/moov-go/billing
github.com/fintech-sdk/moov-go/files
github.com/fintech-sdk/moov-go/onboarding
github.com/fintech-sdk/moov-go/resolution
github.com/fintech-sdk/moov-go/partner
github.com/fintech-sdk/moov-go/bankaccounts
github.com/fintech-sdk/moov-go/cards
github.com/fintech-sdk/moov-go/applepay
github.com/fintech-sdk/moov-go/googlepay
github.com/fintech-sdk/moov-go/paymentmethods
github.com/fintech-sdk/moov-go/terminal
github.com/fintech-sdk/moov-go/wallets
github.com/fintech-sdk/moov-go/transfers
github.com/fintech-sdk/moov-go/sweeps
github.com/fintech-sdk/moov-go/refunds
github.com/fintech-sdk/moov-go/disputes
github.com/fintech-sdk/moov-go/issuing
github.com/fintech-sdk/moov-go/invoices
github.com/fintech-sdk/moov-go/paymentlinks
github.com/fintech-sdk/moov-go/receipts
github.com/fintech-sdk/moov-go/schedules
github.com/fintech-sdk/moov-go/images
github.com/fintech-sdk/moov-go/products
github.com/fintech-sdk/moov-go/support
github.com/fintech-sdk/moov-go/branding
github.com/fintech-sdk/moov-go/enrichment
github.com/fintech-sdk/moov-go/institutions
github.com/fintech-sdk/moov-go/auth
github.com/fintech-sdk/moov-go/e2ee
github.com/fintech-sdk/moov-go/ping

Index

• type Client
  • func NewClientWithBasicAuth(publicKey, privateKey string, opts ...Option) *Client
  • func NewClientWithToken(token string, opts ...Option) *Client
• type Moov
  • func New(c *Client) *Moov
• type Option
  • func WithAPIVersion(v string) Option
  • func WithBaseURL(u string) Option
  • func WithHTTPClient(hc *http.Client) Option
  • func WithLogger(l *slog.Logger) Option
  • func WithMaxRetries(n int) Option
  • func WithOnRetry(fn func(attempt int, delay time.Duration, err error)) Option
• type RequestOption
  • func WithIdempotencyKey(key string) RequestOption
  • func WithRequestAPIVersion(v string) RequestOption
  • func WithRequestMaxRetries(n int) RequestOption
  • func WithWaitFor(value string) RequestOption

Types

type Client

type Client = httpclient.Client

Client is the Moov API HTTP client. Create one with NewClientWithBasicAuth or NewClientWithToken, then pass it to domain service constructors or New.

func NewClientWithBasicAuth

func NewClientWithBasicAuth(publicKey, privateKey string, opts ...Option) *Client

NewClientWithBasicAuth creates a Client authenticated with a public/private key pair (server-side integrations). Always set WithAPIVersion explicitly.

func NewClientWithToken

func NewClientWithToken(token string, opts ...Option) *Client

NewClientWithToken creates a Client authenticated with a short-lived bearer access token (client-side / Moov.js integrations). Obtain a token via auth.Service.Create.

type Moov

type Moov struct {
	// Core
	Ping *ping.Service

	// Moov accounts bounded context
	Accounts        *accounts.Service
	Capabilities    *capabilities.Service
	Representatives *representatives.Service
	Underwriting    *underwriting.Service
	Billing         *billing.Service
	Files           *files.Service
	Onboarding      *onboarding.Service
	Resolution      *resolution.Service
	Partner         *partner.Service

	// Sources bounded context
	BankAccounts   *bankaccounts.Service
	Cards          *cards.Service
	ApplePay       *applepay.Service
	GooglePay      *googlepay.Service
	PaymentMethods *paymentmethods.Service
	Terminal       *terminal.Service
	Wallets        *wallets.Service

	// Money movement bounded context
	Transfers    *transfers.Service
	Sweeps       *sweeps.Service
	Refunds      *refunds.Service
	Disputes     *disputes.Service
	Issuing      *issuing.Service
	Invoices     *invoices.Service
	PaymentLinks *paymentlinks.Service
	Receipts     *receipts.Service
	Schedules    *schedules.Service

	// Account tools bounded context
	Images   *images.Service
	Products *products.Service
	Support  *support.Service

	// Enrichment bounded context
	Branding     *branding.Service
	Enrichment   *enrichment.Service
	Institutions *institutions.Service

	// Authentication bounded context
	Auth *auth.Service
	E2EE *e2ee.Service
}

Moov holds every domain service backed by the same Client. Construct one with New.

Each field is a pointer to a domain-specific service whose methods map 1-to-1 with the Moov API endpoints for that resource group.

func New

func New(c *Client) *Moov

New returns a Moov facade with every domain service backed by c.

client := moov.NewClientWithBasicAuth(pubKey, privKey, moov.WithAPIVersion("v2026.04.00"))
m := moov.New(client)
account, err := m.Accounts.Create(ctx, accounts.CreateRequest{...})

type Option

type Option = httpclient.Option

Option configures a Client at construction time.

func WithAPIVersion

func WithAPIVersion(v string) Option

WithAPIVersion sets the X-Moov-Version header. Always set this explicitly — Moov silently falls back to v2024.01.00 otherwise.

func WithBaseURL

func WithBaseURL(u string) Option

WithBaseURL overrides the API base URL (e.g. for a test server).

func WithHTTPClient

func WithHTTPClient(hc *http.Client) Option

WithHTTPClient replaces the underlying *http.Client.

func WithLogger

func WithLogger(l *slog.Logger) Option

WithLogger attaches a *slog.Logger for request/retry telemetry.

func WithMaxRetries

func WithMaxRetries(n int) Option

WithMaxRetries sets how many additional attempts to make on transient failures.

func WithOnRetry

func WithOnRetry(fn func(attempt int, delay time.Duration, err error)) Option

WithOnRetry registers a callback called before each retry sleep.

type RequestOption

type RequestOption = httpclient.RequestOption

RequestOption customizes a single API call.

func WithIdempotencyKey

func WithIdempotencyKey(key string) RequestOption

WithIdempotencyKey pins an explicit idempotency key for a single call.

func WithRequestAPIVersion

func WithRequestAPIVersion(v string) RequestOption

WithRequestAPIVersion overrides the API version for a single call.

func WithRequestMaxRetries

func WithRequestMaxRetries(n int) RequestOption

WithRequestMaxRetries overrides the retry count for a single call.

func WithWaitFor

func WithWaitFor(value string) RequestOption

WithWaitFor sets X-Wait-For (e.g. "rail-response" for synchronous transfer creation).