- Notifications
You must be signed in to change notification settings - Fork0
Go library for the Stripe API.
License
snai1557/stripe-go
Folders and files
| Name | Name | Last commit message | Last commit date | |
|---|---|---|---|---|
Repository files navigation
The officialStripe Go client library.
- Go 1.15 or later
Make sure your project is using Go Modules (it will have ago.mod file in itsroot if it already is):
go mod init
Then, reference stripe-go in a Go program withimport:
import ("github.com/stripe/stripe-go/v74""github.com/stripe/stripe-go/v74/customer")
Run any of the normalgo commands (build/install/test). The Gotoolchain will resolve and fetch the stripe-go module automatically.
Alternatively, you can also explicitlygo get the package into a project:
go get -u github.com/stripe/stripe-go/v74
For a comprehensive list of examples, check out theAPIdocumentation.
Seevideo demonstrations covering how to use the library.
For details on all the functionality in this library, see theGodocumentation.
Below are a few simple examples:
params:=&stripe.CustomerParams{Description:stripe.String("Stripe Developer"),Email:stripe.String("gostripe@stripe.com"),PreferredLocales:stripe.StringSlice([]string{"en","es"}),}c,err:=customer.New(params)
params:=&stripe.PaymentIntentListParams{Customer:stripe.String(customer.ID),}i:=paymentintent.List(params)fori.Next() {pi:=i.PaymentIntent()}iferr:=i.Err();err!=nil {// handle}
i:=event.List(nil)fori.Next() {e:=i.Event()// 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.PrevPreviousAttributes["resource_name_based_on_type"].(map[string]interface{})["resource_property_name"]}
Alternatively, you can use theevent.Data.Raw property to unmarshal to theappropriate struct.
There are two ways of authenticating requests when performing actions on behalfof a connected account, one that uses theStripe-Account header containing anaccount's ID, and one that uses the account's keys. Usually the former is therecommended approach.See the documentation for more information.
To use theStripe-Account approach, useSetStripeAccount() on aListParamsorParams class. For example:
// For a list requestlistParams:=&stripe.CustomerListParams{}listParams.SetStripeAccount("acct_123")
// For any other kind of requestparams:=&stripe.CustomerParams{}params.SetStripeAccount("acct_123")
To use a key, pass it toAPI'sInit function:
import ("github.com/stripe/stripe-go/v74""github.com/stripe/stripe-go/v74/client")stripe:=&client.API{}stripe.Init("access_token",nil)
If you're running the client in a Google AppEngine environment, you'll need tocreate a per-request Stripe client since thehttp.DefaultClient is notavailable. Here's a sample handler:
import ("fmt""net/http""google.golang.org/appengine""google.golang.org/appengine/urlfetch""github.com/stripe/stripe-go/v74""github.com/stripe/stripe-go/v74/client")funchandler(w http.ResponseWriter,r*http.Request) {c:=appengine.NewContext(r)httpClient:=urlfetch.Client(c)sc:=client.New("sk_test_123",stripe.NewBackends(httpClient))params:=&stripe.CustomerParams{Description:stripe.String("Stripe Developer"),Email:stripe.String("gostripe@stripe.com"),}customer,err:=sc.Customers.New(params)iferr!=nil {fmt.Fprintf(w,"Could not create customer: %v",err)}fmt.Fprintf(w,"Customer created: %v",customer.ID)}
While some resources may contain more/less APIs, the following pattern isapplied throughout the library for a given$resource$:
If you're only dealing with a single key, you can simply import the packagesrequired for the resources you're interacting with without the need to create aclient.
import ("github.com/stripe/stripe-go/v74""github.com/stripe/stripe-go/v74/$resource$")// Setupstripe.Key="sk_key"// Set backend (optional, useful for mocking)// stripe.SetBackend("api", backend)// Createresource,err:= $resource$.New(&stripe.$Resource$Params{})// Getresource,err= $resource$.Get(id,&stripe.$Resource$Params{})// Updateresource,err= $resource$.Update(id,&stripe.$Resource$Params{})// DeleteresourceDeleted,err:= $resource$.Del(id,&stripe.$Resource$Params{})// Listi:= $resource$.List(&stripe.$Resource$ListParams{})fori.Next() {resource:= i.$Resource$()}iferr:=i.Err();err!=nil {// handle}
If you're dealing with multiple keys, it is recommended you useclient.API.This allows you to create as many clients as needed, each with their ownindividual key.
import ("github.com/stripe/stripe-go/v74""github.com/stripe/stripe-go/v74/client")// Setupsc:=&client.API{}sc.Init("sk_key",nil)// the second parameter overrides the backends used if needed for mocking// Create$resource$,err:= sc.$Resource$s.New(&stripe.$Resource$Params{})// Get$resource$,err= sc.$Resource$s.Get(id,&stripe.$Resource$Params{})// Update$resource$,err= sc.$Resource$s.Update(id,&stripe.$Resource$Params{})// Delete$resource$Deleted,err:= sc.$Resource$s.Del(id,&stripe.$Resource$Params{})// Listi:= sc.$Resource$s.List(&stripe.$Resource$ListParams{})fori.Next() {$resource$:= i.$Resource$()}iferr:=i.Err();err!=nil {// handle}
UseLastResponse on anyAPIResource to look at the API response thatgenerated the current object:
c,err:= coupon.New(...)requestID:=coupon.LastResponse.RequestID
Similarly, forList operations, the last response is available on the listobject attached to the iterator:
it:= coupon.List(...)forit.Next() {// Last response *NOT* on the individual iterator object// it.Coupon().LastResponse // wrong// But rather on the list object, also accessible through the iteratorrequestID:=it.CouponList().LastResponse.RequestID}
See the definition ofAPIResponse for available fields.
Note that where API resources are nested in other API resources, onlyLastResponse on the top-level resource is set.
The library automatically retries requests on intermittent failures like on aconnection error, timeout, or on certain API responses like a status409 Conflict.Idempotency keys are always added to requests tomake any such subsequent retries safe.
By default, it will perform up to two retries. That number can be configuredwithMaxNetworkRetries:
import ("github.com/stripe/stripe-go/v74""github.com/stripe/stripe-go/v74/client")config:=&stripe.BackendConfig{MaxNetworkRetries:stripe.Int64(0),// Zero retries}sc:=&client.API{}sc.Init("sk_key",&stripe.Backends{API:stripe.GetBackendWithConfig(stripe.APIBackend,config),Uploads:stripe.GetBackendWithConfig(stripe.UploadsBackend,config),})coupon,err:=sc.Coupons.New(...)
By default, the library logs error messages only (which are sent tostderr).Configure default logging using the globalDefaultLeveledLogger variable:
stripe.DefaultLeveledLogger=&stripe.LeveledLogger{Level:stripe.LevelInfo,}
Or on a per-backend basis:
config:=&stripe.BackendConfig{LeveledLogger:&stripe.LeveledLogger{Level:stripe.LevelInfo, },}
It's possible to use non-Stripe leveled loggers as well. Stripe expects loggersto comply to the following interface:
typeLeveledLoggerInterfaceinterface {Debugf(formatstring,v...interface{})Errorf(formatstring,v...interface{})Infof(formatstring,v...interface{})Warnf(formatstring,v...interface{})}
Some loggers likeLogrus and Zap'sSugaredLoggersupport this interface out-of-the-box so it's possible to setDefaultLeveledLogger to a*logrus.Logger or*zap.SugaredLogger directly.For others it may be necessary to write a thin shim layer to support them.
Allexpandable objects in stripe-go take the form of afull resource struct, but unless expansion is requested, only theID field ofthat struct is populated. Expansion is requested by callingAddExpand onparameter structs. For example:
//// *Without* expansion//c,_:=charge.Get("ch_123",nil)c.Customer.ID// Only ID is populatedc.Customer.Name// All other fields are always empty//// With expansion//p:=&stripe.ChargeParams{}p.AddExpand("customer")c,_=charge.Get("ch_123",p)c.Customer.ID// ID is still availablec.Customer.Name// Name is now also available (if it had a value)
stripe-go is a typed library and it supports all public properties or parameters.
Stripe sometimes launches private beta features which introduce new properties or parameters that are not immediately public. These will not have typed accessors in the stripe-go library but can still be used.
To pass undocumented parameters to Stripe using stripe-go you need to use theAddExtra() method, as shown below:
params:=&stripe.CustomerParams{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:=customer.Create(params)
You can access undocumented properties returned by Stripe by querying the raw response JSON object. An example of this is shown below:
customer,_=customer.Get("cus_1234",nil);varrawDatamap[string]interface{}_=json.Unmarshal(customer.LastResponse.RawJSON,&rawData)secret_feature_enabled,_:=string(rawData["secret_feature_enabled"].(bool))secret_parameter,ok:=rawData["secret_parameter"].(map[string]interface{})ifok {primary:=secret_parameter["primary"].(string)secondary:=secret_parameter["secondary"].(string)}
Stripe can optionally sign the webhook events it sends to your endpoint, allowing you to validate that they were not sent by a third-party. You can read more about ithere.
You can usestripe.webhook.GenerateTestSignedPayload to mock webhook events that come from Stripe:
payload:=map[string]interface{}{"id":"evt_test_webhook","object":"event","api_version":stripe.APIVersion,}testSecret:="whsec_test_secret"payloadBytes,err:=json.Marshal(payload)signedPayload:=webhook.GenerateTestSignedPayload(&webhook.UnsignedPayload{Payload:payloadBytes,Secret:testSecret})event,err:=webhook.ConstructEvent(signedPayload.Payload,signedPayload.Header,signedPayload.Secret)ifevent.ID==payload["id"] {// Do something with the mocked signed event}else {// Handle invalid event payload}
If you're writing a plugin that uses the library, we'd appreciate it if youidentified usingstripe.SetAppInfo:
stripe.SetAppInfo(&stripe.AppInfo{Name:"MyAwesomePlugin",URL:"https://myawesomeplugin.info",Version:"1.2.34",})
This information is passed along when the library makes calls to the StripeAPI. Note that whileName is always required,URL andVersion areoptional.
By default, the library sends request latency telemetry to Stripe. Thesenumbers help Stripe improve the overall latency of its API for all users.
You can disable this behavior if you prefer:
config:=&stripe.BackendConfig{EnableTelemetry:stripe.Bool(false),}
To mock a Stripe client for a unit tests usingGoMock:
- Generate a
Backendtype mock.
mockgen -destination=mocks/backend.go -package=mocks github.com/stripe/stripe-go/v74 Backend- Use the
Backendmock to initialize and call methods on the client.
import ("example/hello/mocks""testing""github.com/golang/mock/gomock""github.com/stretchr/testify/assert""github.com/stripe/stripe-go/v74""github.com/stripe/stripe-go/v74/account")funcUseMockedStripeClient(t*testing.T) {// Create a mock controllermockCtrl:=gomock.NewController(t)defermockCtrl.Finish()// Create a mock stripe backendmockBackend:=mocks.NewMockBackend(mockCtrl)client:= account.Client{B:mockBackend,Key:"key_123"}// 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.GetByID("acc_123",nil)// Asset the resultassert.Equal(t,acc.ID,"acc_123")}
Stripe has features in the beta phase that can be accessed via the beta version of this package.We would love for you to try these and share feedback with us before these features reach the stable phase.To install a beta version of stripe-go use the commit notation of thego get command to point to a beta tag:
go get -u github.com/stripe/stripe-go/v74@v73.3.0-beta.1NoteThere can be breaking changes between beta versions.
We highly recommend keeping an eye on when the beta feature you are interested in goes from beta to stable so that you can move from using a beta version of the SDK to the stable version.
If your beta feature requires aStripe-Version header to be sent, use thestripe.APIVersion field to set it:
NoteThe
APIVersioncan only be set in beta versions of the library.
stripe.APIVersion+="; feature_beta=v3"
New features and bug fixes are released on the latest major version of the Stripe Go client library. If you are on an older major version, we recommend that you upgrade to the latest in order to use the new features and bug fixes including those for security vulnerabilities. Older major versions of the package will continue to be available for use, but will not be receiving any updates.
Pull requests from the community are welcome. If you submit one, please keepthe following guidelines in mind:
- Code must be
go fmtcompliant. - All types, structs and funcs should be documented.
- Ensure that
make testsucceeds.
The test suite needs testify'srequire package to run:
github.com/stretchr/testify/requireBefore running the tests, make sure to grab all of the package's dependencies:
go get -t -vIt also depends onstripe-mock, so make sure to fetch and run it from abackground terminal (stripe-mock's README also containsinstructions for installing via Homebrew and other methods):
go get -u github.com/stripe/stripe-mockstripe-mockRun all tests:
make testRun tests for one package:
go test ./invoiceRun a single test:
go test ./invoice -run TestInvoiceGetFor any requests, bug or comments, pleaseopen an issue orsubmit apull request.