stripe-go

stripe-go is Stripe’s officially maintained Go SDK, generated directly from Stripe’s OpenAPI specification to give every endpoint a fully typed request and response surface. Rather than hand-writing HTTP calls, developers get a stripe.Client with one service per resource (V1Customers, V1PaymentIntents, V1Charges, and over 150 more) exposing consistent Create/Retrieve/Update/Delete/List methods that accept context.Context and typed param structs.

The library wraps the mechanics that matter for a payments integration: automatic retries with idempotency keys on transient failures, expandable-object support so nested resources can be fetched inline, webhook signature verification and test-payload generation, and an escape hatch (AddExtra/rawrequest) for calling undocumented or preview endpoints without waiting on a new release. A legacy client.API resource-pattern is still available for existing integrations but is deprecated in favor of the newer stripe.Client.

Because the whole surface is codegen’d from Stripe’s own API spec, coverage stays exhaustive and in sync with new Stripe features release over release, at the cost of the generated code reading more like a reference than hand-tuned application code.

What You Get

• Typed stripe.Client - a single client exposing one service per API resource (V1Customers, V1PaymentIntents, V1Charges, V1Subscriptions, etc.) with consistent CRUD-style methods.
• Automatic retries and idempotency - transient failures and 409 conflicts are retried automatically (configurable via MaxNetworkRetries), with idempotency keys attached so retries are safe.
• Webhook signing and verification - stripe.ConstructEvent and GenerateTestSignedPayload for validating and testing incoming webhook events.
• Expandable object support - AddExpand on any params struct to inline nested resources instead of just their IDs.
• Undocumented/preview API access - AddExtra for unreleased parameters and a rawrequest package for calling endpoints the typed client doesn’t cover yet.
• Range-based iterators for List/Search - Go 1.23-style for x, err := range sc.V1Customers.List(...) pagination without manual cursor handling.

Common Use Cases

• Charging customers - create customers, attach payment methods, and create/confirm PaymentIntents from a Go backend.
• Subscription billing - manage subscriptions, invoices, and billing portal sessions for SaaS products.
• Marketplace payouts via Connect - onboard connected accounts and route application fees/transfers on behalf of platform users.
• Webhook-driven order fulfillment - verify and handle payment_intent.succeeded and similar events to trigger fulfillment logic.
• Checkout-based purchase flows - create Checkout Sessions and redirect customers to Stripe-hosted payment pages.

Under The Hood

Architecture The library centers on a single stripe.Client struct that aggregates roughly 150 generated *Service types (stripe_client.go), one per API resource, each holding a shared Backend and API key. Every service method (see account_service.go, customer_service.go, etc.) follows the same shape: build a typed params struct, call Backend.Call(method, path, key, params, &result), and unmarshal the JSON response directly into a typed resource struct. This funnels all HTTP concerns — retries, idempotency, telemetry, logging — through one Backend implementation (stripe_client.go, stripe.go), so adding a new endpoint means adding a new service/params/resource triple without touching transport code. A legacy client.API facade sits alongside the newer stripe.Client for backward compatibility, and a separate rawrequest package bypasses the typed layer entirely for undocumented endpoints.

Tech Stack Pure Go with a minimal dependency footprint — go.mod requires only github.com/stretchr/testify for assertions, targeting Go 1.22+. Request bodies are form-encoded through an internal form package rather than a general-purpose serialization library, and the client relies on the standard net/http package with a pluggable http.Client/Backend for testability (including a documented pattern for GoMock-based mocking and Google AppEngine’s per-request HTTP client).

Code Quality The repository carries 144 _test.go files alongside roughly 525 implementation files, plus a deserialization_test.go and generated_examples_test.go that exercise the generated surface against Stripe’s spec. CI (.github/workflows/ci.yml) runs a dedicated lint job against .golangci.yml on every push and PR, and the README requires go fmt compliance and passing just test (backed by stripe-mock) for any contribution. Error handling is idiomatic Go — every service method returns (*Resource, error) — and naming is fully consistent across the generated surface (V1<Resource>Service, <Resource>CreateParams, etc.).

API Design The SDK’s ergonomics are its main differentiator: every method threads context.Context for cancellation, List/Search operations use Go 1.23 range-over-func iterators instead of manual cursor loops, and forward-compatibility is built in via AddExtra/AddExpand so private-preview fields don’t require a new SDK release to use. Idempotency and retry behavior are on by default rather than opt-in, and the webhook and mocking helpers (GenerateTestSignedPayload, the GoMock Backend pattern) address the two most common integration pain points — testing payments code and validating webhooks — directly in the library rather than leaving them to userland.