Go client for the Stripe API
Go Other
Latest commit 0e7296f Jul 19, 2016 @brandur brandur Bump version to 16.3.0
Failed to load latest commit information.
account Mega-commit to move everything over to new parameter system May 24, 2016
balance Mega-commit to move everything over to new parameter system May 24, 2016
bankaccount Mega-commit to move everything over to new parameter system May 24, 2016
bitcoinreceiver Mega-commit to move everything over to new parameter system May 24, 2016
bitcointransaction Mega-commit to move everything over to new parameter system May 24, 2016
card Mega-commit to move everything over to new parameter system May 24, 2016
charge Mega-commit to move everything over to new parameter system May 24, 2016
client add Skus to the client API struct May 12, 2016
countryspec Mega-commit to move everything over to new parameter system May 24, 2016
coupon Mega-commit to move everything over to new parameter system May 24, 2016
currency Reverted import paths to prepare for pull request submission. Nov 10, 2015
customer Add new tset for creating a customer with a plan Jun 23, 2016
discount Add support for go sub functions not passing in customer (#224) May 4, 2016
dispute Mega-commit to move everything over to new parameter system May 24, 2016
event Mega-commit to move everything over to new parameter system May 24, 2016
fee Mega-commit to move everything over to new parameter system May 24, 2016
feerefund Mega-commit to move everything over to new parameter system May 24, 2016
fileupload Mega-commit to move everything over to new parameter system May 24, 2016
invoice adds NoClosed parameter to open an invoice Jul 19, 2016
invoiceitem Mega-commit to move everything over to new parameter system May 24, 2016
order Mega-commit to move everything over to new parameter system May 24, 2016
orderitem Add orders, products, and SKUs to the API. Nov 17, 2015
orderreturn Mega-commit to move everything over to new parameter system May 24, 2016
paymentsource Mega-commit to move everything over to new parameter system May 24, 2016
plan Mega-commit to move everything over to new parameter system May 24, 2016
product Support modifying SKU/product attributes. Jun 24, 2016
recipient Mega-commit to move everything over to new parameter system May 24, 2016
refund Mega-commit to move everything over to new parameter system May 24, 2016
reversal Mega-commit to move everything over to new parameter system May 24, 2016
scripts Add `go vet` and `gofmt` check to CI Mar 27, 2016
sku Merge pull request #268 from stripe/rasmus-update_sku_attributes Jun 30, 2016
sub Using SubParams.QuantityZero in subscription update action Jul 12, 2016
testing Use StripeAccount to avoid name conflict + add testing package Mar 3, 2016
token Mega-commit to move everything over to new parameter system May 24, 2016
transfer Mega-commit to move everything over to new parameter system May 24, 2016
utils Add orders, products, and SKUs to the API. Nov 17, 2015
.gitignore Add `.env` to `.gitignore` Feb 23, 2016
.travis.yml Test against Go 1.6 Mar 22, 2016
CHANGELOG Bump version to 16.3.0 Jul 19, 2016
LICENSE update license to Stripe Aug 29, 2014
Makefile Add `go vet` and `gofmt` check to CI Mar 28, 2016
README.md Normalize indentation in README May 26, 2016
VERSION Bump version to 16.3.0 Jul 19, 2016
account.go Mega-commit to move everything over to new parameter system May 24, 2016
account_test.go Add SourceTransaction and SourceTransfer Mar 18, 2016
balance.go Expose remaining lists consistently (#230) Apr 21, 2016
bankaccount.go Mega-commit to move everything over to new parameter system May 24, 2016
bitcoin_receiver.go Expose remaining lists consistently (#230) Apr 21, 2016
bitcoin_transaction.go 4.4.0 release: Support making bitcoin charges through BitcoinReceiver… Jan 21, 2015
card.go Tokenization Method Jun 20, 2016
charge.go Mega-commit to move everything over to new parameter system May 24, 2016
countryspec.go Expose remaining lists consistently (#230) Apr 21, 2016
coupon.go Expose remaining lists consistently (#230) Apr 21, 2016
customer.go Add `tax_percent` paramter to customer create Jun 23, 2016
discounts.go Return the resource when calling Del Nov 21, 2015
dispute.go Mega-commit to move everything over to new parameter system May 24, 2016
error.go Don't export reference to the parent error May 23, 2016
event.go Expose remaining lists consistently (#230) Apr 21, 2016
example_test.go Fix variable references Dec 4, 2015
fee.go Expose remaining lists consistently (#230) Apr 21, 2016
feerefund.go update comments Sep 23, 2014
fileupload.go Expose remaining lists consistently (#230) Apr 21, 2016
invoice.go adds NoClosed parameter to open an invoice Jul 19, 2016
invoiceitem.go Expose remaining lists consistently (#230) Apr 21, 2016
iter.go Mega-commit to move everything over to new parameter system May 24, 2016
iter_test.go Mega-commit to move everything over to new parameter system May 24, 2016
order.go Add returns to orders. Jul 7, 2016
order_item.go Add orders, products, and SKUs to the API. Nov 17, 2015
order_return.go Set up order return tests, rename package. May 19, 2016
params.go Add `ToValues` to convert `RequestValues` to `url.Values` Jun 3, 2016
params_test.go Add `ToValues` to convert `RequestValues` to `url.Values` Jun 3, 2016
payment_source.go Mega-commit to move everything over to new parameter system May 24, 2016
plan.go Expose `stripe.PlanList` Apr 19, 2016
product.go Expose remaining lists consistently (#230) Apr 21, 2016
recipient.go Expose remaining lists consistently (#230) Apr 21, 2016
refund.go Fix collection of miscellaneous linting errors Mar 28, 2016
reversal.go Add balance transaction to reversals Mar 30, 2015
sku.go Fix SKU attributes, send product. Jun 30, 2016
stripe.go Bump version to 16.3.0 Jul 19, 2016
stripe_test.go Improve testing by looking for a non-blank decline code May 23, 2016
sub.go Add support for go sub functions not passing in customer (#224) May 4, 2016
token.go Mega-commit to move everything over to new parameter system May 24, 2016
transfer.go Add missing `Reversed` and `AmountReversed` fields to `Transfer` May 11, 2016

README.md

Go Stripe GoDoc Build Status

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: "[email protected]",
}
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")

// set this so you can easily retry your request in case of a timeout
params.Params.IdempotencyKey = stripe.NewIdempotencyKey()

i := charge.List(params)
for i.Next() {
    charge := i.Charge()
}

if err := i.Err(); err != nil {
    // handle
}

Events

i := event.List(nil)
for i.Next() {
    e := i.Event()

    // access event data via e.GetObjValue("resource_name_based_on_type", "resource_property_name")
    // alternatively you can access values via e.Data.Obj["resource_name_based_on_type"].(map[string]interface{})["resource_property_name"]

    // access previous attributes via e.GetPrevValue("resource_name_based_on_type", "resource_property_name")
    // alternatively you can access values via e.Data.Prev["resource_name_based_on_type"].(map[string]interface{})["resource_property_name"]
}

Alternatively, you can use the even.Data.Raw property to unmarshal to the appropriate struct.

Authentication with Connect

There are two ways of authenticating requests when performing actions on behalf of a connected account, one that uses the Stripe-Account header containing an account's ID, and one that uses the account's keys. Usually the former is the recommended approach. See the documentation for more information.

To use the Stripe-Account approach, pass the StripeAccount field to a ListParams or Params class. For example:

// For a list request
listParams := &stripe.ChargeListParams{StripeAccount: merchantID}
// For any other kind of request
params := &stripe.CustomerParams{StripeAccount: merchantID}

To use a key, pass it to API's Init function:

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"

    "google.golang.org/appengine"
    "google.golang.org/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$"
)

// Setup
stripe.Key = "sk_key"

stripe.SetBackend("api", backend) // optional, useful for mocking

// Create
$resource$, err := $resource$.New(stripe.$Resource$Params)

// Get
$resource$, err := $resource$.Get(id, stripe.$Resource$Params)

// Update
$resource$, err := $resource$.Update(stripe.$Resource$Params)

// Delete
err := $resource$.Del(id)

// List
i := $resource$.List(stripe.$Resource$ListParams)
for i.Next() {
    $resource$ := i.$Resource$()
}

if err := i.Err(); err != nil {
    // handle
}

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"
)

// Setup
sc := &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(stripe.$Resource$Params)

// Delete
err := sc.$Resource$s.Del(id)

// List
i := sc.$Resource$s.List(stripe.$Resource$ListParams)
for i.Next() {
    resource := i.$Resource$()
}

if err := i.Err(); err != nil {
    // handle
}

Development

Pull requests from the community are welcome. If you submit one, please keep the following guidelines in mind:

  1. Code must be go fmt compliant.
  2. All types, structs and funcs should be documented.
  3. 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.