clearbank

README

Clearbank-go

A production-grade Go package for the ClearBank UK API.

Supports

GBP Accounts GBP Payments (FPS, CHAPS, Bacs, CoP, Cheques) Multi-currency & FX Embedded Banking Webhooks

---

Installation

go get github.com/iamkanishka/clearbank-go

Quick Start

client, err := clearbank.New(clearbank.Config{
    APIToken:       os.Getenv("CLEARBANK_API_TOKEN"),
    PrivateKeyPath: os.Getenv("CLEARBANK_PRIVATE_KEY_PATH"),
    Environment:    clearbank.Simulation,
})

Configuration

Create a client once and reuse it throughout your application.

Authentication

ClearBank requires:

1. API Token
2. RSA private key

The SDK automatically signs mutating requests when a private key is configured.

Accounts

• List Accounts
• Get Account
• Create Virtual Account

Payments

• Faster Payments (FPS)
• CHAPS Payments
• Confirmation of Payee

Multi-Currency & FX

• Currency Accounts
• International Payments
• FX Quotes

Embedded Banking

• Customers
• Accounts

Webhooks

• Signature Verification
• Typed Event Handling

Error Handling

All API errors are returned as *clearbank.APIError.

Idempotency

Use clearbank.WithRequestID(...) when retrying mutating requests.

Telemetry

Register a telemetry hook to observe all API calls.

Security

• Never commit your private_key.pem — add it to .gitignore
• In production, load private keys from an HSM, not the filesystem
• Rotate API tokens before their 1-year expiry
• Verify all inbound webhook signatures before processing
• Store X-Correlation-Id from error responses — required for ClearBank support

---

License

MIT — see LICENSE.

---

Documentation

Overview

Package clearbank provides a production-grade Go client for the ClearBank UK API.

The package covers all ClearBank API surface areas:

• GBP Accounts (real and virtual account management, transactions, Bacs data, camt.053 reporting)
• GBP Payments (FPS, CHAPS, Bacs, Bacs DDIs, Cheques, GBP Cross-Border, Confirmation of Payee)
• Multi-currency & FX (account management, international payments, SEPA SCT UK, FX spot & RFQ)
• Embedded Banking (retail/sole-trader/legal-entity customers, payment/savings/ISA accounts, KYC)
• Webhooks (signature verification, typed event dispatch)

Quick Start

client, err := clearbank.New(clearbank.Config{
    APIToken:       os.Getenv("CLEARBANK_API_TOKEN"),
    PrivateKeyPath: os.Getenv("CLEARBANK_PRIVATE_KEY_PATH"),
    Environment:   clearbank.Simulation,
})
if err != nil {
    log.Fatal(err)
}

accounts, err := client.Accounts.List(ctx, clearbank.ListAccountsParams{})

Authentication

Every mutating request (POST, PUT, PATCH) requires a DigitalSignature header computed by RSA-SHA256 signing the request body with your private key. The client handles this automatically when PrivateKeyPEM or PrivateKeyPath is configured.

Environments

Use Simulation for integration testing and Production for live traffic.

Error Handling

All API errors are returned as *APIError, which includes the HTTP status code, ClearBank error message, and the X-Correlation-Id for support escalation.

Idempotency

Every request includes a unique X-Request-Id (UUID v4). For retrying failed mutating requests, use RequestOption WithRequestID to reuse the same ID.

Index

• func GenerateRequestID() string
• func ParseRSAPublicKey(pemBytes []byte) (interface{}, error)
• type APIError
• type Client
  • func New(cfg Config) (*Client, error)
• type Config
• type Environment
• type ListAccountsParams
• type RequestOption
  • func WithRequestID(id string) RequestOption
• type TelemetryEvent
• type TelemetryHook

Functions

func GenerateRequestID

func GenerateRequestID() string

GenerateRequestID returns a new UUID v4 for use as X-Request-Id.

func ParseRSAPublicKey

func ParseRSAPublicKey(pemBytes []byte) (interface{}, error)

ParseRSAPublicKey decodes a PEM-encoded RSA public key for webhook verification.

Types

type APIError

type APIError = httpclient.APIError

APIError represents a structured error returned by the ClearBank API.

type Client

type Client struct {
	// Accounts provides GBP real and virtual account management.
	Accounts *accounts.Service
	// Payments provides GBP payment operations (FPS, CHAPS, Bacs, CoP, etc.).
	Payments *payments.Service
	// MultiCurrency provides multi-currency account management and FX operations.
	MultiCurrency *multicurrency.Service
	// Embedded provides Banking-as-a-Service customer and account management.
	Embedded *embedded.Service
	// Webhooks provides signature verification and typed event parsing.
	Webhooks *webhooks.Service
}

Client is the top-level ClearBank API client. Create one with New and reuse it across your application.

func New

func New(cfg Config) (*Client, error)

New creates and validates a new ClearBank API client.

Returns an error if the configuration is invalid (missing API token, unreadable private key file, unsupported environment).

type Config

type Config = httpclient.Config

Config holds all configuration for the ClearBank client.

type Environment

type Environment = httpclient.Environment

Environment selects between Simulation and Production API endpoints.

const (
	// Simulation targets https://institution-api-sim.clearbank.co.uk
	Simulation Environment = httpclient.Simulation
	// Production targets https://institution-api.clearbank.co.uk
	Production Environment = httpclient.Production
)

type ListAccountsParams

type ListAccountsParams = accounts.ListAccountsParams

Re-export type aliases used by callers.

type RequestOption

type RequestOption = httpclient.RequestOption

RequestOption configures individual API requests.

func WithRequestID

func WithRequestID(id string) RequestOption

WithRequestID sets a specific X-Request-Id on the request. Use this when retrying a failed mutating request with the same ID to satisfy ClearBank's idempotency requirement.

type TelemetryEvent

type TelemetryEvent = telemetry.Event

TelemetryEvent carries observability data for a single API request.

type TelemetryHook

type TelemetryHook = telemetry.Hook

TelemetryHook is called after every HTTP request with observability data.