weavr-go

README

weavr-go

A production-grade Go client for the Weavr Multi embedded banking API.

Zero external dependencies — the entire package uses only the Go standard library.

Installation

go get github.com/iamkanishka/weavr-go

Requires Go 1.22+.

Quick start

package main

import (
    "context"
    "fmt"
    "os"

    "github.com/iamkanishka/weavr-go/auth"
    "github.com/iamkanishka/weavr-go/weavr"
)

func main() {
    client := weavr.New(weavr.Config{
        APIKey:      os.Getenv("WEAVR_API_KEY"),
        Environment: weavr.Sandbox,
    })

    ctx := context.Background()

    // Authenticate
    loginResp, err := client.Auth.Login(ctx, auth.LoginRequest{
        Email:    "user@example.com",
        Password: auth.PasswordValue{Value: "secret"},
    })
    if err != nil {
        panic(err)
    }
    token := loginResp.Token

    // List managed accounts
    accounts, err := client.Accounts.List(ctx, token, nil)
    if err != nil {
        panic(err)
    }
    fmt.Printf("Found %d accounts\n", accounts.Count)
}

Packages

Package	Description
weavr	Root client — composes all resource clients
auth	Login, token exchange, logout
passwords	Password create, update, lost-password flow
stepup	SCA/PSD2 step-up OTP challenges and factor enrolment
corporates	Corporate identity, KYB
consumers	Consumer identity, KYC
users	Authorised Users (list, create, update, activate, invite)
accounts	Managed Accounts (IBAN, block/unblock, statement)
cards	Managed Cards (virtual/physical, spend rules, statement)
transfers	Intra-identity fund transfers
sends	Outgoing Wire Transfers
linked_accounts	External bank account linking
bulk	Bulk process lifecycle (submit/execute/pause/resume/cancel)
backoffice	Back Office API (Bearer token auth, delegated access)
simulator	Sandbox-only event simulation
types	Shared types, structs, enums
errors	Error types (APIError, ValidationError, NetworkError)
testutil	MockServer for testing without real API calls

Authentication

Weavr uses two tokens:

1. Auth Token — returned by client.Auth.Login. Used as Authorization: Bearer <token> on all subsequent requests.
2. Access Token — returned by client.Auth.GetAccessToken. Required when a root user is linked to multiple Corporate/Consumer identities.

// Single-identity flow (most common)
loginResp, _ := client.Auth.Login(ctx, auth.LoginRequest{
    Email:    "user@example.com",
    Password: auth.PasswordValue{Value: "secret"},
})
token := loginResp.Token

// Multi-identity flow
identities, _ := client.Auth.GetIdentities(ctx, loginResp.Token)
accessResp, _ := client.Auth.GetAccessToken(ctx, loginResp.Token, auth.GetAccessTokenRequest{
    IdentityID: identities.Identities[0].ID,
})
token = accessResp.Token

Error handling

accounts, err := client.Accounts.List(ctx, token, nil)
if err != nil {
    var apiErr *weavrerrors.APIError
    if errors.As(err, &apiErr) {
        switch {
        case apiErr.IsNotFound():
            // 404
        case apiErr.IsUnauthorized():
            // 401 — re-authenticate
        case apiErr.IsStepUpRequired():
            // 403 — initiate step-up OTP challenge
        case apiErr.IsRateLimited():
            // 429 — already retried automatically, this is the final failure
        case apiErr.IsServerError():
            // 5xx — already retried automatically
        }
        fmt.Println(apiErr.ErrorCode, apiErr.Message, apiErr.RequestID)
    }
}

Step-up authentication (SCA/PSD2)

Some operations require step-up authentication:

// 1. Attempt the operation → get 403 with step-up error
_, err := client.Accounts.Create(ctx, token, req)
if apiErr, ok := err.(*weavrerrors.APIError); ok && apiErr.IsStepUpRequired() {
    // 2. Initiate step-up OTP
    client.StepUp.InitiateOTP(ctx, token, types.OTPChannelSMS)

    // 3. User provides code from SMS
    code := getUserInput()

    // 4. Verify and get stepped-up token
    resp, _ := client.StepUp.VerifyOTP(ctx, token, types.OTPChannelSMS,
        stepup.VerifyOTPRequest{VerificationCode: code})

    // 5. Retry with stepped-up token
    account, err = client.Accounts.Create(ctx, resp.Token, req)
}

Bulk operations

// Submit up to 10,000 operations
proc, _ := client.Bulk.Submit(ctx, token, "users", bulk.SubmitRequest{
    Operations: []interface{}{
        map[string]string{"email": "a@b.com"},
        map[string]string{"email": "c@d.com"},
    },
})

// Execute
client.Bulk.Execute(ctx, token, proc.BulkID)

// Poll status
status, _ := client.Bulk.Get(ctx, token, proc.BulkID)
fmt.Println(status.Status) // SUBMITTED, RUNNING, COMPLETED, etc.

// Pause / Resume / Cancel
client.Bulk.Pause(ctx, token, proc.BulkID)
client.Bulk.Resume(ctx, token, proc.BulkID)
client.Bulk.Cancel(ctx, token, proc.BulkID)

// Detect state-machine conflicts
if err := client.Bulk.Pause(ctx, token, proc.BulkID); err != nil {
    if bulk.IsProcessorConflict(err) {
        // bulk was not in RUNNING state
    }
}

Idempotency

Pass an idempotency key as the last argument to any mutating call:

account, err := client.Accounts.Create(ctx, token, req, "my-idempotency-key")

The key is sent as idempotency-ref header per Weavr's specification.

Retries

By default, the client retries on HTTP 429, 500, 502, 503, 504 and network errors with exponential backoff and jitter (3 attempts total). Configure via weavr.Config.MaxRetries.

Back Office

The Back Office API uses a different auth scheme (Bearer token from GetAccessToken, not the user login token):

boClient := weavr.New(weavr.Config{
    APIKey:      os.Getenv("WEAVR_API_KEY"),
    Environment: weavr.Sandbox,
})

// Acquire back-office access token (no user login needed)
tokenResp, _ := boClient.BackOffice.GetAccessToken(ctx, backoffice.GetAccessTokenRequest{
    IdentityID: &types.IdentityID{Type: "CORPORATE", ID: "corp-1"},
})

// Use bearer token for back-office operations
card, _ := boClient.BackOffice.GetManagedCard(ctx, tokenResp.Token, "card-1")

Sandbox simulation

// Simulate an incoming wire transfer
client.Simulator.SimulateDeposit(ctx, token, "acc-1", simulator.DepositRequest{
    TransactionAmount: types.CurrencyAmount{Currency: "GBP", Amount: 10000},
})

// Simulate card purchase
client.Simulator.SimulateCardPurchase(ctx, token, "card-1", simulator.CardAuthorisationRequest{
    TransactionAmount:    types.CurrencyAmount{Currency: "GBP", Amount: 500},
    MerchantCategoryCode: "5411",
})

// Simulate KYB approval
client.Simulator.SimulateKYB(ctx, token, "corp-1",
    simulator.SimulateKYBRequest{KYBState: simulator.KYBOutcomeApproved})

Testing

weavr-go ships with testutil.MockServer so you can test without real API keys:

func TestMyFeature(t *testing.T) {
    srv := testutil.NewMockServer(t)
    srv.Handle("POST", "/login_with_password", 200, `{"token":"test-token"}`)
    srv.Handle("GET", "/managed_accounts", 200, `{"accounts":[],"count":0}`)

    client := weavr.New(weavr.Config{
        APIKey:        "test-key",
        CustomBaseURL: srv.URL(),
    })

    loginResp, _ := client.Auth.Login(ctx, auth.LoginRequest{
        Email:    "test@example.com",
        Password: auth.PasswordValue{Value: "pw"},
    })
    _, _ = client.Accounts.List(ctx, loginResp.Token, nil)

    srv.AssertCalled(t, "GET", "/managed_accounts")
}

Development

make test          # run all tests
make test-race     # run tests with race detector
make vet           # go vet
make fmt           # gofmt
make lint          # golangci-lint (requires installation)

License

MIT