stripe-go

In version 32, all fields on parameter structs (those ending in *Params) have been converted to pointers. This allows the library to distinguish between a field being unset (nil) and a field being explicitly set to a zero value.

To set these fields, you must use the provided helper functions instead of passing raw values or taking addresses of literals.

Available helper functions:

• stripe.Bool(bool)
• stripe.Float64(float64)
• stripe.Int64(int64)
• stripe.String(string)

Note on zero values: Previously used fields like CouponEmpty or QuantityZero have been removed. To send an empty value, use the corresponding field with the appropriate helper (e.g., stripe.String("") or stripe.Int64(0)).

// Example: Initializing a parameter struct with a zero value
UsageRecord {
    Quantity: stripe.Int64(0),
}

In Google AppEngine, http.DefaultClient is unavailable. You must create a per-request client using urlfetch.Client and stripe.NewBackends.

import (
	"fmt"
	"net/http"

	"google.golang.org/appengine"
	"google.golang.org/appengine/urlfetch"

	"github.com/stripe/stripe-go/v86"
)

func handler(w http.ResponseWriter, r *http.Request) {
	ctx := appengine.NewContext(r)
	httpClient := urlfetch.Client(ctx)

	backends := stripe.NewBackends(httpClient)
	sc := stripe.NewClient("sk_test_123", stripe.WithBackends(backends))

	params := &stripe.CustomerCreateParams{
		Description: stripe.String("Stripe Developer"),
		Email:       stripe.String("gostripe@stripe.com"),
	}
	customer, err := sc.V1Customers.Create(ctx, params)
	if err != nil {
		fmt.Fprintf(w, "Could not create customer: %v", err)
		return
	}
	fmt.Fprintf(w, "Customer created: %v", customer.ID)
}

By default, expandable objects in stripe-go only populate the ID field. To retrieve the full resource object, use the AddExpand method on the parameter struct before making the API call.

// With expansion
p := &stripe.ChargeCreateParams{}
p.AddExpand("customer")
c, _ = sc.V1Charges.Retrieve(context.TODO(), "ch_123", p)

// c.Customer.ID is available
// c.Customer.Name is now also available

The package depends on stripe-mock for local development and testing. You must fetch and run it in a background terminal to simulate the Stripe API locally.

1. Install stripe-mock: go get -u github.com/stripe/stripe-mock
2. Run the mock server: stripe-mock

To mock the Stripe client using GoMock:

1. Generate a mock for the Backend type using mockgen.
2. Initialize a stripe.Backends struct using your mock backend.
3. Use stripe.NewClient with the mocked backends.

mockgen -destination=mocks/backend.go -package=mocks github.com/stripe/stripe-go/v86 Backend

To install the Stripe Go client library, ensure your project uses Go Modules. You can initialize a module with go mod init and then either import the package directly in your code or explicitly fetch it using go get.

Requirements:

• Go 1.22+ (supports the 4 most recent Go versions at the time of release).

go mod init
go get -u github.com/stripe/stripe-go/v86

Preview features are available in specific SDK versions:

• Public Preview: Versions with a -beta.X suffix.
• Private Preview: Versions with an -alpha.X suffix.

Install them by specifying the version in your go.mod file. For public previews, you can use stripe.AddBetaVersion(name, version) to set required beta headers.

You can run tests using the just command runner or standard go test commands.

To run all tests: just test or go test ./...

To run tests for a specific package (e.g., invoice): just test ./invoice or go test ./invoice

To run a single specific test: just test ./invoice -run TestInvoiceGet or go test ./invoice -run TestInvoiceGet

When performing actions on behalf of a connected account, you can use one of two methods:

1. Stripe-Account Header (Recommended): Use SetStripeAccount() on a ListParams or Params object to pass the account ID.
2. Account Keys: Pass the specific account's access token directly into stripe.NewClient.

Example using SetStripeAccount:

listParams := &stripe.CustomerListParams{}
listParams.SetStripeAccount("acct_123")

// For a list request
listParams := &stripe.CustomerListParams{}
listParams.SetStripeAccount("acct_123")