checkout-go

Production-grade Go client for the Checkout.com API. All 168 endpoints. Zero external dependencies. Race-detector clean.

---

Features

Core Client

• Initialize SDK (New)
• Client and configuration management

Payments

• Payments processing
• Payment flows
• Payment links
• Hosted payments
• Payment contexts
• Setup flows
• Payment methods

Vault & Financial Services

• Tokenization
• Instruments management
• Customer profiles
• Transfers
• Balance management
• Forex
• Card metadata
• Network tokens
• Account updater
• Apple Pay & Google Pay
• Forwarding
• Compliance
• Agentic commerce
• Sessions
• Reports
• Financial actions

Disputes

• Dispute management
• Workflow handling

Issuing

• Cards
• Cardholders
• Controls
• Platforms
• Identity

Webhooks

• Signature verification
• Event parsing
• Invalid signature error handling

Error Handling

• API error structures

Utilities

• Idempotency support (e.g., idempotency keys)

The root package contains exactly one Go source file (checkout.go). All service logic lives in typed sub-packages.

---

Installation

go get github.com/iamkanishka/checkout-go

Requires Go 1.25+. Zero external runtime dependencies.

---

Quick start

import (
    checkout "github.com/iamkanishka/checkout-go"
    "github.com/iamkanishka/checkout-go/errs"
    "github.com/iamkanishka/checkout-go/option"
    "github.com/iamkanishka/checkout-go/payments"
)

c := checkout.New(checkout.Config{
    Prefix:          os.Getenv("CHECKOUT_PREFIX"), // first 8 chars of client_id
    Environment:     checkout.Sandbox,
    AccessKeyID:     os.Getenv("CHECKOUT_ACCESS_KEY_ID"),
    AccessKeySecret: os.Getenv("CHECKOUT_ACCESS_KEY_SECRET"),
})

// Request a payment
payment, err := c.Payments().Request(ctx, payments.Request{
    Amount:   10_000, // GBP £100.00 (minor units)
    Currency: "GBP",
    Source:   map[string]any{"type": "token", "token": "tok_..."},
    Reference: "ORD-001",
}, option.WithIdempotencyKey("ORD-001-attempt-1"))

// Capture it
_, err = c.Payments().Capture(ctx, payment.ID, payments.CaptureRequest{})

// Partial refund (£25)
_, err = c.Payments().Refund(ctx, payment.ID, payments.RefundRequest{Amount: 2_500})

---

Authentication

OAuth 2.0 (recommended)

checkout.New(checkout.Config{
    Prefix:          "vkuhvk4v",
    AccessKeyID:     "ack_...",
    AccessKeySecret: "...",
})

Tokens are fetched, cached in-memory, and proactively refreshed 90s before expiry using a singleflight pattern.

Static secret key

checkout.New(checkout.Config{Prefix: "vkuhvk4v", SecretKey: "sk_..."})

---

Error handling

import "github.com/iamkanishka/checkout-go/errs"

payment, err := c.Payments().Request(ctx, req)
if err != nil {
    var apiErr *errs.APIError
    if errors.As(err, &apiErr) {
        switch {
        case apiErr.IsNotFound():        // 404
        case apiErr.IsRateLimited():     // 429 — already retried MaxAttempts times
        case apiErr.IsConflict():        // 409 — idempotency collision
        case apiErr.IsUnauthorized():    // 401
        case apiErr.IsValidationError(): // 422
        case apiErr.IsServerError():     // 5xx
        }
        log.Printf("HTTP %d [%s] codes=%v", apiErr.StatusCode, apiErr.RequestID, apiErr.ErrorCodes)
    }
}

---

Idempotency

Cko-Idempotency-Key (UUIDv4) is auto-injected on all eligible endpoints: POST /payment-contexts, POST /payments (and all action sub-paths), POST /transfers.

// Custom key — safe to retry with the same value
c.Payments().Request(ctx, req, option.WithIdempotencyKey("order-42-attempt-1"))

// Prefix auto-generated keys
checkout.New(checkout.Config{IdempotencyKeyPrefix: "myapp"})
// → "myapp-550e8400-..."

---

Retry

Full-jitter exponential backoff: delay = rand(0, min(base × 2^attempt, max))

checkout.New(checkout.Config{
    Retry: checkout.RetryConfig{
        MaxAttempts: 4,
        BaseDelay:   500 * time.Millisecond,
        MaxDelay:    30 * time.Second,
    },
})

Retried: 429, 5xx, network errors. Not retried: 4xx (except 429), 409.

---

AWS PrivateLink

checkout.New(checkout.Config{Prefix: "vkuhvk4v", PrivateLink: true})
// → https://pl-vkuhvk4v.api.checkout.com

---

mTLS

cert, _ := tls.LoadX509KeyPair("client.crt", "client.key")
checkout.New(checkout.Config{
    Prefix: "vkuhvk4v",
    HTTPClient: &http.Client{
        Transport: &http.Transport{
            TLSClientConfig: &tls.Config{Certificates: []tls.Certificate{cert}},
        },
    },
})

---

Webhook verification

import "github.com/iamkanishka/checkout-go/webhook"

body, err := webhook.Verify(r, os.Getenv("CKO_WEBHOOK_KEY"))
if errors.Is(err, webhook.ErrInvalidSignature) {
    http.Error(w, "forbidden", http.StatusForbidden)
    return
}
var event webhook.Event
_ = json.Unmarshal(body, &event)

Or use the convenience aliases from the root package:

body, err := checkout.VerifyWebhook(r, key)
errors.Is(err, checkout.ErrInvalidWebhookSignature)

---

Structured logging

checkout.New(checkout.Config{
    Logger: slog.New(slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{Level: slog.LevelDebug})),
})

---

Testing

go test ./... -race -count=1

All tests use net/http/httptest. No live API calls. No credentials needed.

---

Complete API

Service	Operations	Package
Payments	Request, List, Get, GetActions, IncrementAuthorization, CancelRetry, Capture, Refund, Reverse, Void, Search	payments
Flow	CreateSession, SubmitSession, CreateAndSubmit	payments
Payment Links	Create, Get	payments
Hosted Payments Page	Create, Get	payments
Payment Contexts	Request, Get	payments
Payment Setups	Create, Update, Get, Confirm	payments
Payment Methods	List	payments
Tokens	Create	vault
Instruments	Create, Get, Update, Delete, GetBankAccountFieldFormatting	vault
Customers	Create, Get, Update, Delete	vault
Transfers	Create, Get	vault
Balances	Get	vault
Forex	GetRates	vault
Card Metadata	Get	vault
Network Tokens	Provision, Get, RequestCryptogram, Delete	vault
Account Updater	GetUpdatedCredentials	vault
Apple Pay	GenerateCSR, UploadCertificate, EnrollDomain	vault
Google Pay	EnrollEntity, RegisterDomain, GetRegisteredDomains, GetEnrollmentState	vault
Forward	SendRequest, GetRequest, CreateSecret, ListSecrets, UpdateSecret, DeleteSecret	vault
Sessions (3DS)	Create, Get, Update, Complete, Update3DSMethodCompletion	vault
Compliance Requests	Get, Respond	vault
Agentic Commerce	CreateDelegatedToken	vault
Reports	List, Get, GetFile	vault
Financial Actions	List	vault
Disputes	List, Get, Accept, ProvideEvidence, GetEvidence, SubmitEvidence, SubmitArbitrationEvidence, GetSubmittedArbitrationEvidence, GetSubmittedEvidence, GetSchemeFiles, UploadFile, GetFile	disputes
Workflows	List, Create, Get, Patch, Delete, AddAction, UpdateAction, RemoveAction, AddCondition, UpdateCondition, RemoveCondition, Test, GetEventTypes, GetEvent, GetActionInvocations, GetSubjectEvents, ReflowByEvent, ReflowByEventAndWorkflow, Reflow, ReflowBySubject, ReflowBySubjectAndWorkflow	disputes
Cardholders	Create, Get, Update, ListCards	issuing
Cardholder Access Tokens	Request	issuing
Cards	Create, Get, Update, GetCredentials, Activate, Suspend, Revoke, Renew, ScheduleRevocation, DeleteScheduledRevocation, Enrol3DS, Get3DSEnrollment, Update3DSEnrollment	issuing
Controls	Create, ListByTarget, Get, Update, Delete	issuing
Control Profiles	Create, List, Get, Update, Delete, AddTarget, RemoveTarget	issuing
Control Groups	Create, ListByTarget, Get, Delete	issuing
Issuing Transactions	List, Get	issuing
Issuing Disputes	Create, Get, Cancel, Escalate	issuing
Issuing Sandbox	SimulateAuthorization, SimulateIncrementalAuthorization, SimulateClearing, SimulateRefund, SimulateReversal	issuing
Platform Entities	Onboard, Get, Update, UploadFile, GetFile, ListMembers, ReinviteMember	issuing
Platform Payment Instruments	Add, Get, Update, List	issuing
Payout Schedules	Get, Update	issuing
Reserve Rules	Add, Get, Update, List	issuing
Identity Applicants	Create, Get, Update, Anonymize	issuing
Identity Verification	CreateAndStart, Create, Get, Anonymize, CreateAttempt, ListAttempts, GetAttempt, GetReport	issuing
AML Screening	Create, Get	issuing
Face Authentication	Create, Get, Anonymize, CreateAttempt, ListAttempts, GetAttempt	issuing
ID Document Verification	Create, Get, Anonymize, CreateAttempt, ListAttempts, GetAttempt, GetReport	issuing

---

License

MIT — see LICENSE.