Go Stripe
Summary
The official Stripe Go client library.
Versioning
Each revision of the binding is tagged and the version is updated accordingly.
Given Go's lack of built-in versioning, it is highly recommended you use a
package management tool in order to ensure a newer
version of the binding does not affect backwards compatibility.
To see the list of past versions, run git tag
. To manually get an older
version of the client, clone this repo, checkout the specific tag and build the
library:
git clone https://github.com/stripe/stripe-go.git
cd stripe-go
git checkout api_version_tag
make build
For more details on changes between versions, see the binding
changelog and API changelog.
Installation
go get github.com/stripe/stripe-go
Documentation
For a comprehensive list of examples, check out the API
documentation.
For details on all the functionality in this library, see the GoDoc
documentation.
Below are a few simple examples:
Customers
params := &stripe.CustomerParams{
Balance: -123,
Desc: "Stripe Developer",
Email: "gostripe@stripe.com",
}
params.SetSource(&stripe.CardParams{
Name: "Go Stripe",
Number: "378282246310005",
Month: "06",
Year: "15",
})
customer, err := customer.New(params)
Charges
params := &stripe.ChargeListParams{Customer: customer.Id}
params.Filters.AddFilter("include[]", "", "total_count")
params.Params.IdempotencyKey = stripe.NewIdempotencyKey()
i := charge.List(params)
for i.Next() {
charge := i.Charge()
}
if err := i.Err(); err != nil {
}
Events
i := event.List(nil)
for i.Next() {
e := i.Event()
}
Alternatively, you can use the even.Data.Raw
property to unmarshal to the
appropriate struct.
Connect Flows
If you're using an access token you will need to use a client. Simply pass the
access token value as the tok
when initializing the client.
import (
"github.com/stripe/stripe-go"
"github.com/stripe/stripe-go/client"
)
stripe := &client.API{}
stripe.Init("access_token", nil)
Google AppEngine
If you're running the client in a Google AppEngine environment, you'll need to
create a per-request Stripe client since the http.DefaultClient
is not
available. Here's a sample handler:
import (
"fmt"
"net/http"
"appengine"
"appengine/urlfetch"
"github.com/stripe/stripe-go"
"github.com/stripe/stripe-go/client"
)
func handler(w http.ResponseWriter, r *http.Request) {
c := appengine.NewContext(r)
httpClient := urlfetch.Client(c)
sc := client.New("sk_live_key", stripe.NewBackends(httpClient))
fmt.Fprintf(w, "Ready to make calls to the Stripe API")
}
Usage
While some resources may contain more/less APIs, the following pattern is
applied throughout the library for a given $resource$
:
Without a Client
If you're only dealing with a single key, you can simply import the packages
required for the resources you're interacting with without the need to create a
client.
import (
"github.com/stripe/stripe-go"
"github.com/stripe/stripe-go/$resource$"
)
stripe.Key = "sk_key"
stripe.SetBackend("api", backend)
$resource$, err := $resource$.New(stripe.$Resource$Params)
$resource$, err := $resource$.Get(id, stripe.$Resource$Params)
$resource$, err := $resource$.Update(stripe.$Resource$Params)
err := $resource$.Del(id)
i := $resource$.List(stripe.$Resource$ListParams)
for i.Next() {
$resource$ := i.$Resource$()
}
if err := i.Err(); err != nil {
}
With a Client
If you're dealing with multiple keys, it is recommended you use client.API
.
This allows you to create as many clients as needed, each with their own
individual key.
import (
"github.com/stripe/stripe-go"
"github.com/stripe/stripe-go/client"
)
sc := &client.API{}
sc.Init("sk_key", nil)
$resource$, err := sc.$Resource$s.New(stripe.$Resource$Params)
$resource$, err := sc.$Resource$s.Get(id, stripe.$Resource$Params)
$resource$, err := sc.$Resource$s.Update(stripe.$Resource$Params)
err := sc.$Resource$s.Del(id)
i := sc.$Resource$s.List(stripe.$Resource$ListParams)
for i.Next() {
resource := i.$Resource$()
}
if err := i.Err(); err != nil {
}
Development
Pull requests from the community are welcome. If you submit one, please keep
the following guidelines in mind:
- Code must be
go fmt
compliant. - All types, structs and funcs should be documented.
- Ensure that
make test
succeeds.
Test
For running additional tests, follow the steps below:
Set the STRIPE_KEY
environment variable to match your test private key, then
run make test
:
STRIPE_KEY=YOUR_API_KEY make test
Or to run tests for a particular subpackage:
STRIPE_KEY=YOUR_API_KEY go test ./invoice
Or to run a particular test (it's worth noting however that Go will report a
success even if the referenced test doesn't exist):
STRIPE_KEY=YOUR_API_KEY go test -run "TestAllInvoicesScenarios" ./invoice
For any requests, bug or comments, please open an issue or submit a
pull request.