Requirements

Installation

go mod init

import ("github.com/stripe/stripe-go/v82""github.com/stripe/stripe-go/v82/customer")

go get -u github.com/stripe/stripe-go/v82

Documentation

Customers

sc:=stripe.NewClient(apiKey)params:=&stripe.CustomerCreateParams{Description:stripe.String("Stripe Developer"),Email:stripe.String("gostripe@stripe.com"),PreferredLocales:stripe.StringSlice([]string{"en","es"}),}c,err:=sc.V1Customers.Create(context.TODO(),params)

PaymentIntents

sc:=stripe.NewClient(apiKey)params:=&stripe.PaymentIntentListParams{Customer:stripe.String(customer.ID),}forpi,err:=rangesc.V1PaymentIntents.List(context.TODO(),params) {// handle err// do something}

Events

sc:=stripe.NewClient(apiKey)fore,err:=rangesc.V1Events.List(context.TODO(),nil) {// access event data via e.GetObjectValue("resource_name_based_on_type", "resource_property_name")// alternatively you can access values via e.Data.Object["resource_name_based_on_type"].(map[string]interface{})["resource_property_name"]// access previous attributes via e.GetPreviousValue("resource_name_based_on_type", "resource_property_name")// alternatively you can access values via e.Data.PreviousAttributes["resource_name_based_on_type"].(map[string]interface{})["resource_property_name"]}

Authentication with Connect

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

import ("github.com/stripe/stripe-go/v82")sc:=stripe.NewClient("access_token")

Google AppEngine

import ("fmt""net/http""google.golang.org/appengine""google.golang.org/appengine/urlfetch""github.com/stripe/stripe-go/v82")funchandler(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)iferr!=nil {fmt.Fprintf(w,"Could not create customer: %v",err)return}fmt.Fprintf(w,"Customer created: %v",customer.ID)}

Usage

With Stripe Client

import"github.com/stripe/stripe-go/v82"// Setupsc:=stripe.NewClient("sk_key")// To set backends, e.g. for testing, or to customize use this instead:// sc := stripe.NewClient("sk_key", stripe.WithBackends(backends))// Createc,err:=sc.V1Customers.Create(context.TODO(),&stripe.CustomerCreateParams{})// Retrievec,err:=sc.V1Customers.Retrieve(context.TODO(),id,&stripe.CustomerRetrieveParams{})// Updatec,err:=sc.V1Customers.Update(context.TODO(),id,&stripe.CustomerUpdateParams{})// Deletec,err:=sc.V1Customers.Delete(context.TODO(),id,&stripe.CustomerDeleteParams{})// Listforc,err:=rangesc.Customers.List(context.TODO(),&stripe.CustomerListParams{}) {// handle err// do something}

stripe.Client vs legacyclient.API pattern

Without a Client (Legacy)

import ("github.com/stripe/stripe-go/v82""github.com/stripe/stripe-go/v82/customer")// Setupstripe.Key="sk_key"// Set backend (optional, useful for mocking)// stripe.SetBackend("api", backend)// Createc,err:=customer.New(&stripe.CustomerParams{})// Getc,err:=customer.Get(id,&stripe.CustomerParams{})// Updatec,err:=customer.Update(id,&stripe.CustomerParams{})// Deletec,err:=customer.Del(id,&stripe.CustomerParams{})// Listi:=customer.List(&stripe.CustomerListParams{})fori.Next() {c:=i.Customer()// do something}iferr:=i.Err();err!=nil {// handle}

Other usage patterns

Accessing the Last Response

coupon,err:=sc.V1Coupons.Create(...)requestID:=coupon.LastResponse.RequestID

Automatic Retries

import ("github.com/stripe/stripe-go/v82")config:=&stripe.BackendConfig{MaxNetworkRetries:stripe.Int64(0),// Zero retries}backends:=&stripe.NewBackendWithConfig(config)sc:=stripe.NewClient("sk_key",stripe.WithBackends(backends))coupon,err:=sc.V1Coupons.Create(...)

Configuring Logging

stripe.DefaultLeveledLogger=&stripe.LeveledLogger{Level:stripe.LevelInfo,}

config:=&stripe.BackendConfig{LeveledLogger:&stripe.LeveledLogger{Level:stripe.LevelInfo,    },}

typeLeveledLoggerInterfaceinterface {Debugf(formatstring,v...interface{})Errorf(formatstring,v...interface{})Infof(formatstring,v...interface{})Warnf(formatstring,v...interface{})}

Expanding Objects

//// *Without* expansion//c,_:=sc.V1Charges.Retrieve(context.TODO(),"ch_123",nil)c.Customer.ID// Only ID is populatedc.Customer.Name// All other fields are always empty//// With expansion//p:=&stripe.ChargeCreateParams{}p.AddExpand("customer")c,_=sc.V1Charges.Retrieve(context.TODO(),"ch_123",p)c.Customer.ID// ID is still availablec.Customer.Name// Name is now also available (if it had a value)

How to use undocumented parameters and properties

Parameters

params:=&stripe.CustomerCreateParams{Email:stripe.String("jenny.rosen@example.com")}params.AddExtra("secret_feature_enabled","true")params.AddExtra("secret_parameter[primary]","primary value")params.AddExtra("secret_parameter[secondary]","secondary value")customer,err:=sc.V1Customer.Create(context.TODO(),params)

Properties

customer,_=sc.V1Charges.Retrieve(context.TODO(),"cus_1234",nil);varrawDatamap[string]interface{}_=json.Unmarshal(customer.LastResponse.RawJSON,&rawData)secretFeatureEnabled,_:=string(rawData["secret_feature_enabled"].(bool))secretParameter,ok:=rawData["secret_parameter"].(map[string]interface{})ifok {primary:=secretParameter["primary"].(string)secondary:=secretParameter["secondary"].(string)}

Webhook signing

Testing Webhook signing

payload:=map[string]interface{}{"id":"evt_test_webhook","object":"event","api_version":stripe.APIVersion,}testSecret:="whsec_test_secret"payloadBytes,err:=json.Marshal(payload)signedPayload:=stripe.GenerateTestSignedPayload(&webhook.UnsignedPayload{Payload:payloadBytes,Secret:testSecret})event,err:=stripe.ConstructEvent(signedPayload.Payload,signedPayload.Header,signedPayload.Secret)ifevent.ID==payload["id"] {// Do something with the mocked signed event}else {// Handle invalid event payload}

Writing a Plugin

stripe.SetAppInfo(&stripe.AppInfo{Name:"MyAwesomePlugin",URL:"https://myawesomeplugin.info",Version:"1.2.34",})

Telemetry

config:=&stripe.BackendConfig{EnableTelemetry:stripe.Bool(false),}

Mocking clients for unit tests

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

import ("example/hello/mocks""testing""github.com/golang/mock/gomock""github.com/stretchr/testify/assert""github.com/stripe/stripe-go/v82")funcUseMockedStripeClient(t*testing.T) {// Create a mock controllermockCtrl:=gomock.NewController(t)defermockCtrl.Finish()// Create a mock stripe backendmockBackend:=mocks.NewMockBackend(mockCtrl)backends:=&stripe.Backends{API:mockBackend}client:=stripe.NewClient("sk_test",stripe.WithBackends(backends))// Set up a mock callmockBackend.EXPECT().Call("GET","/v1/accounts/acc_123",gomock.Any(),gomock.Any(),gomock.Any()).// Return nil errorReturn(nil).Do(func(methodstring,pathstring,keystring,params stripe.ParamsContainer,v*stripe.Account) {// Set the return value for the method*v= stripe.Account{ID:"acc_123",}}).Times(1)// Call the client methodacc,_:=client.V1Accounts.GetByID(context.TODO(),"acc_123",nil)// Asset the resultassert.Equal(t,"acc_123",acc.ID)}

Public Preview SDKs

require (...github.com/stripe/stripe-go/v82 <replace-with-the-version-of-your-choice>...)

stripe.AddBetaVersion("feature_beta","v3")

Private Preview SDKs

Custom Request

import ("encoding/json""fmt""github.com/stripe/stripe-go/v82""github.com/stripe/stripe-go/v82/form""github.com/stripe/stripe-go/v82/rawrequest")funcmake_raw_request()error {stripe.Key="sk_test_123"b,err:=stripe.GetRawRequestBackend(stripe.APIBackend)iferr!=nil {returnerr}client:= rawrequest.Client{B:b,Key:apiKey}payload:=map[string]interface{}{"event_name":"hotdogs_eaten","payload":map[string]string{"value":"123","stripe_customer_id":"cus_Quq8itmW58RMet",},}// for a v2 request, json encode the payloadbody,err:=json.Marshal(payload)iferr!=nil {returnerr}v2_resp,err:=client.RawRequest(http.MethodPost,"/v2/billing/meter_events",string(body),nil)iferr!=nil {returnerr}varv2_responsemap[string]interface{}err=json.Unmarshal(v2_resp.RawJSON,&v2_response)iferr!=nil {returnerr}fmt.Printf("%#v\n",v2_response)// for a v1 request, form encode the payloadformValues:=&form.Values{}form.AppendTo(formValues,payload)content:=formValues.Encode()v1_resp,err:=client.RawRequest(http.MethodPost,"/v1/billing/meter_events",content,nil)iferr!=nil {returnerr}varv1_responsemap[string]interface{}err=json.Unmarshal(v1_resp.RawJSON,&v1_response)iferr!=nil {returnerr}fmt.Printf("%#v\n",v1_response)returnnil}

Support

Development

Test

go get -u github.com/stripe/stripe-mockstripe-mock

justtest# or: go test ./...

justtest ./invoice# or: go test ./invoice

justtest ./invoice -run TestInvoiceGet# or: go test ./invoice -run TestInvoiceGet